Skip to content

Multi-story program

A program turns a single high-level intent into a whole system. Pipemason decomposes the intent into a dependency graph of stories, then runs the full per-story pipeline once per story, in order.

When to use a program

Reach for a program — rather than a single pipemason start — when the work spans multiple features or domains that depend on each other: an API plus a web client plus a mobile app, for example. A single run is for one feature; a program coordinates many.

Start a program

Describe the system you want and pick the greenfield mode for building from scratch:

pipemason program start "build a Linear-style issue tracker with API + web + mobile" \
  --mode greenfield-system

Pipemason first produces a plan: a roadmap of stories arranged as a directed acyclic graph (the DAG), where each edge is a dependency. Greenfield programs also establish a shared design system before story work begins, so the domains stay visually and structurally consistent.

Note

Use --mode greenfield-mobile for a net-new mobile or game app plus a minimum-viable backend. For changing an existing system, see the Brownfield upgrade guide.

Track the DAG

At any point, inspect the roadmap and how far each story has progressed:

pipemason program status

This prints the program roadmap and the DAG's progress — which stories are complete, in flight, blocked, or waiting on a dependency.

Advance the program

A program walks the DAG and runs each ready story. To advance it to the next step — for example after resolving an escalation, or to continue a paused program — use:

pipemason program resume

Stories run in dependency order. Each one drives the same per-story pipeline you saw in Your first run, so every story gets its own spec, tests, gates, and commits.

Branch strategy

By default a program uses stacked pull requests: each story lands on its own branch stacked on the story it depends on, so reviewers see focused, reviewable diffs that build on one another. If you'd rather keep everything on one integration branch, switch strategies at start:

pipemason program start "..." --mode greenfield-system \
  --branch-strategy program-branch
  • stacked PRs (default) — one branch and PR per story, stacked.
  • program-branch — all stories accumulate on a single program branch.

Typical flow

  1. Start the program with an intent and a greenfield mode.
  2. Review the generated roadmap with pipemason program status.
  3. Let it iterate; resume with pipemason program resume as needed.
  4. Resolve any escalation a story raises, then resume.
  5. Review the stacked PRs as stories complete.