guides

Multi-story program

When a feature is actually a whole system, run a program. This walks through writing the intent, reviewing the roadmap, and watching stories ship in DAG order.

1. Write a sharp intent

The intent is the program's spec. Tight intents produce tight roadmaps. Aim for 2–4 sentences naming the domains, the tier constraints, and any explicit non-goals.

Build a Linear-style issue tracker. Web (Next.js) + API (Hono on Cloudflare
Workers) + DB (D1) + mobile (React Native + Expo). Three role tiers gated
server-side. v1 monitor-only — member management and admin tooling deferred.

2. Dry-run to get the roadmap

pipemason program start "<your intent>" \
  --mode greenfield-system \
  --dry-run

This runs program_plan and stops. Read .pipeline/ROADMAP.md — it's the story DAG the orchestrator will dispatch. Look for:

Story decomposition that matches your mental model.
Sensible dependency chains (no circular waits, no over-coupling).
Risk / size estimates that look honest.
Acceptance criteria you can actually verify.

Tip

Iterating on the roadmap is much cheaper than iterating on implementation. Spend 10 minutes here.

3. Kick off the real run

When the roadmap is right, remove --dry-run and re-run. The orchestrator picks up from iterate and dispatches stories in dependency order.

pipemason program start "<your intent>" --mode greenfield-system

4. Watch on the dashboard

The program page on /dashboard shows the DAG live. Each story shows its current phase, a progress bar, and a link to its branch + PR. Failed stories surface their failure_class for triage.

5. Parallelism

Set parallelism: 3 in .pipeline/config.yml to let the orchestrator dispatch up to three ready stories at the same time. Use this when stories touch independent domains (e.g. API + web + mobile can usually run in parallel after the contract phase finishes).

6. Program verify

After every story completes, the program-verify phase runs a cross-cutting pass: dependency audit, license audit, secrets scan, PII audit, per-platform pen-tests, contract drift detection. The verdict (pass, pass-with-warnings, or block) is written to verify-report.md.