diff --git a/src/modules/bmm/docs/scale-adaptive-system.md b/src/modules/bmm/docs/scale-adaptive-system.md index becbab75..946c6574 100644 --- a/src/modules/bmm/docs/scale-adaptive-system.md +++ b/src/modules/bmm/docs/scale-adaptive-system.md @@ -32,11 +32,11 @@ BMad Method adapts to three distinct planning tracks: ### Three Tracks at a Glance -| Track | Planning Depth | Time Investment | Best For | -| --------------------- | --------------------- | --------------- | ------------------------------------------ | -| **Quick Flow** | Tech-spec only | Hours to 1 day | Simple features, bug fixes, clear scope | -| **BMad Method** | PRD + Arch + UX | 1-3 days | Products, platforms, complex features | -| **Enterprise Method** | Method + Test/Sec/Ops | 3-7 days | Enterprise needs, compliance, multi-tenant | +| Track | Planning Depth | Best For | +| --------------------- | --------------------- | ------------------------------------------ | +| **Quick Flow** | Tech-spec only | Simple features, bug fixes, clear scope | +| **BMad Method** | PRD + Arch + UX | Products, platforms, complex features | +| **Enterprise Method** | Method + Test/Sec/Ops | Enterprise needs, compliance, multi-tenant | ### Decision Tree diff --git a/src/modules/bmm/docs/workflows-analysis.md b/src/modules/bmm/docs/workflows-analysis.md index cf475ce5..1e15f258 100644 --- a/src/modules/bmm/docs/workflows-analysis.md +++ b/src/modules/bmm/docs/workflows-analysis.md @@ -1,7 +1,5 @@ # BMM Analysis Workflows (Phase 1) -**Reading Time:** ~7 minutes - ## Overview 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 -%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%% -graph TB - subgraph Discovery["DISCOVERY & IDEATION (Optional)"] - direction LR - BrainstormProject["Analyst: brainstorm-project
Multi-track solution exploration"] - BrainstormGame["Analyst: brainstorm-game
Game concept generation"] - end +Phase 1 Analysis consists of three categories of optional workflows: - subgraph Research["RESEARCH & VALIDATION (Optional)"] - direction TB - ResearchWF["Analyst: research
• market (TAM/SAM/SOM)
• technical (framework evaluation)
• competitive (landscape)
• user (personas, JTBD)
• domain (industry analysis)
• deep_prompt (AI research)"] - end +### Discovery & Ideation (Optional) - subgraph Strategy["STRATEGIC CAPTURE (Recommended for Greenfield)"] - direction LR - ProductBrief["Analyst: product-brief
Product vision + strategy
(Interactive or YOLO mode)"] - GameBrief["Game Designer: game-brief
Game vision capture
(Interactive or YOLO mode)"] - end +- **brainstorm-project** - Multi-track solution exploration for software projects +- **brainstorm-game** - Game concept generation (coming soon) - Discovery -.->|Software| ProductBrief - Discovery -.->|Games| GameBrief - Discovery -.->|Validate ideas| Research - Research -.->|Inform brief| ProductBrief - Research -.->|Inform brief| GameBrief - ProductBrief --> Phase2["Phase 2: prd workflow"] - GameBrief --> Phase2Game["Phase 2: gdd workflow"] - Research -.->|Can feed directly| Phase2 +### Research & Validation (Optional) - style Discovery fill:#e1f5fe,stroke:#01579b,stroke-width:3px,color:#000 - style Research fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000 - 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 +- **research** - Market, technical, competitive, user, domain, and AI research +- **domain-research** - Industry-specific deep dive research - style BrainstormProject fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000 - style BrainstormGame fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000 - style ResearchWF fill:#fff59d,stroke:#f57f17,stroke-width:2px,color:#000 - style ProductBrief fill:#ce93d8,stroke:#6a1b9a,stroke-width:2px,color:#000 - style GameBrief fill:#ce93d8,stroke:#6a1b9a,stroke-width:2px,color:#000 -``` +### Strategic Capture (Recommended for Greenfield) + +- **product-brief** - Product vision and strategy definition + +These workflows feed into Phase 2 (Planning) workflows, particularly the `prd` workflow. --- ## Quick Reference -| Workflow | Agent | Required | Purpose | Output | -| ---------------------- | ------------- | ----------- | -------------------------------------------------------------- | ---------------------------- | -| **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 | -| **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 | +| Workflow | Agent | Required | Purpose | Output | +| ---------------------- | ------- | ----------- | -------------------------------------------------------------- | ---------------------------- | +| **brainstorm-project** | Analyst | No | Explore solution approaches and architectures | Solution options + rationale | +| **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 | --- @@ -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 **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 **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 ### Starting a Software Project @@ -234,16 +172,10 @@ graph TB 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 ``` -research (market type) → product-brief or game-brief → Phase 2 +research (market type) → product-brief → Phase 2 ``` ### Technical Decision Only @@ -258,6 +190,12 @@ research (technical type) → Use findings in Phase 3 (architecture) 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) @@ -267,8 +205,8 @@ Analysis outputs feed directly into Planning: | Analysis Output | Planning Input | | --------------------------- | -------------------------- | | product-brief.md | **prd** workflow | -| game-brief.md | **gdd** workflow | | market-research.md | **prd** context | +| domain-research.md | **prd** context | | technical-research.md | **architecture** (Phase 3) | | 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 -2. research (market) - validate viability +2. research (market/technical/domain) - validate viability 3. product-brief - capture strategic vision 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) ``` @@ -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. **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?** -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?** A: Typically hours to 1-2 days. If taking longer, you may be over-analyzing. Move to Planning. diff --git a/src/modules/bmm/docs/workflows-implementation.md b/src/modules/bmm/docs/workflows-implementation.md index aeff9cb1..7d756097 100644 --- a/src/modules/bmm/docs/workflows-implementation.md +++ b/src/modules/bmm/docs/workflows-implementation.md @@ -1,7 +1,5 @@ # BMM Implementation Workflows (Phase 4) -**Reading Time:** ~8 minutes - ## 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. @@ -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: -![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 - -```mermaid -%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%% -graph TB - subgraph Setup["SPRINT SETUP - Run Once"] - direction TB - SprintPlanning["SM: sprint-planning
Initialize sprint status file"] - end - - subgraph EpicCycle["EPIC CYCLE - Repeat Per Epic"] - direction TB - EpicContext["SM: epic-tech-context
Generate epic technical guidance"] - ValidateEpic["SM: validate-epic-tech-context
(Optional validation)"] - - EpicContext -.->|Optional| ValidateEpic - ValidateEpic -.-> StoryLoopStart - EpicContext --> StoryLoopStart[Start Story Loop] - end - - subgraph StoryLoop["STORY LIFECYCLE - Repeat Per Story"] - direction TB - - CreateStory["SM: create-story
Create next story from queue"] - ValidateStory["SM: validate-create-story
(Optional validation)"] - StoryContext["SM: story-context
Assemble dynamic context"] - StoryReady["SM: story-ready-for-dev
Mark ready without context"] - ValidateContext["SM: validate-story-context
(Optional validation)"] - DevStory["DEV: develop-story
Implement with tests"] - CodeReview["DEV: code-review
Senior dev review"] - StoryDone["DEV: story-done
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["EPIC COMPLETION"] - direction TB - Retrospective["SM: epic-retrospective
Post-epic lessons learned"] - end - - subgraph Support["SUPPORTING WORKFLOWS"] - direction TB - CorrectCourse["SM: correct-course
Handle mid-sprint changes"] - WorkflowStatus["Any Agent: workflow-status
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 -``` +For a visual representation of the complete workflow, see: [workflow-method-greenfield.excalidraw](./images/workflow-method-greenfield.excalidraw) --- ## Quick Reference -| Workflow | Agent | When | Purpose | -| ------------------------------ | ----- | -------------------------------- | ------------------------------------------- | -| **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 | -| **validate-create-story** | SM | Optional after create-story | Independent validation of story draft | -| **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 | -| **story-done** | DEV | Per story | Mark complete and advance queue | -| **epic-retrospective** | SM | After epic complete | Review lessons and extract insights | -| **correct-course** | SM | When issues arise | Handle significant mid-sprint changes | -| **workflow-status** | Any | Anytime | Check "what should I do now?" | +| Workflow | Agent | When | Purpose | +| ------------------- | ----- | --------------------- | ------------------------------------- | +| **sprint-planning** | SM | Once at Phase 4 start | Initialize sprint tracking file | +| **create-story** | SM | Per story | Create next story from epic backlog | +| **dev-story** | DEV | Per story | Implement story with tests | +| **code-review** | DEV | Per story | Senior dev quality review | +| **retrospective** | SM | After epic complete | Review lessons and extract insights | +| **correct-course** | SM | When issues arise | Handle significant mid-sprint changes | --- @@ -132,27 +42,26 @@ graph TB ### 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:** - Initialize and maintain sprint tracking -- Generate technical context (epic and story level) -- Orchestrate story lifecycle with optional validations -- Mark stories ready for development -- Handle course corrections -- Facilitate retrospectives +- Create stories from epic backlog +- Handle course corrections when issues arise +- Facilitate retrospectives after epic completion +- Orchestrate overall implementation flow ### DEV (Developer) - Implementation and Quality -**Workflows:** develop-story, code-review, story-done +**Workflows:** dev-story, code-review **Responsibilities:** - Implement stories with tests - Perform senior developer code reviews -- Mark stories complete and advance queue - 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:** -1. SM runs `epic-tech-context` -2. SM optionally runs `validate-epic-tech-context` +- Epic context and stories are already prepared from Phase 3 **Per Story (repeat until epic complete):** 1. SM runs `create-story` -2. SM optionally runs `validate-create-story` -3. SM runs `story-context` OR `story-ready-for-dev` (choose one) -4. SM optionally runs `validate-story-context` (if story-context was used) -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 +2. DEV runs `dev-story` +3. DEV runs `code-review` +4. If code review fails: DEV fixes issues in `dev-story`, then re-runs `code-review` **After Epic Complete:** -- SM runs `epic-retrospective` -- Move to next epic (start with `epic-tech-context` again) +- SM runs `retrospective` +- Move to next epic **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. -### 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 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 - -### Level 0-1 (Quick Flow) - -``` -tech-spec (PM) - → sprint-planning (SM) - → story loop (SM/DEV) -``` - -### Level 2-4 (BMad Method / Enterprise) +### (BMad Method / Enterprise) ``` PRD (PM) → Architecture (Architect) @@ -251,9 +137,8 @@ PRD (PM) → Architecture (Architect) → implementation-readiness (Architect) → sprint-planning (SM, once) → [Per Epic]: - epic-tech-context (SM) → story loop (SM/DEV) - → epic-retrospective (SM) + → retrospective (SM) → [Next Epic] ``` @@ -261,10 +146,9 @@ PRD (PM) → Architecture (Architect) ## Related Documentation +- [Phase 1: Analysis Workflows](./workflows-analysis.md) - [Phase 2: Planning Workflows](./workflows-planning.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?** 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?** 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?** -A: DEV runs `develop-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. +A: DEV runs `dev-story` to make fixes, re-runs tests, then runs `code-review` again until it passes. --- diff --git a/src/modules/bmm/docs/workflows-planning.md b/src/modules/bmm/docs/workflows-planning.md index 19d16402..3ce91599 100644 --- a/src/modules/bmm/docs/workflows-planning.md +++ b/src/modules/bmm/docs/workflows-planning.md @@ -1,7 +1,5 @@ # BMM Planning Workflows (Phase 2) -**Reading Time:** ~10 minutes - ## 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. @@ -12,101 +10,46 @@ Phase 2 (Planning) workflows are **required** for all projects. They transform s --- -## Phase 2 Planning Workflow Map +## Phase 2 Planning Workflow Overview -```mermaid -%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%% -graph TB - Start["START: workflow-init
Discovery + routing"] +Phase 2 Planning uses a scale-adaptive system with three tracks: - subgraph QuickFlow["QUICK FLOW (Simple Planning)"] - direction TB - TechSpec["PM: tech-spec
Technical document
→ Story or Epic+Stories
1-15 stories typically"] - end +### Quick Flow (Simple Planning) - subgraph BMadMethod["BMAD METHOD (Recommended)"] - direction TB - PRD["PM: prd
Strategic PRD with FRs/NFRs"] - GDD["Game Designer: gdd
Game design doc"] - Narrative["Game Designer: narrative
Story-driven design"] +- Entry: `workflow-init` routes based on project complexity +- Workflow: `tech-spec` +- Output: Technical document with story/epic structure +- Story count: 1-15 (typical) +- Next: Phase 4 (Implementation) - skips Phase 3 - UXDesign["UX Designer: create-ux-design
Optional UX specification"] - end +### BMad Method (Recommended) - subgraph Solutioning["PHASE 3: SOLUTIONING"] - direction TB - Architecture["Architect: architecture
System design + decisions"] - Epics["PM: create-epics-and-stories
Epic+Stories breakdown
(10-50+ stories typically)"] - end +- Entry: `workflow-init` routes based on project complexity +- Workflows: `prd` → (optional) `create-ux-design` +- Output: PRD with FRs/NFRs +- Story count: 10-50+ (typical) +- Next: Phase 3 (Solutioning) → Phase 4 - subgraph Enterprise["ENTERPRISE METHOD"] - direction TB - EntNote["Uses BMad Method Planning
+
Extended Phase 3 workflows
(Architecture + Security + DevOps)
30+ stories typically"] - end +### Enterprise Method - subgraph Updates["MID-STREAM UPDATES (Anytime)"] - direction LR - CorrectCourse["PM/SM: correct-course
Update requirements/stories"] - end +- Planning: Same as BMad Method (`prd` workflow) +- Solutioning: Extended Phase 3 workflows (Architecture + Security + DevOps) +- Story count: 30+ (typical) +- Next: Phase 4 - Start -->|Bug fix, simple| QuickFlow - 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["Phase 4: Implementation"] - Epics --> ReadinessCheck["Architect: implementation-readiness
Gate check"] - Enterprise -.->|Uses BMad planning| Architecture - Enterprise --> Phase3Ext["Phase 3: Extended
(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 -``` +The `correct-course` workflow can be used anytime for significant requirement changes. --- ## Quick Reference -| Workflow | Agent | Track | Purpose | Typical Stories | -| ---------------------------- | ------------- | ----------- | --------------------------------------------------------- | --------------- | -| **workflow-init** | PM/Analyst | All | Entry point: discovery + routing | N/A | -| **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+ | -| **gdd** | Game Designer | BMad Method | Game Design Document with requirements | 10-50+ | -| **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 | +| Workflow | Agent | Track | Purpose | Typical Stories | +| -------------------- | ----------- | ----------------------- | ----------------------------------------------- | --------------- | +| **workflow-init** | PM/Analyst | All | Entry point: discovery + routing | N/A | +| **tech-spec** | PM | Quick Flow | Technical document → Story or Epic+Stories | 1-15 | +| **prd** | PM | BMad Method, Enterprise | Strategic PRD with FRs/NFRs (no epic breakdown) | 10-50+ | +| **create-ux-design** | UX Designer | BMad Method, Enterprise | Optional UX specification (after PRD) | 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. @@ -195,7 +138,7 @@ The system guides but never forces. You can override recommendations. **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:** @@ -268,70 +211,7 @@ The system guides but never forces. You can override recommendations. --- -### gdd (Game Design Document) - -**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) +### create-ux-design (UX Design) **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 **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) - **Software product** → `prd` (BMad Method) -- **Game (gameplay-first)** → `gdd` (BMad Method) -- **Game (story-first)** → `narrative` + `gdd` (BMad Method) -- **UX innovation project** → `ux` + `prd` (BMad Method) +- **UX innovation project** → `create-ux-design` + `prd` (BMad Method) - **Enterprise with compliance** → Choose track in `workflow-init` → Enterprise Method --- @@ -437,14 +290,12 @@ The system guides but never forces. You can override recommendations. Planning outputs feed into Solutioning: -| Planning Output | Solutioning Input | Track Decision | -| ------------------- | ------------------------------------ | ---------------------------- | -| tech-spec.md | Skip Phase 3 → Phase 4 directly | Quick Flow (no architecture) | -| 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 | -| Enterprise docs | **architecture** + security/ops | Enterprise Method (required) | +| Planning Output | Solutioning Input | Track Decision | +| --------------- | ---------------------------------- | ---------------------------- | +| tech-spec.md | Skip Phase 3 → Phase 4 directly | Quick Flow (no architecture) | +| PRD.md | **architecture** (Level 3-4) | BMad Method (recommended) | +| ux-spec.md | **architecture** (frontend design) | BMad Method | +| Enterprise docs | **architecture** + security/ops | Enterprise Method (required) | **Key Decision Points:** @@ -468,11 +319,11 @@ If `workflow-init` suggests BMad Method, there's likely complexity you haven't c ### 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 -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" @@ -492,9 +343,8 @@ Always run `document-project` before planning brownfield projects. AI agents nee 1. (Optional) Analysis: product-brief, research 2. workflow-init → routes to prd 3. PM: prd workflow -4. (Optional) UX Designer: ux workflow -5. PM: create-epics-and-stories (may be automatic) -6. → Phase 3: architecture +4. (Optional) UX Designer: create-ux-design workflow +5. → Phase 3: architecture ``` ### 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 2. workflow-init → routes to prd 3. PM: prd workflow -4. PM: create-epics-and-stories -5. → Phase 3: architecture (recommended for focused solution design) +4. → Phase 3: architecture (recommended for focused solution design) ``` ### Bug Fix (Quick Flow) ``` 1. workflow-init → routes to tech-spec -2. Architect: tech-spec workflow +2. PM: tech-spec workflow 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) ``` @@ -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. **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?** A: Optional but recommended for greenfield. Helps strategic thinking. `workflow-init` offers it based on context. diff --git a/src/modules/bmm/docs/workflows-solutioning.md b/src/modules/bmm/docs/workflows-solutioning.md index 4a6d4c2d..fbbfd1ae 100644 --- a/src/modules/bmm/docs/workflows-solutioning.md +++ b/src/modules/bmm/docs/workflows-solutioning.md @@ -1,7 +1,5 @@ # BMM Solutioning Workflows (Phase 3) -**Reading Time:** ~8 minutes - ## 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. @@ -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 -%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%% -graph TB - FromPlanning["FROM Phase 2 Planning
PRD (FRs/NFRs) complete"] +Phase 3 Solutioning has different paths based on the planning track selected: - subgraph QuickFlow["QUICK FLOW PATH"] - direction TB - SkipArch["Skip Phase 3
Go directly to Implementation"] - end +### Quick Flow Path - subgraph BMadEnterprise["BMAD METHOD + ENTERPRISE (Same Start)"] - direction TB - OptionalUX["UX Designer: create-ux-design
(Optional)"] - Architecture["Architect: architecture
System design + ADRs"] +- From Planning: tech-spec complete +- Action: Skip Phase 3 entirely +- Next: Phase 4 (Implementation) - subgraph Optional["ENTERPRISE ADDITIONS (Optional)"] - direction LR - SecArch["Architect: security-architecture
(Future)"] - DevOps["Architect: devops-strategy
(Future)"] - end +### BMad Method & Enterprise Path - EpicsStories["PM: create-epics-and-stories
Break down FRs/NFRs into epics"] - GateCheck["Architect: implementation-readiness
Validation before Phase 4"] +- From Planning: PRD with FRs/NFRs complete +- 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 - Architecture -.->|Enterprise only| Optional - Architecture --> EpicsStories - Optional -.-> EpicsStories - EpicsStories --> GateCheck - end +### Gate Check Results - subgraph Result["GATE CHECK RESULTS"] - direction LR - Pass["✅ PASS
Proceed to Phase 4"] - Concerns["⚠️ CONCERNS
Proceed with caution"] - Fail["❌ FAIL
Resolve issues first"] - end - - FromPlanning -->|Quick Flow| QuickFlow - FromPlanning -->|BMad Method
or Enterprise| OptionalUX - - QuickFlow --> Phase4["Phase 4: Implementation"] - 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 -``` +- **PASS** - All criteria met, proceed to Phase 4 +- **CONCERNS** - Minor gaps identified, proceed with caution +- **FAIL** - Critical issues, must resolve before Phase 4 ---