Best Practices

Targeted recommendations for when to use specific patterns within xcaffold. Each guide is grounded in the actual compiler, parser, and schema — not generalized advice. All patterns follow the Harness-as-Code principle: the .xcaf manifest is the source of truth, and compiled output is never edited directly.

• Project Structure — From quickstart flat files to domain-driven structures for large teams.
• Workspace Context — Using kind: context to anchor agent awareness without polluting every interaction.
• Skill Organization — The required subdirectory layout, when to use references/, scripts/, assets/, and examples/.
• Blueprint Design — Opt-in resource subset selection for large projects, CI pipelines, and specialized workflows.
• Policy Organization — Writing kind: policy constraints with the correct target, match, require, and deny fields.
• Agent Design Patterns — Specialized agents, composition with skills and rules, tool scoping, and per-provider overrides.
• Rule Organization — Activation modes, path-scoped rules, provider fallback behavior, and file layout patterns.
• Variables and Overrides — Injecting shared values with variable files and customizing resources per provider with override manifests.
• Multi-Target Compilation — Managing a single manifest set that compiles to multiple providers, with fidelity notes and target scoping.