concepts

Modes

Every program picks one of four modes when it starts. The mode decides which top-level phases run and what artifacts they produce.

Mode	Use case	Top-level phases
`greenfield-system`	Multi-domain SaaS / platform from scratch	`program_plan → design_system → iterate → program_verify`
`greenfield-mobile`	Net-new mobile or game app + minimum-viable backend	`program_plan → design_system → iterate → program_verify`
`brownfield-upgrade`	Migrate an existing system safely	`audit → program_plan → migration_plan → iterate → program_verify`
`brownfield-extension`	Add a capability to an existing system	`audit → program_plan → iterate → program_verify`

Picking a mode

greenfield-system

Use when you're building a multi-domain SaaS from scratch — API + web + DB + maybe mobile. The design_system phase produces a shared design-token surface, brand palette, and component inventory the per-story implementations all consume.

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

greenfield-mobile

Net-new mobile app or mobile game, optionally with a minimum-viable backend. Same phase set as greenfield-system but planning pre-picks React Native + Expo (or visionOS or Swift / Kotlin natives based on the intent) and the design system targets mobile conventions.

pipemason program start "build a meditation timer app with streaks + reminders" \
  --mode greenfield-mobile

brownfield-upgrade

Migrating an existing system — auth swap, framework bump, schema redesign, monolith-to-services. The audit phase produces a frozen AUDIT.md snapshot of the current system; migration_plan writes ordered, reversible migration steps; iterate ships them one PR at a time with rollback gates.

pipemason program start "migrate auth from Auth0 to Clerk preserving sessions" \
  --mode brownfield-upgrade

brownfield-extension

Adding a feature to an existing system without rewriting it. Same as brownfield-upgrade but skips migration_plan — the change should slot into the existing system without coordinated migrations.

pipemason program start "add SSO + SCIM provisioning to our existing auth" \
  --mode brownfield-extension

Mode-specific artifacts

greenfield-* writes DESIGN-SYSTEM.md + brand tokens during design_system.
brownfield-* writes AUDIT.md during audit.
brownfield-upgrade additionally writes MIGRATIONS.md during migration_plan.

All four modes share PROGRAM.md, ROADMAP.md, and per-story spec.md / STATE.md / iterations.log.