Three engineers on the same team, three laptops, three copies of the same .claude/ directory. One of them tweaks a hook to block a destructive command and forgets to tell anyone. Another rewrites an agent definition to run on a cheaper model tier. The third adds a skill that the other two have never seen. A week later the pipeline behaves differently on every machine, nobody can say why, and the senior developer spends a Friday afternoon diffing three directories by eye and reconciling them by hand. There is no plan, no apply, no rollback. There is a person, a terminal, and a growing suspicion that this problem has been solved before.
It has. We watched a version of this play out on a consulting engagement, and the diagnosis wrote itself. This is the 2014 Terraform problem reborn at the harness layer. A decade ago, teams provisioned cloud infrastructure by clicking through consoles and running one-off scripts, and every environment drifted away from every other one until somebody codified the whole thing into a file you could diff, plan, and apply. The agent harness is now the infrastructure that drifts. It deserves the same treatment, and almost nobody is giving it.
Figure 1 - The harness-as-code stack: Three layers describe how teams turn agent configuration into managed artifacts. Workflow orchestration and skill packaging both have mature tools. The bottom row, whole-harness declarative state, is empty for its precise scope. That empty cell is the argument of this article.
The harness is already infrastructure, on paper
The framing is not ours alone. In its guide to the new software development lifecycle, Google states the position plainly: an agent is a model plus a harness [1]. The harness is everything wrapped around the model that decides what it can see and do, the AGENTS.md context files, the system prompts, the eval suites, the skill libraries. Google’s guidance is that these components “are code, reviewed in pull requests, versioned with the project, and owned by named engineers” [1]. The companion Kaggle whitepaper puts it even more directly, describing the harness as “an engineered resource that lives in version control just like the code itself” [2].
Read that twice, because it reframes the whole discipline. The model is the part you rent from a vendor. The harness is the part you build, and it is doing most of the work. Google’s own diagrams describe a small model core surrounded by a much larger harness layer [1]. The intelligence you actually ship to a project is not the raw weights. It is the accumulated configuration around them: which tools the agent can call, which files it reads first, which quality gates block a bad commit, which specialized sub-agents own which directories.
KEY INSIGHT: If the harness is where most of your engineering value lives, then treating it as a pile of dotfiles you copy between laptops is the same mistake teams made with cloud servers before infrastructure as code. The fix is to make harness state a managed, versioned, diffable artifact, not a folder you hope stays in sync.
So the harness is infrastructure on paper. The problem is that the tooling to manage it as infrastructure does not exist yet for its full scope. To see the gap clearly, it helps to break the harness-as-code space into three layers.
Figure 2 - The pattern repeats: In 2014, cloud infrastructure was provisioned by hand and drifted until infrastructure as code codified it. In 2026, the agent harness is the new hand-provisioned infrastructure. The same primitives that tamed the cloud, plan, apply, diff, and drift detection, are what the harness layer is missing.
Layer one: workflow orchestration is solved
The first layer is workflow orchestration. This is the plumbing that routes a task through a defined sequence of steps: research, then design, then build, then review, with retries and branching and state passed between stages. Tools like LangGraph and Temporal have covered the general case for a while, and the agent-native entrant here is Archon, which as of July 2026 describes itself as “the first open-source harness builder for AI coding” [3]. It has roughly 22.9 thousand stars and its latest release is v0.5.0, published June 26, 2026 [3].
Archon is genuinely good at what it does, and its own documentation tells you what that is. It builds reproducible workflow pipelines, and it reaches for the same analogy every time: a Dockerfile for your agent, a GitHub Actions workflow for your agent. That analogy is exact and it is also the tell. A Dockerfile and a CI workflow describe a process, an ordered set of steps that run to produce an output. That is orchestration. It is not the same thing as the declarative state of the whole harness sitting on disk.
We want to be precise here because the vocabulary collides. Archon calling itself a “harness builder” is fair marketing, but the scope it builds is the workflow, the sequence of what runs. It is Layer one, and Layer one is solved. What it does not do, and does not claim to do, is manage your .claude/ directory as a single declarative resource you can plan, apply, and roll back.
Figure 3 - Layer one, orchestration: Workflow tools route a task through ordered stages with retries and branching. This is process, not state. Archon, LangGraph, and Temporal cover it well. The output is a running pipeline, not a versioned snapshot of the harness itself.
Layer two: skill packaging is solved
The second layer is skill packaging. A skill in the modern sense is an organized folder of instructions, scripts, and resources that an agent discovers and loads on demand. Anthropic published Agent Skills as an open standard for cross-platform portability on December 18, 2025, and the standard now has real cross-vendor traction, with more than thirty tools implementing it and a dedicated specification site at agentskills.io [4].
The infrastructure vendors moved into this layer fast, which tells you it is worth owning. HashiCorp shipped HashiCorp Agent Skills, packaging its own product knowledge into installable skill units [5]. Pulumi shipped Pulumi Agent Skills, with a plugin system that lets an agent pull in Pulumi’s deployment expertise as a discrete, versioned bundle [6]. Both are the same move: take a body of domain knowledge, wrap it in the Agent Skills contract, and distribute it through existing package channels rather than a bespoke marketplace.
Skill packaging is solved because the unit is well defined and the distribution story is boring, in the good way. A skill is a folder. You version it, you publish it, you install it. What skill packaging does not address is the harness as a whole. A skill is one component. The harness is the skill plus the agents plus the hooks plus the settings plus the slash commands plus the context files, all of it, as one coherent, diffable state.
Figure 4 - Layer two, skill packaging: A skill is a self-contained folder of instructions, scripts, and resources, distributed like any other package. The Agent Skills open standard, plus HashiCorp and Pulumi’s implementations, make this layer a solved problem. But a skill is one component of the harness, not the whole harness.
Layer three: whole-harness state is the empty cell
Here is the row that is empty. There is no vendor-neutral tool that treats the whole local harness, the entire .claude/ filesystem on your own disk, as declarative state you can plan, apply, diff, and drift-check. That is the specific, narrow claim, and every word in it is load-bearing.
We have to be careful, because a careless version of this claim is wrong, and an informed reader will catch it. Declarative infrastructure as code for agents is not entirely absent. It exists in two shapes, and neither one fills the empty cell.
The first shape is vendor-locked infrastructure for hosted agents. Amazon’s Bedrock AgentCore harness reached general availability in 2026, taking a project from idea to a production-grade agent and managing the operational surface: memory, gateway, a skills catalog, an identity vault, and a microVM runtime [7]. In April 2026 it added first-class infrastructure-as-code support, shipping both CDK constructs and a Terraform provider [8]. So you genuinely can declare an agent in HCL today. The catch is the lock-in. AgentCore added multi-provider model support, so it is portable at the model layer, but the operational layer that the IaC actually manages stays inside AWS. You are declaring an Amazon-hosted agent, not your local harness.
The second shape is community tooling for a single vendor’s hosted agents. Anthropic itself has shipped Managed Agents, a server-hosted runtime that decouples the reasoning from the execution [9], billed by the session-hour at roughly $0.08 per session-hour [10]. On top of that hosted product, a community developer published an unofficial Terraform provider, andasv/anthropic-claude-managed-agents, that manages those server-hosted Managed Agents declaratively through Anthropic’s API [11]. It is the closest thing in the wild to declarative harness state in HCL. But it manages Anthropic’s hosted agents, not the .claude/ directory on your laptop, and it is unofficial and single-vendor.
This matters enough to state without hedging: Anthropic has not shipped official infrastructure-as-code tooling for the local Claude Code harness. We checked this directly against vendor sources. The category, for its precise scope, is genuinely empty.
KEY INSIGHT: The empty cell is not “declarative agent infrastructure.” That exists. The empty cell is the intersection of three constraints at once: vendor-neutral, so it is not locked to one cloud; operating on the local filesystem, so it manages the
.claude/directory you actually edit; and offering the real infrastructure-as-code primitives, plan, apply, diff, and drift. No shipping tool sits at that intersection.
Figure 5 - The competitive landscape: Plot the tools on two axes, vendor-neutral versus vendor-locked, and hosted-agent scope versus local-harness scope. Bedrock AgentCore is vendor-locked and hosted. The community Anthropic provider is vendor-specific and hosted. Archon covers workflow, HashiCorp and Pulumi cover skills. The vendor-neutral, local-harness, full-primitives quadrant is empty.
A second proof point, from a different vendor entirely
The shippable-harness-bundle pattern is not speculative, and the clearest evidence comes from a domain that has nothing to do with general coding. Google published an open-source CI/CD extension for coding agents, and its shape matches this article’s thesis almost exactly, even though its own presenters never framed it as harness infrastructure as code [12]. The extension bundles four things into one installable, version-controlled unit: a set of skills for deployment and pipeline design and release orchestration, a local MCP server that runs with the user’s own credentials, a local knowledge base of curated CI/CD best practices, and a comprehensive eval suite run against real projects on every release [12].
Two details make it a strong data point. First, the presenters state that “by leveraging standard primitives, we have ensured that this is harness agnostic and can be adopted to tool of your choice” [12], and they proved it by running the whole bundle inside Claude Code in the first live demo, not inside Google’s own agent. Second, as presented in the talk, the bundle bakes governance defaults directly into the harness rather than leaving them as opt-in add-ons. Secret scanning gates every deploy as a blocking step. IAM roles are auto-generated at least privilege per pipeline stage. Generated Cloud Deploy pipelines set require_approval: true on the production stage and wire auto-rollback rules by default [12].
Those defaults are exactly the tacit knowledge that normally lives in one senior engineer’s head. A versioned harness bundle can encode that knowledge and ship it, so every team that installs the bundle inherits the guardrail instead of rediscovering the hard way why it exists. This is a narrower thing than whole-harness state, one domain, CI/CD, rather than the entire harness, but it proves the bundle pattern works in production and that parties other than the model vendor are already building it.
Pi shows what package-managed harness state looks like
If you want to see the empty cell filled for a real harness, the cleanest existing example is Pi, an open-source coding agent whose entire extension model is package-managed harness state. In Pi, the harness is not hidden inside vendor infrastructure. It is TypeScript files on disk, or npm packages, versioned and installable, and the extension API surface is documented directly by the project [13].
Here is what a Pi extension can actually reach, enumerated from the project’s own extension documentation [14]:
- Register custom tools the model can call, with
pi.registerTool(). - Register custom slash commands, with
pi.registerCommand(). - Intercept lifecycle events to block or modify tool calls, inject context, or customize compaction, hooking events including
session_start,before_agent_start,tool_call,tool_result, andinput. - Persist session state that survives restarts, with
pi.appendEntry(). - Drive user interaction prompts, with
ctx.uifor select, confirm, input, and notify. - Render full custom TUI components, with
ctx.ui.custom(). - Load tools dynamically at runtime, with
pi.setActiveTools(). - Override the built-in tools, read, bash, edit, write, grep, find, and ls.
- Register custom model providers, with
pi.registerProvider(). - Manage sessions directly: new sessions, forking, tree navigation, and compaction.
The distribution story is the important part. TypeScript files are auto-discovered in a global ~/.pi/agent/extensions/ directory or a project-local .pi/extensions/ directory, they are shared through npm or git as ordinary packages declared in settings.json, and they hot-reload with a /reload command because the runtime loads TypeScript through jiti without a compile step [14]. The harness augmentation is code, on disk, versioned, installable, and reloadable in a running session.
Pi is one harness proving the pattern for itself. It shows that a harness can be declarative, package-managed state rather than a folder of dotfiles. What it does not do, because it is not trying to, is generalize that pattern across every harness. Pi’s extensions are Pi’s. The gap in the stack is a layer that does for the whole .claude/ directory, and eventually for any harness, what Pi’s extension system does for Pi.
Figure 6 - Harness state as a package: A Pi extension starts as a TypeScript file on disk, ships as an npm or git package, and hot-reloads into a live session. This is harness state managed the way we manage any other code: authored, versioned, distributed through existing package channels, installed with one command. It is the empty cell, filled, for one harness.
The primitives the harness layer is missing
The reason the Terraform analogy keeps returning is that the primitives Terraform gave the cloud are exactly the primitives the harness layer needs. Four of them do most of the work.
Plan. Before you change anything, you see what will change. A dry run that reads your current harness state, compares it to the desired state, and prints the delta. No surprises, no changing three laptops and hoping.
Apply. You commit the plan, and the tool makes the change atomically. Either the whole harness moves to the new state or none of it does. No half-applied configuration where the hook updated but the agent definition did not.
Diff. At any moment you can ask how two harness states differ, this laptop against that one, this branch against main, today against last week. The Friday-afternoon manual reconciliation becomes a command.
Drift detection. The harness on disk stops matching the harness in version control the moment someone edits a file by hand. Drift detection is the alarm that tells you the real state has wandered from the declared state, so you can pull it back before three configurations become five.
None of these are exotic. They are the same four operations that turned cloud provisioning from an art into an engineering discipline. Applied to the .claude/ directory, they turn the harness from a folder you copy into a resource you manage.
Figure 7 - The four primitives: Plan previews the delta before you touch anything. Apply commits it atomically. Diff compares any two harness states on demand. Drift detection catches hand edits that pull the real state away from the declared state. These are the operations the harness layer borrows from a decade of infrastructure as code.
The directory is already the state
The good news is that Claude Code’s harness is already file-based, which means the raw material for declarative management is sitting on disk right now. The .claude/ directory holds the whole harness as plain files: agent definitions, hook scripts, skill folders, slash commands, settings, and the CLAUDE.md orientation document that every session reads first. It is already versioned in git in any serious project. What it lacks is the management layer on top, the schema that describes a valid harness, the plan and apply that move it safely, the environment overlays that let a development harness and a production harness share a base and differ only where they must.
This is the same recognition that drove our own work on the Bootstrap Framework, the meta-project we described in part in Multi-Agent Pipelines in Claude Code [15]. The pattern that made Bootstrap work was refusing to teach every developer how to hand-configure a harness, and instead building a system that generates the configuration. The natural next step, the one we are prototyping now, is to treat that generated configuration as declarative state: a schema you can validate, a plan you can review, a harness you can apply, diff, and roll back. We are not ready to make promises about a ship date, and we would rather the argument stand on its own than lean on a product. The category needs to exist whether or not we are the ones who fill it.
Figure 8 - The directory is the state: The .claude/ directory already holds the entire harness as plain files, agents, hooks, skills, commands, settings, and the orientation document. It is already in git. What is missing is the layer that treats the whole directory as one declarative resource with a schema, a plan, and drift detection, rather than a folder that three engineers edit independently.
Whoever writes the schema first sets the standard
There is a strategic edge to all of this that is worth naming. HashiCorp did not win the cloud infrastructure layer because Terraform was the only tool that could provision a server. It won because HCL, its configuration language, became the shared standard that everyone else had to interoperate with. Standards accrue to whoever ships an opinionated, open specification early, before the space fragments into five incompatible formats that nobody can reconcile.
The harness layer is at exactly that pre-standard moment. Today the empty cell is empty. The risk is not that it stays empty forever. The risk is that it fills with a handful of mutually incompatible YAML dialects, each locked to a different vendor’s hosted runtime, and teams end up rewriting their harness definition every time they change agents. The opportunity is an opinionated, vendor-neutral, open schema for local harness state, shipped early enough to become the thing the others interoperate with.
Even if a model vendor ships official local-harness tooling tomorrow, and one of them eventually will, the layer they cannot own is the cross-harness one. A vendor’s IaC will always describe a vendor’s harness. The durable position is the neutral schema that describes any harness, the way HCL describes any cloud. That is the cell worth filling.
Conclusion
The harness is where the engineering lives, and the industry has already said so out loud. Google frames the harness as versioned infrastructure owned by named engineers [1]. The Agent Skills open standard made skill packaging portable across vendors [4]. Archon made workflow orchestration reproducible [3]. Pi proved that whole-harness state can be package-managed code rather than a folder of dotfiles [13][14]. Google’s own CI/CD extension proved that a harness bundle with skills, an MCP server, a knowledge base, and evals can ship as one versioned unit and run inside a harness it was not built for [12]. Every piece of the argument is already on the table.
What is missing is one specific tool: vendor-neutral, operating on the local .claude/ filesystem, offering plan, apply, diff, and drift detection over the whole harness as declarative state. Declarative infrastructure for hosted agents exists, in AWS-locked form with Bedrock AgentCore [7][8] and in unofficial single-vendor form with the community Anthropic provider [11]. The intersection that would actually solve the three-engineers-three-laptops problem, the local, neutral, full-primitives cell, is empty.
For teams running Claude Code at scale, the practical takeaway does not wait for a product. Put the .claude/ directory under real version control, review harness changes in pull requests the way you review code, and treat any hand edit to a running harness as drift to be reconciled rather than a convenience to be tolerated. The tooling will come. The discipline can start now. Whoever writes the opinionated, open schema for harness state first will set the standard the rest of the layer has to speak.
The Series
This is Part 3 of the 3-part Harness Architecture & Security sub-series:
- The Pi Comparison: What Claude Code’s Open-Source Rival Reveals About Harness Design. What an open-source competitor teaches about how a harness should be structured.
- Delete the Bash Tool: Five Levels of Agentic Security. A graduated model for locking down what an agent is allowed to execute.
- Your Agent Harness Belongs in Git: The Case for Declarative Harness State (this article). Why whole-harness state is the empty cell in the harness-as-code stack, and what plan, apply, diff, and drift should fill it with.
References
[1] A. Osmani, S. Saboo, and S. Kartakis, “The New SDLC With Vibe Coding,” Google, 2026. https://addyosmani.com/blog/new-sdlc-vibe-coding/
[2] A. Osmani, S. Saboo, and S. Kartakis, “The New SDLC With Vibe Coding,” Kaggle Whitepaper, 2026. https://www.kaggle.com/whitepaper-the-new-SDLC-with-vibe-coding
[3] C. Medin, “Archon,” GitHub, 2026. https://github.com/coleam00/Archon
[4] Anthropic, “Equipping agents for the real world with Agent Skills,” Anthropic Engineering Blog, Dec 2025. https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
[5] HashiCorp, “Introducing HashiCorp Agent Skills,” HashiCorp Blog, 2026. https://www.hashicorp.com/en/blog/introducing-hashicorp-agent-skills
[6] Pulumi, “Pulumi Agent Skills,” Pulumi Blog, 2026. https://www.pulumi.com/blog/pulumi-agent-skills/
[7] Amazon Web Services, “Amazon Bedrock AgentCore harness is now generally available,” AWS Machine Learning Blog, 2026. https://aws.amazon.com/blogs/machine-learning/amazon-bedrock-agentcore-harness-is-now-generally-available-go-from-idea-to-production-grade-agent-in-minutes/
[8] Amazon Web Services, “AgentCore: new features to build agents faster,” AWS What’s New, Apr 2026. https://aws.amazon.com/about-aws/whats-new/2026/04/agentcore-new-features-to-build-agents-faster/
[9] Anthropic, “Scaling Managed Agents: Decoupling the brain from the hands,” Anthropic Engineering Blog, 2026. https://www.anthropic.com/engineering/managed-agents
[10] Anthropic, “Claude Managed Agents: get to production 10x faster,” Claude Blog, Apr 2026. https://claude.com/blog/claude-managed-agents
[11] andasv, “Terraform provider for Anthropic Claude Managed Agents,” Terraform Registry, 2026. https://registry.terraform.io/providers/andasv/anthropic-claude-managed-agents/latest/docs
[12] H. Choudhry and Y. Ganashakran, “Accelerate CI/CD with Coding Agents,” Google Cloud, 2026. https://www.youtube.com/watch?v=lRcMin582KI
[13] M. Zechner, “Pi,” GitHub, 2026. https://github.com/badlogic/pi-mono
[14] M. Zechner, “Pi Extensions,” Pi Documentation, 2026. https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md
[15] G. Dotzlaw, K. Dotzlaw, and R. Dotzlaw, “Multi-Agent Pipelines in Claude Code: Researcher, Architect, Developer, Reviewer,” 2026. /insights/claude-code-03-multi-agent-pipelines/
Building production AI, or modernizing a legacy system?
That is the kind of work we do at Dotzlaw Consulting. Book a free 20-minute intro call and tell us what you are trying to build, or what is slowing you down.