Programs

A program groups related stories and tracks their progress.

A program operates above individual runs. You hand it a larger intent — an entire system to build, a mobile or game app, or a multi-step upgrade — and it decomposes that intent into a dependency graph of stories, then runs the per-story pipeline once per story in dependency order.

Start a program

Start a program with an intent and a mode:

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

The --mode flag tells the program what kind of work it is doing, which determines the planning steps it runs before iterating. See Modes for the full list.

How a program is planned

Before any code is written, a program produces a plan and freezes it. The plan is a roadmap of stories arranged as a directed acyclic graph (a DAG) so that each story runs only after the work it depends on is complete. Depending on the mode, a program also produces an audit of an existing system, a migration plan, or a design system — each frozen before iteration begins so parallel work cannot drift away from it.

Iterating through stories

Once planning is frozen, the program enters its iterate stage. It walks the DAG and drives a run for each story in order. Stories that have no dependency on each other can be branched independently; by default story branches are stacked so later work builds on the branches it depends on.

Tracking progress

Program state lives in .pipeline/PROGRAM.md alongside the roadmap. Track progress two ways:

pipemason program status   # roadmap + DAG progress
pipemason program resume   # advance to the next phase / story

The dashboard shows the same roadmap with per-story status so you can see which stories are complete, in progress, blocked, or waiting on you.

Program verification

After every story is complete, a program runs an integrated verification pass against the assembled stack — checking the stories work together, not just in isolation. If that pass finds cross-story problems, the program appends follow-up stories and loops back to iterate; otherwise the program closes.

When a program escalates

Like a run, a program stops rather than guessing when it hits something ambiguous — unanswered planning questions, a roadmap with cycles, or a conflict it must not auto-resolve. It records what it needs and waits for you.

Cost controls

Programs can run for a while, so you can cap spend. Set a cumulative ceiling with --max-cost and a per-day ceiling with --max-daily-cost at program start. When the daily ceiling is reached the program pauses for the day and resumes automatically the next day.