22 KiB

Raw Blame History

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

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

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

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:

No documentation: Run document-project workflow (10-30 min)
Has docs, no index.md: Run index-docs task (2-5 min)
Complete documentation: Skip to planning

For complete brownfield guidance: See Brownfield Development Guide

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:

(Optional) Brief analysis
Tech-spec with single story
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:

(Optional) Research OAuth providers
Tech-spec with epic + 3 stories
(Optional) UX Design if UI is complex
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:

Product Brief (recommended)
PRD with epics
(Optional) UX Design
(Optional) Architecture if system design needed
Implement with sprint planning
Create epic-tech-spec for each epic as you implement
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:

Research + Product Brief
Comprehensive PRD
UX Design (recommended)
System Architecture (required)
Gate check
Implement with phased approach
Create epic-tech-spec per epic before implementing
Run retrospective after each epic
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:

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.

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.

Quick Start Guide - Get started with BMM
Quick Spec Flow - Fast-track for Level 0-1
Brownfield Guide - Existing codebase workflows
Glossary - Complete terminology
FAQ - Common questions
Workflows Guide - Complete workflow reference

Scale Adaptive System - Because one size doesn't fit all.

22 KiB Raw Blame History

BMad Method Scale Adaptive System

Overview

The Problem It Solves

The Solution

Quick Reference

Five Levels at a Glance

Level Selection Decision Tree

Quick Keywords

How Level Detection Works

1. Keyword Analysis

2. Story Count Estimation

3. Complexity Indicators

Manual Override

The Five Levels

Level 0: Single Atomic Change

Level 1: Small Feature

Level 2: Medium Project

Level 3: Complex Integration

Level 4: Enterprise Scale

Planning Documents by Level

Understanding Document Types

Tech-Spec (Level 0-1)

PRD (Level 2-4)

Architecture Document (Level 2-4)

Epic-Tech-Spec (Level 2-4)

Workflow Comparison

Brownfield Projects

Critical First Step

Why document-project is Critical

Brownfield Workflow Pattern

Common Scenarios

Scenario 1: Bug Fix (Level 0)

Scenario 2: Small Feature (Level 1)

Scenario 3: Customer Portal (Level 2)

Scenario 4: E-commerce Platform (Level 3)

Scenario 5: Adding Feature to Existing App (Brownfield Level 1)

Best Practices

1. Document-Project First for Brownfield

2. Trust the Detection

3. Start Small, Upgrade Later

4. Don't Skip Gate Checks

5. Create Epic-Tech-Specs Just-Before-Implementation

6. Run Retrospectives Between Epics

7. Optional UX for Level 1

8. Architecture Scales

Appendix

A. Terminology Quick Reference

B. Workflow Path Configuration

C. FAQ

Related Documentation

22 KiB

Raw Blame History