What is xcaffold
xcaffold is a Harness-as-Code toolchain — declare your agent configuration once in .xcaf manifests, compile to any provider's native format, detect drift, and enforce policy.
Every AI coding tool ships its own configuration format and directory structure. Use multiple tools and you maintain separate configuration trees that drift from each other silently. When someone updates the rules in one, the others are forgotten.
xcaffold solves this with a single source of truth: .xcaf manifests that compile deterministically into native configuration for any supported provider. Add a new provider — xcaffold handles the translation. No manual migration, no format-specific maintenance.
The compilation pipeline
xcaffold follows a deterministic pipeline:
- Author — declare agents, skills, rules, hooks, MCP servers, and policies in
.xcafmanifests underxcaf/ - Compile —
xcaffold applytranslates each manifest into the native format of every target provider - Verify —
xcaffold statusdetects manual edits to compiled output via SHA-256 hashes - Enforce —
xcaffold validateevaluates policy constraints before compilation
Providers are pluggable. The architecture is open — adding a target requires implementing two Go interfaces. The .xcaf schema stays the same regardless of how many providers you target.
What it manages
xcaffold has two categories of .xcaf resources.
Provider kinds — the agent harness
These compile into native output files inside each target provider's directory. They are the actual agent configuration that providers consume.
| Kind | Purpose |
|---|---|
agent | Identity, system prompt, model selection, tool declarations |
skill | Reusable capability modules with scoped tool access |
rule | Constraints and standards enforced at the provider level |
hooks | Lifecycle hooks — pre/post tool use, session events |
mcp | MCP server declarations and connection configuration |
memory | Persistent memory definitions |
settings | Provider-level permissions and behavior settings |
context | Workspace context declarations |
workflow | Multi-step agent procedures |
Xcaffold kinds — compiler governance
These govern the compiler itself. They are evaluated at compile time but produce no output files in provider directories.
| Kind | Purpose |
|---|---|
project | Project metadata, targets, and test configuration |
policy | Compile-time constraints; violations block xcaffold apply |
blueprint | Resource subset selectors for multi-environment targeting |
global | Shared defaults inherited across projects via extends: |
Core commands
| Command | What it does |
|---|---|
xcaffold init | Scaffold a new project |
xcaffold import | Import existing provider config into .xcaf |
xcaffold apply | Compile .xcaf manifests to provider-native output |
xcaffold status | Detect drift in compiled output |
xcaffold validate | Check schema, references, and policy compliance |
xcaffold graph | Visualize resource scope and dependencies |
xcaffold list | List all declared resources |