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