Schemas

A schema is the YAML file that describes a workflow: the artifacts a blueprint produces, the phases that drive it, and the pipeline that ties phases together. Every blueprint records the schema it uses in its .contractor.yaml, and contractor ships two:

• contractor-base — the full workflow with proposal → requirements + design → tasks, parallel review, and a gate before close. The default if a blueprint does not specify a schema.
• contractor-lite — a slimmer workflow with brief → tasks and a single-agent review, for small changes that don't earn the full proposal/requirements/design ceremony.

Shipped schemas live under packages/cli/schemas/<name>/schema.yaml. The dashboard's schema viewer reads them and lets users fork a shipped schema into their own copy under ~/.contractor/schemas/<name>/ (see the dashboard schemas page for the fork mechanics — those details live in the dashboard docs, not here).

Choosing a schema

contractor blueprint new <name> reads the schema flag (or falls back to contractor-base) and writes it into the blueprint's .contractor.yaml. Use contractor-base when:

• The change is non-trivial enough to deserve a why/what proposal.
• Behavior changes need explicit, testable requirements.
• A reviewer (or your future self) will want to read the design rationale months later.

Use contractor-lite when:

• The change is one or two task-groups.
• A one-page brief captures everything a reviewer needs to know.
• The full requirements/design ceremony would cost more than the change itself.

If a contractor-lite change starts growing, stop and reach for contractor-base instead — the two artifacts in contractor-lite (brief, tasks) cannot represent multi-capability deltas.

What a schema.yaml declares

A schema has three top-level sections: artifacts, phases, and pipeline.

artifacts

Each artifact is a node in the dependency graph. It declares:

• id — kebab-case identifier.
• generates — the file path (or glob, e.g. requirements/**/*.md) the artifact produces inside a blueprint directory.
• description — short prose for status output.
• template — the template file (under templates/ next to the schema) that scaffolds the artifact.
• instruction — the agent prompt for producing this artifact in the propose phase.
• requires — list of artifact ids this one depends on; the dependency graph is built from these edges.

The contractor-base artifacts form a diamond: proposal (no deps) → requirements and design (both depend on proposal, neither depends on the other) → tasks (depends on both).

phases

Phases are the units a pipeline executes. Each phase declares:

• id — the step id used by the pipeline (e.g. propose, implement, review, close).
• strategy — one of the named strategies (artifact-loop, task-group-implement, parallel-agents, agent, rebase-review). The strategy decides how the phase fans out at runtime.
• tracks — for phases that drive an artifact (e.g. tasks.md for implement).
• instruction — the agent prompt that wraps the strategy's output.
• agents — for parallel-agents phases, the list of sub-agents (each with its own id and instruction).
• namespace — the slash-command namespace (e.g. contractor) when the phase is exposed as a static command.

Phases also generate slash commands: contractor ai install writes one per phase under .claude/commands/blueprint/.

pipeline

The pipeline lists the steps contractor run executes by default for blueprints on this schema. Each step is one of:

• A phase reference: { phase: "implement", critical: true, model: "opus[1m]", needs_prepared_worktree: true }. Resolves to an agent step that calls the phase's slash command.
• A kind: shell step: { kind: "shell", command: "pnpm test", critical: true, when: "scope" }. Runs an arbitrary shell command (with {{scope}} substitution).
• A kind: gate step: { kind: "gate", description: "Review changes before continuing to close" }. Pauses for user approval — see Gates.

contractor-base ships with implement → review → gate → close (the gate is implicit at the boundary; close is non-critical so a rejected gate ends the run cleanly).

The needs_prepared_worktree flag

Any agent or shell step in a pipeline may set needs_prepared_worktree: true. Both shipped schemas set it on the implement phase. When the runner reaches a flagged step, it consults the per-worktree prepare marker and, if invalid or missing, injects a synthetic prepare step before the scheduled one. See Worktrees for the full mechanics.

Forking a schema

When a shipped schema is close to what you want but not exact, fork it from the dashboard. Forks copy the schema into ~/.contractor/schemas/<name>/ and become editable from the schema detail page. Forked schemas appear alongside shipped ones in the schema list, and any blueprint can reference one by name in its .contractor.yaml.

Forking is a dashboard concern; the on-disk fork lives in the user's home directory and is consumed by the CLI like any other schema. The CLI does not provide a fork command today — author the directory by hand or use the dashboard.