ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

Fix workflow documentation - remove non-existent workflows and Mermaid diagrams 

- Updated workflows-implementation.md: removed validate workflows, epic-tech-context, story-context
- Updated workflows-analysis.md: removed brainstorm-game, game-brief, added domain-research
- Updated workflows-planning.md: removed gdd, narrative, moved create-epics-and-stories to Phase 3
- Updated workflows-solutioning.md: already correct with create-epics-and-stories in Phase 3
- Removed all Mermaid diagrams and replaced with text descriptions
- Updated quick reference tables to reflect actual workflows
- Fixed flow examples to match current implementation
This commit is contained in:
Brian Madison 2025-11-26 20:42:20 -06:00
parent 355ccebca2
commit 04b328bd2a
5 changed files with 159 additions and 561 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
src/modules/bmm/docs/scale-adaptive-system.md
View File

@ -32,11 +32,11 @@ BMad Method adapts to three distinct planning tracks:
### Three Tracks at a Glance ### Three Tracks at a Glance
| Track | Planning Depth | Time Investment | Best For | | Track | Planning Depth | Best For |
| --------------------- | --------------------- | --------------- | ------------------------------------------ | | --------------------- | --------------------- | ------------------------------------------ |
| **Quick Flow** | Tech-spec only | Hours to 1 day | Simple features, bug fixes, clear scope | | **Quick Flow** | Tech-spec only | Simple features, bug fixes, clear scope |
| **BMad Method** | PRD + Arch + UX | 1-3 days | Products, platforms, complex features | | **BMad Method** | PRD + Arch + UX | Products, platforms, complex features |
| **Enterprise Method** | Method + Test/Sec/Ops | 3-7 days | Enterprise needs, compliance, multi-tenant | | **Enterprise Method** | Method + Test/Sec/Ops | Enterprise needs, compliance, multi-tenant |
### Decision Tree ### Decision Tree

187
src/modules/bmm/docs/workflows-analysis.md
View File

@ -1,7 +1,5 @@
# BMM Analysis Workflows (Phase 1) # BMM Analysis Workflows (Phase 1)
**Reading Time:** ~7 minutes
## Overview ## Overview
Phase 1 (Analysis) workflows are **optional** exploration and discovery tools that help validate ideas, understand markets, and generate strategic context before planning begins. Phase 1 (Analysis) workflows are **optional** exploration and discovery tools that help validate ideas, understand markets, and generate strategic context before planning begins.
@ -14,61 +12,36 @@ Phase 1 (Analysis) workflows are **optional** exploration and discovery tools th
--- ---
## Phase 1 Analysis Workflow Map ## Phase 1 Analysis Workflow Overview
```mermaid Phase 1 Analysis consists of three categories of optional workflows:
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
graph TB
subgraph Discovery["<b>DISCOVERY & IDEATION (Optional)</b>"]
direction LR
BrainstormProject["<b>Analyst: brainstorm-project</b><br/>Multi-track solution exploration"]
BrainstormGame["<b>Analyst: brainstorm-game</b><br/>Game concept generation"]
end
subgraph Research["<b>RESEARCH & VALIDATION (Optional)</b>"] ### Discovery & Ideation (Optional)
direction TB
ResearchWF["<b>Analyst: research</b><br/>• market (TAM/SAM/SOM)<br/>• technical (framework evaluation)<br/>• competitive (landscape)<br/>• user (personas, JTBD)<br/>• domain (industry analysis)<br/>• deep_prompt (AI research)"]
end
subgraph Strategy["<b>STRATEGIC CAPTURE (Recommended for Greenfield)</b>"] - **brainstorm-project** - Multi-track solution exploration for software projects
direction LR - **brainstorm-game** - Game concept generation (coming soon)
ProductBrief["<b>Analyst: product-brief</b><br/>Product vision + strategy<br/>(Interactive or YOLO mode)"]
GameBrief["<b>Game Designer: game-brief</b><br/>Game vision capture<br/>(Interactive or YOLO mode)"]
end
Discovery -.->|Software| ProductBrief ### Research & Validation (Optional)
Discovery -.->|Games| GameBrief
Discovery -.->|Validate ideas| Research
Research -.->|Inform brief| ProductBrief
Research -.->|Inform brief| GameBrief
ProductBrief --> Phase2["<b>Phase 2: prd workflow</b>"]
GameBrief --> Phase2Game["<b>Phase 2: gdd workflow</b>"]
Research -.->|Can feed directly| Phase2
style Discovery fill:#e1f5fe,stroke:#01579b,stroke-width:3px,color:#000 - **research** - Market, technical, competitive, user, domain, and AI research
style Research fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000 - **domain-research** - Industry-specific deep dive research
style Strategy fill:#f3e5f5,stroke:#4a148c,stroke-width:3px,color:#000
style Phase2 fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
style Phase2Game fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
style BrainstormProject fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000 ### Strategic Capture (Recommended for Greenfield)
style BrainstormGame fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000
style ResearchWF fill:#fff59d,stroke:#f57f17,stroke-width:2px,color:#000 - **product-brief** - Product vision and strategy definition
style ProductBrief fill:#ce93d8,stroke:#6a1b9a,stroke-width:2px,color:#000
style GameBrief fill:#ce93d8,stroke:#6a1b9a,stroke-width:2px,color:#000 These workflows feed into Phase 2 (Planning) workflows, particularly the `prd` workflow.
```
--- ---
## Quick Reference ## Quick Reference
| Workflow | Agent | Required | Purpose | Output | | Workflow | Agent | Required | Purpose | Output |
| ---------------------- | ------------- | ----------- | -------------------------------------------------------------- | ---------------------------- | | ---------------------- | ------- | ----------- | -------------------------------------------------------------- | ---------------------------- |
| **brainstorm-project** | Analyst | No | Explore solution approaches and architectures | Solution options + rationale | | **brainstorm-project** | Analyst | No | Explore solution approaches and architectures | Solution options + rationale |
| **brainstorm-game** | Analyst | No | Generate game concepts using creative techniques | Game concepts + evaluation |
| **research** | Analyst | No | Multi-type research (market/technical/competitive/user/domain) | Research reports | | **research** | Analyst | No | Multi-type research (market/technical/competitive/user/domain) | Research reports |
| **domain-research** | Analyst | No | Industry-specific deep dive research | Domain analysis report |
| **product-brief** | Analyst | Recommended | Define product vision and strategy (interactive) | Product Brief document | | **product-brief** | Analyst | Recommended | Define product vision and strategy (interactive) | Product Brief document |
| **game-brief** | Game Designer | Recommended | Capture game vision before GDD (interactive) | Game Brief document |
--- ---
@ -98,37 +71,6 @@ graph TB
--- ---
### brainstorm-game
**Purpose:** Generate game concepts through systematic creative exploration using five brainstorming techniques.
**Agent:** Analyst
**When to Use:**
- Generating original game concepts
- Exploring variations on themes
- Breaking creative blocks
- Validating game ideas against constraints
**Techniques Used:**
- SCAMPER (systematic modification)
- Mind Mapping (hierarchical exploration)
- Lotus Blossom (radial expansion)
- Six Thinking Hats (multi-perspective)
- Random Word Association (lateral thinking)
**Key Outputs:**
- Method-specific artifacts (5 separate documents)
- Consolidated concept document with feasibility
- Design pillar alignment matrix
**Example:** "Roguelike with psychological themes" → Emotions as characters, inner demons as enemies, therapy sessions as rest points, deck composition affects narrative.
---
### research ### research
**Purpose:** Comprehensive multi-type research system consolidating market, technical, competitive, user, and domain analysis. **Purpose:** Comprehensive multi-type research system consolidating market, technical, competitive, user, and domain analysis.
@ -157,6 +99,38 @@ graph TB
--- ---
### domain-research
**Purpose:** Industry-specific deep dive research to understand domain context, regulations, standards, and patterns relevant to complex projects.
**Agent:** Analyst
**When to Use:**
- Entering new industry verticals
- Highly regulated domains (healthcare, finance, education)
- Complex business domains with specialized terminology
- Need to understand industry standards and compliance requirements
**Key Features:**
- Industry analysis and trends
- Regulatory landscape
- Standards and compliance requirements
- Domain-specific patterns and best practices
- Key players and ecosystem analysis
**Key Outputs:**
- Domain analysis report
- Compliance checklist
- Standards reference guide
- Risk assessment for domain-specific challenges
**Example:** "Healthcare application" → HIPAA compliance requirements, FDA regulations, HL7/FHIR standards, healthcare ecosystem players, domain-specific data patterns.
---
### product-brief ### product-brief
**Purpose:** Interactive product brief creation that guides strategic product vision definition. **Purpose:** Interactive product brief creation that guides strategic product vision definition.
@ -190,42 +164,6 @@ graph TB
--- ---
### game-brief
**Purpose:** Lightweight interactive brainstorming session capturing game vision before Game Design Document.
**Agent:** Game Designer
**When to Use:**
- Starting new game project
- Exploring game ideas before committing
- Pitching concepts to team/stakeholders
- Validating market fit and feasibility
**Game Brief vs GDD:**
| Aspect | Game Brief | GDD |
| ------------ | ------------------ | ------------------------- |
| Purpose | Validate concept | Design for implementation |
| Detail Level | High-level vision | Detailed specs |
| Format | Conversational | Structured |
| Output | Concise vision doc | Comprehensive design |
**Key Outputs:**
- Game vision (concept, pitch)
- Target market and positioning
- Core gameplay pillars
- Scope and constraints
- Reference framework
- Risk assessment
- Success criteria
**Integration:** Feeds into GDD workflow (Phase 2).
---
## Decision Guide ## Decision Guide
### Starting a Software Project ### Starting a Software Project
@ -234,16 +172,10 @@ graph TB
brainstorm-project (if unclear) → research (market/technical) → product-brief → Phase 2 (prd) brainstorm-project (if unclear) → research (market/technical) → product-brief → Phase 2 (prd)
``` ```
### Starting a Game Project
```
brainstorm-game (if generating concepts) → research (market/competitive) → game-brief → Phase 2 (gdd)
```
### Validating an Idea ### Validating an Idea
``` ```
research (market type) → product-brief or game-brief → Phase 2 research (market type) → product-brief → Phase 2
``` ```
### Technical Decision Only ### Technical Decision Only
@ -258,6 +190,12 @@ research (technical type) → Use findings in Phase 3 (architecture)
research (market/competitive type) → product-brief → Phase 2 research (market/competitive type) → product-brief → Phase 2
``` ```
### Domain Research for Complex Industries
```
domain-research → research (compliance/regulatory) → product-brief → Phase 2
```
--- ---
## Integration with Phase 2 (Planning) ## Integration with Phase 2 (Planning)
@ -267,8 +205,8 @@ Analysis outputs feed directly into Planning:
| Analysis Output | Planning Input | | Analysis Output | Planning Input |
| --------------------------- | -------------------------- | | --------------------------- | -------------------------- |
| product-brief.md | **prd** workflow | | product-brief.md | **prd** workflow |
| game-brief.md | **gdd** workflow |
| market-research.md | **prd** context | | market-research.md | **prd** context |
| domain-research.md | **prd** context |
| technical-research.md | **architecture** (Phase 3) | | technical-research.md | **architecture** (Phase 3) |
| competitive-intelligence.md | **prd** positioning | | competitive-intelligence.md | **prd** positioning |
@ -306,20 +244,11 @@ Use analysis workflows to align stakeholders before committing to detailed plann
``` ```
1. brainstorm-project - explore approaches 1. brainstorm-project - explore approaches
2. research (market) - validate viability 2. research (market/technical/domain) - validate viability
3. product-brief - capture strategic vision 3. product-brief - capture strategic vision
4. → Phase 2: prd 4. → Phase 2: prd
``` ```
### Greenfield Game (Full Analysis)
```
1. brainstorm-game - generate concepts
2. research (competitive) - understand landscape
3. game-brief - capture vision
4. → Phase 2: gdd
```
### Skip Analysis (Clear Requirements) ### Skip Analysis (Clear Requirements)
``` ```
@ -351,10 +280,10 @@ Use analysis workflows to align stakeholders before committing to detailed plann
A: No! Analysis is entirely optional. Use only workflows that help you think through your problem. A: No! Analysis is entirely optional. Use only workflows that help you think through your problem.
**Q: Which workflow should I start with?** **Q: Which workflow should I start with?**
A: If unsure, start with `research` (market type) to validate viability, then move to `product-brief` or `game-brief`. A: If unsure, start with `research` (market type) to validate viability, then move to `product-brief`.
**Q: Can I skip straight to Planning?** **Q: Can I skip straight to Planning?**
A: Yes! If you know what you're building and why, skip Phase 1 entirely and start with Phase 2 (prd/gdd/tech-spec). A: Yes! If you know what you're building and why, skip Phase 1 entirely and start with Phase 2 (prd/tech-spec).
**Q: How long should Analysis take?** **Q: How long should Analysis take?**
A: Typically hours to 1-2 days. If taking longer, you may be over-analyzing. Move to Planning. A: Typically hours to 1-2 days. If taking longer, you may be over-analyzing. Move to Planning.

179
src/modules/bmm/docs/workflows-implementation.md
View File

@ -1,7 +1,5 @@
# BMM Implementation Workflows (Phase 4) # BMM Implementation Workflows (Phase 4)
**Reading Time:** ~8 minutes
## Overview ## Overview
Phase 4 (Implementation) workflows manage the iterative sprint-based development cycle using a **story-centric workflow** where each story moves through a defined lifecycle from creation to completion. Phase 4 (Implementation) workflows manage the iterative sprint-based development cycle using a **story-centric workflow** where each story moves through a defined lifecycle from creation to completion.
@ -14,117 +12,29 @@ Phase 4 (Implementation) workflows manage the iterative sprint-based development
Phase 4 is the final phase of the BMad Method workflow. To see how implementation fits into the complete methodology: Phase 4 is the final phase of the BMad Method workflow. To see how implementation fits into the complete methodology:
![BMad Method Workflow - Standard Greenfield](./images/workflow-method-greenfield.svg) The BMad Method consists of four phases working in sequence:
_Complete workflow showing Phases 1-4. Phase 4 (Implementation) is the rightmost column, showing the iterative epic and story cycles detailed below._ 1. **Phase 1 (Analysis)** - Optional exploration and discovery workflows
2. **Phase 2 (Planning)** - Required requirements definition using scale-adaptive system
3. **Phase 3 (Solutioning)** - Technical architecture and design decisions
4. **Phase 4 (Implementation)** - Iterative sprint-based development with story-centric workflow
--- Phase 4 focuses on the iterative epic and story cycles where stories are implemented, reviewed, and completed one at a time.
## Phase 4 Workflow Lifecycle For a visual representation of the complete workflow, see: [workflow-method-greenfield.excalidraw](./images/workflow-method-greenfield.excalidraw)
```mermaid
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
graph TB
subgraph Setup["<b>SPRINT SETUP - Run Once</b>"]
direction TB
SprintPlanning["<b>SM: sprint-planning</b><br/>Initialize sprint status file"]
end
subgraph EpicCycle["<b>EPIC CYCLE - Repeat Per Epic</b>"]
direction TB
EpicContext["<b>SM: epic-tech-context</b><br/>Generate epic technical guidance"]
ValidateEpic["<b>SM: validate-epic-tech-context</b><br/>(Optional validation)"]
EpicContext -.->|Optional| ValidateEpic
ValidateEpic -.-> StoryLoopStart
EpicContext --> StoryLoopStart[Start Story Loop]
end
subgraph StoryLoop["<b>STORY LIFECYCLE - Repeat Per Story</b>"]
direction TB
CreateStory["<b>SM: create-story</b><br/>Create next story from queue"]
ValidateStory["<b>SM: validate-create-story</b><br/>(Optional validation)"]
StoryContext["<b>SM: story-context</b><br/>Assemble dynamic context"]
StoryReady["<b>SM: story-ready-for-dev</b><br/>Mark ready without context"]
ValidateContext["<b>SM: validate-story-context</b><br/>(Optional validation)"]
DevStory["<b>DEV: develop-story</b><br/>Implement with tests"]
CodeReview["<b>DEV: code-review</b><br/>Senior dev review"]
StoryDone["<b>DEV: story-done</b><br/>Mark complete, advance queue"]
CreateStory -.->|Optional| ValidateStory
ValidateStory -.-> StoryContext
CreateStory --> StoryContext
CreateStory -.->|Alternative| StoryReady
StoryContext -.->|Optional| ValidateContext
ValidateContext -.-> DevStory
StoryContext --> DevStory
StoryReady -.-> DevStory
DevStory --> CodeReview
CodeReview -.->|Needs fixes| DevStory
CodeReview --> StoryDone
StoryDone -.->|Next story| CreateStory
end
subgraph EpicClose["<b>EPIC COMPLETION</b>"]
direction TB
Retrospective["<b>SM: epic-retrospective</b><br/>Post-epic lessons learned"]
end
subgraph Support["<b>SUPPORTING WORKFLOWS</b>"]
direction TB
CorrectCourse["<b>SM: correct-course</b><br/>Handle mid-sprint changes"]
WorkflowStatus["<b>Any Agent: workflow-status</b><br/>Check what's next"]
end
Setup --> EpicCycle
EpicCycle --> StoryLoop
StoryLoop --> EpicClose
EpicClose -.->|Next epic| EpicCycle
StoryLoop -.->|If issues arise| CorrectCourse
StoryLoop -.->|Anytime| WorkflowStatus
EpicCycle -.->|Anytime| WorkflowStatus
style Setup fill:#e3f2fd,stroke:#1565c0,stroke-width:3px,color:#000
style EpicCycle fill:#c5e1a5,stroke:#33691e,stroke-width:3px,color:#000
style StoryLoop fill:#f3e5f5,stroke:#6a1b9a,stroke-width:3px,color:#000
style EpicClose fill:#ffcc80,stroke:#e65100,stroke-width:3px,color:#000
style Support fill:#fff3e0,stroke:#e65100,stroke-width:3px,color:#000
style SprintPlanning fill:#90caf9,stroke:#0d47a1,stroke-width:2px,color:#000
style EpicContext fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000
style ValidateEpic fill:#c5e1a5,stroke:#33691e,stroke-width:1px,color:#000
style CreateStory fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style ValidateStory fill:#e1bee7,stroke:#6a1b9a,stroke-width:1px,color:#000
style StoryContext fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style StoryReady fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style ValidateContext fill:#e1bee7,stroke:#6a1b9a,stroke-width:1px,color:#000
style DevStory fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px,color:#000
style CodeReview fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px,color:#000
style StoryDone fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px,color:#000
style Retrospective fill:#ffb74d,stroke:#e65100,stroke-width:2px,color:#000
```
--- ---
## Quick Reference ## Quick Reference
| Workflow | Agent | When | Purpose | | Workflow | Agent | When | Purpose |
| ------------------------------ | ----- | -------------------------------- | ------------------------------------------- | | ------------------- | ----- | --------------------- | ------------------------------------- |
| **sprint-planning** | SM | Once at Phase 4 start | Initialize sprint tracking file | | **sprint-planning** | SM | Once at Phase 4 start | Initialize sprint tracking file |
| **epic-tech-context** | SM | Per epic | Generate epic-specific technical guidance |
| **validate-epic-tech-context** | SM | Optional after epic-tech-context | Validate tech spec against checklist |
| **create-story** | SM | Per story | Create next story from epic backlog | | **create-story** | SM | Per story | Create next story from epic backlog |
| **validate-create-story** | SM | Optional after create-story | Independent validation of story draft | | **dev-story** | DEV | Per story | Implement story with tests |
| **story-context** | SM | Optional per story | Assemble dynamic story context XML |
| **validate-story-context** | SM | Optional after story-context | Validate story context against checklist |
| **story-ready-for-dev** | SM | Optional per story | Mark story ready without generating context |
| **develop-story** | DEV | Per story | Implement story with tests |
| **code-review** | DEV | Per story | Senior dev quality review | | **code-review** | DEV | Per story | Senior dev quality review |
| **story-done** | DEV | Per story | Mark complete and advance queue | | **retrospective** | SM | After epic complete | Review lessons and extract insights |
| **epic-retrospective** | SM | After epic complete | Review lessons and extract insights |
| **correct-course** | SM | When issues arise | Handle significant mid-sprint changes | | **correct-course** | SM | When issues arise | Handle significant mid-sprint changes |
| **workflow-status** | Any | Anytime | Check "what should I do now?" |
--- ---
@ -132,27 +42,26 @@ graph TB
### SM (Scrum Master) - Primary Implementation Orchestrator ### SM (Scrum Master) - Primary Implementation Orchestrator
**Workflows:** sprint-planning, epic-tech-context, validate-epic-tech-context, create-story, validate-create-story, story-context, validate-story-context, story-ready-for-dev, epic-retrospective, correct-course **Workflows:** sprint-planning, create-story, retrospective, correct-course
**Responsibilities:** **Responsibilities:**
- Initialize and maintain sprint tracking - Initialize and maintain sprint tracking
- Generate technical context (epic and story level) - Create stories from epic backlog
- Orchestrate story lifecycle with optional validations - Handle course corrections when issues arise
- Mark stories ready for development - Facilitate retrospectives after epic completion
- Handle course corrections - Orchestrate overall implementation flow
- Facilitate retrospectives
### DEV (Developer) - Implementation and Quality ### DEV (Developer) - Implementation and Quality
**Workflows:** develop-story, code-review, story-done **Workflows:** dev-story, code-review
**Responsibilities:** **Responsibilities:**
- Implement stories with tests - Implement stories with tests
- Perform senior developer code reviews - Perform senior developer code reviews
- Mark stories complete and advance queue
- Ensure quality and adherence to standards - Ensure quality and adherence to standards
- Complete story implementation lifecycle
--- ---
@ -183,24 +92,19 @@ Stories move through these states in the sprint status file:
**Per Epic:** **Per Epic:**
1. SM runs `epic-tech-context` - Epic context and stories are already prepared from Phase 3
2. SM optionally runs `validate-epic-tech-context`
**Per Story (repeat until epic complete):** **Per Story (repeat until epic complete):**
1. SM runs `create-story` 1. SM runs `create-story`
2. SM optionally runs `validate-create-story` 2. DEV runs `dev-story`
3. SM runs `story-context` OR `story-ready-for-dev` (choose one) 3. DEV runs `code-review`
4. SM optionally runs `validate-story-context` (if story-context was used) 4. If code review fails: DEV fixes issues in `dev-story`, then re-runs `code-review`
5. DEV runs `develop-story`
6. DEV runs `code-review`
7. If code review passes: DEV runs `story-done`
8. If code review finds issues: DEV fixes in `develop-story`, then back to code-review
**After Epic Complete:** **After Epic Complete:**
- SM runs `epic-retrospective` - SM runs `retrospective`
- Move to next epic (start with `epic-tech-context` again) - Move to next epic
**As Needed:** **As Needed:**
@ -215,14 +119,6 @@ Stories move through these states in the sprint status file:
Complete each story's full lifecycle before starting the next. This prevents context switching and ensures quality. Complete each story's full lifecycle before starting the next. This prevents context switching and ensures quality.
### Epic-Level Technical Context
Generate detailed technical guidance per epic (not per story) using `epic-tech-context`. This provides just-in-time architecture without upfront over-planning.
### Story Context (Optional)
Use `story-context` to assemble focused context XML for each story, pulling from PRD, architecture, epic context, and codebase docs. Alternatively, use `story-ready-for-dev` to mark a story ready without generating context XML.
### Quality Gates ### Quality Gates
Every story goes through `code-review` before being marked done. No exceptions. Every story goes through `code-review` before being marked done. No exceptions.
@ -233,17 +129,7 @@ The `sprint-status.yaml` file is the single source of truth for all implementati
--- ---
## Common Patterns ### (BMad Method / Enterprise)
### Level 0-1 (Quick Flow)
```
tech-spec (PM)
→ sprint-planning (SM)
→ story loop (SM/DEV)
```
### Level 2-4 (BMad Method / Enterprise)
``` ```
PRD (PM) → Architecture (Architect) PRD (PM) → Architecture (Architect)
@ -251,9 +137,8 @@ PRD (PM) → Architecture (Architect)
→ implementation-readiness (Architect) → implementation-readiness (Architect)
→ sprint-planning (SM, once) → sprint-planning (SM, once)
→ [Per Epic]: → [Per Epic]:
epic-tech-context (SM)
→ story loop (SM/DEV) → story loop (SM/DEV)
→ epic-retrospective (SM) → retrospective (SM)
→ [Next Epic] → [Next Epic]
``` ```
@ -261,10 +146,9 @@ PRD (PM) → Architecture (Architect)
## Related Documentation ## Related Documentation
- [Phase 1: Analysis Workflows](./workflows-analysis.md)
- [Phase 2: Planning Workflows](./workflows-planning.md) - [Phase 2: Planning Workflows](./workflows-planning.md)
- [Phase 3: Solutioning Workflows](./workflows-solutioning.md) - [Phase 3: Solutioning Workflows](./workflows-solutioning.md)
- [Quick Spec Flow](./quick-spec-flow.md) - Level 0-1 fast track
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding project levels
--- ---
@ -276,20 +160,11 @@ A: Run `workflow-status` - it reads the sprint status file and tells you exactly
**Q: Story needs significant changes mid-implementation?** **Q: Story needs significant changes mid-implementation?**
A: Run `correct-course` to analyze impact and route appropriately. A: Run `correct-course` to analyze impact and route appropriately.
**Q: Do I run epic-tech-context for every story?**
A: No! Run once per epic, not per story. Use `story-context` or `story-ready-for-dev` per story instead.
**Q: Do I have to use story-context for every story?**
A: No, it's optional. You can use `story-ready-for-dev` to mark a story ready without generating context XML.
**Q: Can I work on multiple stories in parallel?** **Q: Can I work on multiple stories in parallel?**
A: Not recommended. Complete one story's full lifecycle before starting the next. Prevents context switching and ensures quality. A: Not recommended. Complete one story's full lifecycle before starting the next. Prevents context switching and ensures quality.
**Q: What if code review finds issues?** **Q: What if code review finds issues?**
A: DEV runs `develop-story` to make fixes, re-runs tests, then runs `code-review` again until it passes. A: DEV runs `dev-story` to make fixes, re-runs tests, then runs `code-review` again until it passes.
**Q: When do I run validations?**
A: Validations are optional quality gates. Use them when you want independent review of epic tech specs, story drafts, or story context before proceeding.
--- ---

229
src/modules/bmm/docs/workflows-planning.md
View File

@ -1,7 +1,5 @@
# BMM Planning Workflows (Phase 2) # BMM Planning Workflows (Phase 2)
**Reading Time:** ~10 minutes
## Overview ## Overview
Phase 2 (Planning) workflows are **required** for all projects. They transform strategic vision into actionable requirements using a **scale-adaptive system** that automatically selects the right planning depth based on project complexity. Phase 2 (Planning) workflows are **required** for all projects. They transform strategic vision into actionable requirements using a **scale-adaptive system** that automatically selects the right planning depth based on project complexity.
@ -12,100 +10,45 @@ Phase 2 (Planning) workflows are **required** for all projects. They transform s
--- ---
## Phase 2 Planning Workflow Map ## Phase 2 Planning Workflow Overview
```mermaid Phase 2 Planning uses a scale-adaptive system with three tracks:
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
graph TB
Start["<b>START: workflow-init</b><br/>Discovery + routing"]
subgraph QuickFlow["<b>QUICK FLOW (Simple Planning)</b>"] ### Quick Flow (Simple Planning)
direction TB
TechSpec["<b>PM: tech-spec</b><br/>Technical document<br/>→ Story or Epic+Stories<br/>1-15 stories typically"]
end
subgraph BMadMethod["<b>BMAD METHOD (Recommended)</b>"] - Entry: `workflow-init` routes based on project complexity
direction TB - Workflow: `tech-spec`
PRD["<b>PM: prd</b><br/>Strategic PRD with FRs/NFRs"] - Output: Technical document with story/epic structure
GDD["<b>Game Designer: gdd</b><br/>Game design doc"] - Story count: 1-15 (typical)
Narrative["<b>Game Designer: narrative</b><br/>Story-driven design"] - Next: Phase 4 (Implementation) - skips Phase 3
UXDesign["<b>UX Designer: create-ux-design</b><br/>Optional UX specification"] ### BMad Method (Recommended)
end
subgraph Solutioning["<b>PHASE 3: SOLUTIONING</b>"] - Entry: `workflow-init` routes based on project complexity
direction TB - Workflows: `prd` → (optional) `create-ux-design`
Architecture["<b>Architect: architecture</b><br/>System design + decisions"] - Output: PRD with FRs/NFRs
Epics["<b>PM: create-epics-and-stories</b><br/>Epic+Stories breakdown<br/>(10-50+ stories typically)"] - Story count: 10-50+ (typical)
end - Next: Phase 3 (Solutioning) → Phase 4
subgraph Enterprise["<b>ENTERPRISE METHOD</b>"] ### Enterprise Method
direction TB
EntNote["<b>Uses BMad Method Planning</b><br/>+<br/>Extended Phase 3 workflows<br/>(Architecture + Security + DevOps)<br/>30+ stories typically"]
end
subgraph Updates["<b>MID-STREAM UPDATES (Anytime)</b>"] - Planning: Same as BMad Method (`prd` workflow)
direction LR - Solutioning: Extended Phase 3 workflows (Architecture + Security + DevOps)
CorrectCourse["<b>PM/SM: correct-course</b><br/>Update requirements/stories"] - Story count: 30+ (typical)
end - Next: Phase 4
Start -->|Bug fix, simple| QuickFlow The `correct-course` workflow can be used anytime for significant requirement changes.
Start -->|Software product| PRD
Start -->|Game project| GDD
Start -->|Story-driven| Narrative
Start -->|Enterprise needs| Enterprise
PRD -.->|Optional| UXDesign
GDD -.->|Optional| UXDesign
Narrative -.->|Optional| UXDesign
PRD --> Architecture
GDD --> Architecture
Narrative --> Architecture
UXDesign --> Architecture
Architecture --> Epics
QuickFlow --> Phase4["<b>Phase 4: Implementation</b>"]
Epics --> ReadinessCheck["<b>Architect: implementation-readiness</b><br/>Gate check"]
Enterprise -.->|Uses BMad planning| Architecture
Enterprise --> Phase3Ext["<b>Phase 3: Extended</b><br/>(Arch + Sec + DevOps)"]
ReadinessCheck --> Phase4
Phase3Ext --> Phase4
Phase4 -.->|Significant changes| CorrectCourse
CorrectCourse -.->|Updates| Epics
style Start fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000
style QuickFlow fill:#c5e1a5,stroke:#33691e,stroke-width:3px,color:#000
style BMadMethod fill:#e1bee7,stroke:#6a1b9a,stroke-width:3px,color:#000
style Enterprise fill:#ffcdd2,stroke:#c62828,stroke-width:3px,color:#000
style Updates fill:#ffecb3,stroke:#ff6f00,stroke-width:3px,color:#000
style Phase3 fill:#90caf9,stroke:#0d47a1,stroke-width:2px,color:#000
style Phase4 fill:#ffcc80,stroke:#e65100,stroke-width:2px,color:#000
style TechSpec fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000
style PRD fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style GDD fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style Narrative fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style UXDesign fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style Epics fill:#ba68c8,stroke:#6a1b9a,stroke-width:3px,color:#000
style EntNote fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000
style Phase3Ext fill:#ef5350,stroke:#c62828,stroke-width:2px,color:#000
style CorrectCourse fill:#ffb74d,stroke:#ff6f00,stroke-width:2px,color:#000
```
--- ---
## Quick Reference ## Quick Reference
| Workflow | Agent | Track | Purpose | Typical Stories | | Workflow | Agent | Track | Purpose | Typical Stories |
| ---------------------------- | ------------- | ----------- | --------------------------------------------------------- | --------------- | | -------------------- | ----------- | ----------------------- | ----------------------------------------------- | --------------- |
| **workflow-init** | PM/Analyst | All | Entry point: discovery + routing | N/A | | **workflow-init** | PM/Analyst | All | Entry point: discovery + routing | N/A |
| **tech-spec** | PM | Quick Flow | Technical document → Story or Epic+Stories | 1-15 | | **tech-spec** | PM | Quick Flow | Technical document → Story or Epic+Stories | 1-15 |
| **prd** | PM | BMad Method | Strategic PRD with FRs/NFRs (no epic breakdown) | 10-50+ | | **prd** | PM | BMad Method, Enterprise | Strategic PRD with FRs/NFRs (no epic breakdown) | 10-50+ |
| **gdd** | Game Designer | BMad Method | Game Design Document with requirements | 10-50+ | | **create-ux-design** | UX Designer | BMad Method, Enterprise | Optional UX specification (after PRD) | N/A |
| **narrative** | Game Designer | BMad Method | Story-driven game/experience design | 10-50+ |
| **create-ux-design** | UX Designer | BMad Method | Optional UX specification (after PRD) | N/A |
| **create-epics-and-stories** | PM | BMad Method | Break requirements into Epic+Stories (AFTER architecture) | N/A |
| **correct-course** | PM/SM | All | Mid-stream requirement changes | N/A | | **correct-course** | PM/SM | All | Mid-stream requirement changes | N/A |
**Note:** Story counts are guidance. V6 improvement: Epic+Stories are created AFTER architecture for better quality. **Note:** Story counts are guidance. V6 improvement: Epic+Stories are created AFTER architecture for better quality.
@ -195,7 +138,7 @@ The system guides but never forces. You can override recommendations.
**Agent:** PM (orchestrates others as needed) **Agent:** PM (orchestrates others as needed)
**Always Use:** This is your planning starting point. Don't call prd/gdd/tech-spec directly unless skipping discovery. **Always Use:** This is your planning starting point. Don't call prd/tech-spec directly unless skipping discovery.
**Process:** **Process:**
@ -268,70 +211,7 @@ The system guides but never forces. You can override recommendations.
--- ---
### gdd (Game Design Document) ### create-ux-design (UX Design)
**Purpose:** Complete game design document for game projects (BMad Method track).
**Agent:** Game Designer
**When to Use:**
- Designing any game (any genre)
- Need comprehensive design documentation
- Team needs shared vision
- Publisher/stakeholder communication
**BMM GDD vs Traditional:**
- Scale-adaptive detail (not waterfall)
- Agile epic structure
- Direct handoff to implementation
- Integrated with testing workflows
**Key Outputs:**
- GDD.md (complete game design)
- Epic breakdown (Core Loop, Content, Progression, Polish)
**Integration:** Feeds into Architecture (Phase 3)
**Example:** Roguelike card game → Core concept (Slay the Spire meets Hades), 3 characters, 120 cards, 50 enemies, Epic breakdown with 26 stories.
---
### narrative (Narrative Design)
**Purpose:** Story-driven design workflow for games/experiences where narrative is central (BMad Method track).
**Agent:** Game Designer (Narrative Designer persona) + Creative Problem Solver (CIS)
**When to Use:**
- Story is central to experience
- Branching narrative with player choices
- Character-driven games
- Visual novels, adventure games, RPGs
**Combine with GDD:**
1. Run `narrative` first (story structure)
2. Then run `gdd` (integrate story with gameplay)
**Key Outputs:**
- narrative-design.md (complete narrative spec)
- Story structure (acts, beats, branching)
- Characters (profiles, arcs, relationships)
- Dialogue system design
- Implementation guide
**Integration:** Combine with GDD, then feeds into Architecture (Phase 3)
**Example:** Choice-driven RPG → 3 acts, 12 chapters, 5 choice points, 3 endings, 60K words, 40 narrative scenes.
---
### ux (UX-First Design)
**Purpose:** UX specification for projects where user experience is the primary differentiator (BMad Method track). **Purpose:** UX specification for projects where user experience is the primary differentiator (BMad Method track).
@ -367,31 +247,6 @@ The system guides but never forces. You can override recommendations.
--- ---
### create-epics-and-stories
**Purpose:** Break requirements into bite-sized stories organized in epics (BMad Method track).
**Agent:** PM
**When to Use:**
- **REQUIRED:** After Architecture workflow is complete (Phase 3)
- After PRD defines FRs/NFRs and Architecture defines HOW to build
- Optional: Can also run earlier (after PRD, after UX) for basic structure, then refined after Architecture
**Key Outputs:**
- epics.md (all epics with story breakdown)
- Epic files (epic-1-\*.md, etc.)
**V6 Improvement:** Epics+Stories are now created AFTER architecture for better quality:
- Architecture decisions inform story breakdown (tech choices affect implementation)
- Stories have full context (PRD + UX + Architecture)
- Better sequencing with technical dependencies considered
---
### correct-course ### correct-course
**Purpose:** Handle significant requirement changes during implementation (all tracks). **Purpose:** Handle significant requirement changes during implementation (all tracks).
@ -426,9 +281,7 @@ The system guides but never forces. You can override recommendations.
- **Bug fix or single change** → `tech-spec` (Quick Flow) - **Bug fix or single change** → `tech-spec` (Quick Flow)
- **Software product** → `prd` (BMad Method) - **Software product** → `prd` (BMad Method)
- **Game (gameplay-first)** → `gdd` (BMad Method) - **UX innovation project** → `create-ux-design` + `prd` (BMad Method)
- **Game (story-first)** → `narrative` + `gdd` (BMad Method)
- **UX innovation project** → `ux` + `prd` (BMad Method)
- **Enterprise with compliance** → Choose track in `workflow-init` → Enterprise Method - **Enterprise with compliance** → Choose track in `workflow-init` → Enterprise Method
--- ---
@ -438,11 +291,9 @@ The system guides but never forces. You can override recommendations.
Planning outputs feed into Solutioning: Planning outputs feed into Solutioning:
| Planning Output | Solutioning Input | Track Decision | | Planning Output | Solutioning Input | Track Decision |
| ------------------- | ------------------------------------ | ---------------------------- | | --------------- | ---------------------------------- | ---------------------------- |
| tech-spec.md | Skip Phase 3 → Phase 4 directly | Quick Flow (no architecture) | | tech-spec.md | Skip Phase 3 → Phase 4 directly | Quick Flow (no architecture) |
| PRD.md | **architecture** (Level 3-4) | BMad Method (recommended) | | PRD.md | **architecture** (Level 3-4) | BMad Method (recommended) |
| GDD.md | **architecture** (game tech) | BMad Method (recommended) |
| narrative-design.md | **architecture** (narrative systems) | BMad Method |
| ux-spec.md | **architecture** (frontend design) | BMad Method | | ux-spec.md | **architecture** (frontend design) | BMad Method |
| Enterprise docs | **architecture** + security/ops | Enterprise Method (required) | | Enterprise docs | **architecture** + security/ops | Enterprise Method (required) |
@ -468,11 +319,11 @@ If `workflow-init` suggests BMad Method, there's likely complexity you haven't c
### 3. Iterate on Requirements ### 3. Iterate on Requirements
Planning documents are living. Refine PRDs/GDDs as you learn during Solutioning and Implementation. Planning documents are living. Refine PRDs as you learn during Solutioning and Implementation.
### 4. Involve Stakeholders Early ### 4. Involve Stakeholders Early
Review PRDs/GDDs with stakeholders before Solutioning. Catch misalignment early. Review PRDs with stakeholders before Solutioning. Catch misalignment early.
### 5. Focus on "What" Not "How" ### 5. Focus on "What" Not "How"
@ -492,9 +343,8 @@ Always run `document-project` before planning brownfield projects. AI agents nee
1. (Optional) Analysis: product-brief, research 1. (Optional) Analysis: product-brief, research
2. workflow-init → routes to prd 2. workflow-init → routes to prd
3. PM: prd workflow 3. PM: prd workflow
4. (Optional) UX Designer: ux workflow 4. (Optional) UX Designer: create-ux-design workflow
5. PM: create-epics-and-stories (may be automatic) 5. → Phase 3: architecture
6. → Phase 3: architecture
``` ```
### Brownfield Software (BMad Method) ### Brownfield Software (BMad Method)
@ -503,28 +353,17 @@ Always run `document-project` before planning brownfield projects. AI agents nee
1. Technical Writer or Analyst: document-project 1. Technical Writer or Analyst: document-project
2. workflow-init → routes to prd 2. workflow-init → routes to prd
3. PM: prd workflow 3. PM: prd workflow
4. PM: create-epics-and-stories 4. → Phase 3: architecture (recommended for focused solution design)
5. → Phase 3: architecture (recommended for focused solution design)
``` ```
### Bug Fix (Quick Flow) ### Bug Fix (Quick Flow)
``` ```
1. workflow-init → routes to tech-spec 1. workflow-init → routes to tech-spec
2. Architect: tech-spec workflow 2. PM: tech-spec workflow
3. → Phase 4: Implementation (skip Phase 3) 3. → Phase 4: Implementation (skip Phase 3)
``` ```
### Game Project (BMad Method)
```
1. (Optional) Analysis: game-brief, research
2. workflow-init → routes to gdd
3. Game Designer: gdd workflow (or narrative + gdd if story-first)
4. Game Designer creates epic breakdown
5. → Phase 3: architecture (game systems)
```
### Enterprise Project (Enterprise Method) ### Enterprise Project (Enterprise Method)
``` ```
@ -602,7 +441,7 @@ A: Run `correct-course` workflow. It analyzes impact and updates planning artifa
A: Recommended! Architecture distills massive codebase into focused solution design for your specific project. A: Recommended! Architecture distills massive codebase into focused solution design for your specific project.
**Q: When do I run create-epics-and-stories?** **Q: When do I run create-epics-and-stories?**
A: Usually automatic during PRD/GDD. Can also run standalone later to regenerate epics. A: In Phase 3 (Solutioning), after architecture is complete.
**Q: Should I use product-brief before PRD?** **Q: Should I use product-brief before PRD?**
A: Optional but recommended for greenfield. Helps strategic thinking. `workflow-init` offers it based on context. A: Optional but recommended for greenfield. Helps strategic thinking. `workflow-init` offers it based on context.

79
src/modules/bmm/docs/workflows-solutioning.md
View File

@ -1,7 +1,5 @@
# BMM Solutioning Workflows (Phase 3) # BMM Solutioning Workflows (Phase 3)
**Reading Time:** ~8 minutes
## Overview ## Overview
Phase 3 (Solutioning) workflows translate **what** to build (from Planning) into **how** to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins. Phase 3 (Solutioning) workflows translate **what** to build (from Planning) into **how** to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
@ -14,73 +12,30 @@ Phase 3 (Solutioning) workflows translate **what** to build (from Planning) into
--- ---
## Phase 3 Solutioning Workflow Map ## Phase 3 Solutioning Workflow Overview
```mermaid Phase 3 Solutioning has different paths based on the planning track selected:
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
graph TB
FromPlanning["<b>FROM Phase 2 Planning</b><br/>PRD (FRs/NFRs) complete"]
subgraph QuickFlow["<b>QUICK FLOW PATH</b>"] ### Quick Flow Path
direction TB
SkipArch["<b>Skip Phase 3</b><br/>Go directly to Implementation"]
end
subgraph BMadEnterprise["<b>BMAD METHOD + ENTERPRISE (Same Start)</b>"] - From Planning: tech-spec complete
direction TB - Action: Skip Phase 3 entirely
OptionalUX["<b>UX Designer: create-ux-design</b><br/>(Optional)"] - Next: Phase 4 (Implementation)
Architecture["<b>Architect: architecture</b><br/>System design + ADRs"]
subgraph Optional["<b>ENTERPRISE ADDITIONS (Optional)</b>"] ### BMad Method & Enterprise Path
direction LR
SecArch["<b>Architect: security-architecture</b><br/>(Future)"]
DevOps["<b>Architect: devops-strategy</b><br/>(Future)"]
end
EpicsStories["<b>PM: create-epics-and-stories</b><br/>Break down FRs/NFRs into epics"] - From Planning: PRD with FRs/NFRs complete
GateCheck["<b>Architect: implementation-readiness</b><br/>Validation before Phase 4"] - Optional: create-ux-design (if UX is critical)
- Required: architecture - System design with ADRs
- Required: create-epics-and-stories - Break requirements into implementable stories
- Required: implementation-readiness - Gate check validation
- Enterprise additions: Optional security-architecture and devops-strategy (future workflows)
OptionalUX -.-> Architecture ### Gate Check Results
Architecture -.->|Enterprise only| Optional
Architecture --> EpicsStories
Optional -.-> EpicsStories
EpicsStories --> GateCheck
end
subgraph Result["<b>GATE CHECK RESULTS</b>"] - **PASS** - All criteria met, proceed to Phase 4
direction LR - **CONCERNS** - Minor gaps identified, proceed with caution
Pass["✅ PASS<br/>Proceed to Phase 4"] - **FAIL** - Critical issues, must resolve before Phase 4
Concerns["⚠️ CONCERNS<br/>Proceed with caution"]
Fail["❌ FAIL<br/>Resolve issues first"]
end
FromPlanning -->|Quick Flow| QuickFlow
FromPlanning -->|BMad Method<br/>or Enterprise| OptionalUX
QuickFlow --> Phase4["<b>Phase 4: Implementation</b>"]
GateCheck --> Result
Pass --> Phase4
Concerns --> Phase4
Fail -.->|Fix issues| Architecture
style FromPlanning fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px,color:#000
style QuickFlow fill:#c5e1a5,stroke:#33691e,stroke-width:3px,color:#000
style BMadEnterprise fill:#90caf9,stroke:#0d47a1,stroke-width:3px,color:#000
style Optional fill:#ffcdd2,stroke:#c62828,stroke-width:3px,color:#000
style Result fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000
style Phase4 fill:#ffcc80,stroke:#e65100,stroke-width:2px,color:#000
style SkipArch fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000
style OptionalUX fill:#64b5f6,stroke:#0d47a1,stroke-width:2px,color:#000
style Architecture fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000
style SecArch fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000
style DevOps fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000
style EpicsStories fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000
style GateCheck fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000
style Pass fill:#81c784,stroke:#388e3c,stroke-width:2px,color:#000
style Concerns fill:#ffb74d,stroke:#f57f17,stroke-width:2px,color:#000
style Fail fill:#e57373,stroke:#d32f2f,stroke-width:2px,color:#000
```
--- ---