BMAD-METHOD/src/modules/bmm/workflows/README.md

548 lines
29 KiB
Markdown

---
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
```bash
# 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