BMAD-METHOD/bmad/bmm/docs/scale-adaptive-system.md

31 KiB

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:

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
  • Full BMM Workflows (Level 2-4): ../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.