.contractor.yaml

Every blueprint directory contains a .contractor.yaml describing the schema, scope, lifecycle stage, and base branch for that blueprint. The file is validated against BlueprintMetadataSchema in packages/cli/src/lib/artifact-graph/types.ts, and is written by contractor blueprint new and updated by lifecycle commands like contractor blueprint ready.

.contractor.yaml is blueprint-level, not project-level — in particular, the schema field lives here, not in contractor/config.yaml. A repo with multiple active blueprints can run different schemas in each.

Schema

{
  schema: string;        // default: "contractor-base"
  scope?: string;
  description?: string;
  pipeline?: string;
  lifecycle: "propose" | "implement"; // default: "implement"
  baseBranch?: string;
}

A missing or unparseable file falls back to defaults derived from the Zod schema (schema: "contractor-base", lifecycle: "implement").

Fields

schema

The schema this blueprint runs against. Resolved by resolveSchema(name, contractorDir), which checks bundled schemas (contractor-base, contractor-lite) and any user-fork schemas under ~/.contractor/schemas/<name>/. Defaults to contractor-base.

schema: contractor-base

This is a blueprint-level field. Each blueprint records its own schema, so two active blueprints in the same repo can use different schemas. There is no project-wide override — contractor blueprint new --schema <name> writes the chosen schema into the new blueprint's .contractor.yaml and stops there.

scope

Optional scope name validating against contractor/config.yaml.scopes. When set, the value is substituted into {{scope}} placeholders in pipeline kind: shell steps and gates when: scope step guards on (see Using scopes).

scope: cli

contractor blueprint new --scope <name> writes this field at creation time. The implement agent's preamble also tells the agent to focus its changes within the scoped subfolder.

description

Optional one-line description shown in contractor blueprint list output and in the dashboard's blueprint cards. Useful when a kebab-case name does not convey intent.

description: Add resume support to contractor run.

pipeline

Optional pipeline name to run for this blueprint, overriding contractor/config.yaml.pipeline. Resolved against the project pipelines map first, then the global pipelines map. An unknown name fails the run with Unknown pipeline "<name>". Available pipelines: ….

pipeline: fast-iteration

The full resolution chain is documented in Pipelines.

lifecycle

The blueprint's lifecycle stage. One of:

• propose — the blueprint is still being authored. The propose phase (artifact-loop) is the active phase; contractor run is not expected to run yet.
• implement — the blueprint is ready for contractor run. Set by contractor blueprint ready <name>.

lifecycle: implement

contractor blueprint new writes lifecycle: propose initially, and contractor blueprint ready <name> flips it to implement.

baseBranch

The branch the blueprint's worktree was created from. Used by contractor blueprint base <name> and consumed by the close phase (the squash-merge target). When unset, resolveBlueprintBaseBranch falls back to the repo's default branch (main or whatever git symbolic-ref refs/remotes/origin/HEAD points at).

baseBranch: develop

contractor blueprint new --base <branch> writes this field; otherwise it stays unset and the default-branch fallback applies.

A complete example

# contractor/blueprints/add-resume-support/.contractor.yaml
schema: contractor-base
scope: cli
description: Add --resume support to contractor run, including last-failed.
pipeline: fast-iteration
lifecycle: implement
baseBranch: main