Skip to content

Brownfield upgrade

Changing a system that already exists is different from building a new one. A brownfield upgrade first reads what's there, then plans and executes a multi-story change with migration discipline built in.

When to use it

Use a brownfield upgrade for changes that ripple across an existing codebase — “migrate auth to passkeys,” “move from one framework version to the next,” or any change where you can't flip a switch in one commit without risk. If you're only adding a new, self-contained capability, a single run or a greenfield-style extension is usually enough.

Audit the system first

Start by snapshotting the current system. The audit captures what exists so the plan is grounded in reality rather than assumptions:

pipemason audit

The audit produces a frozen snapshot of the system. If it surfaces open questions that would block planning, answer them before continuing — the program won't plan around ambiguity it can't resolve.

Start the upgrade

With the audit in hand, start the program in brownfield-upgrade mode:

pipemason program start "migrate auth to passkeys" \
  --mode brownfield-upgrade

The program produces a roadmap of stories and a migration plan before any code changes. The migration plan is where the safety lives.

Migration discipline

Brownfield upgrades enforce a careful change pattern so the system keeps working at every step:

  • Feature flags — new behavior ships behind a flag so it can be enabled and disabled without redeploying.
  • Dual-write — during a data or behavior migration, both the old and new paths are written so neither side loses information mid-flight.
  • Cutover — switching fully to the new path is a deliberate, flagged step, not a side effect of a feature commit.

Heads-up

A story that tries to flip behavior without a flag will pause and escalate rather than make a one-way, big-bang change on its own. That's by design — see the Handling escalations guide.

Track and advance

Watch the roadmap and advance the program the same way as any program:

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

Typical flow

  1. Run pipemason audit and resolve any blocking questions.
  2. Start the program with --mode brownfield-upgrade.
  3. Review the roadmap and migration plan via pipemason program status.
  4. Advance with pipemason program resume, resolving escalations as they arise.
  5. Perform the flagged cutover once the new path is verified.