Skip to content

Modes

Program modes: greenfield and brownfield variants.

A mode tells a program what kind of work it is doing. You pass it with --mode when you start a program, and it determines which planning steps the program runs before it begins iterating through stories. There are two greenfield modes for building from scratch and two brownfield modes for changing an existing system.

pipemason program start "<intent>" --mode <mode>

greenfield-system

Build a multi-domain system or platform from scratch. The program plans a roadmap and a design system up front, then iterates the stories that compose the new system across whatever domains it spans.

greenfield-mobile

Build a net-new mobile or game app, together with the minimum backend it needs to function. Like greenfield-system it plans before building, but it is scoped to an app-first shape.

brownfield-upgrade

Read an existing system and plan plus execute a multi-story change to it — for example, migrating authentication to passkeys or moving a framework version forward. This mode adds an audit of the current system and a migration plan, and the migration plan enforces upgrade discipline: feature flags, dual-write where appropriate, and a deliberate cutover rather than a big-bang switch.

Heads-up

For a brownfield upgrade, run pipemason audit first to snapshot the existing system. By default a story may not flip behavior without a flag — the program escalates rather than make an unguarded change.

brownfield-extension

Add a new capability to an existing system without rewriting it. The program audits what is already there, plans the new work, and goes straight to iterating — it does not run the migration-planning step that brownfield-upgrade uses, because it is adding rather than changing existing behavior.

How modes differ

The mode you choose changes the pre-iteration planning a program performs:

  • Greenfield modes plan a roadmap and a design system, then iterate.
  • brownfield-upgrade audits the system, plans a roadmap, plans a migration, then iterates.
  • brownfield-extension audits the system, plans a roadmap, then iterates.

All four converge on the same iterate stage, where the per-story pipeline runs once per story. See Programs for that flow and the State machine for the exact transitions.