Preview — full styling will appear after the next deploy completes.

bmad-method

Greenfield vs Brownfield

Different constraints, different artifact chains

BMAD distinguishes greenfield projects (new codebase, no inherited constraints) from brownfield projects (existing codebase, technical debt, integration points). The artifact chain and the Architect's responsibilities differ significantly between the two.

flowchart TD
    P([Project Start]) --> GBQ{Greenfield or<br>Brownfield?}
    GBQ -->|Greenfield| GF[BA Phase<br>clean slate]
    GBQ -->|Brownfield| BF[Codebase Survey<br>by Developer Persona<br>read-only mode]
    BF --> CBD[Codebase Context Doc<br>Architecture · Tech stack<br>Conventions · Known debt]
    CBD --> BA_BF[BA Phase<br>with codebase constraints]
    GF --> REST([Standard BMAD<br>Artifact Chain])
    BA_BF --> REST

In a greenfield project, the artifact chain starts from scratch. There is no existing codebase to understand, no existing patterns to respect, and no technical debt to work around. The BA defines the problem, the PM defines the stories, the Architect makes unconstrained design choices, and the Developer implements against a clean slate. The main risk in greenfield BMAD projects is over-engineering — the Architect must actively resist producing comprehensive architecture documents for a system that doesn't exist yet.

Brownfield projects start with an additional input: a codebase context document. Before the BA or PM phases begin, the Developer persona — in a read-only survey mode — examines the existing system and produces a concise summary: the current architecture, the tech stack, the naming conventions, the test patterns, and known technical debt that will affect new work. This document travels alongside the PRD and stories throughout the artifact chain.

The key difference in brownfield implementation is that the Developer persona operates within constraints it did not choose. It must match existing patterns even when better patterns exist, because inconsistency in an existing codebase is a form of technical debt. When brownfield implementation genuinely requires deviating from established patterns, that deviation needs a human decision and an ADR — not a silent change because the AI found a cleaner approach.