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

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

@@ -1,759 +0,0 @@
-# BMad Method Brownfield Development Guide
-
-**Complete guide for working with existing codebases**
-
-**Reading Time:** ~35 minutes
-
----
-
-## Quick Navigation
-
-**Jump to:**
-
-- [Quick Reference](#quick-reference) - Commands and files
-- [Common Scenarios](#common-scenarios) - Real-world examples
-- [Troubleshooting](#troubleshooting) - Problem solutions
-- [Best Practices](#best-practices) - Success tips
-
----
-
-## What is Brownfield Development?
-
-Brownfield projects involve working within existing codebases rather than starting fresh:
-
-- **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
-
-**Key Difference from Greenfield:** You must understand and respect existing patterns, architecture, and constraints.
-
-**Core Principle:** AI agents need comprehensive documentation to understand existing code before they can effectively plan or implement changes.
-
----
-
-## Getting Started
-
-### Understanding Planning Tracks
-
-For complete track details, see [Scale Adaptive System](./scale-adaptive-system.md).
-
-**Brownfield tracks at a glance:**
-
-| 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 |
-
-**Note:** Story counts are guidance, not definitions. Tracks are chosen based on planning needs.
-
-### Track Selection for Brownfield
-
-When you run `workflow-init`, it handles brownfield intelligently:
-
-**Step 1: Shows what it found**
-
-- Old planning docs (PRD, epics, stories)
-- Existing codebase
-
-**Step 2: Asks about YOUR work**
-
-> "Are these works in progress, previous effort, or proposed 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
-
-**Step 3: Analyzes your description**
-
-- Keywords: "fix", "bug" → Quick Flow, "dashboard", "platform" → BMad Method, "enterprise", "multi-tenant" → Enterprise Method
-- Complexity assessment
-- Confirms suggested track with you
-
-**Key Principle:** System asks about YOUR current work first, uses old artifacts as context only.
-
-**Example: Old Complex PRD, New Simple Work**
-
-```
-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 0: Documentation (Critical First Step)
-
-🚨 **For brownfield projects: Always ensure adequate AI-usable documentation before planning**
-
-### Default Recommendation: Run document-project
-
-**Best practice:** Run `document-project` workflow unless you have **confirmed, trusted, AI-optimized documentation**.
-
-### Why Document-Project is Almost Always the Right Choice
-
-Existing documentation often has quality issues that break AI workflows:
-
-**Common Problems:**
-
-- **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
-
-**Impact on AI Agents:**
-
-- 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
-
-### Documentation Decision Tree
-
-**Step 1: Assess Existing Documentation Quality**
-
-Ask yourself:
-
-- ✅ 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?
-
-**If ANY answer is NO → Run `document-project`**
-
-**Step 2: Check for Massive Documents**
-
-If you have documentation but files are huge (>500 lines, 10+ level 2 sections):
-
-1. **First:** Run `shard-doc` tool to split large files:
-
-   ```bash
-   # Load BMad Master or any agent
-   bmad/core/tools/shard-doc.xml --input docs/massive-doc.md
-   ```
-
-   - Splits on level 2 sections by default
-   - Creates organized, manageable files
-   - Preserves content integrity
-
-2. **Then:** Run `index-docs` task to create navigation:
-
-   ```bash
-   bmad/core/tasks/index-docs.xml --directory ./docs
-   ```
-
-3. **Finally:** Validate quality - if sharded docs still seem incomplete/outdated → Run `document-project`
-
-### Four Real-World Scenarios
-
-| 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    |
-
-### Scenario A: No Documentation (Most Common)
-
-**Action: Run document-project workflow**
-
-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
-
-**Outputs:**
-
-- `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.)
-
-### Scenario B: Docs Exist But Quality Unknown/Poor (Very Common)
-
-**Action: Run document-project workflow (regenerate)**
-
-Even if `docs/` folder exists, if you're unsure about quality → **regenerate**.
-
-**Why regenerate instead of index?**
-
-- 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
-
-**document-project** will:
-
-- Scan actual codebase (source of truth)
-- Generate fresh, accurate documentation
-- Structure properly for AI consumption
-- Include only relevant, current information
-
-### Scenario C: Good Docs But Needs Structure
-
-**Action: Shard massive files, then index**
-
-If you have **good, current documentation** but it's in massive files:
-
-**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)
-```
-
-**Step 2: Generate index**
-
-```bash
-bmad/core/tasks/index-docs.xml --directory ./docs
-```
-
-**Step 3: Validate**
-
-- 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**
-
-### Scenario D: Confirmed AI-Optimized Documentation (Rare)
-
-**Action: Skip Phase 0**
-
-Only skip if ALL conditions met:
-
-- ✅ `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
-
-**If unsure → Run document-project** (costs 10-30 minutes, saves hours of confusion)
-
-### Why document-project is Critical
-
-Without AI-optimized documentation, workflows fail:
-
-- **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
-
-### Key Principle
-
-**When in doubt, run document-project.**
-
-It's better to spend 10-30 minutes generating fresh, accurate docs than to waste hours debugging AI agents working from bad documentation.
-
----
-
-## Workflow Phases by Track
-
-### Phase 1: Analysis (Optional)
-
-**Workflows:**
-
-- `brainstorm-project` - Solution exploration
-- `research` - Technical/market research
-- `product-brief` - Strategic planning (BMad Method/Enterprise tracks only)
-
-**When to use:** Complex features, technical decisions, strategic additions
-
-**When to skip:** Bug fixes, well-understood features, time-sensitive changes
-
-See [Workflows Guide](../workflows/README.md) for details.
-
-### Phase 2: Planning (Required)
-
-**Planning approach adapts by track:**
-
-**Quick Flow:** Use `tech-spec` workflow
-
-- Creates tech-spec.md
-- Auto-detects existing stack (brownfield)
-- Confirms conventions with you
-- Generates implementation-ready stories
-
-**BMad Method/Enterprise:** Use `prd` workflow
-
-- Creates PRD.md + epic breakdown
-- References existing architecture
-- Plans integration points
-
-**Brownfield-specific:** See [Scale Adaptive System](./scale-adaptive-system.md) for complete workflow paths by track.
-
-### Phase 3: Solutioning (BMad Method/Enterprise Only)
-
-**Critical for brownfield:**
-
-- 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
-```
-
-**Status Progression:**
-
-- Epic: `backlog → contexted`
-- Story: `backlog → drafted → ready-for-dev → in-progress → review → done`
-
-**Brownfield-Specific Implementation Tips:**
-
-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
-
----
-
-## Best Practices
-
-### 1. Always Document First
-
-Even if you know the code, AI agents need `document-project` output for context. Run it before planning.
-
-### 2. Be Specific About Current Work
-
-When workflow-init asks about your work:
-
-- ✅ "Update payment method enums to include Apple Pay"
-- ❌ "Fix stuff"
-
-### 3. Choose Right Documentation Approach
-
-- **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
-
-Tech-spec and story-context will detect conventions. Follow them unless explicitly modernizing.
-
-### 5. Plan Integration Points Explicitly
-
-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
-
-### 6. Design for Gradual Rollout
-
-- Use feature flags for new functionality
-- Plan rollback strategies
-- Maintain backward compatibility
-- Create migration scripts if needed
-
-### 7. Test Integration Thoroughly
-
-- Regression testing of existing features
-- Integration point validation
-- Performance impact assessment
-- API contract verification
-
-### 8. Use Sprint Planning Effectively
-
-- Run `sprint-planning` at Phase 4 start
-- Context epics before drafting stories
-- Update `sprint-status.yaml` as work progresses
-
-### 9. Leverage Context Injection
-
-- Run `epic-tech-context` before story drafting
-- Always create `story-context` before implementation
-- These reference existing patterns for consistency
-
-### 10. Learn Continuously
-
-- Run `retrospective` after each epic
-- Incorporate learnings into next stories
-- Update discovered patterns
-- Share insights across team
-
----
-
-## Common Scenarios
-
-### Scenario 1: Bug Fix (Quick Flow)
-
-**Situation:** Authentication token expiration causing logout issues
-
-**Track:** Quick Flow
-
-**Workflow:**
-
-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
-
----
-
-### Scenario 2: Small Feature (Quick Flow)
-
-**Situation:** Add "forgot password" to existing auth system
-
-**Track:** Quick Flow
-
-**Workflow:**
-
-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 (BMad Method)
-
-**Situation:** Add user dashboard with analytics, preferences, activity
-
-**Track:** BMad Method
-
-**Workflow:**
-
-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 (BMad Method)
-
-**Situation:** Add real-time collaboration to document editor
-
-**Track:** BMad Method
-
-**Workflow:**
-
-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 (Enterprise Method)
-
-**Situation:** Add multi-tenancy to single-tenant SaaS platform
-
-**Track:** Enterprise Method
-
-**Workflow:**
-
-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
-
-For complete troubleshooting, see [Troubleshooting Guide](./troubleshooting.md).
-
-### AI Agents Lack Codebase Understanding
-
-**Symptoms:**
-
-- Suggestions don't align with existing patterns
-- Ignores available components
-- Doesn't reference existing code
-
-**Solution:**
-
-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
-
-### Have Documentation But Agents Can't Find It
-
-**Symptoms:**
-
-- README.md, ARCHITECTURE.md exist
-- AI agents ask questions already answered
-- No `docs/index.md` file
-
-**Solution:**
-
-- **Quick fix:** Run `index-docs` task (2-5min)
-- **Comprehensive:** Run `document-project` workflow (10-30min)
-
-### Integration Points Unclear
-
-**Symptoms:**
-
-- Not sure how to connect new code to existing
-- Unsure which files to modify
-
-**Solution:**
-
-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
-
-### Existing Tests Breaking
-
-**Symptoms:**
-
-- Regression test failures
-- Previously working functionality broken
-
-**Solution:**
-
-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
-
-### Inconsistent Patterns Being Introduced
-
-**Symptoms:**
-
-- New code style doesn't match existing
-- Different architectural approach
-
-**Solution:**
-
-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
-
----
-
-## Quick Reference
-
-### Commands by Phase
-
-```bash
-# Phase 0: Documentation (If Needed)
-# Analyst agent:
-document-project        # Create comprehensive docs (10-30min)
-# OR load index-docs task for existing docs (2-5min)
-
-# Phase 1: Analysis (Optional)
-# Analyst agent:
-brainstorm-project      # Explore solutions
-research                # Gather data
-product-brief           # Strategic planning (BMad Method/Enterprise only)
-
-# Phase 2: Planning (Required)
-# 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
-
-**Phase 0 Output:**
-
-- `docs/index.md` - **Master AI entry point (REQUIRED)**
-- `docs/project-overview.md`
-- `docs/architecture.md`
-- `docs/source-tree-analysis.md`
-
-**Phase 1-3 Tracking:**
-
-- `docs/bmm-workflow-status.yaml` - Progress tracker
-
-**Phase 2 Planning:**
-
-- `docs/tech-spec.md` (Quick Flow track)
-- `docs/PRD.md` (BMad Method/Enterprise tracks)
-- Epic breakdown
-
-**Phase 3 Architecture:**
-
-- `docs/architecture.md` (BMad Method/Enterprise tracks)
-
-**Phase 4 Implementation:**
-
-- `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`
-
-### Decision Flowchart
-
-```mermaid
-flowchart TD
-    START([Brownfield Project])
-    CHECK{Has docs/<br/>index.md?}
-
-    START --> CHECK
-    CHECK -->|No| DOC[document-project<br/>Deep scan]
-    CHECK -->|Yes| TRACK{What Track?}
-
-    DOC --> TRACK
-
-    TRACK -->|Quick Flow| TS[tech-spec]
-    TRACK -->|BMad Method| PRD[prd → architecture]
-    TRACK -->|Enterprise| PRD2[prd → arch + security/devops]
-
-    TS --> IMPL[Phase 4<br/>Implementation]
-    PRD --> IMPL
-    PRD2 --> IMPL
-
-    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
-```
-
----
-
-## Prevention Tips
-
-**Avoid issues before they happen:**
-
-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
-
----
-
-## Related Documentation
-
-- **[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
-
----
-
-## Support & Resources
-
-**Community:**
-
-- [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)
-
-**Documentation:**
-
-- [BMM Workflows Guide](../workflows/README.md)
-- [Test Architect Guide](../testarch/README.md)
-- [BMM Module README](../README.md)
-
----
-
-_Brownfield development is about understanding and respecting what exists while thoughtfully extending it._