511 lines
25 KiB
Markdown
511 lines
25 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 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.
|