pipemason

concepts

Programs

A program is a coordinated set of runs with a planned DAG of dependencies. Use one when "a feature" is actually a whole system, a new app, or a multi-PR upgrade.

When to reach for a program

Use pipemason start when the work fits on one ticket and one PR. Use pipemason program start when any of these are true:

  • You're starting a system from scratch (greenfield).
  • You're upgrading or migrating an existing system where order and rollback matter.
  • The end state crosses 3+ domains with non-trivial dependencies.
  • You'd otherwise have to sequence 5+ pipemason start invocations by hand.

How a program decomposes

The program-plan phase reads your intent and writes .pipeline/ROADMAP.md: a list of stories, each with an id, an epic, size + risk estimates, dependencies on upstream stories, and acceptance criteria. The roadmap is frozen at the end of program_plan; the iterate phase then dispatches stories in dependency order, one per branch.

Top-level state

.pipeline/
├── PROGRAM.md                # program-level state (status, phase, counters)
├── ROADMAP.md                # frozen story DAG
├── AUDIT.md                  # only for brownfield-* modes
├── MIGRATIONS.md             # only for brownfield-upgrade
├── DESIGN-SYSTEM.md          # only for greenfield-* modes
└── stories/
    ├── S-E001-001/           # one directory per dispatched story
    │   ├── spec.md
    │   ├── STATE.md
    │   └── iterations.log
    └── S-E001-002/

The dashboard streams PROGRAM.md + each story's state live, so you can watch which stories are running, which have landed, and which escalated.

Branch strategy

Programs ship as stacked branches by default: each story's branch is based on the upstream story's branch, not on main. The orchestrator picks the right base from the DAG when it dispatches each story. The alternative — program-branch — runs every story off a single program-level branch (set in config.yml if needed).

Modes

A program picks one of four modes which decides which top-level phases run and what artifacts they produce.

  • greenfield-system — multi-domain SaaS / platform from scratch.
  • greenfield-mobile — new mobile or game app + minimum-viable backend.
  • brownfield-upgrade — migrate an existing system safely.
  • brownfield-extension — add a capability without rewriting.

Top-level state machine

Greenfield programs walk:

program_init → program_plan → design_system → iterate → program_verify → complete

Brownfield programs walk:

program_init → audit → program_plan → migration_plan? → iterate → program_verify → complete

Note

migration_plan only runs for brownfield-upgrade. brownfield-extension skips it. Both brownfield modes run audit first to freeze a system snapshot the rest of the program can rely on.

Dry-run the plan

You can ask for the roadmap without writing any code — useful for sanity-checking the decomposition before spending tokens on implementation:

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

Read .pipeline/ROADMAP.md, iterate on the prompt, or edit the roadmap by hand. When you're satisfied, re-run without --dry-run.