The Uncompiled Agent Problem

Here is a scenario that plays out in codebases every week. A developer spends a few hours crafting the perfect agent configuration. They get the system prompt right, wire up the correct tools, and their Claude Code agent finally behaves exactly as intended. They commit .claude/ to the repository and move on.

Three weeks later, someone tweaks the agent's markdown file to fix a "small wording issue." Two weeks after that, someone adds a new tool reference. Six weeks later, the agent that worked perfectly on day one is producing inconsistent results — and nobody can tell you when or why it changed.

This is the uncompiled agent problem.

The Core Asymmetry

Modern software engineering treats source code with deep discipline. We have compilers that reject invalid inputs, type systems that enforce contracts, and CI pipelines that verify behavior. None of these protections exist for AI agent configurations.

A .claude/agents/backend-dev.md file is a plain markdown document. Any developer with write access can open it in any text editor and change it. There is no schema validation, no drift detection, and no compilation gate standing between a typo and your production agent's behavior.

What a Drift Event Looks Like

Consider the anatomy of a subtle but damaging configuration drift.

A developer defines an agent at xcaf/agents/code-reviewer/agent.xcaf with model: sonnet and tools: [Read, Glob, Grep]. This agent is meant to be a read-only code reviewer — it should never modify files or execute commands.

Six weeks later, someone opens .claude/agents/code-reviewer.md directly — the compiled output file — and adds Bash and Edit to the tools list, reasoning that "removing the restriction would speed it up."

The agent now has access to Bash. Nobody notices for weeks because it still produces code review comments. Then, during an agentic session, it starts running commands and editing files.

The dangerous pattern: The symptom looks like model misbehavior. The root cause is in an unmanaged configuration file. Developers report bugs upstream instead of looking at their own provider directories.

The Infrastructure-as-Code Analogy

The infrastructure-as-code movement solved this exact pattern for cloud resources.

In the 2000s, developers configured servers by hand. An EC2 instance would accumulate small manual changes over months until nobody could reliably reproduce its configuration. Terraform solved this by inverting the model: you declare your desired state in code, and the tool compiles it into cloud API calls. The cloud resources become build output. You never directly edit an EC2 instance — you edit the .tf file, run terraform apply, and the tool reconciles the declared state with reality.

xcaffold applies this exact model to AI agent configurations. Your .xcaf source files declare what your agents, rules, and skills should look like. The compiler handles the rest.

Start with a project manifest that declares which providers you target:

kind: project
version: "1.0"
name: platform-api
targets:
  - claude
  - cursor

Then define each agent in its own file. Here is xcaf/agents/code-reviewer/agent.xcaf:

---
kind: agent
version: "1.0"
name: code-reviewer
description: Security-focused code reviewer.
model: sonnet
tools: [Read, Glob, Grep]
rules: [security-mandate, owasp-top10]
skills: [security-review, dependency-audit]
---
Review the provided diff for correctness, style, and test coverage.
Focus on security vulnerabilities and dependency risks.
Never execute shell commands or modify files directly.

When you run xcaffold apply, this source file is compiled into the exact format each target provider expects:

.claude/
  agents/
    code-reviewer.md       <- generated, do not edit
  skills/
    security-review/
      SKILL.md
    dependency-audit/
      SKILL.md
  rules/
    security-mandate.md
    owasp-top10.md

The .claude/ directory is now build output. Just like you don't edit a compiled binary, you don't edit these files directly.

What This Unlocks

Once your agent configuration is managed by a compiler, capabilities become available that were previously impossible with hand-maintained files.

SHA-256 integrity tracking. After each compilation, xcaffold writes a state manifest recording the hash of every generated file. Running xcaffold status recomputes these hashes and flags any file whose content diverged. If a developer manually edits .claude/agents/code-reviewer.md, the next status check surfaces it immediately:

$ xcaffold status

sandbox  ·  last applied 3 days ago

  PROVIDER       FILES   STATUS
  antigravity       28   ✓ synced
  claude            90   ✗ 1 modified
  copilot            1   ✓ synced
  cursor            54   ✓ synced
  gemini            55   ✗ 1 modified

  Sources  52 .xcaf files  ·  no changes since last apply

Drift detected in 2 providers:

  claude
    ✗  missing   CLAUDE.md  (root)

  gemini
    ✗  missing   GEMINI.md  (root)

→ Run 'xcaffold apply' to restore.

The tool checks byte-for-byte identity against the hash. A single changed character in an agent's system prompt causes a full hash mismatch. This is intentional: partial drift is still drift.

Multi-provider compilation. The same source files compile to five different target directories. One source of truth, five consistent outputs:

A developer working across multiple providers no longer maintains parallel configuration directories by hand. Change the .xcaf source, run xcaffold apply, and every provider directory updates in lockstep.

The import path. Adopting xcaffold for an existing project doesn't require starting from scratch. xcaffold import scans existing provider directories — auto-detecting which providers are present — and reverse-engineers them into .xcaf source files under xcaf/. From that point forward, you have an authoritative source of truth. Run xcaffold apply, and the compiler regenerates the provider directories from managed source.

The Separation That Matters

The files in your provider directories haven't changed. What has changed is who is responsible for them. The answer is now: the compiler. Not whoever has a text editor open.

Agent configuration drift is not a people problem. It is an architecture problem. The solution is the same one the industry found for infrastructure: compile it, validate it, and treat the output as build artifacts that nobody touches manually.