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

package/src/modules/bmm/docs/scale-adaptive-system.md

@@ -0,0 +1,749 @@
+# BMad Method Scale Adaptive System
+
+**Automatically adapts workflows to project complexity - from bug fixes to enterprise systems**
+
+---
+
+## Overview
+
+The **Scale Adaptive System** is BMad Method's intelligent workflow orchestration that automatically adjusts planning depth, documentation requirements, and implementation processes based on project size and complexity.
+
+### The Problem It Solves
+
+Traditional methodologies apply the same process to every project:
+
+- ❌ **Overkill:** Bug fix requires full design docs
+- ❌ **Insufficient:** Enterprise system built with minimal planning
+- ❌ **One-Size-Fits-None:** Same process for 1 story and 100 stories
+
+### The Solution
+
+BMad Method **adapts workflows to match project scale**:
+
+- ✅ **Level 0 (1 story):** Tech-spec only, implement immediately
+- ✅ **Level 2 (10 stories):** PRD + Architecture, structured approach
+- ✅ **Level 4 (100+ stories):** Full enterprise planning, comprehensive docs
+
+**Result:** Right amount of planning for every project - no more, no less.
+
+---
+
+## Quick Reference
+
+### Five Levels at a Glance
+
+| Level | Scope                | Stories | Documentation       | Timeline |
+| ----- | -------------------- | ------- | ------------------- | -------- |
+| **0** | Single atomic change | 1       | tech-spec only      | Hours    |
+| **1** | Small feature        | 1-10    | tech-spec + epic    | Days     |
+| **2** | Medium project       | 5-15    | PRD + optional arch | Weeks    |
+| **3** | Complex integration  | 12-40   | PRD + architecture  | Months   |
+| **4** | Enterprise scale     | 40+     | Full methodology    | Quarters |
+
+### Level Selection Decision Tree
+
+```mermaid
+flowchart TD
+    START{Describe your project}
+
+    START -->|Bug fix, typo, patch| L0[Level 0<br/>tech-spec only]
+    START -->|Small feature, 2-3 stories| L1[Level 1<br/>tech-spec + epic]
+    START -->|Dashboard, multiple features| L2[Level 2<br/>PRD + optional arch]
+    START -->|Platform, complex integration| L3[Level 3<br/>PRD + architecture]
+    START -->|Enterprise, multi-tenant| L4[Level 4<br/>Full methodology]
+
+    style L0 fill:#bfb,stroke:#333,stroke-width:2px
+    style L1 fill:#bbf,stroke:#333,stroke-width:2px
+    style L2 fill:#ffb,stroke:#333,stroke-width:2px
+    style L3 fill:#fbf,stroke:#333,stroke-width:2px
+    style L4 fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+### Quick Keywords
+
+- **Level 0:** fix, bug, typo, small change, patch
+- **Level 1:** simple, basic, small feature, add, minor
+- **Level 2:** dashboard, several features, admin panel, medium
+- **Level 3:** platform, integration, complex, system, architecture
+- **Level 4:** enterprise, multi-tenant, multiple products, ecosystem, scale
+
+---
+
+## How Level Detection Works
+
+When you run `workflow-init`, it analyzes your project using three methods:
+
+### 1. Keyword Analysis
+
+Scans your description for level-specific keywords (see Quick Keywords above).
+
+### 2. Story Count Estimation
+
+Asks about expected scope and matches to ranges:
+
+| Stories | Suggested Level |
+| ------- | --------------- |
+| 1       | Level 0         |
+| 2-10    | Level 1         |
+| 5-15    | Level 2         |
+| 12-40   | Level 3         |
+| 40+     | Level 4         |
+
+**Note:** Overlap zones (5-10, 12-15) are intentional - choose based on need for product-level planning.
+
+### 3. Complexity Indicators
+
+Additional factors:
+
+- Multiple teams involved? → Higher level
+- External integrations? → Higher level
+- Compliance requirements? → Higher level
+- Multi-tenant needs? → Level 4
+- Existing system modifications? → Consider brownfield path
+
+### Manual Override
+
+**You can always override the suggested level.** workflow-init asks for confirmation - if you disagree, just say so and choose the appropriate level. Trust your judgment.
+
+**Example:**
+
+```
+workflow-init: "Based on your description: Level 3 project. Is that correct?"
+You: "No, this is simpler - Level 2"
+workflow-init: "Got it, creating Level 2 workflow"
+```
+
+---
+
+## The Five Levels
+
+### Level 0: Single Atomic Change
+
+**Definition:** Single-story projects like bug fixes, typos, or small patches.
+
+**Story Count:** 1 story
+
+**Timeline:** Hours to 1 day
+
+**Documentation Requirements:**
+
+- **tech-spec.md** - Technical specification with implementation details
+- Single story file
+
+**Workflow Path:**
+
+```
+(Brownfield: document-project first if needed)
+↓
+Tech-Spec → Implement
+```
+
+**No Architecture:** Skip entirely
+**No PRD:** Tech-spec serves as complete planning doc
+
+**Use For:**
+
+- Bug fixes
+- Single file changes
+- Minor configuration updates
+- Small refactors
+- Typo corrections
+
+**Example:** "Fix authentication token expiration bug in auth middleware"
+
+**Keywords:** fix, bug, typo, small change, quick update, patch
+
+---
+
+### Level 1: Small Feature
+
+**Definition:** Small coherent features with 2-10 related stories.
+
+**Story Count:** 1-10 stories (typically 2-5)
+
+**Timeline:** 1-3 days
+
+**Documentation Requirements:**
+
+- **tech-spec.md** - Technical specification with epic breakdown
+- **Epic organization** - Stories grouped by epic
+- 2-10 story files
+
+**Workflow Path:**
+
+```
+(Brownfield: document-project first if needed)
+↓
+Tech-Spec + Epic → (Optional) UX Design → Implement
+```
+
+**No Architecture:** Skip entirely
+**No PRD:** Tech-spec with epic is sufficient
+
+**Use For:**
+
+- Single module additions
+- Small UI enhancements
+- Isolated feature additions
+- API endpoint additions (OAuth, forgot password, search)
+
+**Example:** "Add OAuth social login (Google, GitHub, Facebook)"
+
+**UX Note:** Tech-spec can include UX considerations inline, or run separate UX Design workflow if UI is complex.
+
+**Keywords:** simple, basic, small feature, add, minor
+
+---
+
+### Level 2: Medium Project
+
+**Definition:** Multiple related features across 1-3 epics.
+
+**Story Count:** 5-15 stories
+
+**Timeline:** 1-2 weeks
+
+**Documentation Requirements:**
+
+- **PRD.md** - Product requirements document
+- **epics.md** - Epic breakdown with stories
+- **tech-spec.md** (optional) - Or use epic-tech-specs during implementation
+- **architecture.md** (optional) - Only if system design needed
+
+**Workflow Path:**
+
+```
+(Brownfield: document-project first if needed)
+↓
+Analysis (recommended) → PRD + Epics → (Optional) UX Design → (Optional) Architecture → Implement
+                                                                                            ↓
+                                                                           Epic-tech-spec per epic (recommended)
+                                                                                            ↓
+                                                                           Retrospective after each epic (if >1 epic)
+```
+
+**Architecture:** Optional - only if system design needed
+**Epic-Tech-Specs:** Recommended during implementation
+
+**Use For:**
+
+- Multiple related features
+- Cross-module enhancements
+- Admin dashboards
+- Customer portals
+- Reporting systems
+
+**Example:** "Add user dashboard with analytics, preferences, and activity history"
+
+**Level 2 Decision:** Choose Level 2 over Level 1 when you need product-level planning, have multiple epics, or require stakeholder alignment.
+
+**Keywords:** dashboard, several features, admin panel, medium
+
+---
+
+### Level 3: Complex Integration
+
+**Definition:** Complex systems with multiple subsystems and integrations.
+
+**Story Count:** 12-40 stories
+
+**Timeline:** 3-6 weeks
+
+**Documentation Requirements:**
+
+- **PRD.md** - Comprehensive product requirements
+- **epics.md** - Detailed epic breakdown
+- **architecture.md** - Required comprehensive system architecture
+- **UX design** (recommended for user-facing systems)
+
+**Workflow Path:**
+
+```
+(Brownfield: document-project first if needed)
+↓
+Analysis + Research → PRD + Epics → (Recommended) UX Design → Architecture (required) → Gate Check → Implement
+                                                                                                      ↓
+                                                                                     Epic-tech-spec per epic (recommended)
+                                                                                                      ↓
+                                                                                     Retrospective after each epic
+```
+
+**Architecture:** Required - comprehensive system design
+**Gate Check:** Required - validate cohesion before implementation
+**Epic-Tech-Specs:** Highly recommended
+
+**Use For:**
+
+- Major feature additions
+- Architectural integrations
+- Multi-system changes
+- E-commerce platforms
+- SaaS products
+- Multi-module systems
+
+**Example:** "Adding real-time collaboration features to existing document editor"
+
+**Critical for Level 3:**
+
+- Architecture review before planning
+- Integration strategy document
+- Backward compatibility planning
+- Phased rollout consideration
+
+**Keywords:** platform, integration, complex, system, architecture
+
+---
+
+### Level 4: Enterprise Scale
+
+**Definition:** Enterprise-scale projects across multiple products or major platform expansions.
+
+**Story Count:** 40+ stories
+
+**Timeline:** 3-6 months
+
+**Documentation Requirements:**
+
+- **Product brief** - Strategic planning document
+- **PRD.md** - Comprehensive product requirements
+- **epics.md** - Detailed epic breakdown
+- **architecture.md** - Required enterprise-grade architecture
+- **UX design** (recommended) - Design system and patterns
+
+**Workflow Path:**
+
+```
+(Brownfield: document-project first - nearly mandatory)
+↓
+Analysis + Research → PRD + Epics → UX Design → Enterprise Architecture → Gate Check → Implement
+                                                                                          ↓
+                                                                         Epic-tech-spec per epic (recommended)
+                                                                                          ↓
+                                                                         Additional design docs for complex subsystems
+                                                                                          ↓
+                                                                         Retrospective after each epic
+```
+
+**Architecture:** Required - enterprise-grade system design including:
+
+- Multi-tenancy design
+- Security architecture
+- Scalability planning
+- Integration architecture
+- Data architecture
+- Deployment architecture
+
+**Gate Checks:** Required - multiple validation gates
+**Additional Design Documents:** Created during implementation as needed
+
+**Use For:**
+
+- Platform expansions
+- Multi-team initiatives
+- System-wide modernization
+- Multi-tenant systems
+- Product ecosystems
+- Enterprise platforms
+
+**Example:** "Adding multi-tenancy to existing single-tenant SaaS platform"
+
+**Critical for Enterprise:**
+
+- Documentation phase nearly mandatory
+- Analysis phase (research, product brief) required
+- Full architecture review before planning
+- Extensive integration testing strategy
+- Risk assessment and mitigation planning
+- Cross-team coordination
+- Feature flag implementation
+- Migration strategy for existing data/users
+
+**Keywords:** enterprise, multi-tenant, multiple products, ecosystem, scale
+
+---
+
+## Planning Documents by Level
+
+### Understanding Document Types
+
+```mermaid
+flowchart TD
+    LEVEL{What Level?}
+
+    LEVEL -->|0-1| TS[tech-spec<br/>Created upfront<br/>Only planning doc]
+    LEVEL -->|2-4| PRD[PRD<br/>Created upfront<br/>Product planning]
+
+    PRD --> ARCH{Architecture<br/>needed?}
+    ARCH -->|Yes<br/>Level 3-4| ARCHD[architecture.md<br/>Created upfront<br/>System design]
+    ARCH -->|Optional<br/>Level 2| MAYBE[Maybe architecture<br/>if system design needed]
+
+    TS --> IMPL1[Implementation]
+    ARCHD --> IMPL2[Implementation]
+    MAYBE --> IMPL2
+
+    IMPL2 --> ETS[epic-tech-spec<br/>Created just-in-time<br/>Per epic during Phase 4]
+
+    style TS fill:#bfb,stroke:#333,stroke-width:2px
+    style PRD fill:#bbf,stroke:#333,stroke-width:2px
+    style ARCHD fill:#ffb,stroke:#333,stroke-width:2px
+    style ETS fill:#fbf,stroke:#333,stroke-width:2px
+```
+
+### Tech-Spec (Level 0-1)
+
+**Created:** Upfront in Planning Phase (Phase 2)
+**Serves as:** Primary and only planning document
+
+**Contains:**
+
+- Problem statement and solution
+- Source tree changes (specific files)
+- Technical implementation details
+- Detected stack and conventions (brownfield)
+- UX/UI considerations (if user-facing)
+- Testing strategy
+- Developer resources
+
+**When Used:** Replaces PRD + Architecture for small projects
+
+### PRD (Level 2-4)
+
+**Created:** Upfront in Planning Phase (Phase 2)
+**Serves as:** Product-level planning document
+
+**Contains:**
+
+- Product vision and goals
+- Feature requirements
+- Epic breakdown with stories
+- Success criteria
+- User experience considerations
+- Business context
+
+**Complements:** Architecture document (system design)
+
+### Architecture Document (Level 2-4)
+
+**Created:** Upfront in Solutioning Phase (Phase 3)
+**Serves as:** System-level design document
+
+**Scale-Adaptive Complexity:**
+
+- **Level 2:** Optional, lightweight if needed
+- **Level 3:** Required, comprehensive
+- **Level 4:** Required, enterprise-grade
+
+**Contains:**
+
+- System components and responsibilities
+- Data models and schemas
+- Integration patterns
+- Security architecture
+- Performance considerations
+- Deployment architecture
+
+**Note:** Takes the place of tech-spec for system-level planning in Level 2-4 projects.
+
+### Epic-Tech-Spec (Level 2-4)
+
+**Created:** Just-in-time during Implementation Phase (Phase 4)
+**Serves as:** Epic-specific implementation guide
+
+**Contains:**
+
+- Epic-specific technical details
+- Detailed implementation approach for this epic
+- Code-level design decisions
+- Epic-scoped testing strategy
+- Integration points with other epics
+
+**Key Difference from Tech-Spec:**
+
+- **Tech-spec (0-1):** Created upfront, primary planning doc
+- **Epic-tech-spec (2-4):** Created during implementation, supplements PRD + Architecture
+
+**Why Just-In-Time?**
+
+- Implementation learnings inform later epic-tech-specs
+- Avoids over-planning details that may change
+- Keeps specs fresh and relevant
+- Retrospectives provide input for next epic-tech-spec
+
+---
+
+## Workflow Comparison
+
+| Level | Analysis    | Planning         | Architecture | Epic-Tech-Specs | Stories | Retrospectives          |
+| ----- | ----------- | ---------------- | ------------ | --------------- | ------- | ----------------------- |
+| **0** | Optional    | Tech-spec        | None         | N/A             | 1       | N/A                     |
+| **1** | Optional    | Tech-spec + Epic | None         | N/A             | 2-10    | N/A                     |
+| **2** | Recommended | PRD              | Optional     | Recommended     | 5-15    | After each epic (if >1) |
+| **3** | Required    | PRD              | Required     | Recommended     | 12-40   | After each epic         |
+| **4** | Required    | PRD              | Required     | Recommended     | 40+     | After each epic         |
+
+---
+
+## Brownfield Projects
+
+### Critical First Step
+
+🚨 **For ALL brownfield projects (Level 0-4): Run document-project BEFORE planning workflows**
+
+### Why document-project is Critical
+
+- **Tech-spec workflow** (Level 0-1) uses this for auto-detection
+- **PRD workflow** (Level 2-4) references existing code
+- **Architecture workflow** (Level 3-4) builds on existing structure
+- **Epic-tech-specs** reference existing implementations
+
+### Brownfield Workflow Pattern
+
+```mermaid
+flowchart TD
+    START([Brownfield Project])
+    CHECK{Has docs/<br/>index.md?}
+
+    START --> CHECK
+    CHECK -->|No| DOC[document-project workflow<br/>Creates comprehensive docs]
+    CHECK -->|Yes| PLAN[Continue to Planning]
+
+    DOC --> PLAN
+    PLAN --> IMPL[Implementation]
+
+    style START fill:#f9f,stroke:#333,stroke-width:2px
+    style DOC fill:#ffb,stroke:#333,stroke-width:2px
+    style PLAN fill:#bfb,stroke:#333,stroke-width:2px
+```
+
+**Three Options:**
+
+1. **No documentation:** Run document-project workflow (10-30 min)
+2. **Has docs, no index.md:** Run index-docs task (2-5 min)
+3. **Complete documentation:** Skip to planning
+
+**For complete brownfield guidance:** See [Brownfield Development Guide](./brownfield-guide.md)
+
+---
+
+## Common Scenarios
+
+### Scenario 1: Bug Fix (Level 0)
+
+**Input:** "Fix email validation bug in login form"
+
+**Detection:**
+
+- Keywords: "fix", "bug"
+- Estimated stories: 1
+
+**Result:** Level 0 → Tech-spec only
+
+**Workflow:**
+
+1. (Optional) Brief analysis
+2. Tech-spec with single story
+3. Implement immediately
+
+**Time:** ~2-4 hours total
+
+---
+
+### Scenario 2: Small Feature (Level 1)
+
+**Input:** "Add OAuth social login (Google, GitHub, Facebook)"
+
+**Detection:**
+
+- Keywords: "add", "feature"
+- Estimated stories: 2-3
+
+**Result:** Level 1 → Tech-spec with epic
+
+**Workflow:**
+
+1. (Optional) Research OAuth providers
+2. Tech-spec with epic + 3 stories
+3. (Optional) UX Design if UI is complex
+4. Implement story-by-story
+
+**Time:** 1-3 days
+
+---
+
+### Scenario 3: Customer Portal (Level 2)
+
+**Input:** "Build customer portal with dashboard, tickets, billing"
+
+**Detection:**
+
+- Keywords: "portal", "dashboard"
+- Estimated stories: 10-12
+
+**Result:** Level 2 → PRD + optional architecture
+
+**Workflow:**
+
+1. Product Brief (recommended)
+2. PRD with epics
+3. (Optional) UX Design
+4. (Optional) Architecture if system design needed
+5. Implement with sprint planning
+6. Create epic-tech-spec for each epic as you implement
+7. Run retrospective after each epic
+
+**Time:** 1-2 weeks
+
+---
+
+### Scenario 4: E-commerce Platform (Level 3)
+
+**Input:** "Build full e-commerce platform with products, cart, checkout, admin, analytics"
+
+**Detection:**
+
+- Keywords: "platform", "full"
+- Estimated stories: 30-35
+
+**Result:** Level 3 → PRD + Architecture required
+
+**Workflow:**
+
+1. Research + Product Brief
+2. Comprehensive PRD
+3. UX Design (recommended)
+4. System Architecture (required)
+5. Gate check
+6. Implement with phased approach
+7. Create epic-tech-spec per epic before implementing
+8. Run retrospective after each epic
+9. Create additional design docs as needed for complex subsystems
+
+**Time:** 3-6 weeks
+
+---
+
+### Scenario 5: Adding Feature to Existing App (Brownfield Level 1)
+
+**Input:** "Add search functionality to existing product catalog"
+
+**Detection:**
+
+- Keywords: "add", "existing"
+- Estimated stories: 3-4
+- Field type: Brownfield
+
+**Result:** Level 1 Brownfield
+
+**Critical First Step:**
+
+1. **Run document-project** to analyze existing codebase
+
+**Then Workflow:** 2. Tech-spec (uses document-project output for analysis) 3. Auto-detects existing patterns 4. Confirms conventions 5. Implement following existing patterns
+
+**Time:** 1-3 days (including documentation)
+
+---
+
+## Best Practices
+
+### 1. Document-Project First for Brownfield
+
+Always run document-project before starting any brownfield workflow. Even if you know the code, AI agents need it.
+
+### 2. Trust the Detection
+
+If workflow-init suggests Level 2, there's probably complexity you haven't considered. Review before overriding.
+
+### 3. Start Small, Upgrade Later
+
+Uncertain between Level 1 and 2? Start with Level 1. You can always run PRD creation later if needed.
+
+### 4. Don't Skip Gate Checks
+
+For Level 3-4, gate checks prevent costly mistakes. Invest the time upfront.
+
+### 5. Create Epic-Tech-Specs Just-Before-Implementation
+
+For Level 2-4, create epic-tech-spec right before implementing each epic. Don't create all upfront.
+
+### 6. Run Retrospectives Between Epics
+
+Capture learnings after each epic. Feed insights into next epic-tech-spec.
+
+### 7. Optional UX for Level 1
+
+If your Level 1 feature has complex UI, run separate UX Design. Otherwise, include UX notes in tech-spec.
+
+### 8. Architecture Scales
+
+Level 2 architecture is lighter than Level 3, which is lighter than Level 4. Don't over-architect.
+
+---
+
+## Appendix
+
+### A. Terminology Quick Reference
+
+For complete definitions, see [Glossary](./glossary.md).
+
+**Key Terms:**
+
+- **Scale-Adaptive:** System that adjusts workflow based on project complexity
+- **Tech-Spec:** Technical specification document (Level 0-1, created upfront)
+- **Epic-Tech-Spec:** Epic technical specification (Level 2-4, created just-in-time)
+- **PRD:** Product Requirements Document
+- **Just-In-Time Design:** Creating epic-tech-specs during implementation, not upfront
+- **Context Injection:** Dynamic guidance via epic-tech-context and story-context workflows
+- **Greenfield:** New project from scratch
+- **Brownfield:** Existing codebase
+
+### B. Workflow Path Configuration
+
+The v6 system uses modular path definitions stored in YAML configuration files.
+
+**Location:** `src/modules/bmm/workflows/workflow-status/paths/`
+
+**Files:**
+
+- `greenfield-level-0.yaml` through `greenfield-level-4.yaml`
+- `brownfield-level-0.yaml` through `brownfield-level-4.yaml`
+- `game-design.yaml`
+- `project-levels.yaml` (source of truth)
+
+Each path file defines:
+
+- Required vs optional workflows for each phase
+- Agent assignments
+- Expected outputs
+- Phase progression rules
+
+### C. FAQ
+
+**Q: What's the difference between tech-spec and epic-tech-spec?**
+A: Tech-spec (Level 0-1) is created upfront and serves as the primary planning doc. Epic-tech-spec (Level 2-4) is created during implementation per epic and supplements PRD + Architecture.
+
+**Q: Why no tech-spec at Level 2+?**
+A: Level 2+ needs product-level planning (PRD) and system-level design (Architecture), which tech-spec doesn't provide. Instead, use epic-tech-specs during implementation for detailed technical guidance per epic.
+
+**Q: Do I always need Architecture at Level 2?**
+A: No, it's optional. Only create Architecture if you need system-level design. Many Level 2 projects work with just PRD + epic-tech-specs.
+
+**Q: Can I change levels mid-project?**
+A: Yes! If you started at Level 1 but realize it's Level 2, run create-prd to add proper planning docs. The system is flexible.
+
+For more questions, see [FAQ](./faq.md).
+
+---
+
+## Related Documentation
+
+- **[Quick Start Guide](./quick-start.md)** - Get started with BMM
+- **[Quick Spec Flow](./quick-spec-flow.md)** - Fast-track for Level 0-1
+- **[Brownfield Guide](./brownfield-guide.md)** - Existing codebase workflows
+- **[Glossary](./glossary.md)** - Complete terminology
+- **[FAQ](./faq.md)** - Common questions
+- **[Workflows Guide](../workflows/README.md)** - Complete workflow reference
+
+---
+
+_Scale Adaptive System - Because one size doesn't fit all._