npm - bmad-method - Versions diffs - 6.0.0-alpha.4 → 6.0.0-alpha.5 - Mend

bmad-method 6.0.0-alpha.4 → 6.0.0-alpha.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (162) hide show

package/bmad/bmm/docs/brownfield-guide.md CHANGED Viewed

@@ -1,799 +1,398 @@
 # BMad Method Brownfield Development Guide
-## Overview
+**Complete guide for working with existing codebases**
-This guide provides comprehensive guidance for using BMad Method v6 with existing codebases (brownfield projects). Whether you're fixing a single bug, adding a small feature, or implementing a major system expansion, BMad Method adapts to your project's complexity while ensuring AI agents have the context they need to work effectively.
+**Reading Time:** ~35 minutes
-**Core Principle:** In brownfield development, producing contextual artifacts for agents is paramount. AI agents require comprehensive documentation to understand existing patterns, constraints, and integration points before they can effectively plan or implement changes.
-## What is Brownfield Development?
+---
-Brownfield projects involve working within existing codebases rather than starting fresh. This includes:
+## Quick Navigation
-- **Bug fixes** - Single file changes to resolve issues
-- **Small features** - Adding functionality to existing modules
-- **Feature sets** - Multiple related features across several areas
-- **Major integrations** - Complex additions requiring architectural changes
-- **System expansions** - Enterprise-scale enhancements to existing platforms
+**Jump to:**
-The key difference from greenfield development: you must understand and respect existing patterns, architecture, and constraints.
+- [Quick Reference](#quick-reference) - Commands and files
+- [Common Scenarios](#common-scenarios) - Real-world examples
+- [Troubleshooting](#troubleshooting) - Problem solutions
+- [Best Practices](#best-practices) - Success tips
-## Scale-Adaptive Workflow System
+---
-BMad Method v6 uses a **scale-adaptive** approach that automatically routes brownfield projects through appropriate workflows based on complexity:
+## What is Brownfield Development?
-### Brownfield Complexity Levels
+Brownfield projects involve working within existing codebases rather than starting fresh:
-| Level | Scope                  | Story Count   | Workflow Approach                        | Documentation Depth                                    |
-| ----- | ---------------------- | ------------- | ---------------------------------------- | ------------------------------------------------------ |
-| **0** | Single atomic change   | 1 story       | Lightweight tech-spec only               | Quick understanding of affected area                   |
-| **1** | Small feature addition | 1-10 stories  | Tech-spec with epic breakdown            | Focused documentation of integration points            |
-| **2** | Medium feature set     | 5-15 stories  | PRD + tech-spec                          | Comprehensive docs for affected systems                |
-| **3** | Complex integration    | 12-40 stories | PRD → architecture → implementation      | Full system documentation + integration planning       |
-| **4** | Enterprise expansion   | 40+ stories   | Full methodology with strategic planning | Complete codebase documentation + architectural review |
+- **Bug fixes** - Single file changes
+- **Small features** - Adding to existing modules
+- **Feature sets** - Multiple related features
+- **Major integrations** - Complex architectural additions
+- **System expansions** - Enterprise-scale enhancements
-### How Scale Determination Works
+**Key Difference from Greenfield:** You must understand and respect existing patterns, architecture, and constraints.
-When you run `workflow-init`, it asks about YOUR work first, then uses existing artifacts as context:
+**Core Principle:** AI agents need comprehensive documentation to understand existing code before they can effectively plan or implement changes.
-#### Step 1: Understand What You're Working On
+---
-The workflow asks you first:
+## Getting Started
-1. **Project name**: "What's your project called?"
+### Understanding Planning Tracks
-2. **If it finds existing work** (code or planning documents):
-   - Shows what it found (PRD, epics, stories, codebase)
-   - Asks a clear question:
+For complete track details, see [Scale Adaptive System](./scale-adaptive-system.md).
-> **"Looking at what I found, are these:**
->
-> a) **Works in progress you're finishing** - continuing the work described in these documents
-> b) **Documents from a previous effort** - you're starting something NEW and different now
-> c) **The proposed work you're about to start** - these describe what you want to do
-> d) **None of these** - let me explain what I'm actually working on"
+**Brownfield tracks at a glance:**
-**If you choose (a) or (c):** System analyzes the artifacts to get project details
-**If you choose (b) or (d):** System asks you to describe your NEW work
+| Track                 | Scope                      | Typical Stories | Key Difference                                  |
+| --------------------- | -------------------------- | --------------- | ----------------------------------------------- |
+| **Quick Flow**        | Bug fixes, small features  | 1-15            | Must understand affected code and patterns      |
+| **BMad Method**       | Feature sets, integrations | 10-50+          | Integrate with existing architecture            |
+| **Enterprise Method** | Enterprise expansions      | 30+             | Full system documentation + compliance required |
-3. **Asks about your work**: "Tell me about what you're working on. What's the goal?"
+**Note:** Story counts are guidance, not definitions. Tracks are chosen based on planning needs.
-4. **Analyzes your description** using keyword detection:
+### Track Selection for Brownfield
-**Level 0 Keywords:** "fix", "bug", "typo", "small change", "update", "patch"
-**Level 1 Keywords:** "simple", "basic", "small feature", "add", "minor"
-**Level 2 Keywords:** "dashboard", "several features", "admin panel", "medium"
-**Level 3 Keywords:** "platform", "integration", "complex", "system"
-**Level 4 Keywords:** "enterprise", "multi-tenant", "multiple products", "ecosystem"
+When you run `workflow-init`, it handles brownfield intelligently:
-**Examples:**
+**Step 1: Shows what it found**
-- "I need to update payment method enums" → **Level 0**
-- "Adding forgot password feature" → **Level 1**
-- "Building admin dashboard with analytics" → **Level 2**
-- "Adding real-time collaboration to document editor" → **Level 3**
-- "Implementing multi-tenancy across our SaaS" → **Level 4**
+- Old planning docs (PRD, epics, stories)
+- Existing codebase
-5. **Suggests and confirms**: "Based on your description: Level X brownfield project. Is that correct?"
+**Step 2: Asks about YOUR work**
-#### How It Handles Old Artifacts
+> "Are these works in progress, previous effort, or proposed work?"
-**Scenario: Old Level 3 PRD, New Level 0 Work**
+- **(a) Works in progress** → Uses artifacts to determine level
+- **(b) Previous effort** → Asks you to describe NEW work
+- **(c) Proposed work** → Uses artifacts as guidance
+- **(d) None of these** → You explain your work
-```
-System: "I found: PRD.md (Level 3, 30 stories, modified 6 months ago)"
-System: "Are these works in progress you're finishing, or documents from a previous effort?"
+**Step 3: Analyzes your description**
-You: "b - Documents from a previous effort"
+- Keywords: "fix", "bug" → Quick Flow, "dashboard", "platform" → BMad Method, "enterprise", "multi-tenant" → Enterprise Method
+- Complexity assessment
+- Confirms suggested track with you
-System: "Tell me about what you're working on"
-You: "I need to update payment method enums"
+**Key Principle:** System asks about YOUR current work first, uses old artifacts as context only.
-System: "Level 0 brownfield project. Is that correct?"
-You: "yes"
+**Example: Old Complex PRD, New Simple Work**
-✅ Result: Level 0 workflow
 ```
-**Key Principle:** The system asks about YOUR current work first, then uses old artifacts as context, not as the primary source of truth.
-## The Five Phases of Brownfield Development
-### Phase 0: Documentation (Conditional)
-Phase 0 has three possible scenarios based on your existing documentation state:
-#### Scenario A: No Documentation
-**When:** Codebase lacks adequate documentation for AI agents
-**Action:** Run `document-project` workflow to create comprehensive documentation from scratch
-#### Scenario B: Documentation Exists, But No Index
-**When:** You have README, architecture docs, or other documentation BUT no `index.md` (master AI retrieval source)
-**Action:** Run the `index-docs` task to generate `index.md` from existing documentation
-**The `index-docs` Task** (from `bmad/core/tasks/index-docs.xml`):
-- Scans your documentation directory
-- Reads each file to understand its purpose
-- Creates organized `index.md` with file listings and descriptions
-- Provides structured navigation for AI agents
-- Lightweight and fast (just indexes, doesn't scan codebase)
-**Why This Matters:** The `index.md` file is the primary entry point for AI agents. Without it, agents must hunt through multiple files. Even with good existing docs, the index provides structured navigation and ensures agents can quickly find relevant context.
-**When to Use `document-project` Instead:**
-If your existing docs are inadequate or you need comprehensive codebase analysis:
-- Use `document-project` workflow with appropriate scan level (deep/exhaustive)
-- It will discover your existing docs in Step 2 and show them to you
-- It will generate NEW documentation from codebase analysis
-- Final `index.md` will link to BOTH existing docs AND newly generated docs
-- Result: Comprehensive documentation combining your existing docs with AI-friendly codebase analysis
-#### Scenario C: Complete Documentation with Index
-**When:** You have comprehensive documentation including `docs/index.md`
-**Action:** Skip Phase 0 entirely and proceed to Phase 1 or Phase 2
-#### The `document-project` Workflow
-This critical workflow analyzes and documents your existing codebase:
-**What It Does:**
-- Detects project type (web, backend, mobile, CLI, etc.)
-- Identifies tech stack and dependencies
-- Analyzes architecture patterns
-- Documents API routes and data models
-- Maps component structure
-- Extracts development workflows
-- **NEW:** Can incorporate existing documentation and generate master index
-**Three Scan Levels:**
-1. **Quick Scan** (2-5 min) - Pattern-based analysis without reading source
-   - Use for: Fast project overview, initial understanding, index generation
-   - Reads: Config files, manifests, directory structure, existing docs
-2. **Deep Scan** (10-30 min) - Reads critical directories
-   - Use for: Brownfield PRD preparation, focused analysis
-   - Reads: Key paths based on project type (controllers, models, components)
-   - Incorporates: Existing documentation as input
-3. **Exhaustive Scan** (30-120 min) - Reads ALL source files
-   - Use for: Migration planning, complete system understanding
-   - Reads: Every source file (excludes node_modules, dist, .git)
-   - Incorporates: All existing documentation
-**Output Files:**
-- `index.md` - Master documentation index (primary AI retrieval source)
-- `project-overview.md` - Executive summary
-- `architecture.md` - Detailed architecture analysis
-- `source-tree-analysis.md` - Annotated directory structure
-- `api-contracts.md` - API documentation (if applicable)
-- `data-models.md` - Database schemas (if applicable)
-- Additional conditional files based on project type
-**Working with Existing Documentation:**
-If you have existing docs (README, ARCHITECTURE.md, CONTRIBUTING.md, etc.) you have two options:
-**Option 1: Just need an index (`index-docs` task)**
-- Fast, lightweight approach
-- Run the `index-docs` task from `bmad/core/tasks/index-docs.xml`
-- Scans your docs directory and generates organized `index.md`
-- Reads each file to create accurate descriptions
-- Links to all existing documentation
-- Perfect when docs are good but need structured navigation for AI agents
-**Option 2: Need comprehensive codebase documentation (`document-project` workflow)**
-- Scans the actual codebase to generate technical documentation
-- Discovers existing docs (README, ARCHITECTURE.md, etc.) in Step 2
-- Shows you what it found and asks for additional context
-- Generates NEW documentation files from codebase analysis:
-  - `project-overview.md` - Executive summary from codebase
-  - `architecture.md` - Architecture analysis from code
-  - `api-contracts.md` - API documentation from routes/controllers
-  - `data-models.md` - Database schemas from models
-  - `source-tree-analysis.md` - Annotated directory structure
-- Creates `index.md` that links to BOTH existing docs AND newly generated docs
-- Complements your existing documentation with AI-friendly codebase analysis
-**Deep-Dive Mode:** If you already have documentation but need exhaustive analysis of a specific area (e.g., authentication system, dashboard module), you can run the workflow in deep-dive mode to create comprehensive documentation for just that subsystem.
-**Example Usage:**
-```bash
-# Scenario A: No documentation
-bmad analyst workflow-status
-# → Directs to document-project
-bmad analyst document-project
-# → Choose: Deep scan (recommended for brownfield)
-# Scenario B: Has docs but no index
-# Option 1: Just generate index from existing docs
-# Run the index-docs task directly (lightweight, fast)
-# Load bmad/core/tasks/index-docs.xml
-# Specify your docs directory (e.g., ./docs)
-# Option 2: Need comprehensive codebase docs too
-bmad analyst document-project
-# → Choose: Deep or Exhaustive scan
-# → Creates index.md AND additional codebase documentation
-# Scenario C: Complete with index
-bmad analyst workflow-status
-# → Skips Phase 0, proceeds to Phase 1 or 2
+System: "Found PRD.md (BMad Method track, 30 stories, 6 months old)"
+System: "Is this work in progress or previous effort?"
+You: "Previous effort - I'm just fixing a bug now"
+System: "Tell me about your current work"
+You: "Update payment method enums"
+System: "Quick Flow track (tech-spec approach). Correct?"
+You: "Yes"
+✅ Creates Quick Flow workflow
 ```
-### Phase 1: Analysis (Optional)
-**Purpose:** Explore solutions and gather context before formal planning.
-**Available Workflows:**
-- `brainstorm-project` - Solution exploration for new features
-- `research` - Market/technical research for decision-making
-- `product-brief` - Strategic product planning document
-**When to Use:**
-- Complex features requiring multiple solution approaches
-- Technical decisions needing research (frameworks, patterns, tools)
-- Strategic additions requiring business context
-**When to Skip:**
-- Bug fixes or minor changes with obvious solutions
-- Well-understood features with clear requirements
-- Time-sensitive changes where planning overhead isn't justified
-### Phase 2: Planning (Required)
-**Purpose:** Create formal requirements and break down work into epics and stories.
-The planning approach adapts to your brownfield project's complexity:
-#### Level 0: Single Atomic Change
-**Workflow:** `tech-spec` only
-**Outputs:** `tech-spec.md` + single story file
-**Next Phase:** → Implementation (Phase 4)
-**Use For:**
-- Bug fixes
-- Single file changes
-- Minor configuration updates
-- Small refactors
-**Key Considerations:**
-- Must understand existing pattern in affected file
-- Document integration points
-- Identify potential side effects
-**Example:** Fixing authentication token expiration bug in auth middleware
-#### Level 1: Small Feature
-**Workflow:** `tech-spec` only
-**Outputs:** `tech-spec.md` + epic breakdown + 2-10 story files
-**Next Phase:** → Implementation (Phase 4)
-**Use For:**
-- Single module additions
-- Small UI enhancements
-- Isolated feature additions
-- API endpoint additions
-**Key Considerations:**
-- Identify reusable existing components
-- Respect current architectural patterns
-- Plan integration with existing APIs/services
-**Example:** Adding "forgot password" feature to existing auth system
-#### Level 2: Medium Feature Set
-**Workflow:** `prd` → `tech-spec`
-**Outputs:** `PRD.md` + `epics.md` + `tech-spec.md`
-**Next Phase:** → Implementation (Phase 4)
-**Use For:**
-- Multiple related features
-- Cross-module enhancements
-- Moderate scope additions
-- Feature sets spanning 1-2 areas
-**Key Considerations:**
-- Document all integration points
-- Map dependencies to existing systems
-- Identify shared components for reuse
-- Plan migration strategy if changing patterns
-**Special Note:** Level 2 uses `tech-spec` instead of full architecture workflow to keep planning lightweight while still providing adequate technical guidance.
-**Example:** Adding user dashboard with analytics, preferences, and activity history
-#### Level 3: Complex Integration
+---
-**Workflow:** `prd` → `create-architecture` → implementation
-**Outputs:** `PRD.md` + `epics.md` + `architecture.md` (extension of existing)
-**Next Phase:** → Solutioning (Phase 3) → Implementation (Phase 4)
+## Phase 0: Documentation (Critical First Step)
-**Use For:**
+🚨 **For brownfield projects: Always ensure adequate AI-usable documentation before planning**
-- Major feature additions
-- Architectural integrations
-- Multi-system changes
-- Complex data migrations
+### Default Recommendation: Run document-project
-**Key Considerations:**
+**Best practice:** Run `document-project` workflow unless you have **confirmed, trusted, AI-optimized documentation**.
-- Review existing architecture first
-- Plan integration strategy
-- Document architectural extensions
-- Identify migration paths
-- Plan backward compatibility
+### Why Document-Project is Almost Always the Right Choice
-**Phase 3 Workflows:**
+Existing documentation often has quality issues that break AI workflows:
-- `architecture-review` - Review existing architecture first
-- `integration-planning` - Create integration strategy document
-- `create-architecture` - Extend existing architecture documentation
-- `solutioning-gate-check` - Validate architecture before implementation
+**Common Problems:**
-**Example:** Adding real-time collaboration features to existing document editor
+- **Too Much Information (TMI):** Massive markdown files with 10s or 100s of level 2 sections
+- **Out of Date:** Documentation hasn't been updated with recent code changes
+- **Wrong Format:** Written for humans, not AI agents (lacks structure, index, clear patterns)
+- **Incomplete Coverage:** Missing critical architecture, patterns, or setup info
+- **Inconsistent Quality:** Some areas documented well, others not at all
-#### Level 4: Enterprise Expansion
+**Impact on AI Agents:**
-**Workflow:** Full methodology with strategic analysis
-**Outputs:** Product brief → PRD → comprehensive architecture → phased implementation
-**Next Phase:** → Solutioning (Phase 3) → Implementation (Phase 4)
+- AI agents hit token limits reading massive files
+- Outdated docs cause hallucinations (agent thinks old patterns still apply)
+- Missing structure means agents can't find relevant information
+- Incomplete coverage leads to incorrect assumptions
-**Use For:**
+### Documentation Decision Tree
-- Platform expansions
-- Multi-team initiatives
-- System-wide modernization
-- Major architectural shifts
+**Step 1: Assess Existing Documentation Quality**
-**Key Considerations:**
+Ask yourself:
-- Comprehensive codebase documentation required (Phase 0)
-- Deep architectural review mandatory
-- Backward compatibility strategy
-- Phased rollout planning
-- Feature flag implementation
-- Migration strategy for existing data/users
-- Cross-team coordination
+- ✅ Is it **current** (updated in last 30 days)?
+- ✅ Is it **AI-optimized** (structured with index.md, clear sections, <500 lines per file)?
+- ✅ Is it **comprehensive** (architecture, patterns, setup all documented)?
+- ✅ Do you **trust** it completely for AI agent consumption?
-**Critical for Enterprise:**
+**If ANY answer is NO → Run `document-project`**
-- Documentation phase is nearly mandatory
-- Analysis phase (research, product brief) recommended
-- Full architecture review before planning
-- Extensive integration testing strategy
-- Risk assessment and mitigation planning
+**Step 2: Check for Massive Documents**
-**Example:** Adding multi-tenancy to existing single-tenant SaaS platform
+If you have documentation but files are huge (>500 lines, 10+ level 2 sections):
-### Phase 3: Solutioning (Levels 2-4)
+1. **First:** Run `shard-doc` tool to split large files:
-**Purpose:** Design architectural extensions and integration strategy.
+   ```bash
+   # Load BMad Master or any agent
+   bmad/core/tools/shard-doc.xml --input docs/massive-doc.md
+   ```
-**Workflows Available:**
+   - Splits on level 2 sections by default
+   - Creates organized, manageable files
+   - Preserves content integrity
-| Workflow                 | Level | Purpose                              | Output                    |
-| ------------------------ | ----- | ------------------------------------ | ------------------------- |
-| `architecture-review`    | 3-4   | Review existing architecture         | Analysis document         |
-| `integration-planning`   | 3-4   | Plan integration approach            | Integration strategy      |
-| `create-architecture`    | 2-4   | Extend architecture documentation    | architecture.md (updated) |
-| `validate-architecture`  | 2-4   | Validate design decisions            | Validation report         |
-| `solutioning-gate-check` | 3-4   | Final approval before implementation | Gate check report         |
+2. **Then:** Run `index-docs` task to create navigation:
-**Critical Differences from Greenfield:**
+   ```bash
+   bmad/core/tasks/index-docs.xml --directory ./docs
+   ```
-- You're **extending** existing architecture, not creating from scratch
-- Must document **integration points** explicitly
-- Need **migration strategy** for any pattern changes
-- Require **backward compatibility** considerations
-- Should plan **feature flags** for gradual rollout
+3. **Finally:** Validate quality - if sharded docs still seem incomplete/outdated → Run `document-project`
-**Architecture Extensions Should Include:**
+### Four Real-World Scenarios
-- How new components integrate with existing systems
-- Data flow between new and existing modules
-- API contract changes (if any)
-- Database schema changes and migration strategy
-- Security implications and authentication integration
-- Performance impact on existing functionality
+| Scenario | You Have                                   | Action                     | Why                                     |
+| -------- | ------------------------------------------ | -------------------------- | --------------------------------------- |
+| **A**    | No documentation                           | `document-project`         | Only option - generate from scratch     |
+| **B**    | Docs exist but massive/outdated/incomplete | `document-project`         | Safer to regenerate than trust bad docs |
+| **C**    | Good docs but no structure                 | `shard-doc` → `index-docs` | Structure existing content for AI       |
+| **D**    | Confirmed AI-optimized docs with index.md  | Skip Phase 0               | Rare - only if you're 100% confident    |
-### Phase 4: Implementation (Iterative)
+### Scenario A: No Documentation (Most Common)
-**Purpose:** Transform plans into working code through sprint-based iteration.
+**Action: Run document-project workflow**
-#### The Sprint Planning Entry Point
+1. Load Analyst or Technical Writer (Paige) agent
+2. Run `*document-project`
+3. Choose scan level:
+   - **Quick** (2-5min): Pattern analysis, no source reading
+   - **Deep** (10-30min): Reads critical paths - **Recommended**
+   - **Exhaustive** (30-120min): Reads all files
-Phase 4 begins with the `sprint-planning` workflow:
+**Outputs:**
-**What It Does:**
+- `docs/index.md` - Master AI entry point
+- `docs/project-overview.md` - Executive summary
+- `docs/architecture.md` - Architecture analysis
+- `docs/source-tree-analysis.md` - Directory structure
+- Additional files based on project type (API, web app, etc.)
-1. Extracts all epics and stories from epic files
-2. Creates `sprint-status.yaml` - single source of truth for tracking
-3. Auto-detects existing story files and contexts
-4. Maintains status through development lifecycle
+### Scenario B: Docs Exist But Quality Unknown/Poor (Very Common)
-**Run sprint-planning:**
+**Action: Run document-project workflow (regenerate)**
-- Initially after Phase 2 or Phase 3 completion
-- After creating epic contexts
-- Periodically to sync with file system
-- To check overall progress
+Even if `docs/` folder exists, if you're unsure about quality → **regenerate**.
-#### The Implementation Loop
+**Why regenerate instead of index?**
-```
-Phase Transition → sprint-planning
-                       ↓
-                 epic-tech-context (per epic)
-                       ↓
-    ┌──────────────────┴──────────────────┐
-    │                                      │
-    ↓                                      ↓
-create-story → story-context → dev-story → code-review
-    │              │               │            │
-    ↓              ↓               ↓            ↓
- drafted    ready-for-dev    in-progress     review
-                                   │            │
-                                   └────→───────┘
-                                         ↓
-                                       done
-                                         │
-                              [epic complete?]
-                                         ↓
-                                  retrospective
-```
+- Outdated docs → AI makes wrong assumptions
+- Incomplete docs → AI invents missing information
+- TMI docs → AI hits token limits, misses key info
+- Human-focused docs → Missing AI-critical structure
-#### Status State Machine
+**document-project** will:
-**Epic Status:**
+- Scan actual codebase (source of truth)
+- Generate fresh, accurate documentation
+- Structure properly for AI consumption
+- Include only relevant, current information
-```
-backlog → contexted
-```
+### Scenario C: Good Docs But Needs Structure
-**Story Status:**
+**Action: Shard massive files, then index**
-```
-backlog → drafted → ready-for-dev → in-progress → review → done
-```
+If you have **good, current documentation** but it's in massive files:
-#### Phase 4 Workflows
-| Workflow            | Agent | Purpose                         | Status Update                               |
-| ------------------- | ----- | ------------------------------- | ------------------------------------------- |
-| `sprint-planning`   | SM    | Initialize sprint tracking      | Creates sprint-status.yaml                  |
-| `epic-tech-context` | SM    | Create epic technical context   | Epic: backlog → contexted                   |
-| `create-story`      | SM    | Draft individual story          | Story: backlog → drafted                    |
-| `story-context`     | SM    | Generate implementation context | Story: drafted → ready-for-dev              |
-| `dev-story`         | DEV   | Implement story                 | Story: ready-for-dev → in-progress → review |
-| `code-review`       | SM/SR | Quality validation              | Manual state management                     |
-| `retrospective`     | SM    | Capture epic learnings          | Retrospective: optional → completed         |
-| `correct-course`    | SM    | Handle issues/scope changes     | Adaptive based on situation                 |
-#### Brownfield-Specific Implementation Considerations
-1. **Respect Existing Patterns**
-   - Use existing coding conventions
-   - Follow established architectural approaches
-   - Maintain consistency with current UI/UX patterns
-   - Preserve team preferences and standards
-2. **Integration Testing is Critical**
-   - Test interactions with existing functionality
-   - Validate API contracts remain unchanged (unless intentionally versioned)
-   - Check for regression in existing features
-   - Verify performance impact on legacy components
-3. **Gradual Rollout Strategy**
-   - Implement feature flags for new functionality
-   - Plan rollback strategy
-   - Support backward compatibility
-   - Consider migration scripts for data/schema changes
-4. **Context Injection**
-   - `epic-tech-context`: Provides technical guidance specific to epic scope
-   - `story-context`: Generates implementation context for each story
-   - Both reference existing codebase patterns and integration points
-   - Ensures developers have exact expertise needed for each task
-## Workflow Routing by Level
-### Visual Decision Tree
+**Step 1: Shard large documents**
+```bash
+# For each massive doc (>500 lines or 10+ level 2 sections)
+bmad/core/tools/shard-doc.xml \
+  --input docs/api-documentation.md \
+  --output docs/api/ \
+  --level 2  # Split on ## headers (default)
 ```
-Start → workflow-status
-           ↓
-    [Has documentation?]
-           ↓
-      No ─→ document-project → [Choose scan level]
-      Yes ↓
-           ↓
-    [Complexity level?]
-           ↓
-    ┌──────┴──────┬──────┬──────┬──────┐
-    ↓             ↓      ↓      ↓      ↓
-  Level 0      Level 1  Level 2  Level 3  Level 4
-    ↓             ↓         ↓       ↓        ↓
-tech-spec    tech-spec    prd     prd      prd
-    ↓             ↓         ↓       ↓        ↓
-    └─────────────┴─────────┤       ├────────┘
-                            ↓       ↓
-                      tech-spec   create-architecture
-                            ↓       ↓
-                            └───────┤
-                                    ↓
-                            sprint-planning
-                                    ↓
-                          Implementation Loop
-```
-### Path Files
-The v6 system uses modular path definitions for each brownfield level:
-**Location:** `/src/modules/bmm/workflows/workflow-status/paths/`
-- `brownfield-level-0.yaml` - Single atomic change path
-- `brownfield-level-1.yaml` - Small feature path
-- `brownfield-level-2.yaml` - Medium project path
-- `brownfield-level-3.yaml` - Complex integration path
-- `brownfield-level-4.yaml` - Enterprise expansion path
-Each path file clearly defines:
-- Required vs optional workflows for each phase
-- Agent assignments
-- Expected outputs
-- Integration notes
-## Universal Entry Points
-### `workflow-status` - Your Command Center
-**Always start here.** This workflow:
-- Checks for existing workflow status file
-- Displays current phase and progress
-- Shows next recommended action
-- Routes to appropriate workflows based on context
-**For New Projects:**
-- Detects missing status file
-- Directs to `workflow-init`
-- Guides through project setup
-**For Existing Projects:**
-- Displays current phase and progress
-- Shows Phase 4 implementation state
-- Recommends exact next action
-- Offers to change workflow if needed
-**Example Usage:**
+**Step 2: Generate index**
 ```bash
-bmad analyst workflow-status
+bmad/core/tasks/index-docs.xml --directory ./docs
 ```
-### `workflow-init` - Smart Initialization
-If you don't have a status file, this workflow initializes your project workflow by asking about YOUR work first, then using artifacts as context:
+**Step 3: Validate**
-**Step 1: Quick Scan (Context Only)**
+- Review generated `docs/index.md`
+- Check that sharded files are <500 lines each
+- Verify content is current and accurate
+- **If anything seems off → Run document-project instead**
-- Checks for existing code (`src/`, package files, `.git`)
-- Checks for planning artifacts (PRD, epics, stories, architecture docs)
-- Does NOT analyze in depth yet - just sees what's there
+### Scenario D: Confirmed AI-Optimized Documentation (Rare)
-**Step 2: Ask About YOUR Work**
+**Action: Skip Phase 0**
-Asks: "What's your project called?"
+Only skip if ALL conditions met:
-Then, if it found existing work, shows what it found and asks:
+- ✅ `docs/index.md` exists and is comprehensive
+- ✅ Documentation updated within last 30 days
+- ✅ All doc files <500 lines with clear structure
+- ✅ Covers architecture, patterns, setup, API surface
+- ✅ You personally verified quality for AI consumption
+- ✅ Previous AI agents used it successfully
-> **"Looking at what I found, are these:**
->
-> a) Works in progress you're finishing
-> b) Documents from a previous effort (you're doing something NEW now)
-> c) The proposed work you're about to start
-> d) None of these - let me explain"
+**If unsure → Run document-project** (costs 10-30 minutes, saves hours of confusion)
-**Your Paths:**
+### Why document-project is Critical
-- **Choose (a) or (c):** System analyzes the artifacts to determine level
-- **Choose (b) or (d):** System asks you to describe your NEW work
+Without AI-optimized documentation, workflows fail:
-**Step 3: Determine Level**
+- **tech-spec** (Quick Flow) can't auto-detect stack/patterns → Makes wrong assumptions
+- **PRD** (BMad Method) can't reference existing code → Designs incompatible features
+- **architecture** can't build on existing structure → Suggests conflicting patterns
+- **story-context** can't inject existing patterns → Dev agent rewrites working code
+- **dev-story** invents implementations → Breaks existing integrations
-If continuing old work: Counts stories from artifacts
-If new work: Asks "Tell me about what you're working on" and uses keyword detection
+### Key Principle
-Then confirms: "Level X brownfield project. Is that correct?"
+**When in doubt, run document-project.**
-**Step 4: Create Workflow**
+It's better to spend 10-30 minutes generating fresh, accurate docs than to waste hours debugging AI agents working from bad documentation.
-- Loads appropriate path file: `brownfield-level-{0-4}.yaml`
-- Generates workflow with all phases and workflows
-- Creates status file
-**Example: Old Level 3 PRD, New Level 0 Work**
-```
-System: "What's your project called?"
-You: "PaymentApp"
+---
-System: "I found: PRD.md (Level 3, 30 stories, 6mo ago), src/ codebase"
-System: "Are these works in progress, previous effort, or proposed work?"
+## Workflow Phases by Track
-You: "b - Previous effort"
+### Phase 1: Analysis (Optional)
-System: "Tell me about what you're working on"
-You: "I need to update payment method enums"
+**Workflows:**
-System: "Level 0 brownfield project. Is that correct?"
-You: "yes"
+- `brainstorm-project` - Solution exploration
+- `research` - Technical/market research
+- `product-brief` - Strategic planning (BMad Method/Enterprise tracks only)
-✅ Creates Level 0 workflow
-```
+**When to use:** Complex features, technical decisions, strategic additions
-**Smart Features:**
+**When to skip:** Bug fixes, well-understood features, time-sensitive changes
-- Asks about YOUR work first
-- Uses artifacts as context, not primary source
-- Keyword detection: "fix", "update" → Level 0
-- Handles scaffolds: "Just a starter" → still greenfield
-- Flags missing documentation automatically
+See [Workflows Guide](../workflows/README.md) for details.
-## Key Artifacts in Brownfield Projects
-### Tracking Documents
+### Phase 2: Planning (Required)
-**`bmm-workflow-status.md`** (Phases 0-3)
+**Planning approach adapts by track:**
-- Current phase and progress
-- Workflow history
-- Next recommended actions
-- Project metadata
+**Quick Flow:** Use `tech-spec` workflow
-**`sprint-status.yaml`** (Phase 4 only)
+- Creates tech-spec.md
+- Auto-detects existing stack (brownfield)
+- Confirms conventions with you
+- Generates implementation-ready stories
-- All epics, stories, retrospectives
-- Current status for each item
-- Single source of truth for implementation
-- Updated by agents as work progresses
+**BMad Method/Enterprise:** Use `prd` workflow
-### Planning Documents
+- Creates PRD.md + epic breakdown
+- References existing architecture
+- Plans integration points
-**Level 0-1:**
+**Brownfield-specific:** See [Scale Adaptive System](./scale-adaptive-system.md) for complete workflow paths by track.
-- `tech-spec.md` - Technical specification
-- `story-{key}.md` - Story files
+### Phase 3: Solutioning (BMad Method/Enterprise Only)
-**Level 2:**
+**Critical for brownfield:**
-- `PRD.md` - Product requirements
-- `epics.md` - Epic breakdown
-- `tech-spec.md` - Technical specification
+- Review existing architecture FIRST
+- Document integration points explicitly
+- Plan backward compatibility
+- Consider migration strategy
+**Workflows:**
+- `create-architecture` - Extend architecture docs (BMad Method/Enterprise)
+- `solutioning-gate-check` - Validate before implementation (BMad Method/Enterprise)
+### Phase 4: Implementation (All Tracks)
+**Sprint-based development through story iteration:**
+```mermaid
+flowchart TD
+    SPRINT[sprint-planning<br/>Initialize tracking]
+    EPIC[epic-tech-context<br/>Per epic]
+    CREATE[create-story]
+    CONTEXT[story-context]
+    DEV[dev-story]
+    REVIEW[code-review]
+    CHECK{More stories?}
+    RETRO[retrospective<br/>Per epic]
+    SPRINT --> EPIC
+    EPIC --> CREATE
+    CREATE --> CONTEXT
+    CONTEXT --> DEV
+    DEV --> REVIEW
+    REVIEW --> CHECK
+    CHECK -->|Yes| CREATE
+    CHECK -->|No| RETRO
+    style SPRINT fill:#bfb,stroke:#333,stroke-width:2px
+    style RETRO fill:#fbf,stroke:#333,stroke-width:2px
+```
-**Level 3-4:**
+**Status Progression:**
-- `PRD.md` - Product requirements
-- `epics.md` - Epic breakdown
-- `architecture.md` - Architecture extensions
-- Integration and validation reports
+- Epic: `backlog → contexted`
+- Story: `backlog → drafted → ready-for-dev → in-progress → review → done`
-### Implementation Documents
+**Brownfield-Specific Implementation Tips:**
-**Phase 4 Artifacts:**
+1. **Respect existing patterns** - Follow established conventions
+2. **Test integration thoroughly** - Validate interactions with existing code
+3. **Use feature flags** - Enable gradual rollout
+4. **Context injection matters** - epic-tech-context and story-context reference existing patterns
-- `sprint-status.yaml` - Status tracking
-- `epic-{n}-context.md` - Epic technical contexts
-- `stories/` directory:
-  - `{epic}-{story}-{title}.md` - Story definitions
-  - `{epic}-{story}-{title}-context.md` - Implementation contexts
+---
-## Best Practices for Brownfield Success
+## Best Practices
 ### 1. Always Document First
-Even if you know the codebase well, AI agents need comprehensive context. Run `document-project` with appropriate scan level before planning.
-**Why:** AI discovers undocumented patterns, integration points, and constraints that humans might overlook or take for granted.
-**Important:** Even if you have good documentation (README, ARCHITECTURE.md, etc.), you still need `docs/index.md` as the master AI retrieval source. If you have docs but no index:
-- **Quick fix:** Run the `index-docs` task (lightweight, just creates index)
-- **Comprehensive:** Use `document-project` with Deep scan to create index AND enhance docs
-- The index provides structured navigation for AI agents
-### 2. Be Specific About Your Current Work
-When `workflow-init` asks about your work, be specific about what you're doing NOW:
-**Good descriptions:**
-- "I need to update payment method enums to include Apple Pay"
-- "Adding forgot password feature to existing auth system"
-- "Building admin dashboard with analytics and user management"
+Even if you know the code, AI agents need `document-project` output for context. Run it before planning.
-**Why this matters:** The system uses your description to suggest the right complexity level. Clear, specific descriptions lead to accurate routing through appropriate workflows.
+### 2. Be Specific About Current Work
-### 3. Choose the Right Documentation Approach
+When workflow-init asks about your work:
-**For existing docs without index:**
+- ✅ "Update payment method enums to include Apple Pay"
+- ❌ "Fix stuff"
-- Use `index-docs` task - fast, lightweight, just generates index
-- Located at `bmad/core/tasks/index-docs.xml`
+### 3. Choose Right Documentation Approach
-**For comprehensive codebase documentation:**
-- Use `document-project` workflow with appropriate scan level:
-  - **Quick:** Fast overview, planning next steps
-  - **Deep:** Brownfield PRD preparation (most common)
-  - **Exhaustive:** Migration planning, complete understanding
+- **Has good docs, no index?** → Run `index-docs` task (fast)
+- **No docs or need codebase analysis?** → Run `document-project` (Deep scan)
 ### 4. Respect Existing Patterns
-The brownfield templates identify:
-- Current coding conventions
-- Architectural approaches
-- Technology constraints
-- Team preferences
-**Always preserve these unless explicitly modernizing them.**
+Tech-spec and story-context will detect conventions. Follow them unless explicitly modernizing.
 ### 5. Plan Integration Points Explicitly
-Document in your tech-spec or architecture:
+Document in tech-spec/architecture:
 - Which existing modules you'll modify
 - What APIs/services you'll integrate with
 - How data flows between new and existing code
-- What shared components you'll reuse
 ### 6. Design for Gradual Rollout
-Brownfield changes should support:
-- Feature flags for new functionality
-- Rollback strategies
-- Backward compatibility
-- Migration scripts (if needed)
+- Use feature flags for new functionality
+- Plan rollback strategies
+- Maintain backward compatibility
+- Create migration scripts if needed
 ### 7. Test Integration Thoroughly
-Use the Test Architect (TEA) workflows:
-- `test-design` - Plan integration test strategy
-- `test-review` - Validate test coverage
-- `nfr-assess` - Check performance/security impact
-**Critical for Brownfield:**
 - Regression testing of existing features
 - Integration point validation
 - Performance impact assessment
@@ -804,457 +403,357 @@ Use the Test Architect (TEA) workflows:
 - Run `sprint-planning` at Phase 4 start
 - Context epics before drafting stories
 - Update `sprint-status.yaml` as work progresses
-- Re-run sprint-planning to sync with file system
 ### 9. Leverage Context Injection
 - Run `epic-tech-context` before story drafting
 - Always create `story-context` before implementation
-- These workflows reference existing patterns for consistency
+- These reference existing patterns for consistency
 ### 10. Learn Continuously
 - Run `retrospective` after each epic
-- Incorporate learnings into next story drafts
-- Update patterns discovered during development
+- Incorporate learnings into next stories
+- Update discovered patterns
 - Share insights across team
-## Common Brownfield Scenarios
+---
+## Common Scenarios
-### Scenario 1: Bug Fix (Level 0)
+### Scenario 1: Bug Fix (Quick Flow)
 **Situation:** Authentication token expiration causing logout issues
+**Track:** Quick Flow
 **Workflow:**
-1. `workflow-status` → detects brownfield, suggests Level 0
-2. Skip Phase 0 if auth system is documented
-3. `tech-spec` → analyzes bug, plans fix, creates single story
-4. `sprint-planning` → creates sprint status
-5. `dev-story` → implement fix
-6. `code-review` → validate fix + test regression
+1. **Document:** Skip if auth system documented, else run `document-project` (Quick scan)
+2. **Plan:** Load PM → run `tech-spec`
+   - Analyzes bug
+   - Detects stack (Express, Jest)
+   - Confirms conventions
+   - Creates tech-spec.md + story
+3. **Implement:** Load DEV → run `dev-story`
+4. **Review:** Load DEV → run `code-review`
+**Time:** 2-4 hours
-**Time:** ~2-4 hours total
+---
-### Scenario 2: Small Feature (Level 1)
+### Scenario 2: Small Feature (Quick Flow)
 **Situation:** Add "forgot password" to existing auth system
+**Track:** Quick Flow
 **Workflow:**
-1. `workflow-status` → suggests Level 1
-2. Phase 0: `document-project` (deep scan of auth module if not documented)
-3. Phase 1: Optional - skip if requirements are clear
-4. Phase 2: `tech-spec` → creates epic with 3-5 stories
-5. Phase 4: `sprint-planning` → `create-story` → `dev-story` → repeat
+1. **Document:** Run `document-project` (Deep scan of auth module if not documented)
+2. **Plan:** Load PM → run `tech-spec`
+   - Detects Next.js 13.4, NextAuth.js
+   - Analyzes existing auth patterns
+   - Confirms conventions
+   - Creates tech-spec.md + epic + 3-5 stories
+3. **Implement:** Load SM → `sprint-planning` → `create-story` → `story-context`
+   Load DEV → `dev-story` for each story
+4. **Review:** Load DEV → `code-review`
 **Time:** 1-3 days
-### Scenario 3: Feature Set (Level 2)
+---
+### Scenario 3: Feature Set (BMad Method)
 **Situation:** Add user dashboard with analytics, preferences, activity
+**Track:** BMad Method
 **Workflow:**
-1. `workflow-status` → suggests Level 2
-2. Phase 0: `document-project` (deep scan) - critical for understanding existing UI patterns
-3. Phase 1: `research` (if evaluating analytics libraries)
-4. Phase 2: `prd` → `tech-spec`
-5. Phase 4: Sprint-based implementation (10-15 stories)
+1. **Document:** Run `document-project` (Deep scan) - Critical for understanding existing UI patterns
+2. **Analyze:** Load Analyst → `research` (if evaluating analytics libraries)
+3. **Plan:** Load PM → `prd`
+4. **Solution:** Load Architect → `create-architecture` → `solutioning-gate-check`
+5. **Implement:** Sprint-based (10-15 stories)
+   - Load SM → `sprint-planning`
+   - Per epic: `epic-tech-context` → stories
+   - Load DEV → `dev-story` per story
+6. **Review:** Per story completion
 **Time:** 1-2 weeks
-### Scenario 4: Complex Integration (Level 3)
+---
+### Scenario 4: Complex Integration (BMad Method)
 **Situation:** Add real-time collaboration to document editor
+**Track:** BMad Method
 **Workflow:**
-1. `workflow-status` → suggests Level 3
-2. Phase 0: `document-project` (exhaustive if not documented)
-3. Phase 1: `research` (WebSocket vs WebRTC vs CRDT)
-4. Phase 2: `prd` → creates requirements + epics
-5. Phase 3:
-   - `architecture-review` → understand existing editor architecture
-   - `integration-planning` → plan WebSocket integration strategy
-   - `create-architecture` → extend architecture for real-time layer
-   - `solutioning-gate-check` → validate before implementation
-6. Phase 4: Sprint-based implementation (20-30 stories)
+1. **Document:** Run `document-project` (Exhaustive if not documented) - **Mandatory**
+2. **Analyze:** Load Analyst → `research` (WebSocket vs WebRTC vs CRDT)
+3. **Plan:** Load PM → `prd`
+4. **Solution:**
+   - Load Architect → `create-architecture` (extend for real-time layer)
+   - Load Architect → `solutioning-gate-check`
+5. **Implement:** Sprint-based (20-30 stories)
 **Time:** 3-6 weeks
-### Scenario 5: Enterprise Expansion (Level 4)
+---
+### Scenario 5: Enterprise Expansion (Enterprise Method)
 **Situation:** Add multi-tenancy to single-tenant SaaS platform
+**Track:** Enterprise Method
 **Workflow:**
-1. `workflow-status` → suggests Level 4
-2. Phase 0: `document-project` (exhaustive) - **mandatory**
-3. Phase 1: **Required**
-   - `brainstorm-project` → explore multi-tenancy approaches
-   - `research` → database sharding, tenant isolation, pricing models
-   - `product-brief` → strategic document
-4. Phase 2: `prd` → comprehensive requirements
-5. Phase 3:
-   - `architecture-review` → full existing system review
-   - `integration-planning` → phased migration strategy
-   - `create-architecture` → multi-tenancy architecture
-   - `validate-architecture` → external review
-   - `solutioning-gate-check` → executive approval
-6. Phase 4: Phased sprint-based implementation (50+ stories)
+1. **Document:** Run `document-project` (Exhaustive) - **Mandatory**
+2. **Analyze:** **Required**
+   - `brainstorm-project` - Explore multi-tenancy approaches
+   - `research` - Database sharding, tenant isolation, pricing
+   - `product-brief` - Strategic document
+3. **Plan:** Load PM → `prd` (comprehensive)
+4. **Solution:**
+   - `create-architecture` - Full system architecture
+   - `integration-planning` - Phased migration strategy
+   - `create-architecture` - Multi-tenancy architecture
+   - `validate-architecture` - External review
+   - `solutioning-gate-check` - Executive approval
+5. **Implement:** Phased sprint-based (50+ stories)
 **Time:** 3-6 months
-## Troubleshooting Common Issues
-### Issue: AI Lacks Codebase Understanding
-**Symptoms:**
-- Generated plans don't align with existing patterns
-- Suggestions ignore available components
-- Integration approaches miss existing APIs
+---
-**Solution:**
+## Troubleshooting
-1. Run `document-project` with deep or exhaustive scan
-2. Review `index.md` - ensure it captures key systems
-3. If specific area is unclear, run deep-dive mode on that area
-4. Provide additional context in PRD about existing systems
+For complete troubleshooting, see [Troubleshooting Guide](./troubleshooting.md).
-### Issue: Have Documentation But Agents Can't Find It
+### AI Agents Lack Codebase Understanding
 **Symptoms:**
-- You have README, ARCHITECTURE.md, CONTRIBUTING.md, etc.
-- But AI agents aren't using the information effectively
-- Agents ask questions already answered in existing docs
-- No `docs/index.md` file exists
+- Suggestions don't align with existing patterns
+- Ignores available components
+- Doesn't reference existing code
 **Solution:**
-1. **Quick fix:** Run the `index-docs` task (from `bmad/core/tasks/index-docs.xml`)
-   - Lightweight and fast (just indexes existing docs)
-   - Scans your docs directory
-   - Generates organized `index.md` with file descriptions
-   - Provides AI agents with structured navigation
-2. **Comprehensive approach:** Run `document-project` with Deep/Exhaustive scan
-   - Discovers existing docs in Step 2 (shows you what it found)
-   - Generates NEW AI-friendly documentation from codebase analysis
-   - Creates index.md that links to BOTH existing docs AND new docs
-   - Useful when existing docs are good but need technical codebase analysis too
-**Why This Happens:** AI agents need a structured entry point (`index.md`) to efficiently navigate documentation. Without it, they must search through multiple files, often missing relevant context.
+1. Run `document-project` with Deep scan
+2. Verify `docs/index.md` exists
+3. Check documentation completeness
+4. Run deep-dive on specific areas if needed
-### Issue: Plans Feel Too Complex for Simple Changes
+### Have Documentation But Agents Can't Find It
 **Symptoms:**
-- Level 2+ workflow suggested for minor change
-- Too much documentation overhead
+- README.md, ARCHITECTURE.md exist
+- AI agents ask questions already answered
+- No `docs/index.md` file
 **Solution:**
-1. Re-run `workflow-status` or `workflow-init`
-2. Correct the level when prompted (choose Level 0 or 1)
-3. Trust your judgment - BMad Method adapts to your choice
-4. Skip optional phases (Analysis)
+- **Quick fix:** Run `index-docs` task (2-5min)
+- **Comprehensive:** Run `document-project` workflow (10-30min)
-### Issue: Integration Points Unclear
+### Integration Points Unclear
 **Symptoms:**
-- Stories lack detail on connecting to existing systems
-- Uncertainty about which existing code to modify
+- Not sure how to connect new code to existing
+- Unsure which files to modify
 **Solution:**
-1. Ensure Phase 0 documentation is complete
-2. Run deep-dive on integration areas in `document-project`
-3. In Phase 2, explicitly document integration points
-4. In Phase 3 (if Level 3+), use `integration-planning` workflow
-5. Create detailed `epic-tech-context` and `story-context`
+1. Ensure `document-project` captured existing architecture
+2. Check `story-context` - should document integration points
+3. In tech-spec/architecture - explicitly document:
+   - Which existing modules to modify
+   - What APIs/services to integrate with
+   - Data flow between new and existing code
+4. Review architecture document for integration guidance
-### Issue: Existing Tests Breaking
+### Existing Tests Breaking
 **Symptoms:**
 - Regression test failures
-- Existing functionality broken by changes
+- Previously working functionality broken
 **Solution:**
-1. Review existing test patterns in documentation
-2. Use Test Architect workflows:
-   - `test-design` - Plan test strategy upfront
-   - `trace` - Map requirements to tests
-   - `test-review` - Validate before merging
-3. Add regression testing to Definition of Done
-4. Consider feature flags for gradual rollout
+1. Review changes against existing patterns
+2. Verify API contracts unchanged (unless intentionally versioned)
+3. Run `test-review` workflow (TEA agent)
+4. Add regression testing to DoD
+5. Consider feature flags for gradual rollout
-### Issue: Inconsistent Patterns Being Introduced
+### Inconsistent Patterns Being Introduced
 **Symptoms:**
-- New code doesn't match existing style
-- Different architectural approach than existing modules
+- New code style doesn't match existing
+- Different architectural approach
 **Solution:**
-1. Ensure `document-project` captured existing patterns
-2. Review architecture documentation before Phase 4
-3. Use `story-context` to inject pattern guidance
-4. Include pattern adherence in `code-review` checklist
-5. Run retrospectives to identify pattern deviations
-## Test Architect Integration
-The Test Architect (TEA) plays a critical role in brownfield projects to prevent regression and validate integration.
-### Four-Stage Approach
-**Stage 1 (Before Development):**
-- Risk assessment identifying legacy dependencies
-- Test design planning for regression + new features
-- Integration point identification
-**Stage 2 (During Development):**
+1. Check convention detection (Quick Spec Flow should detect patterns)
+2. Review documentation - ensure `document-project` captured patterns
+3. Use `story-context` - injects pattern guidance
+4. Add to code-review checklist: pattern adherence, convention consistency
+5. Run retrospective to identify deviations early
-- Requirements tracing validating existing functionality preservation
-- NFR validation ensuring performance/security unchanged
-**Stage 3 (Code Review):**
-- Deep analysis of API contracts, data migrations
-- Performance regression checks
-- Integration point validation
-- Dependency mapping
-**Stage 4 (Post-Review):**
-- Gate status updates
-- Technical debt documentation
-### TEA Workflows for Brownfield
-| Workflow      | Purpose                    | When to Use                          |
-| ------------- | -------------------------- | ------------------------------------ |
-| `test-design` | Plan testing strategy      | After Phase 2, before implementation |
-| `test-review` | Validate test coverage     | During story review                  |
-| `trace`       | Map requirements to tests  | After test implementation            |
-| `nfr-assess`  | Check performance/security | Before major releases                |
-| `atdd`        | Acceptance test planning   | For user-facing features             |
-### Risk Scoring for Brownfield
-TEA uses enhanced brownfield metrics:
-- **Regression Risk** = integration_points × code_age
-- **Data Risk** = migration_complexity × data_volume
-- **Performance Risk** = current_load × added_complexity
-- **Compatibility Risk** = api_consumers × contract_changes
-**Automatic Thresholds:**
+---
-- Score ≥9: Automatic failure (must mitigate)
-- Score ≥6: Concern (requires mitigation plan)
-- Score <6: Acceptable (document only)
+## Quick Reference
-## Quick Reference Commands
+### Commands by Phase
 ```bash
-# Universal Entry Point (Always Start Here)
-bmad analyst workflow-status
 # Phase 0: Documentation (If Needed)
-bmad analyst document-project
-# → Choose: Quick / Deep / Exhaustive
+# Analyst agent:
+document-project        # Create comprehensive docs (10-30min)
+# OR load index-docs task for existing docs (2-5min)
 # Phase 1: Analysis (Optional)
-bmad analyst brainstorm-project    # Explore solutions
-bmad analyst research              # Gather technical/market data
-bmad analyst product-brief         # Strategic planning
+# Analyst agent:
+brainstorm-project      # Explore solutions
+research                # Gather data
+product-brief           # Strategic planning (BMad Method/Enterprise only)
 # Phase 2: Planning (Required)
-bmad pm tech-spec           # Level 0-1 only
-bmad pm prd                 # Level 2-4 only
-# Phase 3: Solutioning (Levels 2-4)
-bmad architect architecture-review      # Review existing (L3-4)
-bmad architect integration-planning     # Plan integration (L3-4)
-bmad architect create-architecture      # Extend architecture (L2-4)
-bmad architect solutioning-gate-check   # Final approval (L3-4)
-# Phase 4: Implementation (All Levels)
-bmad sm sprint-planning        # FIRST: Initialize tracking
-bmad sm epic-tech-context      # Create epic context
-bmad sm create-story           # Draft story
-bmad sm story-context          # Create story context
-bmad dev dev-story             # Implement story
-bmad sm code-review           # Review implementation
-# (Manually update sprint-status.yaml to 'done')
-bmad sm retrospective          # After epic completion
-bmad sm correct-course         # If issues arise
-# Test Architect (Integration Throughout)
-bmad tea test-design          # Plan testing strategy
-bmad tea test-review          # Validate test coverage
-bmad tea nfr-assess           # Check performance/security
+# PM agent:
+tech-spec               # Quick Flow track
+prd                     # BMad Method/Enterprise tracks
+# Phase 3: Solutioning (BMad Method/Enterprise)
+# Architect agent:
+create-architecture          # Extend architecture
+solutioning-gate-check       # Final validation
+# Phase 4: Implementation (All Tracks)
+# SM agent:
+sprint-planning              # Initialize tracking
+epic-tech-context            # Epic context
+create-story                 # Draft story
+story-context                # Story context
+# DEV agent:
+dev-story                    # Implement
+code-review                  # Review
+# SM agent:
+retrospective                # After epic
+correct-course               # If issues
 ```
-## Key Files Reference
-### Documentation Phase
-- `docs/index.md` - **Master documentation index (REQUIRED for AI agents)** - Primary entry point
-- `docs/project-overview.md` - Executive summary
-- `docs/architecture.md` - Architecture analysis
-- `docs/source-tree-analysis.md` - Annotated directory structure
-- `docs/api-contracts.md` - API documentation (if applicable)
-- `docs/data-models.md` - Database schemas (if applicable)
-- `docs/deep-dive-{area}.md` - Area-specific deep dives
-- Existing docs (README.md, ARCHITECTURE.md, etc.) - Incorporated and linked from index
-### Planning Phase
+### Key Files
-- `bmm-workflow-status.md` - Phase 0-3 tracking
-- `PRD.md` - Product requirements (L2-4)
-- `epics.md` - Epic breakdown (L2-4)
-- `tech-spec.md` - Technical specification (L0-2)
+**Phase 0 Output:**
-### Solutioning Phase
+- `docs/index.md` - **Master AI entry point (REQUIRED)**
+- `docs/project-overview.md`
+- `docs/architecture.md`
+- `docs/source-tree-analysis.md`
-- `architecture.md` - Architecture extensions (L2-4)
-- `integration-strategy.md` - Integration planning (L3-4)
-- Validation and gate check reports
+**Phase 1-3 Tracking:**
-### Implementation Phase
+- `docs/bmm-workflow-status.yaml` - Progress tracker
-- `sprint-status.yaml` - **Single source of truth** for Phase 4
-- `epic-{n}-context.md` - Epic technical contexts
-- `stories/{epic}-{story}-{title}.md` - Story files
-- `stories/{epic}-{story}-{title}-context.md` - Story contexts
+**Phase 2 Planning:**
-## Comparison: v4 vs v6 Brownfield
+- `docs/tech-spec.md` (Quick Flow track)
+- `docs/PRD.md` (BMad Method/Enterprise tracks)
+- Epic breakdown
-### What Changed
+**Phase 3 Architecture:**
-**v4 Approach:**
+- `docs/architecture.md` (BMad Method/Enterprise tracks)
-- Task-based system with fixed workflows
-- Manual tracking across multiple documents
-- Heavy upfront documentation requirements
-- Rigid phase progression
+**Phase 4 Implementation:**
-**v6 Improvements:**
+- `docs/sprint-status.yaml` - **Single source of truth**
+- `docs/epic-{n}-context.md`
+- `docs/stories/{epic}-{story}-{title}.md`
+- `docs/stories/{epic}-{story}-{title}-context.md`
-- Scale-adaptive workflows (0-4 levels)
-- Unified status tracking (`workflow-status`, `sprint-status.yaml`)
-- Three-level scanning (quick/deep/exhaustive)
-- Just-in-time context injection
-- Flexible resumability
-- Modular workflow paths
-- Intelligent routing system
+### Decision Flowchart
-### Migration from v4
+```mermaid
+flowchart TD
+    START([Brownfield Project])
+    CHECK{Has docs/<br/>index.md?}
-If you used BMad Method v4, here's how to transition:
+    START --> CHECK
+    CHECK -->|No| DOC[document-project<br/>Deep scan]
+    CHECK -->|Yes| TRACK{What Track?}
-**Old v4 Task → New v6 Workflow:**
+    DOC --> TRACK
-- `create-brownfield-prd` → `prd` (with brownfield path)
-- `document-project` → `document-project` (enhanced with scan levels)
-- Legacy task templates → Replaced by workflow system
-- Manual status tracking → `sprint-status.yaml` + agents
+    TRACK -->|Quick Flow| TS[tech-spec]
+    TRACK -->|BMad Method| PRD[prd → architecture]
+    TRACK -->|Enterprise| PRD2[prd → arch + security/devops]
-**Key Conceptual Shifts:**
+    TS --> IMPL[Phase 4<br/>Implementation]
+    PRD --> IMPL
+    PRD2 --> IMPL
-1. **Scale-adaptive planning** - Choose level based on complexity
-2. **Phase 0 is conditional** - Only if documentation is lacking
-3. **Sprint status is centralized** - Single YAML file for Phase 4
-4. **Context injection** - Epic and story contexts provide JIT guidance
-5. **Workflow paths** - Clean separation by level and field type
-## Tips for Success
+    style START fill:#f9f,stroke:#333,stroke-width:2px
+    style DOC fill:#ffb,stroke:#333,stroke-width:2px
+    style IMPL fill:#bfb,stroke:#333,stroke-width:2px
+```
-### For Solo Developers
+---
-1. Don't skip documentation phase - even if you know the code, AI agents need it
-2. Choose appropriate scan level - deep scan is usually best for brownfield PRDs
-3. Use Level 0-1 for small changes - don't over-engineer simple fixes
-4. Trust the sprint planning system - it tracks everything automatically
-5. Be specific when describing your work - helps system route to the right level
+## Prevention Tips
-### For Teams
+**Avoid issues before they happen:**
-1. Document once, use everywhere - Phase 0 documentation serves entire team
-2. Use sprint-status.yaml as single source of truth - no multiple tracking systems
-3. Run retrospectives after epics - transfer learning to next stories
-4. Coordinate parallel work - multiple stories can be in-progress if capacity allows
-5. Establish clear communication about current iteration scope vs historical complexity
+1. ✅ **Always run document-project for brownfield** - Saves context issues later
+2. ✅ **Use fresh chats for complex workflows** - Prevents hallucinations
+3. ✅ **Verify files exist before workflows** - Check PRD, epics, stories present
+4. ✅ **Read agent menu first** - Confirm agent has the workflow
+5. ✅ **Start with simpler track if unsure** - Easy to upgrade (Quick Flow → BMad Method)
+6. ✅ **Keep status files updated** - Manual updates when needed
+7. ✅ **Run retrospectives after epics** - Catch issues early
+8. ✅ **Follow phase sequence** - Don't skip required phases
-### For Enterprise
+---
-1. Phase 0 is mandatory - comprehensive documentation prevents costly mistakes
-2. Include stakeholders early - Analysis phase (Phase 1) gathers business context
-3. Use gate checks - `solutioning-gate-check` provides approval checkpoint
-4. Plan phased rollout - feature flags and migration strategies are critical
-5. Document architectural extensions - maintain system documentation as you evolve
-6. Consider archiving completed planning artifacts to keep workspace clean
+## Related Documentation
-## Support and Resources
+- **[Scale Adaptive System](./scale-adaptive-system.md)** - Understanding tracks and complexity
+- **[Quick Spec Flow](./quick-spec-flow.md)** - Fast-track for Quick Flow
+- **[Quick Start Guide](./quick-start.md)** - Getting started with BMM
+- **[Glossary](./glossary.md)** - Key terminology
+- **[FAQ](./faq.md)** - Common questions
+- **[Troubleshooting](./troubleshooting.md)** - Problem resolution
+- **[Workflows Guide](../workflows/README.md)** - Complete workflow reference
-**Documentation:**
+---
-- [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Complete v6 workflow reference
-- [Test Architect Guide](../src/modules/bmm/testarch/README.md) - Quality and testing strategy
-- [BMM Module README](../src/modules/bmm/README.md) - Module overview
+## Support & Resources
 **Community:**
-- Discord: [https://discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) (#general-dev, #bugs-issues)
-- GitHub Issues: [https://github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
-- YouTube: [https://www.youtube.com/@BMadCode](https://www.youtube.com/@BMadCode)
+- [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
+- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
+- [YouTube Channel](https://www.youtube.com/@BMadCode)
-**Getting Started:**
-```bash
-# Install BMad Method
-npx bmad-method install
+**Documentation:**
-# Start your first brownfield project
-cd your-project
-bmad analyst workflow-status
-```
+- [BMM Workflows Guide](../workflows/README.md)
+- [Test Architect Guide](../testarch/README.md)
+- [BMM Module README](../README.md)
 ---
-## Remember
-**Brownfield development** is about understanding and respecting what exists while thoughtfully extending it. BMad Method v6's scale-adaptive approach ensures you get the right level of planning and documentation without unnecessary overhead.
-**Key Principles:**
-1. **Ask First, Infer Second**: The system asks about YOUR work first, then uses artifacts as context
-2. **Scale Adapts**: From single fixes (Level 0) to enterprise expansions (Level 4)
-3. **Documentation Matters**: AI agents need comprehensive context to work effectively
-4. **Context Injection**: Epic and story contexts provide just-in-time guidance
-5. **Sprint-Based Tracking**: Single source of truth keeps everyone aligned
-**Quick Start:**
-```bash
-cd your-brownfield-project
-bmad analyst workflow-status
-# System will guide you through:
-# 1. What's your project called?
-# 2. What are you working on? (if finds old work: "is this continuing old work or new work?")
-# 3. Confirms detected level
-# 4. Creates appropriate workflow
-```
-**The system is designed to understand YOUR current work and route you to the right workflows.**
+_Brownfield development is about understanding and respecting what exists while thoughtfully extending it._