schema.yaml

Schema authoring reference — artifacts, phases, and pipelines.

A schema lives at <schema-dir>/schema.yaml and is validated against SchemaYamlSchema in packages/protocol/src/types/schema.ts (re-exported from @soel/contractor-protocol so the web dashboard can validate the same content the CLI consumes). Bundled schemas live under packages/cli/schemas/<name>/schema.yaml; user forks live under ~/.contractor/schemas/<name>/schema.yaml.

This page is the field-by-field reference. For the conceptual overview (what a schema is, when to fork) see Schemas.

Top-level shape

{
  name: string;          // schema id, e.g. "contractor-base"
  version: number;       // default 1, advisory only
  description: string;   // shown in `contractor blueprint new` and the dashboard
  artifacts: Artifact[]; // at least one
  implement?: ImplementPhase;
  phases?: Phase[];
  pipeline?: SchemaPipeline;
}

A schema must declare at least one artifact. phases and pipeline are optional — a schema with only artifacts produces nothing executable, but still passes validation.

`artifacts`

Each artifact is a node in the dependency graph.

{
  id: string;
  generates: string;        // file path (or glob, e.g. "requirements/**/*.md")
  description: string;
  template?: string;        // template filename under <schema-dir>/templates/
  instruction?: string;     // agent prompt for producing this artifact in `propose`
  requires: string[];       // ids of artifacts this one depends on
}

requires is the edge set: contractor's artifact graph (buildArtifactGraph) walks these to compute topological order, dependencies, and dependents. validateArtifactGraph flags cycles, unresolved requires (an id that names no artifact), and unresolved phases[].tracks.

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document outlining the change
    template: proposal.md
    instruction: |
      Create the proposal document that establishes WHY this change is needed.
      ...
    requires: []
 
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      Create the task list that breaks down the implementation work.
      ...
    requires:
      - requirements
      - design

`phases`

Phases are the executable units a pipeline references.

{
  id: string;
  strategy: "artifact-loop" | "task-group-implement"
          | "parallel-agents" | "agent" | "rebase-review";
  instruction?: string;
  namespace: "blueprint" | "contractor"; // default "blueprint"
  tracks?: string;                       // artifact id this phase drives
  agents?: { id: string; instruction: string }[]; // required when strategy is parallel-agents
}

The strategy chooses how the phase is built into a slash command at install time and how it fans out at run time. See Strategies for what each one does.

tracks points at an artifact id whose state drives the phase (e.g. tasks for task-group-implement). validateArtifactGraph reports a unresolved-tracks problem when the named id does not exist.
namespace: contractor marks the phase as a static, repo-agnostic helper (e.g. propose); everything else namespaces under blueprint. See Slash commands.
agents is required when the strategy is parallel-agents and ignored otherwise.

phases:
  - id: implement
    strategy: task-group-implement
    tracks: tasks.md
    instruction: |
      Implement exactly the assigned task-group, mark its checkboxes, commit, and exit.
      ...
 
  - id: review
    strategy: parallel-agents
    instruction: Review changed files for reuse, quality, efficiency, and compliance.
    agents:
      - id: reuse
        instruction: Search for existing utilities that could replace newly written code.
      - id: quality
        instruction: Flag hacky patterns, parameter sprawl, and copy-paste duplication.

`pipeline`

The default pipeline contractor run executes for blueprints on this schema. Steps are one of three kinds — phase reference, shell, or gate.

Phase-reference step

{
  phase: string;
  critical?: boolean;       // default true
  model?: string;
  effort?: "low" | "medium" | "high" | "max";
  when?: "scope";           // skip when blueprint has no scope
  needs_prepared_worktree?: boolean; // default false
}

Resolves to an agent step that calls the named phase's slash command. Inherits the phase's instruction and strategy.

`kind: shell` step

{
  kind: "shell";
  command: string;          // supports {{scope}} substitution
  critical?: boolean;       // default true
  when?: "scope";
  needs_prepared_worktree?: boolean; // default false
}

Runs an arbitrary shell command in the worktree. The {{scope}} placeholder is replaced with the blueprint's scope at run time (or empty when unscoped — pair with when: scope to skip the step entirely).

`kind: gate` step

{
  kind: "gate";
  description: string;
  when?: "scope";
}

Pauses the pipeline and waits for a user decision. The description is shown in the dashboard's gate prompt. See Gates.

`needs_prepared_worktree`

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

Example

pipeline:
  steps:
    - phase: implement
      critical: true
      model: opus[1m]
      needs_prepared_worktree: true
 
    - kind: shell
      command: pnpm --filter @myorg/{{scope}} test
      when: scope
      critical: true
 
    - phase: review
      critical: true
      effort: medium
 
    - kind: gate
      description: Review changes before continuing to close.
 
    - phase: close
      critical: false
      effort: low

`implement` (legacy)

The top-level implement: block is an older shape used by some schemas to declare what the implement phase tracks. New schemas should declare an id: implement entry under phases: instead — both shipped schemas use the modern phase form. The block is preserved for compatibility:

{
  requires: string[];
  tracks?: string;
  instruction?: string;
}