Blueprints: Scoped Agent Environments for Every Workflow

You have a project with twelve agents, eight skills, and a stack of rules built up over weeks. Most of the time, you only need three of those agents and two of those skills. The rest is noise — context pollution that makes your agent slower, more confused, and more expensive to run.

Blueprints fix this. A blueprint is a named subset selector that tells the xcaffold compiler exactly which resources to include in a given compilation run. Everything else is excluded from the output.

What a Blueprint Is

A blueprint lives at xcaf/blueprints/<name>/blueprint.xcaf — a standalone file, separate from your project definition. It declares which agents, skills, rules, workflows, contexts, and MCP servers to include when you compile with --blueprint.

Here is a minimal example:

kind: blueprint
version: "1.0"
name: backend-build

description: "Focused backend development with security enforcement"
agents:
  - backend-dev
  - code-reviewer
skills:
  - golang-tools
  - db-access
  - test-runner
rules:
  - security-mandate
  - commit-standards

Your project.xcaf stays clean — it defines your project identity and targets, not resource lists:

kind: project
version: "1.0"
name: platform-api

description: "Core API service"
targets:
  - claude
  - cursor

Resources are discovered automatically from the xcaf/ directory tree. The blueprint just filters which of those discovered resources make it into the compiled output.

Running xcaffold apply --blueprint backend-build compiles only the listed resources for the configured targets. The architect agent, the adr-writing skill, and anything else not in the blueprint selector simply do not appear in the provider output directories.

The Extends Chain

Blueprints support single-parent inheritance through the extends field. A child blueprint inherits all resource selectors from its parent, then adds or overrides its own.

kind: blueprint
version: "1.0"
name: architecture-review

description: "Full architecture exploration mode"
extends: backend-build
agents:
  - architect
  - tech-lead
skills:
  - system-design
  - adr-writing
rules:
  - api-conventions
  - data-access

The compiler resolves the chain before compilation. Since architecture-review extends backend-build, the final resource set is the union of both:

backend-build
  agents: [backend-dev, code-reviewer]
  skills: [golang-tools, db-access, test-runner]
  rules: [security-mandate, commit-standards]

architecture-review (extends backend-build)
  agents: [backend-dev, code-reviewer, architect, tech-lead]
  skills: [golang-tools, db-access, test-runner, system-design, adr-writing]
  rules: [security-mandate, commit-standards, api-conventions, data-access]

Lists are concatenated and deduplicated. Singleton selectors like settings and hooks use the child-most value — the child overrides the parent.

This is transitive. If backend-build extends security-base, and architecture-review extends backend-build, the compiler walks the full chain. A security-focused base blueprint propagates its constraints to every descendant without requiring each blueprint to redeclare them.

Building Good Blueprints

The most useful blueprints are scoped to a work context, not a role. The difference matters.

A "backend engineer" blueprint is role-scoped — it describes a person. A "backend API workflow" blueprint is context-scoped — it describes a phase of work where you need fast code generation, reliable test patterns, and strict security constraints, but you do not need the full architectural advisory stack.

Context-scoped blueprints tend to have three components:

A solo developer building a side project benefits from context-scoped blueprints just as much as a larger team does. When you are deep in a backend build session, you do not want your agent offering frontend component advice. When you shift to documentation mode, you do not want the test runner skill consuming context window.

Switch the blueprint, switch the environment:

# Morning: backend feature work
xcaffold apply --blueprint backend-build

# Afternoon: documentation pass
xcaffold apply --blueprint docs-mode

Each invocation produces a clean compilation with only the resources relevant to the current task.

Multi-Provider Output

Blueprints compose naturally with xcaffold's multi-provider compilation. When your project targets multiple providers, the blueprint filters resources first, then the compiler emits output for each target.

kind: blueprint
version: "1.0"
name: review-mode

description: "Code review with minimal agent surface"
agents:
  - code-reviewer
skills:
  - review-checklist
rules:
  - commit-standards
  - api-conventions
targets:
  - claude
  - cursor

The targets field on a blueprint is optional. When present, it restricts the blueprint to only those providers — useful when a workflow is specific to a single editor or environment. When omitted, the blueprint inherits the project-level targets.

Running xcaffold apply --blueprint review-mode generates provider-native configurations for both Claude Code and Cursor, but only containing the code-reviewer agent, the review-checklist skill, and the two enforcement rules. The output is minimal, focused, and validated against the xcaffold schema before it hits disk.

Directory Structure

Here is what a project with multiple blueprints looks like on disk:

xcaf/
  agents/
    backend-dev/
      agent.xcaf
    code-reviewer/
      agent.xcaf
    architect/
      agent.xcaf
  skills/
    golang-tools/
      skill.xcaf
    test-runner/
      skill.xcaf
    system-design/
      skill.xcaf
  rules/
    security-mandate/
      rule.xcaf
    commit-standards/
      rule.xcaf
  blueprints/
    backend-build/
      blueprint.xcaf
    architecture-review/
      blueprint.xcaf
    docs-mode/
      blueprint.xcaf
  context/
    project-context/
      project-context.xcaf

Each resource lives in its own directory under xcaf/. Blueprints follow the same convention — xcaf/blueprints/<name>/blueprint.xcaf. The filesystem is the schema. There is no central manifest file that lists resources; xcaffold discovers them by walking the directory tree.

When to Skip the Blueprint

If your project has three agents and two rules, you probably do not need blueprints. Run xcaffold apply without the --blueprint flag and every discovered resource compiles into the output.

Blueprints become valuable when your xcaf/ directory grows past the point where every resource is relevant to every task. That threshold is different for every developer and every project, but the mechanism is there when you hit it.

Blueprints are subset selectors, not starter kits. They participate in the full xcaffold compilation pipeline — schema validation, inheritance resolution, and multi-provider output. They scope your agent environment to exactly what the current workflow demands, and they do it in a single command.