.pipeline/config.yml

.pipeline/config.yml is checked into your repo and read on every run. This page documents the user-facing blocks and what each knob does. The file is scaffolded with documented defaults the first time you run Pipemason in a repo.

domains

Lists the domains present in the repo. A domain is enabled only if it appears here and has a matching entry under commands. The enabled domains determine which agents are eligible to run, so an api-only repo never ships mobile, cloud, or game work.

domains:
  - api
  # - web
  # - mobile
  # - db
  # - cloud

commands

Per-domain commands Pipemason invokes for that domain's gates. Each domain accepts test, lint, typecheck, run, build (and domain-specific keys such as e2e, coverage, or migrate). A missing key disables the corresponding gate for that domain — for example, omit lint and no lint gate runs.

commands:
  api:
    test: "npm test"
    lint: "npm run lint"
    typecheck: "npm run typecheck"
    run: "npm run dev"
    coverage: "npm run test:coverage"

For monorepos that put several stacks under one domain, a services: map lets each service declare its own path and commands; Pipemason then fans the domain out per service.

branch

Controls how Pipemason names the branches it creates. pattern is a template rendered from placeholders: {type}, {description}, {ticket}, {story}, {epic}, {program}, and {user}. Empty placeholders collapse, dangling separators are cleaned up, and the result is sanitized to a valid git ref. types defines the available branch types: the first entry is the default, and a later entry whose keyword appears in the run input (word-boundary, case-insensitive) wins. base selects the base branch (auto probes the repo's default), and max_slug_length caps the generated description fragment.

branch:
  base: auto
  pattern: "{type}/{description}"
  types:
    - name: feature        # first entry is the default
      keywords: []
    - name: bug
      keywords: [bug, fix, hotfix, regression]
  max_slug_length: 60

Note

Program and stacked runs append the story id automatically when {story} is absent from the pattern, so stacked branches never collide.

fan_out

Opt-in per-acceptance-criterion parallelism for the listed phases. When enabled, Pipemason partitions the test plan by (domain, acceptance criterion) and runs one worker per shard, up to max_per_phase concurrently. Cells with fewer than min_rows_for_fanout rows fold together rather than spawning a tiny worker.

fan_out:
  enabled: false
  min_rows_for_fanout: 3
  max_per_phase: 6
  phases: [tdd, e2e]

retry_tier_downshift

On by default. When a phase fails with a mechanical failure class in the allowlist (lint, typo, format), the retry runs at the cheaper target_tier instead of re-burning the original tier. It never applies to reasoning failures such as contract violations, security findings, or plan drift, regardless of the allowlist.

retry_tier_downshift:
  enabled: true
  failure_classes: [lint_error, typo, format_error, test_filename_mismatch]
  target_tier: haiku

plan_then_execute

Opt-in two-wave dispatch for implementation leads. When enabled, a cheaper planner writes a plan first and a stronger executor follows it; if the executor cannot follow the plan it reports plan drift and Pipemason re-plans. agents selects which lead agents the split applies to.

plan_then_execute:
  enabled: false
  agents: ["*-lead"]

cost_controls

On by default. Per-spawn guardrails that bound what any single agent can spend, plus a model-tier ceiling for the whole run:

max_budget_usd_per_spawn — a spawn that would exceed this dollar amount fails fast.
max_turns_per_spawn — caps turns so a runaway loop can't spin forever.
max_model_tier — the tier ceiling for the run. The ladder is haiku < sonnet < opus < fable. The default opus ceiling clamps fable down unless you raise it.

cost_controls:
  enabled: true
  max_budget_usd_per_spawn: 8
  max_turns_per_spawn: 100
  max_model_tier: opus

Note

The --max-tier CLI flag overrides the ceiling per run; the runner uses whichever ceiling is more restrictive. The program-wide spend ceiling is separate — pass --max-cost / --max-daily-cost to pipemason program start.

monitor_windowing

On by default. Runs the per-story orchestration one phase per fresh session instead of one long-lived session whose context grows across all phases, which keeps cost bounded on large runs. max_windows is a hard cap per story. It is safe by degradation: if more than one phase runs in a window the loop simply continues. Set enabled: false to force the legacy single-session behavior.

monitor_windowing:
  enabled: true
  max_windows: 30

accessibility

On by default. Shifts accessibility checks left across the pipeline. enabled is the single source of truth: when true, per-story accessibility criteria and the verify-time conformance gate both block on failures; when false, they revert to advisory. standards selects the target standards (wcag-2.2-aa, section-508, en-301-549), vpat emits a VPAT/ACR at the end of a program, and domains lists the UI domains that get the upstream accessibility agent and gate.

accessibility:
  enabled: true
  standards: [wcag-2.2-aa, section-508, en-301-549]
  vpat: true
  domains: [web, mobile, game-mobile, game-rn]