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

package/src/modules/bmm/docs/brownfield-guide.md

@@ -35,21 +35,21 @@ Brownfield projects involve working within existing codebases rather than starti
 
 ## Getting Started
 
-### Understanding Project Levels
+### Understanding Planning Tracks
 
-For complete level details, see [Scale Adaptive System](./scale-adaptive-system.md).
+For complete track details, see [Scale Adaptive System](./scale-adaptive-system.md).
 
-**Brownfield levels at a glance:**
+**Brownfield tracks at a glance:**
 
-| Level | Scope                | Stories | Key Difference                     |
-| ----- | -------------------- | ------- | ---------------------------------- |
-| **0** | Bug fix              | 1       | Must understand affected code      |
-| **1** | Small feature        | 1-10    | Respect existing patterns          |
-| **2** | Feature set          | 5-15    | Integrate with architecture        |
-| **3** | Complex integration  | 12-40   | Review existing architecture first |
-| **4** | Enterprise expansion | 40+     | Full system documentation required |
+| 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 |
 
-### Level Detection for Brownfield
+**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:
 
@@ -69,45 +69,105 @@ When you run `workflow-init`, it handles brownfield intelligently:
 
 **Step 3: Analyzes your description**
 
-- Keywords: "fix" → Level 0, "add feature" → Level 1, "dashboard" → Level 2
-- Story count estimation
-- Confirms suggested level with you
+- 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 Level 3 PRD, New Level 0 Work**
+**Example: Old Complex PRD, New Simple Work**
 
 ```
-System: "Found PRD.md (Level 3, 30 stories, 6 months old)"
+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: "Level 0 brownfield. Correct?"
+System: "Quick Flow track (tech-spec approach). Correct?"
 You: "Yes"
-✅ Creates Level 0 workflow
+✅ Creates Quick Flow workflow
 ```
 
 ---
 
 ## Phase 0: Documentation (Critical First Step)
 
-🚨 **For brownfield projects: Always ensure adequate documentation before planning**
+🚨 **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?
 
-### Three Scenarios
+**If ANY answer is NO → Run `document-project`**
 
-| Scenario | You Have                    | Action               | Tool     | Time   |
-| -------- | --------------------------- | -------------------- | -------- | ------ |
-| **A**    | No documentation            | Run document-project | Workflow | 10-30m |
-| **B**    | Docs exist, no index.md     | Run index-docs       | Task     | 2-5m   |
-| **C**    | Complete docs with index.md | Skip Phase 0         | -        | 0m     |
+**Step 2: Check for Massive Documents**
 
-### Scenario A: No Documentation
+If you have documentation but files are huge (>500 lines, 10+ level 2 sections):
 
-**Run document-project workflow:**
+1. **First:** Run `shard-doc` tool to split large files:
 
-1. Load Analyst agent
-2. Run "document-project"
+   ```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**
@@ -119,35 +179,91 @@ You: "Yes"
 - `docs/project-overview.md` - Executive summary
 - `docs/architecture.md` - Architecture analysis
 - `docs/source-tree-analysis.md` - Directory structure
-- Additional files based on project type
+- 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**.
 
-### Scenario B: Docs Exist, No Index
+**Why regenerate instead of index?**
 
-**Run index-docs task:**
+- 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
 
-1. Load BMad Master agent (or any agent with task access)
-2. Load task: `bmad/core/tasks/index-docs.xml`
-3. Specify docs directory (e.g., `./docs`)
-4. Task generates `index.md` from existing docs
+**document-project** will:
 
-**Why index.md matters:** Primary entry point for AI agents. Provides structured navigation even when good docs exist.
+- Scan actual codebase (source of truth)
+- Generate fresh, accurate documentation
+- Structure properly for AI consumption
+- Include only relevant, current information
 
-### Scenario C: Complete Documentation
+### Scenario C: Good Docs But Needs Structure
 
-If `docs/index.md` exists with comprehensive content, skip to Phase 1 or 2.
+**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 it, workflows lack context:
+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
 
-- **tech-spec** (Level 0-1) can't auto-detect stack/patterns
-- **PRD** (Level 2-4) can't reference existing code
-- **architecture** (Level 3-4) can't build on existing structure
-- **story-context** can't inject pattern-specific guidance
+**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 Level
+## Workflow Phases by Track
 
 ### Phase 1: Analysis (Optional)
 
@@ -155,7 +271,7 @@ Without it, workflows lack context:
 
 - `brainstorm-project` - Solution exploration
 - `research` - Technical/market research
-- `product-brief` - Strategic planning
+- `product-brief` - Strategic planning (BMad Method/Enterprise tracks only)
 
 **When to use:** Complex features, technical decisions, strategic additions
 
@@ -165,24 +281,24 @@ See [Workflows Guide](../workflows/README.md) for details.
 
 ### Phase 2: Planning (Required)
 
-**Planning approach adapts by level:**
+**Planning approach adapts by track:**
 
-**Level 0-1:** Use `tech-spec` workflow
+**Quick Flow:** Use `tech-spec` workflow
 
 - Creates tech-spec.md
 - Auto-detects existing stack (brownfield)
 - Confirms conventions with you
 - Generates implementation-ready stories
 
-**Level 2-4:** Use `prd` workflow
+**BMad Method/Enterprise:** Use `prd` workflow
 
-- Creates PRD.md + epics.md
+- 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 level.
+**Brownfield-specific:** See [Scale Adaptive System](./scale-adaptive-system.md) for complete workflow paths by track.
 
-### Phase 3: Solutioning (Level 2-4 Only)
+### Phase 3: Solutioning (BMad Method/Enterprise Only)
 
 **Critical for brownfield:**
 
@@ -193,12 +309,10 @@ See [Workflows Guide](../workflows/README.md) for details.
 
 **Workflows:**
 
-- `architecture-review` - Understand existing (Level 3-4)
-- `integration-planning` - Plan integration approach (Level 3-4)
-- `create-architecture` - Extend architecture docs (Level 2-4)
-- `solutioning-gate-check` - Validate before implementation (Level 3-4)
+- `create-architecture` - Extend architecture docs (BMad Method/Enterprise)
+- `solutioning-gate-check` - Validate before implementation (BMad Method/Enterprise)
 
-### Phase 4: Implementation (All Levels)
+### Phase 4: Implementation (All Tracks)
 
 **Sprint-based development through story iteration:**
 
@@ -307,10 +421,12 @@ Document in tech-spec/architecture:
 
 ## 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. **Document:** Skip if auth system documented, else run `document-project` (Quick scan)
@@ -326,10 +442,12 @@ Document in tech-spec/architecture:
 
 ---
 
-### 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. **Document:** Run `document-project` (Deep scan of auth module if not documented)
@@ -346,37 +464,40 @@ Document in tech-spec/architecture:
 
 ---
 
-### 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. **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. **Implement:** Sprint-based (10-15 stories)
+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
-5. **Review:** Per story completion
+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. **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 → `architecture-review` (understand existing editor)
-   - Load Architect → `integration-planning` (WebSocket integration strategy)
    - Load Architect → `create-architecture` (extend for real-time layer)
    - Load Architect → `solutioning-gate-check`
 5. **Implement:** Sprint-based (20-30 stories)
@@ -385,10 +506,12 @@ Document in tech-spec/architecture:
 
 ---
 
-### 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. **Document:** Run `document-project` (Exhaustive) - **Mandatory**
@@ -398,7 +521,7 @@ Document in tech-spec/architecture:
    - `product-brief` - Strategic document
 3. **Plan:** Load PM → `prd` (comprehensive)
 4. **Solution:**
-   - `architecture-review` - Full system review
+   - `create-architecture` - Full system architecture
    - `integration-planning` - Phased migration strategy
    - `create-architecture` - Multi-tenancy architecture
    - `validate-architecture` - External review
@@ -456,7 +579,7 @@ For complete troubleshooting, see [Troubleshooting Guide](./troubleshooting.md).
    - Which existing modules to modify
    - What APIs/services to integrate with
    - Data flow between new and existing code
-4. Run `integration-planning` workflow (Level 3-4)
+4. Review architecture document for integration guidance
 
 ### Existing Tests Breaking
 
@@ -504,21 +627,19 @@ document-project        # Create comprehensive docs (10-30min)
 # Analyst agent:
 brainstorm-project      # Explore solutions
 research                # Gather data
-product-brief           # Strategic planning
+product-brief           # Strategic planning (BMad Method/Enterprise only)
 
 # Phase 2: Planning (Required)
 # PM agent:
-tech-spec               # Level 0-1
-prd                     # Level 2-4
+tech-spec               # Quick Flow track
+prd                     # BMad Method/Enterprise tracks
 
-# Phase 3: Solutioning (Level 2-4)
+# Phase 3: Solutioning (BMad Method/Enterprise)
 # Architect agent:
-architecture-review          # Review existing (L3-4)
-integration-planning         # Plan integration (L3-4)
-create-architecture          # Extend architecture (L2-4)
-solutioning-gate-check       # Final approval (L3-4)
+create-architecture          # Extend architecture
+solutioning-gate-check       # Final validation
 
-# Phase 4: Implementation (All Levels)
+# Phase 4: Implementation (All Tracks)
 # SM agent:
 sprint-planning              # Initialize tracking
 epic-tech-context            # Epic context
@@ -545,17 +666,17 @@ correct-course               # If issues
 
 **Phase 1-3 Tracking:**
 
-- `docs/bmm-workflow-status.md` - Progress tracker
+- `docs/bmm-workflow-status.yaml` - Progress tracker
 
 **Phase 2 Planning:**
 
-- `docs/tech-spec.md` (Level 0-1)
-- `docs/PRD.md` (Level 2-4)
-- `docs/epics.md` (Level 2-4)
+- `docs/tech-spec.md` (Quick Flow track)
+- `docs/PRD.md` (BMad Method/Enterprise tracks)
+- Epic breakdown
 
 **Phase 3 Architecture:**
 
-- `docs/architecture.md` (Level 2-4)
+- `docs/architecture.md` (BMad Method/Enterprise tracks)
 
 **Phase 4 Implementation:**
 
@@ -573,13 +694,13 @@ flowchart TD
 
     START --> CHECK
     CHECK -->|No| DOC[document-project<br/>Deep scan]
-    CHECK -->|Yes| LEVEL{What Level?}
+    CHECK -->|Yes| TRACK{What Track?}
 
-    DOC --> LEVEL
+    DOC --> TRACK
 
-    LEVEL -->|0-1| TS[tech-spec]
-    LEVEL -->|2| PRD[prd]
-    LEVEL -->|3-4| PRD2[prd → architecture]
+    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
@@ -600,7 +721,7 @@ flowchart TD
 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 smaller level if unsure** - Easy to upgrade (L1 → L2)
+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
@@ -609,8 +730,8 @@ flowchart TD
 
 ## Related Documentation
 
-- **[Scale Adaptive System](./scale-adaptive-system.md)** - Understanding levels and complexity
-- **[Quick Spec Flow](./quick-spec-flow.md)** - Fast-track for Level 0-1
+- **[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