Concepts

Understanding-oriented explanations of xcaffold's architectural and philosophical foundations. These documents explain why the system is designed the way it is — not how to use it.

xcaffold is an Agent Configuration Management toolchain that implements the Harness-as-Code approach — declaring the complete agent harness in version-controlled .xcaf manifests and compiling deterministically to native provider formats.

Architecture

• Core Architecture — The one-way deterministic compiler architecture.
• Translation Pipeline — How .xcaf manifests move from discovery to provider output.
• Intermediate Representation — The BIR (Blueprint Intermediate Representation) graph.
• Multi-Target Rendering — How the AST compiles to different provider formats.
• Provider Architecture — The ProviderImporter and TargetRenderer interfaces.

Configuration

• Configuration Scopes — Project, Agent, and Skill scoping isolation.
• Declarative Compilation — The manifest-driven approach to agent configuration.
• Project Variables — Cross-file value reuse and environment configuration.
• Field Classification Model — Two-layer classification of resource fields.
• Layer Precedence — Understanding the target resolution hierarchy.

Execution

• Agent Memory — Understanding the durable, agent-scoped context model.
• State & Drift Detection — How xcaffold tracks compilation output and detects manual edits.

Next Steps

• Tutorials — learning-oriented, step-by-step guides
• Tutorials — task-oriented guides for specific operations
• Reference — full schema reference and CLI command reference