Brownfield Guide

Guide for working with existing codebases using BMad Method. Learn how to extend, enhance, and modernize legacy systems safely.

Overview

Brownfield workflows adapt BMad Method for existing projects. Key differences from greenfield:

• Document existing system first
• Use brownfield templates (focused on changes)
• Skip initial analysis (Analyst)
• Emphasize integration and safety
• Include rollback plans

Prerequisites

• Existing codebase
• BMad Method installed
• Access to web AI platform and IDE

Brownfield Workflow Options

Option 1: Full Enhancement (Multiple Stories)

Use when: Adding significant features, 2+ weeks work, multiple epics

Process: Document → Plan → Develop (same as greenfield but with brownfield templates)

Option 2: Medium Enhancement (2-3 Stories)

Use when: Adding features, 3-10 days work, single epic

Process: Create brownfield epic → Create stories → Develop

Option 3: Small Enhancement (Single Story)

Use when: Small additions, < 4 hours, single story

Process: Create single brownfield story → Develop immediately

Step-by-Step: Full Enhancement

Step 1: Document Existing System

npx bmad-method flatten -i . -o project-complete.xml

What it does:

• Scans entire codebase recursively
• Respects .gitignore patterns
• Creates XML file with all code
• Provides context for AI agents

Output: project-complete.xml (use this as reference for planning)

Step 2: Planning Phase (Web Platform)

Load Planning Team:

• Full-stack: web-bundles/teams/team-fullstack.txt
• Backend-only: web-bundles/teams/team-no-ui.txt

Create Brownfield PRD

*agent pm
*create-prd

PM uses brownfield-prd-tmpl.yaml which focuses on:

• Current State: What exists now
• Enhancement Objectives: What you're adding
• Affected Systems: What will change
• Compatibility Requirements: What must remain unchanged
• Epics and Stories: New features
• Technical Constraints: Existing tech stack
• Migration Strategy: How to roll out changes

Reference: project-complete.xml when PM asks about existing system

Output: docs/brownfield-prd.md

Create Brownfield Architecture

*agent architect
*create-architecture

Architect uses brownfield-architecture-tmpl.yaml which includes:

• Current Architecture: Existing system design
• Proposed Changes: What will be modified
• Affected Components: Impact analysis
• Technical Debt: Existing issues
• Migration Strategy: Implementation plan
• Compatibility: How changes integrate
• Updated Specs: Modified data models, APIs

Output: docs/brownfield-architecture.md

Shard Documents

*agent po
*shard-doc

Output: docs/prd/ and docs/architecture/ directories

Step 3: Development Phase (IDE)

Same as greenfield development with additional safety:

Create Brownfield Stories

*agent sm
*draft

SM uses create-brownfield-story task which includes:

• Integration context with existing code
• Safety checks for existing functionality
• Rollback plan
• Risk assessment

Brownfield Story Additions:

## Integration Context
[Source: project-complete.xml#existing-auth]
Existing authentication uses Passport.js with JWT strategy.
New OAuth integration must coexist with existing JWT auth.

## Safety Checks
- Existing JWT authentication must continue working
- No breaking changes to /api/auth/* endpoints
- Maintain backward compatibility with mobile apps

## Rollback Plan
1. Revert src/auth/oauth.js
2. Remove OAuth routes from src/app.js
3. Restore previous package.json dependencies
4. Run `npm install`

## Risk Assessment
**Medium Risk**: OAuth integration may conflict with existing JWT middleware
**Mitigation**: Test both auth methods thoroughly, use feature flag

Implement with Safety

*agent dev
*develop-story

Dev follows same process but with extra caution:

• Test existing functionality unchanged
• Use feature flags for new code
• Implement rollback points
• Document integration points

Output: Code changes with safety checks

Step-by-Step: Medium Enhancement (2-3 Stories)

Skip Full PRD/Architecture

For medium enhancements (single epic), skip full documents:

*agent sm
*draft

Use brownfield-create-epic task:

1. Creates focused epic document
2. Breaks into 2-3 stories
3. Includes integration context
4. Documents compatibility requirements

Output: docs/epics/brownfield-{feature}.md and story files

Development

Same as full brownfield development above.

Step-by-Step: Small Enhancement (Single Story)

Single-Story Workflow

For very small changes (< 4 hours):

*agent pm
*create-brownfield-story

PM uses brownfield-create-story task to create single story:

• Constraints: Completable in one session (< 4 hours)
• Scope: Follows existing patterns exactly
• Integration: Clear, straightforward
• Risk: Low, isolated change

Story includes:

• Integration context
• Existing patterns to follow
• Safety checks
• Quick rollback plan

Output: Single story file

*agent dev
*develop-story

Implement immediately.

Brownfield Best Practices

1. Document First

Always flatten codebase before planning:

npx bmad-method flatten -i . -o project.xml

2. Understand Before Changing

• Review flattened XML
• Identify existing patterns
• Note integration points
• Understand constraints

3. Maintain Compatibility

• Don't break existing functionality
• Test existing features after changes
• Use feature flags for new code
• Document breaking changes (if unavoidable)

4. Follow Existing Patterns

• Match existing code style
• Use same frameworks/libraries
• Follow established architecture
• Respect existing conventions

5. Safety First

• Include rollback plans
• Test existing functionality
• Use feature flags
• Implement gradually

6. Document Integration

• Reference existing code in stories
• Document integration points
• Note dependencies
• Specify compatibility requirements

Common Brownfield Scenarios

Scenario 1: Adding New API Endpoint to Existing Service

Approach: Single-story workflow

*agent pm
*create-brownfield-story

Story includes:

• Existing API patterns to follow
• Integration with existing middleware
• Compatibility with existing clients

Scenario 2: Modernizing Legacy Component

Approach: Medium enhancement (epic with 2-3 stories)

*agent sm
*draft

Creates brownfield epic:

• Story 1: Extract legacy logic
• Story 2: Implement modern replacement
• Story 3: Migrate usage + remove legacy

Scenario 3: Major Feature Addition

Approach: Full brownfield workflow

Document system → Create PRD → Create Architecture → Develop stories

Troubleshooting Brownfield

Problem: Don't understand existing codebase Solution: Review flattened XML, ask clarifying questions in planning

Problem: New code breaks existing functionality Solution: Increase test coverage for existing features, use feature flags

Problem: Integration points unclear Solution: Use create-brownfield-story task with interactive context gathering

Problem: Can't follow existing patterns Solution: Document deviation in story, get stakeholder approval

Next Steps

• Complete development with Development Phase Guide
• Handle issues with Error Recovery Guide
• Review detailed specs in Agent Reference

Related Documentation

• Quick Start Guide
• Planning Phase Guide
• Development Phase Guide
• Task Reference - See brownfield tasks