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

package/src/modules/bmm/docs/workflows-planning.md

@@ -1,334 +1,241 @@
 # BMM Planning Workflows (Phase 2)
 
-**Reading Time:** ~15 minutes
+**Reading Time:** ~10 minutes
 
 ## Overview
 
-Phase 2 (Planning) workflows are **required** for all projects. They transform strategic vision into actionable requirements that guide implementation. BMM uses a **scale-adaptive planning system** where the workflow automatically selects the right level of detail based on project complexity.
+Phase 2 (Planning) workflows are **required** for all projects. They transform strategic vision into actionable requirements using a **scale-adaptive system** that automatically selects the right planning depth based on project complexity.
 
-**Key principle:** One workflow to rule them all - `plan-project` intelligently routes to the appropriate planning flow based on project characteristics.
+**Key principle:** One unified entry point (`workflow-init`) intelligently routes to the appropriate planning methodology - from quick tech-specs to comprehensive PRDs.
 
-## Quick Reference
-
-| Workflow      | Project Levels | Duration   | Purpose                                 |
-| ------------- | -------------- | ---------- | --------------------------------------- |
-| **prd**       | 2-4            | 2-6 hours  | Strategic PRD + tactical epic breakdown |
-| **tech-spec** | 0-1            | 30-90 min  | Lightweight technical specification     |
-| **gdd**       | 2-4 (games)    | 4-10 hours | Complete game design document           |
-| **narrative** | 2-4 (story)    | 3-8 hours  | Story-driven game/experience design     |
-| **ux**        | 2-4 (UX-heavy) | 3-6 hours  | UX-first design specification           |
-
-**Note:** The `plan-project` workflow is your single entry point. It automatically routes to the right planning workflow based on your answers to discovery questions.
+**When to use:** All projects require planning. The system adapts depth automatically based on complexity.
 
 ---
 
-## Understanding Scale-Adaptive Planning
-
-### Project Complexity Levels
-
-BMM categorizes projects into 5 levels (0-4) to determine the appropriate planning detail:
-
-| Level       | Scope                   | Planning Workflow          | Examples                                                     |
-| ----------- | ----------------------- | -------------------------- | ------------------------------------------------------------ |
-| **Level 0** | Single atomic change    | **tech-spec** (Quick Spec) | Bug fix, single endpoint, config change                      |
-| **Level 1** | Simple isolated feature | **tech-spec** (Quick Spec) | Add validation rule, new API field, small UI component       |
-| **Level 2** | Medium feature          | **prd** (Lightweight)      | User profile page, search feature, data export               |
-| **Level 3** | Large feature set       | **prd** (Standard)         | Complete authentication system, admin dashboard              |
-| **Level 4** | Multi-phase initiative  | **prd** (Comprehensive)    | Platform migration, new product line, enterprise integration |
-
-### How Scale-Adaptive Planning Works
+## Phase 2 Planning Workflow Map
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
+graph TB
+    Start["<b>START: workflow-init</b><br/>Discovery + routing"]
+
+    subgraph QuickFlow["<b>QUICK FLOW (Simple Planning)</b>"]
+        direction TB
+        TechSpec["<b>PM: tech-spec</b><br/>Technical document<br/>→ Story or Epic+Stories<br/>1-15 stories typically"]
+    end
+
+    subgraph BMadMethod["<b>BMAD METHOD (Recommended)</b>"]
+        direction TB
+        PRD["<b>PM: prd</b><br/>Strategic PRD"]
+        GDD["<b>Game Designer: gdd</b><br/>Game design doc"]
+        Narrative["<b>Game Designer: narrative</b><br/>Story-driven design"]
+
+        Epics["<b>PM: create-epics-and-stories</b><br/>Epic+Stories breakdown<br/>10-50+ stories typically"]
+
+        UXDesign["<b>UX Designer: ux</b><br/>Optional UX specification"]
+    end
+
+    subgraph Enterprise["<b>ENTERPRISE METHOD</b>"]
+        direction TB
+        EntNote["<b>Uses BMad Method Planning</b><br/>+<br/>Extended Phase 3 workflows<br/>(Architecture + Security + DevOps)<br/>30+ stories typically"]
+    end
+
+    subgraph Updates["<b>MID-STREAM UPDATES (Anytime)</b>"]
+        direction LR
+        CorrectCourse["<b>PM/SM: correct-course</b><br/>Update requirements/stories"]
+    end
+
+    Start -->|Bug fix, simple| QuickFlow
+    Start -->|Software product| PRD
+    Start -->|Game project| GDD
+    Start -->|Story-driven| Narrative
+    Start -->|Enterprise needs| Enterprise
+
+    PRD --> Epics
+    GDD --> Epics
+    Narrative --> Epics
+    Epics -.->|Optional| UXDesign
+    UXDesign -.->|May update| Epics
+
+    QuickFlow --> Phase4["<b>Phase 4: Implementation</b>"]
+    Epics --> Phase3["<b>Phase 3: Architecture</b>"]
+    Enterprise -.->|Uses BMad planning| Epics
+    Enterprise --> Phase3Ext["<b>Phase 3: Extended</b><br/>(Arch + Sec + DevOps)"]
+    Phase3 --> Phase4
+    Phase3Ext --> Phase4
+
+    Phase4 -.->|Significant changes| CorrectCourse
+    CorrectCourse -.->|Updates| Epics
+
+    style Start fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000
+    style QuickFlow fill:#c5e1a5,stroke:#33691e,stroke-width:3px,color:#000
+    style BMadMethod fill:#e1bee7,stroke:#6a1b9a,stroke-width:3px,color:#000
+    style Enterprise fill:#ffcdd2,stroke:#c62828,stroke-width:3px,color:#000
+    style Updates fill:#ffecb3,stroke:#ff6f00,stroke-width:3px,color:#000
+    style Phase3 fill:#90caf9,stroke:#0d47a1,stroke-width:2px,color:#000
+    style Phase4 fill:#ffcc80,stroke:#e65100,stroke-width:2px,color:#000
+
+    style TechSpec fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000
+    style PRD fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
+    style GDD fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
+    style Narrative fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
+    style UXDesign fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
+    style Epics fill:#ba68c8,stroke:#6a1b9a,stroke-width:3px,color:#000
+    style EntNote fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000
+    style Phase3Ext fill:#ef5350,stroke:#c62828,stroke-width:2px,color:#000
+    style CorrectCourse fill:#ffb74d,stroke:#ff6f00,stroke-width:2px,color:#000
+```
 
-**Step 1: Intent Discovery**
-The `plan-project` workflow asks you questions to understand:
+---
 
-- What are you building?
-- How complex is it?
-- Is this greenfield or brownfield?
-- What are the primary concerns? (features, UX, story, technical architecture)
+## Quick Reference
 
-**Step 2: Intelligent Routing**
-Based on your answers, the workflow routes to:
+| Workflow                     | Agent         | Track       | Purpose                                    | Typical Stories |
+| ---------------------------- | ------------- | ----------- | ------------------------------------------ | --------------- |
+| **workflow-init**            | PM/Analyst    | All         | Entry point: discovery + routing           | N/A             |
+| **tech-spec**                | PM            | Quick Flow  | Technical document → Story or Epic+Stories | 1-15            |
+| **prd**                      | PM            | BMad Method | Strategic PRD                              | 10-50+          |
+| **gdd**                      | Game Designer | BMad Method | Game Design Document                       | 10-50+          |
+| **narrative**                | Game Designer | BMad Method | Story-driven game/experience design        | 10-50+          |
+| **create-epics-and-stories** | PM            | BMad Method | Break PRD/GDD into Epic+Stories            | N/A             |
+| **ux**                       | UX Designer   | BMad Method | Optional UX specification                  | N/A             |
+| **correct-course**           | PM/SM         | All         | Mid-stream requirement changes             | N/A             |
 
-- **tech-spec** (Levels 0-1): Quick Spec Flow for simple changes
-- **prd** (Levels 2-4): Strategic PRD with epic breakdown
-- **gdd** (Levels 2-4, games): Game Design Document
-- **narrative** (Levels 2-4, story-heavy): Narrative-first design
-- **ux** (Levels 2-4, UX-first): UX specification with prototypes
+**Note:** Story counts are guidance based on typical usage, not strict definitions.
 
-**Step 3: Adaptive Detail**
-Each workflow adjusts its depth based on level:
+---
 
-- Level 2: Lightweight documentation
-- Level 3: Standard documentation with multiple epics
-- Level 4: Comprehensive documentation with phased delivery
+## Scale-Adaptive Planning System
 
----
+BMM uses three distinct planning tracks that adapt to project complexity:
 
-## plan-project (Entry Point)
+### Track 1: Quick Flow
 
-### Purpose
+**Best For:** Bug fixes, simple features, clear scope, enhancements
 
-Single unified entry point for all planning workflows. Uses conversational discovery to understand your project and intelligently route to the appropriate planning flow.
+**Planning:** Tech-spec only → Implementation
 
-**Agent:** PM (orchestrates other agents as needed)
-**Phase:** 2 (Planning)
-**Required:** Yes (for all projects)
-**Typical Duration:** Varies by target workflow
+**Time:** Hours to 1 day
 
-### When to Use
+**Story Count:** Typically 1-15 (guidance)
 
-**Always use this as your planning starting point.** Do not call prd, gdd, narrative, ux, or tech-spec directly unless you explicitly want to skip discovery.
+**Documents:** tech-spec.md + story files
 
-### Process Overview
+**Example:** "Fix authentication bug", "Add OAuth social login"
 
-**Phase 1: Discovery (Steps 1-3)**
+---
 
-- Understand project context
-- Assess complexity level (0-4)
-- Identify primary concerns (features, UX, story, technical)
+### Track 2: BMad Method (RECOMMENDED)
 
-**Phase 2: Routing Decision (Step 4)**
+**Best For:** Products, platforms, complex features, multiple epics
 
-- Determine target workflow
-- Explain routing rationale
-- Confirm with user
+**Planning:** PRD + Architecture → Implementation
 
-**Phase 3: Execute Target Workflow (Steps 5-6)**
+**Time:** 1-3 days
 
-- Invoke appropriate planning workflow
-- Pass context and decisions
-- Return to plan-project for completion
+**Story Count:** Typically 10-50+ (guidance)
 
-**Phase 4: Handoff (Step 7)**
+**Documents:** PRD.md (or GDD.md) + architecture.md + epic files + story files
 
-- Document planning decisions
-- Recommend next phase workflows
-- Update workflow status
+**Greenfield:** Product Brief (optional) → PRD → UX (optional) → Architecture → Implementation
 
-### Discovery Questions
+**Brownfield:** document-project → PRD → Architecture (recommended) → Implementation
 
-**Project Type:**
+**Example:** "Customer dashboard", "E-commerce platform", "Add search to existing app"
 
-- What are you building? (software product, game, internal tool, etc.)
-- Is this greenfield (new) or brownfield (existing)?
+**Why Architecture for Brownfield?** Distills massive codebase context into focused solution design for your specific project.
 
-**Complexity Assessment:**
+---
 
-- How would you describe the scope? (single change, simple feature, medium feature, large feature set, multi-phase initiative)
-- How many user-facing features are involved?
-- How many systems or integrations are affected?
+### Track 3: Enterprise Method
 
-**Primary Concerns:**
+**Best For:** Enterprise requirements, multi-tenant, compliance, security-sensitive
 
-- What's most important for this project? (feature functionality, user experience, narrative/story, technical architecture, performance)
+**Planning (Phase 2):** Uses BMad Method planning (PRD + Epic+Stories)
 
-**Special Characteristics:**
+**Solutioning (Phase 3):** Extended workflows (Architecture + Security + DevOps + SecOps as optional additions)
 
-- Is this a game project?
-- Is storytelling central to the experience?
-- Is UX innovation the primary differentiator?
-- Are there unique technical constraints?
+**Time:** 3-7 days total (1-3 days planning + 2-4 days extended solutioning)
 
-### Routing Logic
+**Story Count:** Typically 30+ (but defined by enterprise needs)
 
-```
-IF game_project AND level >= 2:
-  → Route to gdd
+**Documents Phase 2:** PRD.md + epics + epic files + story files
 
-ELSE IF story_central AND level >= 2:
-  → Route to narrative
+**Documents Phase 3:** architecture.md + security-architecture.md (optional) + devops-strategy.md (optional) + secops-strategy.md (optional)
 
-ELSE IF ux_innovation AND level >= 2:
-  → Route to ux
+**Example:** "Multi-tenant SaaS", "HIPAA-compliant portal", "Add SOC2 audit logging"
 
-ELSE IF level <= 1:
-  → Route to tech-spec (Quick Spec Flow)
+---
 
-ELSE:
-  → Route to prd (with level-appropriate depth)
-```
+## How Track Selection Works
 
-### Outputs
+`workflow-init` guides you through educational choice:
 
-- Planning decision document (routing rationale)
-- Output from target workflow (PRD, GDD, Tech Spec, etc.)
-- Handoff recommendations for Phase 3
+1. **Description Analysis** - Analyzes project description for complexity
+2. **Educational Presentation** - Shows all three tracks with trade-offs
+3. **Recommendation** - Suggests track based on keywords and context
+4. **User Choice** - You select the track that fits
 
-### Example Scenarios
+The system guides but never forces. You can override recommendations.
 
-**Scenario 1: Bug Fix**
+---
 
-- **Input**: "Fix null pointer exception in user service"
-- **Discovery**: Level 0 (single atomic change)
-- **Route**: tech-spec (Quick Spec Flow)
-- **Duration**: 20 minutes
+## Workflow Descriptions
 
-**Scenario 2: E-commerce Checkout**
+### workflow-init (Entry Point)
 
-- **Input**: "Build complete checkout flow with payment processing"
-- **Discovery**: Level 3 (large feature set), feature-focused
-- **Route**: prd (Standard depth)
-- **Duration**: 4 hours
+**Purpose:** Single unified entry point for all planning. Discovers project needs and intelligently routes to appropriate track.
 
-**Scenario 3: Roguelike Card Game**
+**Agent:** PM (orchestrates others as needed)
 
-- **Input**: "Roguelike card battler with emotional narrative"
-- **Discovery**: Level 3 (large feature set), game project
-- **Route**: gdd
-- **Duration**: 6 hours
+**Always Use:** This is your planning starting point. Don't call prd/gdd/tech-spec directly unless skipping discovery.
 
-**Scenario 4: Story-Driven Adventure**
+**Process:**
 
-- **Input**: "Narrative adventure game with branching story"
-- **Discovery**: Level 3, story-central
-- **Route**: narrative (then gdd for mechanics)
-- **Duration**: 8 hours total
+1. Discovery (understand context, assess complexity, identify concerns)
+2. Routing Decision (determine track, explain rationale, confirm)
+3. Execute Target Workflow (invoke planning workflow, pass context)
+4. Handoff (document decisions, recommend next phase)
 
 ---
 
-## tech-spec (Quick Spec Flow)
-
-### Purpose
+### tech-spec (Quick Flow)
 
-Lightweight technical specification for Levels 0-1 projects (single changes, simple features). Focuses on implementation details without heavy strategic planning.
+**Purpose:** Lightweight technical specification for simple changes (Quick Flow track). Produces technical document and story or epic+stories structure.
 
-**Agent:** Architect
-**Phase:** 2 (Planning)
-**Project Levels:** 0-1
-**Typical Duration:** 30-90 minutes
+**Agent:** PM
 
-### When to Use
+**When to Use:**
 
 - Bug fixes
 - Single API endpoint additions
 - Configuration changes
 - Small UI component additions
 - Isolated validation rules
-- Single-file modifications
-
-**When NOT to use:**
-
-- Multiple interconnected changes → Use **prd**
-- User-facing feature with multiple screens → Use **prd**
-- Requires epic breakdown → Use **prd**
-
-### Process Overview
-
-**Step 1: Problem Definition**
-
-- What's broken or missing?
-- What's the desired behavior?
-- What are the constraints?
-
-**Step 2: Technical Analysis**
-
-- Current state assessment
-- Root cause (if bug)
-- Dependencies identified
-
-**Step 3: Solution Design**
-
-- Implementation approach
-- Code changes required
-- Test strategy
-- Rollback plan
-
-**Step 4: Documentation**
-
-- Quick Spec document generated
-- Handoff to implementation
-
-### Inputs
-
-- Problem description or feature request
-- Current codebase context (if brownfield)
-- Technical constraints
-- Acceptance criteria (simple)
-
-### Outputs
-
-**Primary Output:** `tech-spec-{feature-name}-{date}.md`
-
-**Document Structure:**
-
-1. Problem Statement
-2. Current State Analysis
-3. Proposed Solution
-4. Implementation Details
-   - Files to modify
-   - API changes
-   - Database changes (if any)
-   - Configuration changes
-5. Test Strategy
-6. Rollback Plan
-7. Acceptance Criteria
-8. Risk Assessment (lightweight)
-
-### Example Output
-
-**Problem:** Null pointer exception when user has no profile image
 
-**Solution:**
+**Key Outputs:**
 
-```markdown
-# Quick Spec: Fix Profile Image Null Pointer
+- **tech-spec.md** - Technical document containing:
+  - Problem statement and solution
+  - Source tree changes
+  - Implementation details
+  - Testing strategy
+  - Acceptance criteria
+- **Story file(s)** - Single story OR epic+stories structure (1-15 stories typically)
 
-## Problem
+**Skip To Phase:** 4 (Implementation) - no Phase 3 architecture needed
 
-Users without profile images cause NPE in UserProfileService.java:line 42
-
-## Root Cause
-
-Method assumes profileImageUrl is never null, but DB allows NULL
-
-## Solution
-
-1. Add null check in UserProfileService
-2. Return default placeholder image URL
-3. Add unit test for null case
-
-## Implementation
-
-- File: `UserProfileService.java`
-- Change: Add null guard: `if (user.profileImageUrl == null) return DEFAULT_AVATAR_URL;`
-- Test: `UserProfileServiceTest.java` - new test case
-- No DB migration needed
-
-## Acceptance Criteria
-
-- AC-1: Users with null profile image see default avatar
-- AC-2: No NPE in logs
-- AC-3: Unit test passes
-
-## Risk: LOW
-
-- Isolated change, single method
-- Backward compatible
-```
-
-### Related Workflows
-
-- **dev-story** (Phase 4) - Implement the spec
-- **prd** - Use for more complex features
+**Example:** "Fix null pointer when user has no profile image" → Single file change, null check, unit test, no DB migration.
 
 ---
 
-## prd (Product Requirements Document)
+### prd (Product Requirements Document)
 
-### Purpose
-
-Strategic PRD with tactical epic breakdown for Levels 2-4 projects. Unified workflow that adapts depth based on project complexity.
+**Purpose:** Strategic PRD with epic breakdown for software products (BMad Method track).
 
 **Agent:** PM (with Architect and Analyst support)
-**Phase:** 2 (Planning)
-**Project Levels:** 2-4
-**Typical Duration:**
-
-- Level 2: 2-3 hours (Lightweight)
-- Level 3: 3-5 hours (Standard)
-- Level 4: 5-8 hours (Comprehensive)
 
-### When to Use
+**When to Use:**
 
 - Medium to large feature sets
 - Multi-screen user experiences
@@ -336,703 +243,287 @@ Strategic PRD with tactical epic breakdown for Levels 2-4 projects. Unified work
 - Multiple system integrations
 - Phased delivery required
 
-### Scale-Adaptive Structure
-
-**Level 2 (Lightweight PRD):**
-
-- Single epic with 5-10 stories
-- Simplified competitive analysis
-- Basic technical considerations
-- 10-15 pages
-
-**Level 3 (Standard PRD):**
-
-- 2-4 epics with 15-30 stories
-- Comprehensive competitive analysis
-- Detailed technical requirements
-- Risk assessment
-- 20-30 pages
-
-**Level 4 (Comprehensive PRD):**
-
-- 5+ epics with 30-50+ stories
-- Multi-phase delivery plan
-- Enterprise architecture considerations
-- Extensive stakeholder analysis
-- Success metrics framework
-- 30-50+ pages
-
-### Process Overview
-
-**Phase 1: Strategic Foundation (Steps 1-4)**
-
-- Problem and opportunity definition
-- User research and personas
-- Competitive analysis
-- Success criteria and metrics
-
-**Phase 2: Solution Definition (Steps 5-8)**
-
-- Core capabilities and features
-- User experience principles
-- Technical requirements
-- Integration points
-
-**Phase 3: Epic Breakdown (Steps 9-12)**
-
-- Identify epics (level-appropriate count)
-- Define user stories per epic
-- Prioritize stories (P0/P1/P2/P3)
-- Sequence for delivery
-
-**Phase 4: Planning and Risks (Steps 13-15)**
-
-- Resource estimation
-- Risk assessment
-- Assumptions and dependencies
-- Success metrics finalized
-
-**Phase 5: Documentation (Step 16)**
-
-- Generate final PRD
-- Create epic files
-- Handoff preparation
-
-### Inputs
-
-Optional:
-
-- product-brief.md (from Phase 1)
-- market-research.md (from Phase 1)
-- competitive-analysis.md (from Phase 1)
-- User input through conversational process
-
-### Outputs
-
-**Primary Outputs:**
+**Scale-Adaptive Structure:**
 
-1. **PRD.md**: Complete product requirements document
-2. **epics.md**: All epics with story breakdown
-3. **Epic Files**: Individual files per epic (e.g., `epic-1-authentication.md`)
+- **Light:** Single epic, 5-10 stories, simplified analysis (10-15 pages)
+- **Standard:** 2-4 epics, 15-30 stories, comprehensive analysis (20-30 pages)
+- **Comprehensive:** 5+ epics, 30-50+ stories, multi-phase, extensive stakeholder analysis (30-50+ pages)
 
-**PRD Structure:**
+**Key Outputs:**
 
-1. Executive Summary
-2. Problem Statement (with evidence)
-3. Goals and Success Metrics
-4. User Personas and Scenarios
-5. Competitive Landscape
-6. Feature Requirements
-   - Core capabilities
-   - User stories (organized by epic)
-   - Acceptance criteria
-7. User Experience Requirements
-8. Technical Requirements
-9. Integration Requirements
-10. Non-Functional Requirements (NFRs)
-11. Assumptions and Constraints
-12. Risks and Mitigation
-13. Success Metrics
-14. Glossary
+- PRD.md (complete requirements)
+- epics.md (epic breakdown)
+- Epic files (epic-1-_.md, epic-2-_.md, etc.)
 
-**Epic File Structure:**
+**Integration:** Feeds into Architecture (Phase 3)
 
-- Epic overview and objectives
-- User stories with acceptance criteria
-- Story priorities (P0/P1/P2/P3)
-- Dependencies and sequencing
-- Technical notes
-- Success criteria
-
-### Example: Level 3 PRD for E-commerce Checkout
-
-**Strategic Section:**
-
-- **Problem**: 68% cart abandonment rate vs 45% industry average
-- **Goal**: Reduce abandonment to 50% in 6 months
-- **Users**: Primary (buyers), Secondary (guest checkout)
-- **Competitors**: Shopify (1-click), Amazon (save payment)
-
-**Epic Breakdown:**
-
-1. **Epic 1: Guest Checkout** (7 stories)
-   - P0: Guest can checkout without account
-   - P1: Email receipt sent
-   - P2: Optional account creation
-2. **Epic 2: Payment Processing** (8 stories)
-   - P0: Credit card integration (Stripe)
-   - P1: Saved payment methods
-   - P2: Alternative payments (PayPal, Apple Pay)
-3. **Epic 3: Order Management** (6 stories)
-   - P0: Order confirmation
-   - P1: Order history
-   - P2: Order tracking
-
-**Total:** 3 epics, 21 stories, 4-6 week delivery
-
-### Related Workflows
-
-- **product-brief** (Phase 1) - Strategic input
-- **architecture** (Phase 3) - Technical design
-- **tech-spec** (Phase 3) - Detailed specifications
-- **create-epics-and-stories** (Phase 4) - If manual epic creation needed
+**Example:** E-commerce checkout → 3 epics (Guest Checkout, Payment Processing, Order Management), 21 stories, 4-6 week delivery.
 
 ---
 
-## gdd (Game Design Document)
-
-### Purpose
-
-Complete game design document for Levels 2-4 game projects, adapted from industry-standard GDD formats with practical scoping.
+### gdd (Game Design Document)
 
-**Agent:** PM (Game Designer persona)
-**Phase:** 2 (Planning)
-**Project Levels:** 2-4 (games)
-**Typical Duration:**
+**Purpose:** Complete game design document for game projects (BMad Method track).
 
-- Level 2: 3-4 hours (Small indie game)
-- Level 3: 5-7 hours (Medium game)
-- Level 4: 8-12 hours (Large/commercial game)
+**Agent:** Game Designer
 
-### When to Use
+**When to Use:**
 
-- Designing a game (any genre)
+- Designing any game (any genre)
 - Need comprehensive design documentation
 - Team needs shared vision
 - Publisher/stakeholder communication
 
-### Comparison to Traditional GDD
+**BMM GDD vs Traditional:**
 
-**Traditional GDD Weaknesses:**
-
-- Too detailed too early
-- Assumes waterfall delivery
-- No connection to implementation tracking
-- No epic/story breakdown
-
-**BMM GDD Improvements:**
-
-- Scale-adaptive detail
+- Scale-adaptive detail (not waterfall)
 - Agile epic structure
-- Direct handoff to implementation (Phase 4)
+- Direct handoff to implementation
 - Integrated with testing workflows
 
-### Process Overview
-
-**Phase 1: Core Concept (Steps 1-4)**
-
-- High concept and elevator pitch
-- Core gameplay loop
-- Design pillars
-- Player experience goals
-
-**Phase 2: Game Systems (Steps 5-10)**
-
-- Mechanics definition
-- Progression systems
-- Economy and balance
-- Combat/interaction systems
-- Level/world design
-- Art and audio direction
+**Key Outputs:**
 
-**Phase 3: Content Scope (Steps 11-13)**
-
-- Content volume (levels, characters, items)
-- Narrative overview (if applicable)
-- Monetization strategy (if F2P/premium)
-
-**Phase 4: Technical and Production (Steps 14-16)**
-
-- Platform and technical requirements
-- Team and timeline
-- Risks and challenges
-- Success metrics
-
-**Phase 5: Epic Breakdown (Step 17)**
-
-- Convert design into epics
-- Create user stories per epic
-- Prioritize features (MVP vs post-launch)
-- Sequence delivery
-
-### Inputs
-
-Optional:
-
-- game-brief.md (from Phase 1)
-- brainstorm-game results (from Phase 1)
-- market-research.md (from Phase 1)
-- Reference game analysis
-
-### Outputs
-
-**Primary Output:** `GDD-{game-name}-{date}.md`
-
-**GDD Structure:**
-
-1. Executive Summary
-2. Core Concept
-   - High concept
-   - Elevator pitch
-   - Design pillars
-3. Gameplay
-   - Core loop
-   - Mechanics
-   - Player actions
-   - Progression
-4. Game Systems
-   - Combat/interaction
-   - Economy
-   - Progression
-   - Customization
-5. World and Narrative
-   - Setting
-   - Story (if applicable)
-   - Characters
-6. Content Scope
-   - Levels/missions
-   - Characters/enemies
-   - Items/abilities
-   - Estimated play time
-7. Art Direction
-8. Audio Direction
-9. User Interface/UX
-10. Technical Requirements
-11. Platforms and Performance
-12. Monetization (if applicable)
-13. Epic Breakdown
-14. Success Metrics
-15. Risks and Mitigations
-
-**Epic Breakdown** (unique to BMM GDD):
-
-- **Epic 1: Core Loop** (foundational mechanics)
-- **Epic 2: Content** (levels, enemies, items)
-- **Epic 3: Progression** (unlocks, upgrades)
-- **Epic 4: Polish** (VFX, audio, UI)
-
-### Example: Level 3 GDD for Roguelike Card Game
-
-**Core Concept:**
-
-- **High Concept**: Slay the Spire meets Hades with emotional narrative
-- **Elevator Pitch**: Roguelike card battler where you play as emotions fighting inner demons
-- **Design Pillars**: Strategic depth, emotional resonance, replayability
-
-**Gameplay:**
-
-- **Core Loop**: Draw cards → Play cards → Resolve combat → Choose path → Repeat
-- **Progression**: Unlock new cards, characters, and story branches
-- **Run Length**: 45-60 minutes per run
-
-**Content Scope:**
-
-- 3 playable characters (Anger, Fear, Joy)
-- 120 cards total (40 per character)
-- 50 enemy types
-- 10 bosses
-- 4 zones (acts)
-
-**Epic Breakdown:**
-
-1. **Epic 1: Core Combat** (8 stories)
-   - P0: Card playing and resolution
-   - P0: Enemy AI
-   - P1: Card effects and combos
-2. **Epic 2: Meta Progression** (6 stories)
-   - P0: Unlock system
-   - P1: Character progression
-3. **Epic 3: Content** (12 stories)
-   - P1: Character 1 (Anger) complete
-   - P1: Character 2 (Fear) complete
-   - P2: Character 3 (Joy) complete
-
-**Estimated Timeline:** 12 months with 3-person team
-
-### Related Workflows
-
-- **game-brief** (Phase 1) - Strategic input
-- **narrative** (Phase 2) - If story-heavy game
-- **architecture** (Phase 3) - Technical design
+- GDD.md (complete game design)
+- Epic breakdown (Core Loop, Content, Progression, Polish)
 
----
+**Integration:** Feeds into Architecture (Phase 3)
 
-## narrative (Narrative Design)
+**Example:** Roguelike card game → Core concept (Slay the Spire meets Hades), 3 characters, 120 cards, 50 enemies, Epic breakdown with 26 stories.
 
-### Purpose
+---
 
-Story-driven design workflow for games and experiences where narrative is central. Creates comprehensive narrative documentation including story structure, character arcs, dialogue systems, and narrative implementation guidance.
+### narrative (Narrative Design)
 
-**Agent:** PM (Narrative Designer persona) + Creative Problem Solver (CIS)
-**Phase:** 2 (Planning)
-**Project Levels:** 2-4 (story-driven projects)
-**Typical Duration:**
+**Purpose:** Story-driven design workflow for games/experiences where narrative is central (BMad Method track).
 
-- Level 2: 2-4 hours (Linear narrative)
-- Level 3: 4-6 hours (Branching narrative)
-- Level 4: 6-10 hours (Complex branching with multiple arcs)
+**Agent:** Game Designer (Narrative Designer persona) + Creative Problem Solver (CIS)
 
-### When to Use
+**When to Use:**
 
-- Story is central to the experience
+- Story is central to experience
 - Branching narrative with player choices
 - Character-driven games
 - Visual novels, adventure games, RPGs
-- Interactive fiction
-
-**When to combine with GDD:**
-
-1. Run **narrative** workflow first (get story structure)
-2. Then run **gdd** workflow (integrate story with gameplay)
-
-### Process Overview
-
-**Phase 1: Story Foundation (Steps 1-4)**
 
-- Story premise and themes
-- Setting and world-building
-- Narrative structure (linear, branching, open)
-- Tone and emotional beats
+**Combine with GDD:**
 
-**Phase 2: Character Development (Steps 5-7)**
+1. Run `narrative` first (story structure)
+2. Then run `gdd` (integrate story with gameplay)
 
-- Protagonist and supporting cast
-- Character arcs and motivations
-- Relationships and dynamics
-
-**Phase 3: Story Structure (Steps 8-11)**
-
-- Act breakdown (3-act, 5-act, hero's journey)
-- Key narrative beats
-- Choice points and consequences
-- Branching paths (if applicable)
-
-**Phase 4: Dialogue and Implementation (Steps 12-15)**
+**Key Outputs:**
 
+- narrative-design.md (complete narrative spec)
+- Story structure (acts, beats, branching)
+- Characters (profiles, arcs, relationships)
 - Dialogue system design
-- Voice and writing style
-- Narrative implementation approach
-- Asset requirements (VO, cutscenes, etc.)
-
-**Phase 5: Integration Planning (Step 16)**
-
-- How narrative integrates with gameplay
-- Pacing and player agency
-- Narrative-gameplay harmony
-
-### Inputs
-
-Optional:
-
-- Story outlines or treatments
-- Character sketches
-- World-building documents
-- Reference stories
-
-### Outputs
-
-**Primary Output:** `narrative-design-{project-name}-{date}.md`
-
-**Document Structure:**
-
-1. Narrative Overview
-   - Premise
-   - Themes
-   - Tone
-2. Story Structure
-   - Act breakdown
-   - Key beats
-   - Branching diagram (if applicable)
-3. Characters
-   - Character profiles
-   - Arcs
-   - Relationships
-4. World-Building
-   - Setting
-   - Lore
-   - History
-5. Dialogue System
-   - Dialogue structure
-   - Choice mechanics
-   - Consequence tracking
-6. Implementation Guide
-   - Narrative assets needed
-   - Integration with gameplay
-   - Technical requirements
-7. Narrative Content Scope
-   - Total word count
-   - Number of scenes/beats
-   - Number of endings (if branching)
-   - VO line count (if voiced)
-
-### Example: Level 3 Narrative for Choice-Driven RPG
-
-**Story Premise:**
-You play as a wandering medic in a post-apocalyptic world where healing is outlawed. Each patient you treat changes the world.
-
-**Structure:**
-
-- 3 acts, 12 chapters
-- 5 major choice points with persistent consequences
-- 3 possible endings (altruistic, pragmatic, corrupted)
-
-**Characters:**
-
-- **Protagonist**: Dr. Elara Chen (complex moral compass)
-- **Antagonist**: The Overseer (believes healing prolongs suffering)
-- **Supporting**: 8 recurring characters
-
-**Branching:**
-
-```
-Chapter 1 → Choice: Save child or save supplies
-  ├─ Save child → Village trusts you (Path A)
-  └─ Save supplies → Village fears you (Path B)
-
-Chapter 5 → Paths converge, new choice: Reveal or hide ability
-  ├─ Reveal → Public hero route
-  └─ Hide → Underground resistance route
-```
-
-**Implementation:**
-
-- Total word count: ~60,000 words
-- 40 narrative scenes
-- 15 hours of gameplay
-- 200+ dialogue nodes
-- Optional VO (2,000 lines)
+- Implementation guide
 
-**Epic Breakdown:**
+**Integration:** Combine with GDD, then feeds into Architecture (Phase 3)
 
-1. **Epic 1: Act 1 Narrative** (6 stories)
-2. **Epic 2: Act 2 Narrative** (8 stories)
-3. **Epic 3: Act 3 Narrative** (7 stories)
-4. **Epic 4: Branching Implementation** (5 stories)
-
-### Related Workflows
-
-- **gdd** (Phase 2) - Combine narrative with gameplay
-- **ux** (Phase 2) - Narrative UI/UX design
+**Example:** Choice-driven RPG → 3 acts, 12 chapters, 5 choice points, 3 endings, 60K words, 40 narrative scenes.
 
 ---
 
-## ux (UX-First Design)
-
-### Purpose
+### ux (UX-First Design)
 
-UX specification workflow for projects where user experience is the primary differentiator or innovation area. Facilitates visual exploration and informed decision-making rather than template-driven design.
+**Purpose:** UX specification for projects where user experience is the primary differentiator (BMad Method track).
 
 **Agent:** UX Designer
-**Phase:** 2 (Planning)
-**Project Levels:** 2-4 (UX-heavy projects)
-**Typical Duration:**
 
-- Level 2: 2-3 hours (Single feature UX)
-- Level 3: 4-5 hours (Multi-screen experience)
-- Level 4: 6-8 hours (Platform-wide UX system)
+**When to Use:**
 
-### When to Use
-
-- UX is the primary competitive advantage
+- UX is primary competitive advantage
 - Complex user workflows needing design thinking
 - Innovative interaction patterns
 - Design system creation
 - Accessibility-critical experiences
 
-**When NOT to use:**
+**Collaborative Approach:**
 
-- Standard CRUD interfaces → Use **prd**
-- Gameplay-first games → Use **gdd**
-- Backend-focused APIs → Use **tech-spec**
+1. Visual exploration (generate multiple options)
+2. Informed decisions (evaluate with user needs)
+3. Collaborative design (refine iteratively)
+4. Living documentation (evolves with project)
 
-### Collaborative UX Design Approach
+**Key Outputs:**
 
-**This is NOT a template filler.** The UX workflow facilitates:
+- ux-spec.md (complete UX specification)
+- User journeys
+- Wireframes and mockups
+- Interaction specifications
+- Design system (components, patterns, tokens)
+- Epic breakdown (UX stories)
 
-1. **Visual Exploration**: Generate multiple design options
-2. **Informed Decisions**: Evaluate options with user needs
-3. **Collaborative Design**: Work with AI to refine iteratively
-4. **Living Documentation**: UX spec evolves with project
+**Integration:** Feeds PRD or updates epics, then Architecture (Phase 3)
 
-### Process Overview
+**Example:** Dashboard redesign → Card-based layout with split-pane toggle, 5 card components, 12 color tokens, responsive grid, 3 epics (Layout, Visualization, Accessibility).
 
-**Phase 1: UX Foundation (Steps 1-4)**
+---
 
-- User research and personas
-- User journeys and workflows
-- Pain points and opportunities
-- UX principles and goals
+### create-epics-and-stories
 
-**Phase 2: Design Exploration (Steps 5-8)**
+**Purpose:** Break PRD/GDD requirements into bite-sized stories organized in epics (BMad Method track).
 
-- Generate multiple design directions
-- Wireframes and mockups
-- Interaction patterns
-- Visual design options
+**Agent:** PM
 
-**Phase 3: Design Refinement (Steps 9-12)**
+**When to Use:**
 
-- Collaborative iteration
-- Accessibility validation
-- Responsive design considerations
-- Component library definition
+- After PRD/GDD complete (often run automatically)
+- Can also run standalone later to re-generate epics/stories
+- When planning story breakdown outside main PRD workflow
 
-**Phase 4: Specification (Steps 13-15)**
+**Key Outputs:**
 
-- Detailed interaction specs
-- Design system documentation
-- Handoff to development
-- Epic breakdown with UX stories
+- epics.md (all epics with story breakdown)
+- Epic files (epic-1-\*.md, etc.)
 
-### Inputs
+**Note:** PRD workflow often creates epics automatically. This workflow can be run standalone if needed later.
 
-Optional:
+---
 
-- User research data
-- Analytics and heatmaps
-- Competitor UX analysis
-- Brand guidelines
-- Accessibility requirements
+### correct-course
 
-### Outputs
+**Purpose:** Handle significant requirement changes during implementation (all tracks).
 
-**Primary Output:** `ux-spec-{project-name}-{date}.md`
+**Agent:** PM, Architect, or SM
 
-**Document Structure:**
+**When to Use:**
 
-1. UX Vision and Principles
-2. User Research Summary
-3. User Journeys
-4. Information Architecture
-5. Wireframes and Mockups
-6. Interaction Specifications
-   - Screen-by-screen flows
-   - Micro-interactions
-   - Error states
-   - Loading states
-7. Design System
-   - Components
-   - Patterns
-   - Tokens (colors, typography, spacing)
-8. Accessibility Requirements
-9. Responsive Behavior
-10. Epic Breakdown (UX Stories)
+- Priorities change mid-project
+- New requirements emerge
+- Scope adjustments needed
+- Technical blockers require replanning
 
-### Example: Level 3 UX Spec for Dashboard Redesign
+**Process:**
 
-**UX Vision:**
-"Information at a glance with progressive disclosure"
+1. Analyze impact of change
+2. Propose solutions (continue, pivot, pause)
+3. Update affected documents (PRD, epics, stories)
+4. Re-route for implementation
 
-**User Journey:**
+**Integration:** Updates planning artifacts, may trigger architecture review
 
-1. User lands on dashboard
-2. Scans key metrics (glanceable)
-3. Drills into details (progressive disclosure)
-4. Takes action (in-context controls)
+---
 
-**Wireframes Generated:**
+## Decision Guide
 
-- Option A: Card-based layout (familiar, modular)
-- Option B: Single-column feed (mobile-first)
-- Option C: Split-pane (power user)
+### Which Planning Workflow?
 
-**Decision:** Option A (card-based) with Option C (split-pane) for power users via toggle
+**Use `workflow-init` (Recommended):** Let the system discover needs and route appropriately.
 
-**Design System:**
+**Direct Selection (Advanced):**
 
-- 5 card components (metric, chart, table, activity, action)
-- 12 color tokens (accessible contrast ratios)
-- Responsive grid (12-column)
+- **Bug fix or single change** → `tech-spec` (Quick Flow)
+- **Software product** → `prd` (BMad Method)
+- **Game (gameplay-first)** → `gdd` (BMad Method)
+- **Game (story-first)** → `narrative` + `gdd` (BMad Method)
+- **UX innovation project** → `ux` + `prd` (BMad Method)
+- **Enterprise with compliance** → Choose track in `workflow-init` → Enterprise Method
 
-**Epic Breakdown:**
+---
 
-1. **Epic 1: Core Layout** (4 stories)
-   - P0: Responsive grid system
-   - P0: Card component library
-2. **Epic 2: Data Visualization** (6 stories)
-   - P1: Chart components
-   - P1: Real-time updates
-3. **Epic 3: Accessibility** (3 stories)
-   - P0: Keyboard navigation
-   - P1: Screen reader support
+## Integration with Phase 3 (Solutioning)
 
-### Related Workflows
+Planning outputs feed into Solutioning:
 
-- **prd** (Phase 2) - UX spec feeds feature requirements
-- **architecture** (Phase 3) - Frontend architecture decisions
+| Planning Output     | Solutioning Input                    | Track Decision               |
+| ------------------- | ------------------------------------ | ---------------------------- |
+| tech-spec.md        | Skip Phase 3 → Phase 4 directly      | Quick Flow (no architecture) |
+| PRD.md              | **architecture** (Level 3-4)         | BMad Method (recommended)    |
+| GDD.md              | **architecture** (game tech)         | BMad Method (recommended)    |
+| narrative-design.md | **architecture** (narrative systems) | BMad Method                  |
+| ux-spec.md          | **architecture** (frontend design)   | BMad Method                  |
+| Enterprise docs     | **architecture** + security/ops      | Enterprise Method (required) |
 
----
+**Key Decision Points:**
 
-## Decision Guide: Which Planning Workflow?
+- **Quick Flow:** Skip Phase 3 entirely → Phase 4 (Implementation)
+- **BMad Method:** Optional Phase 3 (simple), Required Phase 3 (complex)
+- **Enterprise:** Required Phase 3 (architecture + extended planning)
 
-### Use `plan-project` (Recommended)
+See: [workflows-solutioning.md](./workflows-solutioning.md)
 
-Let the workflow discover your needs and route appropriately.
+---
 
-### Direct Workflow Selection (Advanced)
+## Best Practices
 
-**For bug fixes or single changes:**
-→ **tech-spec** (Quick Spec Flow)
+### 1. Always Start with workflow-init
 
-**For software products (Levels 2-4):**
-→ **prd**
+Let the entry point guide you. It prevents over-planning simple features or under-planning complex initiatives.
 
-**For games (Levels 2-4):**
-→ **gdd** (if gameplay-first)
-→ **narrative** + **gdd** (if story-first)
+### 2. Trust the Recommendation
 
-**For story-driven experiences (non-games):**
-→ **narrative** + **prd**
+If `workflow-init` suggests BMad Method, there's likely complexity you haven't considered. Review carefully before overriding.
 
-**For UX-first projects:**
-→ **ux** + **prd**
+### 3. Iterate on Requirements
 
----
+Planning documents are living. Refine PRDs/GDDs as you learn during Solutioning and Implementation.
 
-## Integration with Phase 3 (Solutioning)
+### 4. Involve Stakeholders Early
 
-Planning workflows produce requirements that feed into Solutioning:
+Review PRDs/GDDs with stakeholders before Solutioning. Catch misalignment early.
 
-| Planning Output      | Solutioning Input                     |
-| -------------------- | ------------------------------------- |
-| PRD.md               | **architecture** workflow (Level 3-4) |
-| epics.md             | **tech-spec** workflow (Level 3-4)    |
-| GDD.md               | **architecture** workflow (game tech) |
-| narrative-design.md  | **architecture** (narrative systems)  |
-| ux-spec.md           | **architecture** (frontend design)    |
-| tech-spec.md (Quick) | **dev-story** (Level 0-1)             |
+### 5. Focus on "What" Not "How"
 
-**Key Decision Point:**
+Planning defines **what** to build and **why**. Leave **how** (technical design) to Phase 3 (Solutioning).
 
-- **Levels 0-1**: Skip Solutioning, go directly to Phase 4 (Implementation)
-- **Levels 2**: Optional Solutioning (simple architecture)
-- **Levels 3-4**: **Required** Solutioning (architecture + tech-spec)
+### 6. Document-Project First for Brownfield
 
-See: [workflows-solutioning.md](./workflows-solutioning.md)
+Always run `document-project` before planning brownfield projects. AI agents need existing codebase context.
 
 ---
 
-## Best Practices for Phase 2
+## Common Patterns
 
-### 1. Always Start with `plan-project`
+### Greenfield Software (BMad Method)
 
-Unless you're absolutely certain which workflow you need, use the entry point. It will save time and ensure you get the right level of detail.
+```
+1. (Optional) Analysis: product-brief, research
+2. workflow-init → routes to prd
+3. PM: prd workflow
+4. (Optional) UX Designer: ux workflow
+5. PM: create-epics-and-stories (may be automatic)
+6. → Phase 3: architecture
+```
 
-### 2. Level Honestly
+### Brownfield Software (BMad Method)
 
-Don't over-plan simple features or under-plan complex initiatives. Be honest about project complexity.
+```
+1. Technical Writer or Analyst: document-project
+2. workflow-init → routes to prd
+3. PM: prd workflow
+4. PM: create-epics-and-stories
+5. → Phase 3: architecture (recommended for focused solution design)
+```
 
-### 3. Iterate on Requirements
+### Bug Fix (Quick Flow)
 
-Planning documents are living. You can refine PRDs/GDDs as you learn more during Solutioning and Implementation.
+```
+1. workflow-init → routes to tech-spec
+2. Architect: tech-spec workflow
+3. → Phase 4: Implementation (skip Phase 3)
+```
 
-### 4. Involve Stakeholders Early
+### Game Project (BMad Method)
 
-Review PRDs/GDDs with stakeholders before proceeding to Solutioning. Catch misalignment early.
+```
+1. (Optional) Analysis: game-brief, research
+2. workflow-init → routes to gdd
+3. Game Designer: gdd workflow (or narrative + gdd if story-first)
+4. Game Designer creates epic breakdown
+5. → Phase 3: architecture (game systems)
+```
 
-### 5. Focus on "What" Not "How"
+### Enterprise Project (Enterprise Method)
 
-Planning defines **what** to build and **why**. Leave **how** (technical design) to Phase 3 (Solutioning).
+```
+1. (Recommended) Analysis: research (compliance, security)
+2. workflow-init → routes to Enterprise Method
+3. PM: prd workflow
+4. (Optional) UX Designer: ux workflow
+5. PM: create-epics-and-stories
+6. → Phase 3: architecture + security + devops + test strategy
+```
 
 ---
 
@@ -1041,46 +532,70 @@ Planning defines **what** to build and **why**. Leave **how** (technical design)
 ### ❌ Skipping Planning
 
 "We'll just start coding and figure it out."
-→ **Result**: Scope creep, rework, missed requirements
+**Result:** Scope creep, rework, missed requirements
 
 ### ❌ Over-Planning Simple Changes
 
 "Let me write a 20-page PRD for this button color change."
-→ **Result**: Wasted time, analysis paralysis
+**Result:** Wasted time, analysis paralysis
 
 ### ❌ Planning Without Discovery
 
 "I already know what I want, skip the questions."
-→ **Result**: Solving wrong problem, missing opportunities
+**Result:** Solving wrong problem, missing opportunities
 
 ### ❌ Treating PRD as Immutable
 
 "The PRD is locked, no changes allowed."
-→ **Result**: Ignoring new information, rigid planning
+**Result:** Ignoring new information, rigid planning
 
 ### ✅ Correct Approach
 
-- Use scale-adaptive planning (right level for complexity)
+- Use scale-adaptive planning (right depth for complexity)
 - Involve stakeholders in review
 - Iterate as you learn
 - Keep planning docs living and updated
+- Use `correct-course` for significant changes
 
 ---
 
-## Summary
+## Related Documentation
 
-Phase 2 Planning workflows transform vision into actionable requirements:
+- [Phase 1: Analysis Workflows](./workflows-analysis.md) - Optional discovery phase
+- [Phase 3: Solutioning Workflows](./workflows-solutioning.md) - Next phase
+- [Phase 4: Implementation Workflows](./workflows-implementation.md)
+- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding the three tracks
+- [Quick Spec Flow](./quick-spec-flow.md) - Quick Flow track details
+- [Agents Guide](./agents-guide.md) - Complete agent reference
 
-| Input             | Planning Workflow | Output           |
-| ----------------- | ----------------- | ---------------- |
-| Product idea      | **prd**           | PRD + Epics      |
-| Game concept      | **gdd**           | GDD + Epics      |
-| Story idea        | **narrative**     | Narrative Design |
-| UX innovation     | **ux**            | UX Specification |
-| Bug/simple change | **tech-spec**     | Quick Spec       |
+---
 
-**Key Takeaway:** Planning is **required** for all projects, but the **depth adapts** to project complexity. Trust the scale-adaptive system to guide the right level of detail.
+## Troubleshooting
 
-**Next Phase:** Solutioning (Phase 3) - Technical architecture and detailed specifications
+**Q: Which workflow should I run first?**
+A: Run `workflow-init`. It analyzes your project and routes to the right planning workflow.
 
-See: [workflows-solutioning.md](./workflows-solutioning.md)
+**Q: Do I always need a PRD?**
+A: No. Simple changes use `tech-spec` (Quick Flow). Only BMad Method and Enterprise tracks create PRDs.
+
+**Q: Can I skip Phase 3 (Solutioning)?**
+A: Yes for Quick Flow. Optional for BMad Method (simple projects). Required for BMad Method (complex projects) and Enterprise.
+
+**Q: How do I know which track to choose?**
+A: Use `workflow-init` - it recommends based on your description. Story counts are guidance, not definitions.
+
+**Q: What if requirements change mid-project?**
+A: Run `correct-course` workflow. It analyzes impact and updates planning artifacts.
+
+**Q: Do brownfield projects need architecture?**
+A: Recommended! Architecture distills massive codebase into focused solution design for your specific project.
+
+**Q: When do I run create-epics-and-stories?**
+A: Usually automatic during PRD/GDD. Can also run standalone later to regenerate epics.
+
+**Q: Should I use product-brief before PRD?**
+A: Optional but recommended for greenfield. Helps strategic thinking. `workflow-init` offers it based on context.
+
+---
+
+_Phase 2 Planning - Scale-adaptive requirements for every project._