BMAD-METHOD/src/modules/bmm/workflows

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 Five Phases

┌──────────────────────────────────────────────────────────────┐
│              PHASE 0: DOCUMENTATION (Brownfield)             │
│                  (Conditional - if undocumented)             │
├──────────────────────────────────────────────────────────────┤
│  document-project ──→ Codebase documentation                 │
└────────────────────────────────────────────────────────┼─────┘
                                                         ↓
┌──────────────────────────────────────────────────────────────┐
│                    PHASE 1: ANALYSIS                         │
│                      (Optional)                              │
├──────────────────────────────────────────────────────────────┤
│  brainstorm-game  ──┐                                        │
│  brainstorm-project ├──→ research ──→ product-brief  ──┐     │
│  game-brief ────────┘                          game-brief    │
└────────────────────────────────────────────────────────┼─────┘
                                                         ↓
┌──────────────────────────────────────────────────────────────┐
│                    PHASE 2: PLANNING                         │
│              (Scale-Adaptive Router - by type)               │
├──────────────────────────────────────────────────────────────┤
│  SOFTWARE: prd/tech-spec    GAMES: gdd/narrative             │
│      ├──→ Level 0: tech-spec only      ├──→ GDD (all levels) │
│      ├──→ Level 1: tech-spec only      └──→ Narrative (opt)  │
│      ├──→ Level 2: PRD + Epics ──────────────────────────┐   │
│      └──→ Level 3-4: PRD + Epics ────────────────────────┼┐  │
│  UX: create-ux-design (conditional)                      ││  │
└──────────────────────────────────────────────────────────┼┼──┘
                                                           ↓↓
┌──────────────────────────────────────────────────────────────┐
│                   PHASE 3: SOLUTIONING                       │
│           (Software Levels 2-4 / Complex Games)              │
├──────────────────────────────────────────────────────────────┤
│  create-architecture ──→ architecture.md                     │
│  validate-architecture (optional)                            │
│  solutioning-gate-check (recommended/required)               │
└────────────────────────────────────────────────────────────┬─┘
                                                             ↓
┌──────────────────────────────────────────────────────────────┐
│                  PHASE 4: IMPLEMENTATION                     │
│                    (Sprint-Based Cycle)                      │
├──────────────────────────────────────────────────────────────┤
│  sprint-planning ──→ sprint-status.yaml                      │
│       ↓                                                      │
│  ┌─→ epic-tech-context (per epic)                            │
│  │   ↓                                                       │
│  │   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, if you have not already set up your workflow, run workflow-init, but even if you just run the workflow-status and the file does not exist you should still be directed to run workflow-init.

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. Generate your bmm-workflow-status.md file.

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 phase 1-3 workflows should check workflow-status on start of the workflow.

---

Phase 0: Documentation (Brownfield Only)

Required for undocumented brownfield projects before planning can begin.

Workflows

Workflow	Agent	Purpose	Output	When to Use
document-project	Analyst	Document existing codebase	Project documentation	Brownfield without adequate docs

Flow

Brownfield Check → document-project → Analysis/Planning (Phase 1/2)

Critical: Brownfield projects require adequate documentation before planning. If workflow-init detects an undocumented brownfield project, it will direct you to run document-project first.

---

Phase 1: Analysis (Optional)

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

Workflows

Workflow	Agent	Purpose	Output	When to Use
workflow-status	Analyst	Universal entry point and status checker	Status display + guidance	Start here!
workflow-init	Analyst	Generate an initial workflow status file	Status display + guidance	OR start here!
brainstorm-game	Game Designer	Game concept ideation using 5 methodologies	Concept proposals	New game projects
brainstorm-project	Analyst	Software solution exploration	Architecture proposals	New software projects
game-brief	Game Designer	Structured game design foundation	Game brief document	Before GDD creation
product-brief	Analyst	Strategic product planning culmination	Product brief	End of analysis phase
research	Analyst	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)

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	→ Solutioning → Implementation
3	12-40 stories, 2-5 epics	PRD + epics	→ Solutioning → Implementation
4	40+ stories, 5+ epics	PRD + epics	→ Solutioning → Implementation

Available Workflows

Workflow	Agent	Purpose	Output	Levels
prd	PM	Product Requirements Document	PRD.md + epics	2-4
tech-spec	PM	Technical specification	tech-spec.md	0-1
gdd	PM	Game Design Document	GDD.md	Games (all)
narrative	PM	Game narrative design	narrative.md	Games (opt)
create-ux-design	UX Designer	User experience and interface design	ux-design.md	Conditional

Key Outputs

• PRD.md: Product Requirements Document (Levels 2-4)
• Epics.md: Epic breakdown with stories (Levels 2-4)
• tech-spec.md: Technical specification (Levels 0-1)
• 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)
• narrative.md: Narrative design (game projects, optional)
• ux-design.md: UX specification (conditional, UI-heavy projects)
• bmm-workflow-status.md: Versioned workflow state tracking

Phase 3: Solutioning (Levels 2-4)

Architecture and technical design phase for medium to complex projects.

Workflows

Workflow	Agent	Purpose	Output	When
create-architecture	Architect	Create system-wide architecture	architecture.md with ADRs	Levels 2-4
validate-architecture	Architect	Validate architecture design	Validation report	Optional
solutioning-gate-check	Architect	Validate PRD + UX + architecture	Gate check report	Recommended

Architecture Scope by Level

• Level 2: Lightweight architecture document focusing on key technical decisions
• Level 3-4: Comprehensive architecture with detailed ADRs, system diagrams, integration patterns

Phase 4: Implementation (Iterative)

The core development cycle that transforms requirements into working software through sprint-based iteration.

Sprint Planning - The Phase 4 Entry Point

Phase 4 begins with the sprint-planning workflow, which generates a sprint-status.yaml file that serves as the single source of truth for all implementation tracking.

What sprint-planning does:

1. Extracts all epics and stories from epic files
2. Creates ordered status tracking for every work item
3. Auto-detects existing story files and contexts
4. Maintains status through the development lifecycle

The Sprint Status System

Phase 4 uses a 6-state lifecycle tracked in sprint-status.yaml:

Epic Status Flow:

backlog → contexted

Story Status Flow:

backlog → drafted → ready-for-dev → in-progress → review → done

Retrospective Status:

optional ↔ completed

Status Definitions

Epic Statuses:

• backlog: Epic exists in epic file but not yet contexted
• contexted: Epic technical context created (prerequisite for drafting stories)

Story Statuses:

• backlog: Story only exists in epic file, not yet drafted
• drafted: Story file created (e.g., stories/1-3-plant-naming.md)
• ready-for-dev: Draft approved + story context created
• in-progress: Developer actively working on implementation
• review: Under SM review (via review-story workflow)
• done: Story completed and deployed

Retrospective Statuses:

• optional: Can be done but not required
• completed: Retrospective has been completed

The Implementation Loop

Phase Transition (Phase 2 or 3 → Phase 4)
  ↓
┌─────────────────────────────────────────────────┐
│  SM: sprint-planning                             │
│  Creates: sprint-status.yaml with all epics/    │
│           stories set to 'backlog'               │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  SM: epic-tech-context (for current epic)       │
│  Creates: epic-N-context.md                      │
│  Updates: Epic status to 'contexted'             │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  SM: create-story (drafts next backlog story)   │
│  Creates: story-{key}.md                         │
│  Updates: Story status to 'drafted'              │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  SM: story-context (creates implementation ctx)  │
│  Creates: story-{key}-context.md                 │
│  Updates: Story status to 'ready-for-dev'        │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  DEV: dev-story (implements story)               │
│  Reads: story + context files                    │
│  Updates: Story status to 'in-progress'          │
│           then to 'review' when complete         │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  SM: review-story (validates implementation)     │
│  Reviews: Code changes against DoD               │
│  Feedback: Iteration or approval                 │
└───────────────────┬─────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  DEV/SM: Updates story status to 'done'          │
│  Manual update to sprint-status.yaml             │
└───────────────────┬─────────────────────────────┘
                    ↓
            ┌───────┴────────┐
            │  More stories?  │
            └───────┬─────────┘
                ┌───┴───┐
                ↓       ↓
          [Yes: Loop]  [No: Epic Complete]
                         ↓
                   ┌─────────────────┐
                   │  SM: retrospective│
                   │  Updates: epic-N- │
                   │  retrospective to │
                   │  'completed'      │
                   └─────────────────┘

Workflow Responsibilities

Workflow	Agent	Purpose	Status Updates
sprint-planning	SM	Initialize sprint status tracking	Creates sprint-status.yaml
epic-tech-context	SM	Create epic-specific technical context	Epic: backlog → contexted
create-story	SM	Draft individual story files	Story: backlog → drafted
story-context	SM	Generate implementation context/XML	Story: drafted → ready-for-dev
dev-story	DEV	Implement story	Story: ready-for-dev → in-progress → review
review-story	SM/SR	Quality validation and feedback	(No automatic state change)
retrospective	SM	Capture epic learnings	Retrospective: optional → completed
correct-course	SM	Handle issues/scope changes	(Adaptive based on situation)

Key Guidelines

1. Epic Context First: Epics should be contexted before their stories can be drafted
2. Sequential by Default: Stories are typically worked in order within an epic
3. Parallel Work Supported: Multiple stories can be in-progress if team capacity allows
4. Learning Transfer: SM drafts next story after previous is done to incorporate learnings
5. Flexible Status Updates: Agents and users can manually update sprint-status.yaml as needed

Greenfield vs Brownfield Paths

Greenfield Projects (New Code)

Path: Phase 1 (optional) → Phase 2 → Phase 3 (Levels 2-4) → Phase 4

• Level 0-1: Skip Phase 3, go straight to implementation with tech-spec
• Level 2-4: Full solutioning with architecture before implementation
• Clean slate for architectural decisions
• No existing patterns to constrain design

Brownfield Projects (Existing Code)

Path: Phase 0 (if undocumented) → Phase 1 (optional) → Phase 2 → Phase 3 (Levels 2-4) → Phase 4

Phase 0 - Documentation (Conditional):

workflow-status/workflow-init
    ├─→ Check: Is existing codebase documented?
    │   ├─→ YES: Proceed to Phase 1 or 2
    │   └─→ NO: REQUIRED - Run document-project workflow
    │       ├─→ Analyzes existing code
    │       ├─→ Documents current architecture
    │       ├─→ Identifies technical debt
    │       └─→ Creates baseline documentation
    └─→ Continue with scale-adaptive planning

Critical for Brownfield:

• Must understand existing patterns before planning
• Integration points need documentation
• Technical debt must be visible in planning
• Constraints from existing system affect scale decisions

Agent Participation by Phase

Phase	Primary Agents	Supporting Agents	Key Workflows
0: Documentation	Analyst	-	document-project
1: Analysis	Analyst, Game Designer	PM, Researcher	brainstorm-_, research, _-brief
2: Planning	PM	UX Designer, Analyst	prd, tech-spec, gdd, narrative
3: Solutioning	Architect	PM, Tech Lead	create-architecture, solutioning-gate-check
4: Implementation	SM, DEV	SR (review-story)	sprint-planning, create-story, dev-story

Key Files and Artifacts

Tracking Documents

• bmm-workflow-status.md: Phase and workflow tracking (updated by workflow-status)

  • Current phase and progress
  • Workflow history
  • Next recommended actions
  • Project metadata and configuration

• sprint-status.yaml: Implementation tracking (Phase 4 only)

  • All epics, stories, and retrospectives
  • Current status for each item (backlog → done)
  • Single source of truth for Phase 4 progression
  • Updated by agents as work progresses

• Epics.md: Master epic/story definitions (source of truth for planning, Level 2-4)

Phase Outputs

• Phase 0:

  • Codebase documentation (project overview, architecture, source tree)

• Phase 1:

  • Product briefs, game briefs, research documents

• Phase 2:

  • Level 0: tech-spec.md + story-{slug}.md
  • Level 1: tech-spec.md + epic breakdown + story-{slug}-N.md files
  • Level 2-4: PRD.md + epics.md (+ optional ux-design.md, narrative.md)

• Phase 3:

  • architecture.md (with ADRs)
  • Validation reports
  • Gate check documentation

• Phase 4:

  • sprint-status.yaml (tracking file)
  • epic-N-context.md files (per epic)
  • story-{key}.md files (per story)
  • story-{key}-context.md files (per story)
  • Implemented code and tests

Best Practices

1. Respect the Scale

• Don't create PRDs for Level 0-1 changes (use tech-spec only)
• Don't skip architecture for Level 2-4 projects
• Let the workflow paths determine appropriate artifacts
• Level 2 still requires Phase 3 solutioning (lighter than 3-4)

2. Use Sprint Planning Effectively

• Run sprint-planning at the start of Phase 4
• Context epics before drafting their stories (epic-tech-context)
• Update sprint-status.yaml as work progresses
• Re-run sprint-planning to auto-detect new files/contexts

3. Maintain Flow Integrity

• Stories must be defined in Epics.md before sprint-planning
• Complete epic context before story drafting
• Create story context before implementation
• Each phase completes before the next begins

4. Document Brownfield First

• Never plan without understanding existing code
• Run document-project if codebase is undocumented
• Technical debt must be visible in planning
• Integration points need documentation

5. Learn Continuously

• Run retrospectives after each epic
• Incorporate learnings into next story drafts
• Update workflows based on team feedback
• Share patterns across teams

Common Pitfalls and Solutions

Pitfall	Solution
Skipping sprint-planning	Always run at Phase 4 start - it creates status file
Creating stories without epic context	Run epic-tech-context before create-story
Skipping story-context generation	Always run after create-story for better dev guidance
Not updating sprint-status.yaml	Update statuses as work progresses
Thinking Level 2 skips Phase 3	Level 2 DOES require architecture (just lighter)
Planning brownfield without docs	Run document-project first if undocumented
Not running retrospectives	Complete after every epic for learning transfer
Manually tracking stories elsewhere	Use sprint-status.yaml as single source of truth

Quick Reference Commands

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

# Phase 0: Documentation (Brownfield if needed)
bmad analyst document-project

# Phase 1: Analysis (Optional)
bmad analyst brainstorm-project    # Software ideation
bmad game-designer brainstorm-game # Game ideation
bmad analyst research              # Market/technical research
bmad analyst product-brief         # Software brief
bmad game-designer game-brief      # Game brief

# Phase 2: Planning (Required)
bmad pm prd                  # Level 2-4 software projects
bmad pm tech-spec            # Level 0-1 software projects
bmad pm gdd                  # Game projects (all levels)
bmad pm narrative            # Game narrative (optional)
bmad ux-designer create-ux-design  # UI-heavy projects

# Phase 3: Solutioning (Levels 2-4)
bmad architect create-architecture    # System architecture
bmad architect validate-architecture  # Validation (optional)
bmad architect solutioning-gate-check # Gate check

# Phase 4: Implementation (Sprint-Based)
bmad sm sprint-planning      # FIRST: Initialize sprint tracking
bmad sm epic-tech-context    # Create epic context (per epic)
bmad sm create-story         # Draft story file
bmad sm story-context        # Create story context
bmad dev dev-story           # Implement story
bmad sm review-story         # Quality validation
# (Update sprint-status.yaml to 'done' manually or via workflow)
bmad sm retrospective        # After epic complete
bmad sm correct-course       # If issues arise

Future Enhancements

Coming Soon

• Automated status updates: Workflows automatically update sprint-status.yaml
• Workflow orchestration: Automatic phase transitions and validation
• Progress dashboards: Real-time workflow status visualization
• Team synchronization: Multi-developer story coordination

Under Consideration

• AI-assisted retrospectives with pattern detection
• Automated story sizing based on historical data
• Predictive epic planning with risk assessment
• Cross-project learning transfer
• Enhanced brownfield analysis with architectural debt scoring

---

Version: v6-alpha Last Updated: 2025-10-26

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.

Related Documentation

• Workflow Paths: See workflow-status/paths/ for detailed greenfield/brownfield routing by level
• Phase 2 Planning: See 2-plan-workflows/README.md for scale-adaptive planning details
• Phase 4 Sprint Planning: See 4-implementation/sprint-planning/README.md for sprint status system
• Individual Workflows: Each workflow directory contains its own README with specific instructions