pipeline

Syntax

pipeline "<name>":
  stage <name>: …

What it does

Sequences stages and runs them in order — each stage runs only if the one before it passed, and a failing stage halts the rest (fail-fast). Every stage's body is a loop: it has its own goal, its own done when, and its own back-edge, so the pipeline is really a chain of self-correcting loops with a shared thread of progress. The natural mapping is the reason it exists: an epic → a pipeline, each story → a stage. When a job is too big to verify with a single check, you don't write one giant loop — you break it into ordered stories, each with a check it can pass on its own.

Reach for a pipeline when the work has real ordering constraints: a security scan must pass before you build, the build must be green before a human approves the UI, the deploy runs last. Fail-fast keeps a broken early stage from wasting cycles on everything downstream, and per-stage human gates (a human approves before …) let you put a hard stop in front of the risky steps only. A pipeline needs at least one stage; the pipeline keyword sits at column 0 and each stage is indented under it with its own body indented again. For unordered work that can run at once, an inner stages in parallel: block runs its stages concurrently instead.

Example

pipeline "ship feature":
  stage security:
    goal: no high or critical vulnerabilities
    done when "semgrep --severity=high" finds nothing
  stage build:
    a human approves the plan first
    goal: feature works and tests pass
    done when "pnpm test" passes

How it runs

Example — a gated deploy at the end

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

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

Common mistakes

• A pipeline with no stages. A pipeline needs at least one stage — the pipeline is just the ordering; the stages hold the goals and checks. An empty pipeline won't parse.
• A stage missing its own done when. Each stage is a loop and needs a way to verify itself. A stage with a goal but no check can't confirm it passed, so fail-fast can't decide whether to proceed.
• Reaching for a pipeline when the steps are independent files. If each step runs a whole separate .loop file, that's a flow, not a pipeline. Use a pipeline for stages inside one epic; use a flow to chain files.
• Indentation drift. pipeline at column 0, each stage indented two spaces, the stage body indented again. Mixed depth is the usual parse failure — check with loop-run show.

Related