---
last-redoc-date: 2025-10-12
---

# BMM Workflows - The Complete v6 Flow

The BMM (BMAD Method Module) orchestrates software development through four distinct phases, each with specialized workflows that adapt to project scale (Level 0-4) and context (greenfield vs brownfield). This document serves as the master guide for understanding how these workflows interconnect to deliver the revolutionary v6 methodology.

## Core v6 Innovations

**Scale-Adaptive Planning**: Projects automatically route through different workflows based on complexity (Level 0-4), ensuring appropriate documentation and process overhead.

**Just-In-Time Design**: Technical specifications are created one epic at a time during implementation, not all upfront, incorporating learnings as the project evolves.

**Dynamic Expertise Injection**: Story-context workflows provide targeted technical guidance per story, replacing static documentation with contextual expertise.

**Continuous Learning Loop**: Retrospectives feed improvements back into workflows, making each epic smoother than the last.

## The Four Phases

```
┌──────────────────────────────────────────────────────────────┐
│                    PHASE 1: ANALYSIS                         │
│                      (Optional)                              │
├──────────────────────────────────────────────────────────────┤
│  brainstorm-game ──┐                                         │
│  brainstorm-project ├──→ research ──→ product-brief  ──┐     │
│  game-brief ────────┘                          game-brief ┘  │
└────────────────────────────────────────────────────────┼─────┘
                                                         ↓
┌──────────────────────────────────────────────────────────────┐
│                    PHASE 2: PLANNING                         │
│              (Scale-Adaptive Router - by type)               │
├──────────────────────────────────────────────────────────────┤
│  SOFTWARE: plan-project          GAMES: gdd            │
│      ├──→ Level 0: tech-spec only      ├──→ GDD (all levels) │
│      ├──→ Level 1: tech-spec only      └──→ Narrative design │
│      ├──→ Level 2: PRD + tech-spec                           │
│      └──→ Level 3-4: PRD + Epics ────────────────────────┐   │
└──────────────────────────────────────────────────────────┼───┘
                                                           ↓
┌──────────────────────────────────────────────────────────────┐
│                   PHASE 3: SOLUTIONING                       │
│              (Software Levels 3-4 / Complex Games)           │
├──────────────────────────────────────────────────────────────┤
│  3-solutioning ──→ solution-architecture.md                  │
│       ↓                                                      │
│  tech-spec (per epic, JIT during implementation)             │
└────────────────────────────────────────────────────────────┬─┘
                                                             ↓
┌──────────────────────────────────────────────────────────────┐
│                  PHASE 4: IMPLEMENTATION                     │
│                    (Iterative Cycle)                         │
├──────────────────────────────────────────────────────────────┤
│  ┌─→ create-story ──→ story-context ──→ dev-story ──┐        │
│  │                                                  ↓        │
│  │   retrospective ←── [epic done] ←────── review-story      │
│  │                                            ↓              │
│  └──────────── correct-course ←──[if issues]──┘              │
└──────────────────────────────────────────────────────────────┘
```

## Universal Entry Point: workflow-status

**Before starting any workflow, check your status!**

The `workflow-status` workflow is the **universal entry point** for all BMM workflows:

```bash
bmad analyst workflow-status
# or
bmad pm workflow-status
```

**What it does:**

- ✅ Checks for existing workflow status file
- ✅ Displays current phase, progress, and next action
- ✅ Helps new users plan their workflow approach
- ✅ Guides brownfield projects to documentation first
- ✅ Routes to appropriate workflows based on context

**No status file?** It will:

1. Ask about project context (greenfield vs brownfield)
2. Offer analysis options (full analysis, skip to planning, or quick tech spec)
3. Guide you to the right first workflow

**Status file exists?** It will:

1. Display current phase and progress
2. Show Phase 4 implementation state (BACKLOG/TODO/IN PROGRESS/DONE)
3. Recommend exact next action
4. Offer to change workflow or display menu

**All agents (bmad-master, analyst, pm) should check workflow-status on load.**

---

## Phase 1: Analysis (Optional)

Optional workflows for project discovery and requirements gathering. Output feeds into Phase 2 planning.

### Workflows

| Workflow               | Purpose                                     | Output                    | When to Use            |
| ---------------------- | ------------------------------------------- | ------------------------- | ---------------------- |
| **workflow-status**    | Universal entry point and status checker    | Status display + guidance | **Always start here!** |
| **brainstorm-game**    | Game concept ideation using 5 methodologies | Concept proposals         | New game projects      |
| **brainstorm-project** | Software solution exploration               | Architecture proposals    | New software projects  |
| **game-brief**         | Structured game design foundation           | Game brief document       | Before GDD creation    |
| **product-brief**      | Strategic product planning culmination      | Product brief             | End of analysis phase  |
| **research**           | Multi-mode research (market/technical/deep) | Research artifacts        | When evidence needed   |

### Flow

```
workflow-status (check) → Brainstorming → Research → Brief → Planning (Phase 2)
```

## Phase 2: Planning (Required)

The central orchestrator that determines project scale and generates appropriate planning artifacts.

### Scale Levels

| Level | Scope                    | Outputs                        | Next Phase                     |
| ----- | ------------------------ | ------------------------------ | ------------------------------ |
| **0** | Single atomic change     | tech-spec + 1 story            | → Implementation               |
| **1** | 1-10 stories, 1 epic     | tech-spec + epic + 2-3 stories | → Implementation               |
| **2** | 5-15 stories, 1-2 epics  | PRD + epics                    | → Tech-spec → Implementation   |
| **3** | 12-40 stories, 2-5 epics | PRD + epics                    | → Solutioning → Implementation |
| **4** | 40+ stories, 5+ epics    | PRD + epics                    | → Solutioning → Implementation |

**Key Changes (v6a):**

- **Level 0**: Now generates a single user story in addition to tech-spec
- **Level 1**: Now generates 2-3 stories as part of planning (prefer longer stories over more stories)
- Both Level 0/1 skip Phase 3 and populate Phase 4 story backlog automatically

### Routing Logic

**Universal Entry Point** (workflow-status):

```
workflow-status
    ├─→ Check for existing status file
    │   ├─→ If exists: Display status + recommend next action
    │   └─→ If not exists: Guide workflow planning
    ├─→ Determine project context (greenfield/brownfield)
    ├─→ Determine project type (game/web/mobile/backend/etc)
    ├─→ Assess complexity → assign Level 0-4
    ├─→ Map complete workflow journey
    └─→ Generate bmm-workflow-status.md + direct to first workflow
```

**Direct Routing** (no intermediate routers):

```
workflow-status determines routing:

    SOFTWARE PROJECTS:
    ├─→ Level 0-1 → bmad architect tech-spec
    │   └─→ Validates status file + level
    │   └─→ Generates tech-spec.md + stories
    │   └─→ Direct to Phase 4 (implementation)
    │
    ├─→ Level 2 → bmad pm prd
    │   └─→ Validates status file + level
    │   └─→ Generates PRD.md + epics.md
    │   └─→ Then: bmad architect tech-spec (lightweight solutioning)
    │   └─→ Then: Phase 4 (implementation)
    │
    └─→ Level 3-4 → bmad pm prd
        └─→ Validates status file + level
        └─→ Generates PRD.md + epics.md
        └─→ Then: Phase 3 (solution-architecture)
        └─→ Then: Phase 4 (implementation)

    GAME PROJECTS:
    └─→ All Levels → bmad pm gdd
        └─→ Validates status file + project type
        └─→ Generates GDD.md + epics.md
        └─→ Optional: narrative design
        └─→ Then: Phase 3 or 4 (based on complexity)
```

### Key Outputs

- **PRD.md**: Product Requirements Document (Levels 2-4)
- **Epics.md**: Epic breakdown with stories (Levels 2-4)
- **epic-stories.md**: Epic summary with story links (Level 1)
- **tech-spec.md**: Technical specification (Levels 0-2 only)
- **story-{slug}.md**: Single user story (Level 0)
- **story-{slug}-1.md, story-{slug}-2.md, story-{slug}-3.md**: User stories (Level 1)
- **GDD.md**: Game Design Document (game projects)
- **bmm-workflow-status.md**: Versioned workflow state tracking with story backlog

## Phase 3: Solutioning (Levels 3-4 Only)

Architecture and technical design phase for complex projects.

### Workflows

| Workflow          | Owner     | Purpose                        | Output                             | Timing            |
| ----------------- | --------- | ------------------------------ | ---------------------------------- | ----------------- |
| **3-solutioning** | Architect | Create overall architecture    | solution-architecture.md with ADRs | Once per project  |
| **tech-spec**     | Architect | Create epic-specific tech spec | tech-spec-epic-N.md                | One per epic, JIT |

### Just-In-Time Tech Specs

```
FOR each epic in sequence:
    WHEN ready to implement epic:
        Architect: Run tech-spec workflow for THIS epic only
        → Creates tech-spec-epic-N.md
        → Hands off to implementation
    IMPLEMENT epic completely
    THEN move to next epic
```

**Critical**: Tech specs are created ONE AT A TIME as epics are ready for implementation, not all upfront. This prevents over-engineering and incorporates learning.

## Phase 4: Implementation (Iterative)

The core development cycle that transforms requirements into working software.

### The Story State Machine

Phase 4 uses a 4-state lifecycle to manage story progression, tracked in `bmm-workflow-status.md`:

```
BACKLOG → TODO → IN PROGRESS → DONE
```

#### State Definitions

- **BACKLOG**: Ordered list of stories to be drafted (populated at phase transition)
  - Contains all stories with IDs, titles, and file names
  - Order is sequential (Epic 1 stories first, then Epic 2, etc.)

- **TODO**: Single story that needs drafting (or drafted, awaiting approval)
  - SM drafts story here using `create-story` workflow
  - Story status is "Draft" until user approves
  - User runs `story-ready` workflow to approve

- **IN PROGRESS**: Single story approved for development
  - Moved here by `story-ready` workflow
  - DEV implements using `dev-story` workflow
  - Story status is "Ready" or "In Review"

- **DONE**: Completed stories with dates and points
  - Moved here by `story-approved` workflow after DoD complete
  - Immutable record of completed work

**Key Innovation**: Agents never search for "next story" - they always read the exact story from the status file.

### The Implementation Loop

```
Phase Transition (Phase 2 or 3 → Phase 4)
  ↓
┌─────────────────────────────────────────────────┐
│  BACKLOG populated with all stories              │
│  TODO initialized with first story               │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  SM: create-story (drafts story in TODO)        │
│  Reads: status file TODO section                │
│  Output: Story file with Status="Draft"         │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  User reviews story                              │
│  ↓                                               │
│  SM: story-ready (approves story)                │
│  Actions: TODO → IN PROGRESS                     │
│           BACKLOG → TODO (next story)            │
│           Story Status = "Ready"                 │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  SM: story-context (optional but recommended)   │
│  Generates expertise injection XML               │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  DEV: dev-story (implements story)               │
│  Reads: status file IN PROGRESS section         │
│  Implements with context injection               │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  User reviews implementation (DoD check)         │
│  ↓                                               │
│  DEV: story-approved (marks story done)          │
│  Actions: IN PROGRESS → DONE                     │
│           TODO → IN PROGRESS (if exists)         │
│           BACKLOG → TODO (if exists)             │
│           Story Status = "Done"                  │
└───────────────────┬─────────────────────────────┘
                    ↓
            ┌───────┴────────┐
            │  More stories?  │
            └───────┬─────────┘
                ┌───┴───┐
                ↓       ↓
          [Yes: Loop]  [No: Epic/Project Complete]
                         ↓
                   [retrospective]
```

### Workflow Responsibilities

| Workflow           | Agent  | Purpose                               | State Transition      | No Search Required       |
| ------------------ | ------ | ------------------------------------- | --------------------- | ------------------------ |
| **create-story**   | SM     | Draft story from TODO section         | (Story stays in TODO) | Reads TODO section       |
| **story-ready**    | SM     | Approve drafted story for development | TODO → IN PROGRESS    | Reads TODO section       |
| **story-context**  | SM     | Generate expertise injection XML      | (No state change)     | Reads IN PROGRESS        |
| **dev-story**      | DEV    | Implement story                       | (No state change)     | Reads IN PROGRESS        |
| **story-approved** | DEV    | Mark story done after DoD complete    | IN PROGRESS → DONE    | Reads IN PROGRESS        |
| **review-story**   | SR/DEV | Quality validation (optional)         | (No state change)     | Manual story selection   |
| **correct-course** | SM     | Handle issues/changes                 | (Adaptive)            | Manual story selection   |
| **retrospective**  | SM     | Capture epic learnings                | (No state change)     | Manual or epic-triggered |

### Story File Status Values

Stories have a `Status:` field in their markdown file that reflects their position in the state machine:

```
Status: Draft       (Story created by create-story, awaiting user review)
  ↓
Status: Ready       (User approved via story-ready, ready for implementation)
  ↓
Status: In Review   (Implementation complete, awaiting final approval)
  ↓
Status: Done        (User approved via story-approved, DoD complete)
```

**Status File Position vs Story File Status:**

| Status File State | Story File Status    | Meaning                               |
| ----------------- | -------------------- | ------------------------------------- |
| BACKLOG           | (file doesn't exist) | Story not yet drafted                 |
| TODO              | Draft                | Story drafted, awaiting user approval |
| IN PROGRESS       | Ready or In Review   | Story approved for development        |
| DONE              | Done                 | Story complete, DoD met               |

## Greenfield vs Brownfield Considerations

### Greenfield Projects

- Start with Phase 1 (Analysis) or Phase 2 (Planning)
- Clean architecture decisions in Phase 3
- Straightforward implementation in Phase 4

### Brownfield Projects

```
plan-project (Phase 2)
    ├─→ Check: Is existing codebase documented?
    │   ├─→ YES: Proceed with planning
    │   └─→ NO: HALT with message:
    │       "Brownfield project requires documentation.
    │        Please run codebase-analysis workflow first."
    │        └─→ [TBD: brownfield-analysis workflow]
    │            ├─→ Analyzes existing code
    │            ├─→ Documents current architecture
    │            ├─→ Identifies technical debt
    │            └─→ Creates baseline documentation
    └─→ Continue with scale-adaptive planning
```

**Critical for Brownfield**: Without adequate documentation of the existing system, the planning phase cannot accurately assess scope or create meaningful requirements. The brownfield-analysis workflow (coming soon) will:

- Map existing architecture
- Document current patterns
- Identify integration points
- Assess technical debt
- Create the baseline needed for planning

## Agent Participation by Phase

| Phase              | Primary Agents      | Supporting Agents           |
| ------------------ | ------------------- | --------------------------- |
| **Analysis**       | Analyst, Researcher | PM, PO                      |
| **Planning**       | PM                  | Analyst, UX Expert          |
| **Solutioning**    | Architect           | PM, Tech Lead               |
| **Implementation** | SM, DEV             | SR, PM (for correct-course) |

## Key Files and Artifacts

### Tracking Documents

- **bmm-workflow-status.md**: Versioned workflow state tracking with 4-section story backlog
  - **BACKLOG**: Ordered list of stories to be drafted
  - **TODO**: Single story ready for drafting (or drafted, awaiting approval)
  - **IN PROGRESS**: Single story approved for development
  - **DONE**: Completed stories with dates and points
  - Populated automatically at phase transitions
  - Single source of truth for story progression
  - Agents read (never search) to know what to work on next

- **Epics.md**: Master list of epics and stories (source of truth for planning, Level 2-4)

### Phase Outputs

- **Phase 1**: Briefs and research documents
- **Phase 2**:
  - Level 0: tech-spec.md + story-{slug}.md
  - Level 1: tech-spec.md + epic-stories.md + story-{slug}-N.md files
  - Level 2: PRD.md + epics.md (then tech-spec.md in Phase 3)
  - Level 3-4: PRD.md + epics.md (then solution-architecture.md in Phase 3)
- **Phase 3**: solution-architecture.md, epic-specific tech specs
- **Phase 4**: Story files, context XMLs, implemented code

## Best Practices

### 1. Respect the Scale

- Don't create PRDs for Level 0 changes
- Don't skip architecture for Level 3-4 projects
- Let the workflow determine appropriate artifacts

### 2. Embrace Just-In-Time

- Create tech specs one epic at a time
- Generate stories as needed, not in batches
- Build context injections per story

### 3. Maintain Flow Integrity

- Stories must be enumerated in Epics.md
- Each phase completes before the next begins
- Use fresh context windows for reviews

### 4. Document Brownfield First

- Never plan without understanding existing code
- Technical debt must be visible in planning
- Integration points need documentation

### 5. Learn Continuously

- Run retrospectives after each epic
- Update workflows based on learnings
- Share patterns across teams

## Common Pitfalls and Solutions

| Pitfall                           | Solution                              |
| --------------------------------- | ------------------------------------- |
| Creating all tech specs upfront   | Use JIT approach - one epic at a time |
| Skipping story-context generation | Always run after create-story         |
| Batching story creation           | Create one story at a time            |
| Ignoring scale levels             | Let plan-project determine level      |
| Planning brownfield without docs  | Run brownfield-analysis first         |
| Not running retrospectives        | Schedule after every epic             |

## Quick Reference Commands

```bash
# Universal Entry Point (Start Here!)
bmad analyst workflow-status  # Check status and get recommendations

# Phase 1: Analysis (Optional)
bmad analyst brainstorm-project
bmad analyst research
bmad analyst product-brief

# Phase 2: Planning
bmad pm prd             # Level 2-4 software projects
bmad architect tech-spec # Level 0-1 software projects
bmad pm gdd             # Game projects

# Phase 3: Solutioning (L3-4)
bmad architect solution-architecture
bmad architect tech-spec  # Per epic, JIT

# Phase 4: Implementation
bmad sm create-story      # Draft story from TODO section
bmad sm story-ready       # Approve story for development (after user review)
bmad sm story-context     # Generate context XML (optional but recommended)
bmad dev dev-story        # Implement story from IN PROGRESS section
bmad dev story-approved   # Mark story done (after user confirms DoD)
bmad dev review-story     # Quality validation (optional)
bmad sm correct-course    # If issues arise
bmad sm retrospective     # After epic complete
```

## Future Enhancements

### Coming Soon

- **brownfield-analysis**: Automated codebase documentation generator
- **Workflow orchestration**: Automatic phase transitions
- **Progress dashboards**: Real-time workflow status
- **Team synchronization**: Multi-developer story coordination

### Under Consideration

- AI-assisted retrospectives
- Automated story sizing
- Predictive epic planning
- Cross-project learning transfer

---

This document serves as the authoritative guide to BMM v6a workflow execution. For detailed information about individual workflows, see their respective README files in the workflow folders.
