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

package/bmad/bmm/docs/scale-adaptive-system.md

@@ -1,1045 +0,0 @@
-# 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.
-
----
-
-## Key Terminology
-
-### Analysis Phase
-
-**What it is:** Discovery and research phase that informs planning decisions.
-
-**Activities:**
-
-- **Brainstorming:** Ideation and creative exploration
-- **Research:** Market analysis, technical investigation, user research
-- **Product Brief:** High-level vision and requirements capture
-
-**When used:**
-
-- Optional for Level 0-1 (quick changes)
-- Recommended for Level 2 (provides context)
-- Required for Level 3-4 (critical for complex systems)
-
----
-
-### Tech-Spec (Technical Specification)
-
-**What it is:** Comprehensive technical plan for implementing changes or features. Serves as the **primary planning document** for Level 0-1 projects.
-
-**Contents:**
-
-- Problem statement and solution approach
-- 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:**
-
-- **Level 0:** Single story technical plan
-- **Level 1:** Feature technical plan with epic
-- **Level 2-4:** Not used (PRD + Architecture instead)
-
-**Replacement at Level 2+:** Tech-spec is **replaced by PRD + Architecture** for proper product and system planning.
-
----
-
-### Epic-Tech-Spec (Epic Technical Specification)
-
-**What it is:** Detailed technical planning document created **during implementation** for each epic in Level 2-4 projects.
-
-**Difference from Tech-Spec:**
-
-- **Tech-spec (Level 0-1):** Created upfront, serves as primary planning doc
-- **Epic-tech-spec (Level 2-4):** Created just-before-implementation per epic, supplements PRD + Architecture
-
-**Contents:**
-
-- Epic-specific technical details
-- Detailed implementation approach for this epic
-- Code-level design decisions
-- Epic-scoped testing strategy
-- Integration points with other epics
-
-**When used:**
-
-- **Recommended** for Level 2-4 during implementation phase
-- Created as each epic is worked on
-- Particularly important for:
-  - Complex epics with many stories
-  - Novel technical approaches
-  - Integration-heavy epics
-  - Performance-critical features
-
----
-
-### Architecture Document
-
-**What it is:** System-wide design document that defines structure, components, and interactions.
-
-**Scale-Adaptive:**
-
-- **Level 0-1:** Not used
-- **Level 2:** Optional - lightweight architecture if needed
-- **Level 3:** Required - comprehensive system architecture
-- **Level 4:** Required - enterprise-grade architecture
-
-**Contents:**
-
-- System components and their responsibilities
-- Data models and schemas
-- Integration patterns
-- Security architecture
-- Performance considerations
-- Deployment architecture
-- **Scales in complexity** with project level
-
-**Note:** Architecture document takes the place of tech-spec for system-level planning in Level 2-4 projects.
-
----
-
-### Document-Project Workflow
-
-**What it is:** Brownfield codebase analysis workflow that creates comprehensive documentation of existing code.
-
-**Output:** `docs/index.md` with sharded sections covering:
-
-- Project structure
-- Key modules and services
-- Existing patterns
-- Dependencies
-- Configuration
-
-**Critical for Brownfield:**
-🚨 **Run document-project BEFORE starting any brownfield project (Level 0-4)**
-
-**Why it matters:**
-
-- Tech-spec workflow uses this for brownfield analysis
-- PRD workflow references it for context
-- Architecture workflow builds on existing structure
-- Epic-tech-specs reference existing code
-
-**When to run:**
-
-- Before workflow-init for brownfield projects
-- When joining an existing codebase
-- After major refactors (to update docs)
-
----
-
-## The Five Levels
-
-### Level 0: Single Atomic Change
-
-**Examples:** Bug fixes, typos, single-file changes
-
-| Aspect              | Details                                          |
-| ------------------- | ------------------------------------------------ |
-| **Stories**         | 1 story                                          |
-| **Planning Docs**   | Tech-spec only                                   |
-| **Architecture**    | None                                             |
-| **Best For**        | Bug fixes, small patches, quick updates          |
-| **Brownfield Prep** | Run document-project first (if not already done) |
-
-**Workflow:**
-
-```
-(Brownfield: document-project first)
-↓
-Analysis (optional) → Tech-Spec → Implement
-```
-
-**Keywords:** fix, bug, typo, small change, quick update, patch
-
----
-
-### Level 1: Small Feature
-
-**Examples:** OAuth login, search feature, user profile page
-
-| Aspect              | Details                                             |
-| ------------------- | --------------------------------------------------- |
-| **Stories**         | 1-10 stories (typically 2-3)                        |
-| **Planning Docs**   | Tech-spec with epic                                 |
-| **Architecture**    | None                                                |
-| **UX Design**       | Optional - can be included in tech-spec or separate |
-| **Best For**        | Small coherent features, rapid prototyping          |
-| **Brownfield Prep** | Run document-project first (if not already done)    |
-
-**Workflow:**
-
-```
-(Brownfield: document-project first)
-↓
-Analysis (optional) → Tech-Spec + Epic → (Optional UX Design) → Implement
-```
-
-**UX Note:** Level 1 tech-spec can include UX/UI considerations inline, or you can optionally run separate UX Design workflow if the UI is complex.
-
-**Keywords:** simple, basic, small feature, add, minor
-
----
-
-### Level 2: Medium Project
-
-**Examples:** Admin dashboard, customer portal, reporting system
-
-| Aspect              | Details                                                     |
-| ------------------- | ----------------------------------------------------------- |
-| **Stories**         | 5-15 stories across multiple epics                          |
-| **Planning Docs**   | PRD + Epics                                                 |
-| **Architecture**    | Optional - lightweight architecture if system design needed |
-| **UX Design**       | Optional - recommended for UI-heavy projects                |
-| **Epic-Tech-Specs** | Recommended during implementation per epic                  |
-| **Best For**        | Multiple related features, focused products                 |
-| **Brownfield Prep** | Run document-project first (if not already done)            |
-
-**Workflow:**
-
-```
-(Brownfield: document-project first)
-↓
-Analysis (recommended) → PRD + Epics → (Optional) UX Design → (Optional) Architecture → Implement
-                                                                                            ↓
-                                                                           Epic-Tech-Spec per epic (recommended)
-                                                                                            ↓
-                                                                           Retrospective after each epic (if >1 epic)
-```
-
-**Architecture Note:** Level 2 uses optional **Architecture document** (not tech-spec) if system design is needed. For projects that don't need architecture, PRD + Epics are sufficient.
-
-**Epic-Tech-Specs:** As you implement each epic, create epic-tech-spec for detailed technical guidance. If you have 3 epics, you'll create 3 epic-tech-specs during implementation.
-
-**Retrospectives:** After completing each epic (when there are multiple), run retrospective to capture learnings before starting the next epic.
-
-**Keywords:** dashboard, several features, admin panel, medium
-
----
-
-### Level 3: Complex System
-
-**Examples:** E-commerce platform, SaaS product, multi-module system
-
-| Aspect              | Details                                            |
-| ------------------- | -------------------------------------------------- |
-| **Stories**         | 12-40 stories with subsystems                      |
-| **Planning Docs**   | PRD + Epics + System Architecture                  |
-| **Architecture**    | Required - comprehensive system design             |
-| **UX Design**       | Recommended for user-facing systems                |
-| **Epic-Tech-Specs** | Recommended during implementation per epic         |
-| **Gate Checks**     | Required - validate cohesion before implementation |
-| **Best For**        | Complex integrations, multi-subsystem products     |
-| **Brownfield Prep** | Run document-project first (if not already done)   |
-
-**Workflow:**
-
-```
-(Brownfield: document-project first)
-↓
-Analysis + Research → PRD + Epics → (Recommended) UX Design → Architecture (required) → Gate Check → Implement
-                                                                                                      ↓
-                                                                                     Epic-Tech-Spec per epic (recommended)
-                                                                                                      ↓
-                                                                                     Retrospective after each epic
-```
-
-**Gate Check:** Validates PRD + UX + Architecture cohesion before starting implementation. Prevents costly rework.
-
-**Epic-Tech-Specs:** For complex epics, create detailed epic-tech-spec before implementation. These provide code-level design decisions that Architecture doesn't cover.
-
-**Additional Detail Docs:** For very novel or complex subsystems, you may create additional technical design documents beyond epic-tech-specs. These are created as-needed, not upfront.
-
-**Keywords:** platform, integration, complex, system, architecture
-
----
-
-### Level 4: Enterprise Scale
-
-**Examples:** Multi-product suite, enterprise ecosystem, platform with multiple apps
-
-| Aspect              | Details                                                        |
-| ------------------- | -------------------------------------------------------------- |
-| **Stories**         | 40+ stories across products                                    |
-| **Planning Docs**   | Comprehensive PRD + Epics + Enterprise Architecture            |
-| **Architecture**    | Required - enterprise-grade system design                      |
-| **UX Design**       | Recommended - design system and patterns                       |
-| **Epic-Tech-Specs** | Recommended during implementation per epic                     |
-| **Gate Checks**     | Required - multiple validation gates                           |
-| **Best For**        | Multi-tenant systems, product ecosystems, enterprise platforms |
-| **Brownfield Prep** | Run document-project first (if not already done)               |
-
-**Workflow:**
-
-```
-(Brownfield: document-project first)
-↓
-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
-```
-
-**Enterprise Architecture:** More comprehensive than Level 3, includes:
-
-- Multi-tenancy design
-- Security architecture
-- Scalability planning
-- Integration architecture
-- Data architecture
-- Deployment architecture
-
-**Additional Design Documents:** For enterprise complexity, you may need supplementary technical documents:
-
-- Detailed subsystem designs
-- Integration specifications
-- Performance optimization plans
-- Security implementation guides
-
-These are created **during implementation** as needed, not all upfront.
-
-**Keywords:** enterprise, multi-tenant, multiple products, ecosystem, scale
-
----
-
-## Workflow Comparison
-
-| Level | Analysis    | Planning         | Architecture | Epic-Tech-Specs   | Stories | Retrospectives          |
-| ----- | ----------- | ---------------- | ------------ | ----------------- | ------- | ----------------------- |
-| **0** | Optional    | Tech-spec        | None         | N/A (no epics)    | 1       | N/A                     |
-| **1** | Optional    | Tech-spec + Epic | None         | N/A (single epic) | 2-3     | 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         |
-
----
-
-## Documentation Progression
-
-### Level 0-1: Tech-Spec as Primary Doc
-
-**Why tech-spec for Level 0-1?**
-
-- Changes are focused and atomic
-- Context is specific to implementation
-- Speed is priority
-- Full product planning is overkill
-
-**Tech-spec contents:**
-
-- Technical approach
-- File-level changes
-- Implementation guide
-- Testing strategy
-- **Includes UX considerations** if user-facing
-
-**Created:** Upfront, serves as complete planning doc
-
----
-
-### Level 2: PRD + Optional Architecture
-
-**Why PRD instead of tech-spec?**
-
-- Multiple features need coordination
-- Product vision and requirements matter
-- Stakeholder alignment needed
-- Feature interdependencies exist
-
-**PRD contents:**
-
-- Product vision and goals
-- Feature requirements
-- Epics and story breakdown
-- Success criteria
-- User experience considerations
-
-**Architecture (optional):**
-
-- Only if system design needed
-- Lightweight architectural decisions
-- Component interactions
-- Data models
-
-**Epic-tech-specs (recommended during implementation):**
-
-- Created as each epic is worked on
-- Detailed technical guidance per epic
-- Supplements PRD with implementation details
-
-**Created:** PRD upfront, epic-tech-specs during implementation
-
----
-
-### Level 3-4: PRD + Architecture + Epic-Tech-Specs
-
-**Why comprehensive planning?**
-
-- Complex integrations
-- Multiple subsystems
-- Long-term maintainability
-- Risk management
-- Team coordination
-
-**PRD contents:**
-
-- Comprehensive product vision
-- Detailed requirements
-- Business objectives
-- Market considerations
-- Complete epic breakdown
-
-**Architecture (required):**
-
-- System design
-- Component architecture
-- Data models
-- Integration patterns
-- Security design
-- Performance requirements
-- **Scales with complexity** (Level 3 vs Level 4)
-
-**Epic-tech-specs (recommended during implementation):**
-
-- Created before implementing each epic
-- Code-level design decisions
-- Epic-specific implementation approach
-- Detailed testing strategy
-
-**Additional design docs (as-needed):**
-
-- For novel or complex subsystems
-- Created during implementation
-- Not all created upfront
-- Examples: detailed integration specs, performance optimization plans
-
-**Created:** PRD + Architecture upfront, epic-tech-specs and detail docs during implementation
-
----
-
-## Brownfield Projects: Document-Project First
-
-### Critical Workflow Step
-
-🚨 **For ALL brownfield projects (Level 0-4):**
-
-**BEFORE running any workflow:**
-
-1. Run `document-project` workflow
-2. This analyzes your codebase and creates `docs/index.md`
-3. Output includes sharded documentation of:
-   - Project structure
-   - Key modules
-   - Existing patterns
-   - Dependencies
-   - Configuration
-
-**Why it's 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
-
-```
-Step 1: document-project (FIRST!)
-         ↓
-         Creates docs/index.md with codebase analysis
-         ↓
-Step 2: workflow-init OR tech-spec directly
-         ↓
-         Uses docs/index.md for context
-         ↓
-Step 3: Continue with level-appropriate workflows
-```
-
-**Without document-project:**
-
-- Workflows can't detect existing patterns
-- Convention analysis won't work
-- Integration planning is incomplete
-- You'll miss existing code to reuse
-
----
-
-## Tech-Spec vs Epic-Tech-Spec
-
-### When to Use Each
-
-| Document           | Level | Created When             | Purpose                                         |
-| ------------------ | ----- | ------------------------ | ----------------------------------------------- |
-| **Tech-Spec**      | 0-1   | Upfront (Planning Phase) | Primary planning doc for small changes/features |
-| **Epic-Tech-Spec** | 2-4   | During Implementation    | Detailed technical guidance per epic            |
-
-### Tech-Spec (Level 0-1)
-
-**Characteristics:**
-
-- Created in Planning Phase
-- Serves as primary/only planning document
-- Comprehensive for the entire change/feature
-- Includes all context needed for implementation
-- Can include UX considerations inline
-
-**Workflow context:**
-
-```
-Planning Phase: Tech-Spec created here
-                     ↓
-Implementation Phase: Stories implemented using tech-spec
-```
-
-### Epic-Tech-Spec (Level 2-4)
-
-**Characteristics:**
-
-- Created in Implementation Phase
-- Supplements PRD + Architecture
-- Focused on single epic
-- Detailed code-level design
-- References architecture decisions
-
-**Workflow context:**
-
-```
-Planning Phase: PRD + Architecture created here
-                     ↓
-Implementation Phase:
-  - Epic 1 starts
-  - Create epic-tech-spec-1 (just-before-implementation)
-  - Implement stories for epic 1
-  - Retrospective
-  - Epic 2 starts
-  - Create epic-tech-spec-2
-  - Implement stories for epic 2
-  - Retrospective
-  - ...
-```
-
-**Why not created upfront?**
-
-- 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
-
----
-
-## Level 2 Architecture vs Tech-Spec
-
-### The Question
-
-"What takes the place of architecture with Level 2 since there is no tech-spec?"
-
-### The Answer
-
-Level 2 uses **Architecture document (optional)** instead of tech-spec for system-level planning.
-
-**Comparison:**
-
-| Aspect       | Tech-Spec (Level 0-1)                | Architecture (Level 2)             |
-| ------------ | ------------------------------------ | ---------------------------------- |
-| **Purpose**  | Implementation plan for small change | System design for medium project   |
-| **Scope**    | Single change or small feature       | Multiple epics and features        |
-| **Focus**    | Code-level details                   | System-level design                |
-| **When**     | Replaces need for PRD+Arch           | Supplements PRD                    |
-| **Required** | Yes (primary doc)                    | Optional (if system design needed) |
-
-**Level 2 Documentation Options:**
-
-**Option A: PRD Only (no architecture)**
-
-- For projects that don't need system design
-- Features are independent
-- No complex integrations
-- Example: Admin dashboard with CRUD screens
-
-**Option B: PRD + Architecture**
-
-- For projects needing system design
-- Components interact
-- Integrations exist
-- Example: Customer portal with notifications, webhooks, reporting
-
-**Plus Epic-Tech-Specs (recommended):**
-
-- Created during implementation
-- One per epic
-- Detailed technical guidance
-- References Architecture decisions (if architecture exists)
-
----
-
-## Retrospectives in Multi-Epic Projects
-
-### When to Run Retrospectives
-
-**Trigger:** After completing each epic in Level 2-4 projects **when there are multiple epics**
-
-**Example:**
-
-- Level 2 project with 3 epics
-- Complete Epic 1 → Retrospective
-- Complete Epic 2 → Retrospective
-- Complete Epic 3 → Final retrospective
-
-**Purpose:**
-
-- Capture learnings from completed epic
-- Identify improvements for next epic
-- Adjust approach based on what worked/didn't
-- Feed insights into next epic-tech-spec
-
-### Retrospective Contents
-
-- What went well?
-- What could be improved?
-- Technical insights gained
-- Process adjustments needed
-- Input for next epic planning
-
-**Output feeds into:**
-
-- Next epic-tech-spec
-- Architecture refinements
-- Team process improvements
-
----
-
-## How Level Detection Works
-
-### Automatic Detection (workflow-init)
-
-When you run `workflow-init`, it analyzes your project description using:
-
-#### 1. **Keyword Analysis**
-
-Scans for level-specific keywords:
-
-**Level 0 Keywords:**
-
-- fix, bug, typo, small change, quick update, patch
-
-**Level 1 Keywords:**
-
-- simple, basic, small feature, add, minor
-
-**Level 2 Keywords:**
-
-- dashboard, several features, admin panel, medium
-
-**Level 3 Keywords:**
-
-- platform, integration, complex, system, architecture
-
-**Level 4 Keywords:**
-
-- enterprise, multi-tenant, multiple products, ecosystem, scale
-
-#### 2. **Story Count Estimation**
-
-Asks about expected scope:
-
-| Level   | Story Range   |
-| ------- | ------------- |
-| Level 0 | 1 story       |
-| Level 1 | 1-10 stories  |
-| Level 2 | 5-15 stories  |
-| Level 3 | 12-40 stories |
-| Level 4 | 40+ stories   |
-
-#### 3. **Complexity Indicators**
-
-- Multiple teams involved?
-- External integrations?
-- Compliance requirements?
-- Multi-tenant needs?
-- Existing system modifications? (triggers brownfield)
-
-### Manual Override
-
-You can always override the detected level if workflow-init gets it wrong. The system is a guide, not a constraint.
-
----
-
-## Field Types: Greenfield vs Brownfield
-
-Each level has **two workflow paths**:
-
-### Greenfield (New Project)
-
-- Starting from scratch
-- No existing codebase
-- Establishing new patterns
-- Freedom to choose stack
-
-**Special Features:**
-
-- Starter template recommendations
-- Modern best practices via WebSearch
-- Convention establishment
-
-**Workflow:**
-
-```
-workflow-init → Level detection → Greenfield path
-```
-
-### Brownfield (Existing Project)
-
-- Adding to existing code
-- Working with established patterns
-- Integration with current systems
-- Stack already chosen
-
-**Special Features:**
-
-- Auto-detects existing conventions
-- Analyzes current patterns
-- Confirms before deviating
-- Respects established standards
-
-**Workflow:**
-
-```
-document-project (FIRST!) → workflow-init → Level detection → Brownfield path
-```
-
-**Critical difference:** Brownfield requires document-project BEFORE any other workflow.
-
----
-
-## 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 → Greenfield-level-0.yaml
-
-**Workflow:**
-
-1. (Optional) Brief analysis
-2. Tech-spec with single story
-3. Implement immediately
-
----
-
-### 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 → Greenfield-level-1.yaml
-
-**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
-
----
-
-### 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 → Greenfield-level-2.yaml
-
-**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
-
----
-
-### 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 → Greenfield-level-3.yaml
-
-**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
-
----
-
-### Scenario 5: Adding Feature to Existing App (Brownfield)
-
-**Input:** "Add search functionality to existing product catalog"
-
-**Detection:**
-
-- Keywords: "add", "existing"
-- Estimated stories: 3-4
-- Field type: Brownfield
-
-**Result:** Level 1 → Brownfield-level-1.yaml
-
-**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
-
----
-
-## Workflow Paths Configuration
-
-BMad Method stores workflow paths in YAML configuration files:
-
-### Path File Structure
-
-```
-src/modules/bmm/workflows/workflow-status/paths/
-├── greenfield-level-0.yaml
-├── greenfield-level-1.yaml
-├── greenfield-level-2.yaml
-├── greenfield-level-3.yaml
-├── greenfield-level-4.yaml
-├── brownfield-level-0.yaml
-├── brownfield-level-1.yaml
-├── brownfield-level-2.yaml
-├── brownfield-level-3.yaml
-├── brownfield-level-4.yaml
-├── game-design.yaml
-└── project-levels.yaml (source of truth)
-```
-
-### Path File Format
-
-Each path file defines:
-
-```yaml
-project_type: 'software'
-level: 2
-field_type: 'greenfield'
-description: 'Medium project - multiple epics'
-
-phases:
-  - phase: 1
-    name: 'Analysis'
-    optional: true
-    workflows:
-      - id: 'brainstorm-project'
-        optional: true
-        agent: 'analyst'
-        command: 'brainstorm-project'
-
-  - phase: 2
-    name: 'Planning'
-    required: true
-    workflows:
-      - id: 'prd'
-        required: true
-        agent: 'pm'
-        command: 'prd'
-        output: 'Creates PRD with epics and stories'
-```
-
-### Phase Structure
-
-Each level defines **4 phases**:
-
-1. **Analysis Phase**
-   - Brainstorming
-   - Research
-   - Product Brief
-   - Complexity: Increases with level
-
-2. **Planning Phase**
-   - Level 0-1: Tech-spec
-   - Level 2-4: PRD + (optional/required) Architecture
-
-3. **Solutioning Phase**
-   - Level 0-2: Skipped or optional architecture
-   - Level 3-4: Required architecture + gate checks
-
-4. **Implementation Phase**
-   - Sprint planning
-   - Story-by-story development
-   - Epic-tech-specs created per epic (Level 2-4)
-   - Retrospectives after each epic (Level 2-4)
-
----
-
-## Best Practices
-
-### 1. **Document-Project First for Brownfield**
-
-Always run document-project before starting any brownfield workflow. This is critical for context.
-
-### 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.
-
----
-
-## FAQ
-
-### Q: What's the difference between tech-spec and epic-tech-spec?
-
-**A:**
-
-- **Tech-spec (Level 0-1):** Created upfront in Planning Phase, serves as primary planning doc
-- **Epic-tech-spec (Level 2-4):** Created during Implementation Phase per epic, supplements PRD + Architecture
-
-### Q: Why no tech-spec at Level 2+?
-
-**A:** At Level 2+, you need product-level planning (PRD) and optionally system-level design (Architecture). Tech-spec is too narrow. 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 can work with just PRD + epic-tech-specs.
-
-### Q: What if I forget to run document-project on brownfield?
-
-**A:** Workflows will lack context about existing code. Run document-project and restart your workflow to get proper brownfield analysis.
-
-### Q: Can Level 1 include UX Design?
-
-**A:** Yes! You can either:
-
-- Include UX considerations in the tech-spec (simpler)
-- Run separate UX Design workflow (complex UI)
-
-### Q: When do I create additional design documents?
-
-**A:** Create them during implementation as-needed for:
-
-- Very novel technical approaches
-- Complex subsystems needing detailed design
-- Integration specifications
-- Performance optimization plans
-
-Don't create them all upfront - create just-before-needed.
-
-### Q: Can I change levels mid-project?
-
-**A:** Yes! If you started at Level 1 but realize it's Level 2, you can run `create-prd` to add proper planning docs. The system is flexible.
-
----
-
-## Summary
-
-The Scale Adaptive System ensures:
-
-✅ **Level 0-1:** Fast, lean, tech-spec only → Quick Spec Flow
-✅ **Level 2:** Structured, PRD-driven, optional architecture, epic-tech-specs during implementation
-✅ **Level 3-4:** Comprehensive, PRD + Architecture required, epic-tech-specs per epic, gate checks
-
-**Key Principles:**
-
-- Match planning depth to project complexity
-- Tech-spec for Level 0-1, PRD + Architecture for Level 2-4
-- Epic-tech-specs supplement Level 2-4 during implementation
-- Document-project FIRST for all brownfield projects
-- Create detailed docs just-before-needed, not all upfront
-
-**Result:** Right amount of ceremony for every project, maximum efficiency at every scale.
-
----
-
-## Learn More
-
-- **Quick Spec Flow (Level 0-1):** [quick-spec-flow.md](./quick-spec-flow.md)
-- **Full BMM Workflows (Level 2-4):** [../workflows/README.md](../workflows/README.md)
-- **Document-Project Workflow:** Ask SM agent to run document-project
-- **Run workflow-init:** Load PM agent and ask to run workflow-init
-- **Path Configuration:** `../workflows/workflow-status/paths/`
-- **Level Definitions:** `../workflows/workflow-status/project-levels.yaml`
-
----
-
-_Scale Adaptive System - Because one size doesn't fit all._