contractor/config.yaml

Project-level configuration accepted by ProjectConfigSchema.

contractor/config.yaml is the project-level configuration file, validated against ProjectConfigSchema in packages/cli/src/lib/project-config.ts. Every field is optional — a missing file behaves the same as an empty one, and unknown keys are stripped.

Schema

{
  schema?: string;            // default: "contractor-base"
  context?: string;           // free-form prose shown to the agent during artifact creation
  rules?: Record<string, string[]>; // per-artifact rules (proposal, requirements, design, tasks, …)
  scopes?: string[];          // declared scopes, validated by `contractor blueprint new --scope`
  pipeline?: string;          // default pipeline name for this repo
  pipelines?: Record<string, PipelineDef>; // named custom pipelines
}

schema is also accepted at the project level for convenience, but it is overridden by every blueprint's .contractor.yaml schema: field — see .contractor.yaml.

Fields

`schema`

The default schema name for blueprints created in this repo (contractor blueprint new falls back to this when --schema is omitted). Blueprints record their schema in .contractor.yaml at creation, so changing this later only affects new blueprints.

schema: contractor-base

`context`

Free-form prose inlined into the agent's system prompt during artifact creation (proposal, requirements, design, tasks). Use it to teach the agent about repo-wide conventions that should not be re-derived every run.

context: |
  Tech stack: TypeScript 5, React 18, Node.js 20.
  We use Conventional Commits.
  Tests live alongside source (foo.ts + foo.test.ts).

`rules`

A map from artifact id to a list of bullet-point rules. The artifact ids match the schema's artifacts[].id. Rules are appended to the agent's prompt for that artifact, after context.

rules:
  proposal:
    - Keep proposals under one page.
    - Always list affected packages in the Impact section.
  tasks:
    - Each task should be completable in one focused session.
    - Group tasks by dependency, not by package.

`scopes`

A whitelist of scope names accepted by contractor blueprint new --scope and contractor run --scope. When set, an unknown scope is rejected with an error listing the declared scopes.

Scopes have two visible effects at run time:

The {{scope}} placeholder in any pipeline kind: shell step is substituted with the current scope.
A step with when: scope is skipped when the active blueprint has no scope.

scopes:
  - cli
  - protocol
  - web

See the using scopes guide for an end-to-end walk-through.

`pipeline`

The default pipeline name to run for blueprints in this repo, used by contractor run when neither --pipeline nor the blueprint's .contractor.yaml pipeline: field is set.

pipeline: fast-iteration

`pipelines`

A map of named pipeline definitions. The same shape is accepted at ~/.contractor/config.yaml.pipelines for user-level pipelines available across every repo on the machine; project pipelines win on name collisions.

Each pipeline has a description and an ordered steps list. Steps are one of three kinds — agent, shell, or gate. See Pipelines for the full step reference.

pipelines:
  fast-iteration:
    description: Implement and quick-review without close.
    steps:
      - id: implement
        kind: agent
        slashCommand: implement.md
        critical: true
        needs_prepared_worktree: true
      - id: review
        kind: agent
        slashCommand: review.md
        critical: false
 
  ship-it:
    description: Implement, review, and close in one pipeline.
    steps:
      - id: implement
        kind: agent
        slashCommand: implement.md
        critical: true
      - kind: shell
        command: pnpm test
        critical: true
      - id: review
        kind: agent
        slashCommand: review.md
        critical: true
      - kind: gate
        id: pre-close
        description: Review changes before closing.
      - id: close
        kind: agent
        slashCommand: close.md
        critical: false

Select a custom pipeline at run time with contractor run --pipeline <name>, or pin one to a blueprint with pipeline: in its .contractor.yaml.

A complete example

# contractor/config.yaml
schema: contractor-base
 
context: |
  pnpm monorepo with four workspace packages: cli, protocol, web, www.
  TypeScript ESM, Node >=18, vitest.
 
rules:
  proposal:
    - Capabilities section is the contract — list every requirement file.
  tasks:
    - Group by dependency. Each group commits independently.
 
scopes:
  - cli
  - protocol
  - web
  - www
 
pipeline: ship-it
 
pipelines:
  ship-it:
    description: Implement, scoped tests, review, gate, close.
    steps:
      - id: implement
        kind: agent
        slashCommand: implement.md
        critical: true
        needs_prepared_worktree: true
      - kind: shell
        command: pnpm --filter @soel/contractor-{{scope}} test
        when: scope
        critical: true
      - id: review
        kind: agent
        slashCommand: review.md
        critical: true
      - kind: gate
        id: pre-close
        description: Final review before close.
      - id: close
        kind: agent
        slashCommand: close.md
        critical: false

On This Page

Schema Fields schemacontextrulesscopespipelinepipelinesA complete example