stage

Syntax

stage <name>:
  goal: …

What it does

One step of a pipeline. A stage's body is an ordinary loop — it takes the same lines a top-level loop takes (goal, done when, look at, gates, each cycle, transitions) — so a single stage is a single story with its own self-correcting cycle.

Reach for stages when an epic is too big to verify in one done when. Splitting it into stages gives each story its own checkable finish line, and the pipeline runs them in order: a stage that ends unsatisfied halts the ones after it, so a broken foundation never lets later work pile on top of it. That ordering is the whole point — it keeps a large piece of work honest one verifiable step at a time instead of one giant, unverifiable leap.

Config cascades down to a stage. A file-level each cycle:, models:, or git: block is the default for every stage; the stage overrides just itself by writing its own line. A stage-level git: or models: block lands on that stage's loop only. Put human gates on the risky stages — a human approves before … blocks that stage until someone signs off, which is where deploys and migrations belong.

Example

stage "story: email and password login":
  goal: users log in with email and password
  look at: src/auth/, docs/architecture.md
  done when "pnpm test auth/login" passes
  after 8 tries: stop and warn "login story stuck"

Example — two stages in order

pipeline "epic: checkout v2":

  stage "story: cart totals":
    goal: cart shows correct totals with tax
    look at: src/cart/, src/tax/
    done when "pnpm test cart" passes
    when it fails: reflect, then plan again

  stage "story: checkout submit":
    goal: order submits and payment is captured
    a human approves before charging the card
    done when "pnpm test checkout" passes

Common mistakes

• A stage outside a pipeline. Stages only exist inside a pipeline — a bare stage at column 0 won't parse. An epic is a pipeline; each story is a stage under it.
• A stage with no done when. A stage's body is a loop, and a loop needs a checkable finish line. Without one the pipeline can't tell the story is done and can't safely advance to the next stage.
• Wrong indentation. pipeline sits at column 0, each stage is indented under it, and the stage's own body indents another level. Mixing levels reparses your stage lines as pipeline lines.
• Ordering hazards left ungated. Stages run top to bottom and a failure halts the rest — so put the irreversible work (a migration, a deploy) behind a human approves before … rather than letting it run unattended just because an earlier stage went green.

Related