diff --git a/src/modules/bmm/docs/README.md b/src/modules/bmm/docs/README.md index a4c99264..c29aa4ee 100644 --- a/src/modules/bmm/docs/README.md +++ b/src/modules/bmm/docs/README.md @@ -52,7 +52,7 @@ Complete guide to BMM's AI agent team: - Example party compositions - Multi-module integration (BMM + CIS + BMB + custom) - Agent customization in party mode - - Best practices and troubleshooting + - Best practices --- @@ -65,7 +65,7 @@ Comprehensive guide for brownfield development: - Track selection for brownfield - Integration with existing patterns - Phase-by-phase workflow guidance - - Common scenarios and troubleshooting + - Common scenarios --- @@ -75,7 +75,6 @@ Essential reference materials: - **[Glossary](./glossary.md)** - Key terminology and concepts - **[FAQ](./faq.md)** - Frequently asked questions across all topics -- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions - **[Enterprise Agentic Development](./enterprise-agentic-development.md)** - Team collaboration strategies --- @@ -99,7 +98,7 @@ Essential reference materials: → See [Scale Adaptive System](./scale-adaptive-system.md) **Find specific commands or answers** -→ Check [FAQ](./faq.md) or [Troubleshooting](./troubleshooting.md) +→ Check [FAQ](./faq.md) --- @@ -213,12 +212,12 @@ flowchart TD SAS --> IMPL BF --> IMPL - IMPL --> REF[Quick References
Glossary, FAQ, Troubleshooting] + IMPL --> REF[Quick References
Glossary, FAQ] - style START fill:#bfb,stroke:#333,stroke-width:2px - style QS fill:#bbf,stroke:#333,stroke-width:2px - style DECIDE fill:#ffb,stroke:#333,stroke-width:2px - style IMPL fill:#f9f,stroke:#333,stroke-width:2px + style START fill:#bfb,stroke:#333,stroke-width:2px,color:#000 + style QS fill:#bbf,stroke:#333,stroke-width:2px,color:#000 + style DECIDE fill:#ffb,stroke:#333,stroke-width:2px,color:#000 + style IMPL fill:#f9f,stroke:#333,stroke-width:2px,color:#000 ``` --- diff --git a/src/modules/bmm/docs/agents-guide.md b/src/modules/bmm/docs/agents-guide.md index 331a5008..eb8ecf8f 100644 --- a/src/modules/bmm/docs/agents-guide.md +++ b/src/modules/bmm/docs/agents-guide.md @@ -1013,7 +1013,6 @@ Quick reference for agent selection: - [Enterprise Agentic Development](./enterprise-agentic-development.md) - Team collaboration - [FAQ](./faq.md) - Common questions -- [Troubleshooting](./troubleshooting.md) - Problem resolution - [Glossary](./glossary.md) - Terminology reference --- diff --git a/src/modules/bmm/docs/brownfield-guide.md b/src/modules/bmm/docs/brownfield-guide.md index 4db898de..a5ca1509 100644 --- a/src/modules/bmm/docs/brownfield-guide.md +++ b/src/modules/bmm/docs/brownfield-guide.md @@ -12,7 +12,6 @@ - [Quick Reference](#quick-reference) - Commands and files - [Common Scenarios](#common-scenarios) - Real-world examples -- [Troubleshooting](#troubleshooting) - Problem solutions - [Best Practices](#best-practices) - Success tips --- @@ -336,8 +335,8 @@ flowchart TD CHECK -->|Yes| CREATE CHECK -->|No| RETRO - style SPRINT fill:#bfb,stroke:#333,stroke-width:2px - style RETRO fill:#fbf,stroke:#333,stroke-width:2px + style SPRINT fill:#bfb,stroke:#333,stroke-width:2px,color:#000 + style RETRO fill:#fbf,stroke:#333,stroke-width:2px,color:#000 ``` **Status Progression:** @@ -534,8 +533,6 @@ Document in tech-spec/architecture: ## Troubleshooting -For complete troubleshooting, see [Troubleshooting Guide](./troubleshooting.md). - ### AI Agents Lack Codebase Understanding **Symptoms:** @@ -706,9 +703,9 @@ flowchart TD PRD --> IMPL PRD2 --> IMPL - style START fill:#f9f,stroke:#333,stroke-width:2px - style DOC fill:#ffb,stroke:#333,stroke-width:2px - style IMPL fill:#bfb,stroke:#333,stroke-width:2px + style START fill:#f9f,stroke:#333,stroke-width:2px,color:#000 + style DOC fill:#ffb,stroke:#333,stroke-width:2px,color:#000 + style IMPL fill:#bfb,stroke:#333,stroke-width:2px,color:#000 ``` --- @@ -735,7 +732,6 @@ flowchart TD - **[Quick Start Guide](./quick-start.md)** - Getting started with BMM - **[Glossary](./glossary.md)** - Key terminology - **[FAQ](./faq.md)** - Common questions -- **[Troubleshooting](./troubleshooting.md)** - Problem resolution - **[Workflow Documentation](./README.md#-workflow-guides)** - Complete workflow reference --- diff --git a/src/modules/bmm/docs/faq.md b/src/modules/bmm/docs/faq.md index 45ee66d6..f6ffdb98 100644 --- a/src/modules/bmm/docs/faq.md +++ b/src/modules/bmm/docs/faq.md @@ -557,11 +557,10 @@ Trust your expertise - BMM supports your decisions. **A:** -1. Check [Troubleshooting Guide](./troubleshooting.md) for common issues -2. Search [Complete Documentation](./README.md) for related topics -3. Ask in [Discord Community](https://discord.gg/gk8jAdXWmj) (#general-dev) -4. Open a [GitHub Issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) -5. Watch [YouTube Tutorials](https://www.youtube.com/@BMadCode) +1. Search [Complete Documentation](./README.md) for related topics +2. Ask in [Discord Community](https://discord.gg/gk8jAdXWmj) (#general-dev) +3. Open a [GitHub Issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) +4. Watch [YouTube Tutorials](https://www.youtube.com/@BMadCode) ### Q: How do I report a bug or request a feature? @@ -580,7 +579,6 @@ Please include: - [Quick Start Guide](./quick-start.md) - Get started with BMM - [Glossary](./glossary.md) - Terminology reference -- [Troubleshooting](./troubleshooting.md) - Problem resolution - [Scale Adaptive System](./scale-adaptive-system.md) - Understanding levels - [Brownfield Guide](./brownfield-guide.md) - Existing codebase workflows diff --git a/src/modules/bmm/docs/glossary.md b/src/modules/bmm/docs/glossary.md index 1c12ee3d..c67ee1c0 100644 --- a/src/modules/bmm/docs/glossary.md +++ b/src/modules/bmm/docs/glossary.md @@ -318,4 +318,3 @@ Quick Spec Flow feature that automatically detects existing code style, naming c - [Brownfield Guide](./brownfield-guide.md) - Working with existing codebases - [Quick Spec Flow](./quick-spec-flow.md) - Fast-track for Quick Flow track - [FAQ](./faq.md) - Common questions -- [Troubleshooting](./troubleshooting.md) - Problem resolution diff --git a/src/modules/bmm/docs/quick-spec-flow.md b/src/modules/bmm/docs/quick-spec-flow.md index 05ac4629..3fd2b2f8 100644 --- a/src/modules/bmm/docs/quick-spec-flow.md +++ b/src/modules/bmm/docs/quick-spec-flow.md @@ -60,10 +60,10 @@ flowchart TD STORIES --> IMPL IMPL --> DONE - style START fill:#bfb,stroke:#333,stroke-width:2px - style OPTIONAL fill:#ffb,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5 - style IMPL fill:#bbf,stroke:#333,stroke-width:2px - style DONE fill:#f9f,stroke:#333,stroke-width:3px + style START fill:#bfb,stroke:#333,stroke-width:2px,color:#000 + style OPTIONAL fill:#ffb,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style IMPL fill:#bbf,stroke:#333,stroke-width:2px,color:#000 + style DONE fill:#f9f,stroke:#333,stroke-width:3px,color:#000 ``` --- diff --git a/src/modules/bmm/docs/quick-start.md b/src/modules/bmm/docs/quick-start.md index 67aa559e..126ab746 100644 --- a/src/modules/bmm/docs/quick-start.md +++ b/src/modules/bmm/docs/quick-start.md @@ -323,10 +323,10 @@ flowchart LR P2 --> P3 P3 --> P4 - style P1 fill:#bbf,stroke:#333,stroke-width:2px - style P2 fill:#bfb,stroke:#333,stroke-width:2px - style P3 fill:#ffb,stroke:#333,stroke-width:2px - style P4 fill:#fbf,stroke:#333,stroke-width:2px + style P1 fill:#bbf,stroke:#333,stroke-width:2px,color:#000 + style P2 fill:#bfb,stroke:#333,stroke-width:2px,color:#000 + style P3 fill:#ffb,stroke:#333,stroke-width:2px,color:#000 + style P4 fill:#fbf,stroke:#333,stroke-width:2px,color:#000 ``` ## Common Questions diff --git a/src/modules/bmm/docs/scale-adaptive-system.md b/src/modules/bmm/docs/scale-adaptive-system.md index 63cc2bf0..a8631d18 100644 --- a/src/modules/bmm/docs/scale-adaptive-system.md +++ b/src/modules/bmm/docs/scale-adaptive-system.md @@ -51,9 +51,9 @@ flowchart TD Q1 -->|Yes| QF[Quick Flow
Tech-spec only] Q1 -->|Uncertain| M - style QF fill:#bfb,stroke:#333,stroke-width:2px - style M fill:#bbf,stroke:#333,stroke-width:2px - style E fill:#f9f,stroke:#333,stroke-width:2px + style QF fill:#bfb,stroke:#333,stroke-width:2px,color:#000 + style M fill:#bbf,stroke:#333,stroke-width:2px,color:#000 + style E fill:#f9f,stroke:#333,stroke-width:2px,color:#000 ``` ### Quick Keywords @@ -389,8 +389,8 @@ flowchart TD TRACK -->|Method| M[PRD + Arch] TRACK -->|Enterprise| E[PRD + Arch + Sec/Ops] - style DOC fill:#ffb,stroke:#333,stroke-width:2px - style TRACK fill:#bfb,stroke:#333,stroke-width:2px + style DOC fill:#ffb,stroke:#333,stroke-width:2px,color:#000 + style TRACK fill:#bfb,stroke:#333,stroke-width:2px,color:#000 ``` --- diff --git a/src/modules/bmm/docs/troubleshooting.md b/src/modules/bmm/docs/troubleshooting.md deleted file mode 100644 index f411d98b..00000000 --- a/src/modules/bmm/docs/troubleshooting.md +++ /dev/null @@ -1,680 +0,0 @@ -# BMM Troubleshooting Guide - -Common issues and solutions for the BMad Method Module. - ---- - -## Quick Diagnosis - -**Use this flowchart to find your issue:** - -```mermaid -flowchart TD - START{What's the problem?} - - START -->|Can't get started| SETUP[Setup & Installation Issues] - START -->|Wrong level detected| LEVEL[Level Detection Problems] - START -->|Workflow not working| WORKFLOW[Workflow Issues] - START -->|Agent lacks context| CONTEXT[Context & Documentation Issues] - START -->|Implementation problems| IMPL[Implementation Issues] - START -->|Files/paths wrong| FILES[File & Path Issues] - - style START fill:#ffb,stroke:#333,stroke-width:2px - style SETUP fill:#bfb,stroke:#333,stroke-width:2px - style LEVEL fill:#bbf,stroke:#333,stroke-width:2px - style WORKFLOW fill:#fbf,stroke:#333,stroke-width:2px - style CONTEXT fill:#f9f,stroke:#333,stroke-width:2px -``` - ---- - -## Table of Contents - -- [Setup and Installation Issues](#setup-and-installation-issues) -- [Level Detection Problems](#level-detection-problems) -- [Workflow Issues](#workflow-issues) -- [Context and Documentation Issues](#context-and-documentation-issues) -- [Implementation Issues](#implementation-issues) -- [File and Path Issues](#file-and-path-issues) -- [Agent Behavior Issues](#agent-behavior-issues) -- [Integration Issues (Brownfield)](#integration-issues-brownfield) - ---- - -## Setup and Installation Issues - -### Problem: BMM not found after installation - -**Symptoms:** - -- `bmad` command not recognized -- Agent files not accessible -- Workflows don't load - -**Solution:** - -```bash -# Check if BMM is installed -ls bmad/ - -# If not present, run installer -npx bmad-method@alpha install - -# For fresh install -npx bmad-method@alpha install --skip-version-prompt -``` - -### Problem: Agents don't have menu - -**Symptoms:** - -- Load agent file but no menu appears -- Agent doesn't respond to commands - -**Solution:** - -1. Ensure you're loading the correct agent file path: `bmad/bmm/agents/[agent-name].md` -2. Wait a few seconds for agent to initialize -3. Try asking "show menu" or "help" -4. Check IDE supports Markdown rendering with context -5. For Claude Code: Ensure agent file is open in chat context - -### Problem: Workflows not found - -**Symptoms:** - -- Agent says workflow doesn't exist -- Menu shows workflow but won't run - -**Solution:** - -1. Check workflow exists: `ls bmad/bmm/workflows/` -2. Verify agent has access to workflow (check agent's workflow list) -3. Try using menu number instead of workflow name -4. Restart chat with agent in fresh session - ---- - -## Level Detection Problems - -### Problem: workflow-init suggests wrong level - -**Symptoms:** - -- Detects Level 3 but you only need Level 1 -- Suggests Level 1 but project is actually Level 2 -- Can't figure out appropriate level - -**Solution:** - -1. **Override the suggestion** - workflow-init always asks for confirmation, just say "no" and choose correct level -2. **Be specific in description** - Use level keywords when describing: - - "fix bug" → Level 0 - - "add small feature" → Level 1 - - "build dashboard" → Level 2 -3. **Manual override** - You can always switch levels later if needed - -**Example:** - -``` -workflow-init: "Level 3 project?" -You: "No, this is just adding OAuth login - Level 1" -workflow-init: "Got it, creating Level 1 workflow" -``` - -### Problem: Project level unclear - -**Symptoms:** - -- Between Level 1 and Level 2 -- Not sure if architecture needed -- Story count uncertain - -**Solution:** -**When in doubt, start smaller:** - -- Choose Level 1 instead of Level 2 -- You can always run `create-prd` later if needed -- Level 1 is faster, less overhead -- Easy to upgrade, hard to downgrade - -**Decision criteria:** - -- Single epic with related stories? → Level 1 -- Multiple independent epics? → Level 2 -- Need product-level planning? → Level 2 -- Just need technical plan? → Level 1 - -### Problem: Old planning docs influencing level detection - -**Symptoms:** - -- Old Level 3 PRD in folder -- Working on new Level 0 bug fix -- workflow-init suggests Level 3 - -**Solution:** -workflow-init asks: "Is this work in progress or previous effort?" - -- Answer: "Previous effort" -- Then describe your NEW work clearly -- System will detect level based on NEW work, not old artifacts - ---- - -## Workflow Issues - -### Problem: Workflow fails or hangs - -**Symptoms:** - -- Workflow starts but doesn't complete -- Agent stops responding mid-workflow -- Progress stalls - -**Solution:** - -1. **Check context limits** - Start fresh chat for complex workflows -2. **Verify prerequisites**: - - Phase 2 needs Phase 1 complete (if used) - - Phase 3 needs Phase 2 complete - - Phase 4 needs Phase 3 complete (if Level 3-4) -3. **Restart workflow** - Load agent in new chat and restart -4. **Check status file** - Verify `bmm-workflow-status.md` or `sprint-status.yaml` is present and valid - -### Problem: Agent says "workflow not found" - -**Symptoms:** - -- Request workflow by name -- Agent doesn't recognize it -- Menu doesn't show workflow - -**Solution:** - -1. Check spelling/format - Use exact workflow name or menu shortcut (*prd not *PRD) -2. Verify agent has workflow: - - PM agent: prd, tech-spec - - Architect agent: create-architecture, validate-architecture - - SM agent: sprint-planning, create-story, story-context -3. Try menu number instead of name -4. Check you're using correct agent for workflow - -### Problem: Sprint-planning workflow fails - -**Symptoms:** - -- Can't create sprint-status.yaml -- Epics not extracted from files -- Status file empty or incorrect - -**Solution:** - -1. **Verify epic files exist**: - - Level 1: tech-spec with epic - - Level 2-4: epics.md or sharded epic files -2. **Check file format**: - - Epic files should be valid Markdown - - Epic headers should be clear (## Epic Name) -3. **Run in Phase 4 only** - Ensure Phase 2/3 complete first -4. **Check file paths** - Epic files should be in correct output folder - -### Problem: story-context generates empty or wrong context - -**Symptoms:** - -- Context file created but has no useful content -- Context doesn't reference existing code -- Missing technical guidance - -**Solution:** - -1. **Run epic-tech-context first** - story-context builds on epic context -2. **Check story file exists** - Verify story was created by create-story -3. **For brownfield**: - - Ensure document-project was run - - Verify docs/index.md exists with codebase context -4. **Try regenerating** - Sometimes needs fresh attempt with more specific story details - ---- - -## Context and Documentation Issues - -### Problem: AI agents lack codebase understanding (Brownfield) - -**Symptoms:** - -- Suggestions don't align with existing patterns -- Ignores available components -- Proposes approaches that conflict with architecture -- Doesn't reference existing code - -**Solution:** - -1. **Run document-project** - Critical for brownfield projects - ``` - Load Analyst agent → run document-project - Choose scan level: Deep (recommended for PRD prep) - ``` -2. **Verify docs/index.md exists** - This is master entry point for AI agents -3. **Check documentation completeness**: - - Review generated docs/index.md - - Ensure key systems are documented -4. **Run deep-dive on specific areas** if needed - -### Problem: Have documentation but agents can't find it - -**Symptoms:** - -- README.md, ARCHITECTURE.md exist -- AI agents still ask questions answered in docs -- No docs/index.md file - -**Solution:** -**Option 1: Quick fix (2-5min)** -Run `index-docs` task: - -- Located at `bmad/core/tasks/index-docs.xml` -- Scans existing docs and generates index.md -- Lightweight, just creates navigation - -**Option 2: Comprehensive (10-30min)** -Run document-project workflow: - -- Discovers existing docs in Step 2 -- Generates NEW AI-friendly documentation from codebase -- Creates index.md linking to BOTH existing and new docs - -**Why this matters:** AI agents need structured entry point (index.md) to navigate docs efficiently. - -### Problem: document-project takes too long - -**Symptoms:** - -- Exhaustive scan running for hours -- Impatient to start planning - -**Solution:** -**Choose appropriate scan level:** - -- **Quick (2-5min)** - Pattern analysis, no source reading - Good for initial overview -- **Deep (10-30min)** - Reads critical paths - **Recommended for most brownfield projects** -- **Exhaustive (30-120min)** - Reads all files - Only for migration planning or complete understanding - -For most brownfield projects, **Deep scan is sufficient**. - ---- - -## Implementation Issues - -### Problem: Existing tests breaking (Brownfield) - -**Symptoms:** - -- Regression test failures -- Previously working functionality broken -- Integration tests failing - -**Solution:** - -1. **Review changes against existing patterns**: - - Check if new code follows existing conventions - - Verify API contracts unchanged (unless intentionally versioned) -2. **Run test-review workflow** (TEA agent): - - Analyzes test coverage - - Identifies regression risks - - Suggests fixes -3. **Add regression testing to DoD**: - - All existing tests must pass - - Add integration tests for new code -4. **Consider feature flags** for gradual rollout - -### Problem: Story takes much longer than estimated - -**Symptoms:** - -- Story estimated 4 hours, took 12 hours -- Acceptance criteria harder than expected -- Hidden complexity discovered - -**Solution:** -**This is normal!** Estimates are estimates. To handle: - -1. **Continue until DoD met** - Don't compromise quality -2. **Document learnings in retrospective**: - - What caused the overrun? - - What should we watch for next time? -3. **Consider splitting story** if it's truly two stories -4. **Adjust future estimates** based on this data - -**Don't stress about estimate accuracy** - use them for learning, not judgment. - -### Problem: Integration points unclear - -**Symptoms:** - -- Not sure how to connect new code to existing -- Unsure which files to modify -- Multiple possible integration approaches - -**Solution:** - -1. **For brownfield**: - - Ensure document-project captured existing architecture - - Review architecture docs before implementing -2. **Check story-context** - Should document integration points -3. **In tech-spec/architecture** - Explicitly document: - - Which existing modules to modify - - What APIs/services to integrate with - - Data flow between new and existing code -4. **Run integration-planning workflow** (Level 3-4): - - Architect agent creates integration strategy - -### Problem: Inconsistent patterns being introduced - -**Symptoms:** - -- New code style doesn't match existing -- Different architectural approach -- Not following team conventions - -**Solution:** - -1. **Check convention detection** (Quick Spec Flow): - - Should detect existing patterns - - Asks for confirmation before proceeding -2. **Review documentation** - Ensure document-project captured patterns -3. **Use story-context** - Injects pattern guidance per story -4. **Add to code-review checklist**: - - Pattern adherence - - Convention consistency - - Style matching -5. **Run retrospective** to identify pattern deviations early - ---- - -## File and Path Issues - -### Problem: Output files in wrong location - -**Symptoms:** - -- PRD created in wrong folder -- Story files not where expected -- Documentation scattered - -**Solution:** -Check `bmad/bmm/config.yaml` for configured paths: - -```yaml -output_folder: '{project-root}/docs' -dev_story_location: '{project-root}/docs/stories' -``` - -Default locations: - -- Planning docs (PRD, epics, architecture): `{output_folder}/` -- Stories: `{dev_story_location}/` -- Status files: `{output_folder}/bmm-workflow-status.md`, `{output_folder}/sprint-status.yaml` - -To change locations, edit config.yaml then re-run workflows. - -### Problem: Can't find status file - -**Symptoms:** - -- workflow-status says no status file -- Can't track progress -- Lost place in workflow - -**Solution:** - -1. **Check default location**: `docs/bmm-workflow-status.md` -2. **If missing, reinitialize**: - ``` - Load Analyst agent → run workflow-init - ``` -3. **For Phase 4**: Look for `sprint-status.yaml` in same folder as PRD -4. **Search for it**: - ```bash - find . -name "bmm-workflow-status.md" - find . -name "sprint-status.yaml" - ``` - -### Problem: Sprint-status.yaml not updating - -**Symptoms:** - -- Workflows complete but status unchanged -- Stories stuck in old status -- Epic status not progressing - -**Solution:** - -1. **Manual update required** - Most status changes are manual: - ```yaml - stories: - - id: epic-1-story-1 - status: done # Change this manually - ``` -2. **Some workflows auto-update**: - - sprint-planning creates file - - epic-tech-context changes epic to "contexted" - - create-story changes story to "drafted" - - story-context changes to "ready-for-dev" - - dev-story may auto-update (check workflow) -3. **Re-run sprint-planning** to resync if needed - ---- - -## Agent Behavior Issues - -### Problem: Agent provides vague or generic responses - -**Symptoms:** - -- "Use appropriate framework" -- "Follow best practices" -- Generic advice without specifics - -**Solution:** - -1. **Provide more context** - Be specific in your description: - - "Add OAuth using passport.js to Express server" - - Not: "Add authentication" -2. **For brownfield**: - - Ensure document-project was run - - Agent needs codebase context for specific advice -3. **Reference existing docs**: - - "Based on the existing auth system in UserService..." -4. **Start fresh chat** - Context overload can cause generic responses - -### Problem: Agent hallucinating or making up information - -**Symptoms:** - -- References files that don't exist -- Suggests APIs that aren't in your stack -- Creates imaginary requirements - -**Solution:** - -1. **Use fresh chat** - Context overflow main cause of hallucinations -2. **Provide concrete constraints**: - - "We use Express 4.18.2, not Next.js" - - "Our database is PostgreSQL, not MongoDB" -3. **For brownfield**: - - Document-project provides factual grounding - - Agent sees actual code, not assumptions -4. **Correct immediately**: - - "No, we don't have UserService, we have AuthenticationModule" - -### Problem: Agent won't follow instructions - -**Symptoms:** - -- Ignores specific requests -- Does something different than asked -- Doesn't respect constraints - -**Solution:** - -1. **Be more explicit** - Agents respond to clear, specific instructions: - - "Use EXACTLY these three steps..." - - "Do NOT include database migrations in this story" -2. **Check agent capabilities** - Agent might not have access to requested workflow -3. **Try different phrasing** - Rephrase request to be more direct -4. **Use menu system** - Numbers are clearer than text commands - ---- - -## Integration Issues (Brownfield) - -### Problem: New code conflicts with existing architecture - -**Symptoms:** - -- Integration approach doesn't fit existing structure -- Would require major refactoring -- Conflicts with established patterns - -**Solution:** - -1. **Check if document-project was run** - Agents need architecture context -2. **Review existing architecture docs**: - - Read docs/architecture.md (from document-project) - - Understand current system design -3. **For Level 3-4**: - - Run validate-architecture workflow before planning - - Use integration-planning workflow -4. **Explicitly document integration strategy** in architecture: - - How new components fit existing structure - - What modifications needed to existing code - - Migration path if changing patterns - -### Problem: Breaking changes to existing APIs - -**Symptoms:** - -- Changing API breaks consumers -- Downstream services affected -- Need backward compatibility - -**Solution:** - -1. **Identify all API consumers** (document-project should show this) -2. **Plan versioning strategy**: - - API v1 (existing) + v2 (new) - - Deprecation timeline -3. **Use feature flags** for gradual rollout -4. **Document migration guide** for API consumers -5. **Add to testing strategy**: - - Existing consumers still work (v1) - - New functionality works (v2) - -### Problem: Data migration required - -**Symptoms:** - -- Schema changes needed -- Existing data needs transformation -- Risk of data loss - -**Solution:** - -1. **Create explicit migration strategy** in architecture: - - Forward migration (old → new schema) - - Rollback plan (new → old schema) - - Data validation approach -2. **Test migrations thoroughly**: - - On copy of production data - - Measure performance impact -3. **Plan rollout**: - - Staging environment first - - Gradual production rollout - - Monitoring for issues -4. **Document in tech-spec/architecture**: - - Migration scripts - - Rollback procedures - - Expected downtime - ---- - -## Still Stuck? - -### Getting More Help - -If your issue isn't covered here: - -1. **Check other documentation**: - - [FAQ](./faq.md) - Common questions - - [Glossary](./glossary.md) - Terminology - - [Quick Start](./quick-start.md) - Basic usage - - [Brownfield Guide](./brownfield-guide.md) - Existing codebases - - [Scale Adaptive System](./scale-adaptive-system.md) - Understanding levels - -2. **Community support**: - - [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues - - Active community, fast responses - - Share your specific situation - -3. **Report bugs**: - - [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) - - Include version, steps to reproduce, expected vs actual behavior - -4. **Video tutorials**: - - [YouTube Channel](https://www.youtube.com/@BMadCode) - - Visual walkthroughs of common workflows - ---- - -## Common Error Messages - -### "No workflow status file found" - -**Cause:** Haven't run workflow-init yet -**Fix:** Load Analyst agent → run workflow-init - -### "Epic file not found" - -**Cause:** PRD/epics not created, or wrong path -**Fix:** Verify PRD/epics exist in output folder, check config.yaml paths - -### "Story not in sprint-status.yaml" - -**Cause:** Sprint-planning not run, or story file not created -**Fix:** Run sprint-planning workflow, verify story files exist - -### "Documentation insufficient for brownfield" - -**Cause:** No docs/index.md or document-project not run -**Fix:** Run document-project workflow with Deep scan - -### "Level detection failed" - -**Cause:** Ambiguous project description -**Fix:** Be more specific, use level keywords (fix, feature, platform, etc.) - -### "Context generation failed" - -**Cause:** Missing prerequisites (epic context, story file, or docs) -**Fix:** Verify epic-tech-context run, story file exists, docs present - ---- - -## Prevention Tips - -**Avoid common issues before they happen:** - -1. ✅ **Always run document-project for brownfield** - Saves hours of context issues later -2. ✅ **Use fresh chats for complex workflows** - Prevents hallucinations and context overflow -3. ✅ **Verify files exist before running workflows** - Check PRD, epics, stories are present -4. ✅ **Read agent menu before requesting workflows** - Confirm agent has the workflow -5. ✅ **Start with smaller level if unsure** - Easy to upgrade (Level 1 → 2), hard to downgrade -6. ✅ **Keep status files updated** - Manual updates when needed, don't let them drift -7. ✅ **Run retrospectives after epics** - Catch issues early, improve next epic -8. ✅ **Follow phase sequence** - Don't skip required phases (Phase 2 before 3, 3 before 4) - ---- - -**Issue not listed?** Please [report it](https://github.com/bmad-code-org/BMAD-METHOD/issues) so we can add it to this guide! diff --git a/src/modules/bmm/docs/workflows-analysis.md b/src/modules/bmm/docs/workflows-analysis.md index b23d01af..cf475ce5 100644 --- a/src/modules/bmm/docs/workflows-analysis.md +++ b/src/modules/bmm/docs/workflows-analysis.md @@ -1,685 +1,268 @@ # BMM Analysis Workflows (Phase 1) +**Reading Time:** ~7 minutes + ## Overview -Phase 1 (Analysis) workflows are **optional** exploration and discovery tools that help you understand your project space before committing to detailed planning. These workflows facilitate creative thinking, market validation, and strategic alignment. +Phase 1 (Analysis) workflows are **optional** exploration and discovery tools that help validate ideas, understand markets, and generate strategic context before planning begins. -**When to use Analysis workflows:** +**Key principle:** Analysis workflows help you think strategically before committing to implementation. Skip them if your requirements are already clear. -- Starting a new project from scratch -- Exploring a problem space or opportunity -- Validating market fit before significant investment -- Gathering strategic context for planning phases +**When to use:** Starting new projects, exploring opportunities, validating market fit, generating ideas, understanding problem spaces. -**When to skip Analysis workflows:** - -- Continuing an existing project with clear requirements -- Working on well-defined features with known solutions -- Working under strict constraints where discovery is complete +**When to skip:** Continuing existing projects with clear requirements, well-defined features with known solutions, strict constraints where discovery is complete. --- -## Phase 1 Workflow Map +## Phase 1 Analysis Workflow Map ```mermaid %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%% graph TB - subgraph Creative["CREATIVE EXPLORATION"] - direction TB + subgraph Discovery["DISCOVERY & IDEATION (Optional)"] + direction LR BrainstormProject["Analyst: brainstorm-project
Multi-track solution exploration"] BrainstormGame["Analyst: brainstorm-game
Game concept generation"] end - subgraph Strategic["STRATEGIC PLANNING"] + subgraph Research["RESEARCH & VALIDATION (Optional)"] direction TB - ProductBrief["Analyst: product-brief
Product vision and strategy"] - GameBrief["Game Designer: game-brief
Game vision capture"] + ResearchWF["Analyst: research
• market (TAM/SAM/SOM)
• technical (framework evaluation)
• competitive (landscape)
• user (personas, JTBD)
• domain (industry analysis)
• deep_prompt (AI research)"] end - subgraph Research["RESEARCH AND INVESTIGATION"] - direction TB - ResearchWF["Analyst: research
Market, technical, competitive analysis"] + 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 - Creative -.->|Software projects| ProductBrief - Creative -.->|Game projects| GameBrief - BrainstormProject -.->|May inform| ResearchWF - BrainstormGame -.->|May inform| ResearchWF - ResearchWF -.->|Feeds into| ProductBrief - ResearchWF -.->|Feeds into| GameBrief + 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 - style Creative fill:#e1f5fe,stroke:#01579b,stroke-width:3px,color:#000 - style Strategic fill:#f3e5f5,stroke:#4a148c,stroke-width:3px,color:#000 + 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 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 - style ResearchWF fill:#fff59d,stroke:#f57f17,stroke-width:2px,color:#000 ``` --- ## Quick Reference -| Workflow | Agent | Required | Purpose | -| ------------------ | ------------- | ----------- | ----------------------------------------------------------- | -| brainstorm-project | Analyst | No | Explore solution approaches and architectures | -| brainstorm-game | Analyst | No | Generate game concepts using creative techniques | -| product-brief | Analyst | Recommended | Define product vision and strategy | -| game-brief | Game Designer | Recommended | Capture game vision before GDD | -| research | Analyst | No | Multi-type research system (market, technical, competitive) | +| 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 | --- -## brainstorm-project +## Workflow Descriptions -### Purpose +### brainstorm-project -Generate multiple solution approaches for software projects through parallel ideation tracks that align technical and business thinking from inception. +**Purpose:** Generate multiple solution approaches through parallel ideation tracks (architecture, UX, integration, value). **Agent:** Analyst -**Phase:** 1 (Analysis) -**Required:** No -### When to Use +**When to Use:** -- You have a business objective but unclear technical approach -- Multiple solution paths exist and you need to evaluate trade-offs -- Hidden assumptions need discovery before planning -- Innovation beyond obvious solutions is valuable +- Unclear technical approach with business objectives +- Multiple solution paths need evaluation +- Hidden assumptions need discovery +- Innovation beyond obvious solutions -### Prerequisites +**Key Outputs:** -- Business objectives and constraints -- Technical environment context -- Stakeholder needs identified -- Success criteria defined (at least preliminary) +- Architecture proposals with trade-off analysis +- Value framework (prioritized features) +- Risk analysis (dependencies, challenges) +- Strategic recommendation with rationale -### Process Overview - -**1. Context Capture** - -- Business objectives and constraints -- Technical environment -- Stakeholder needs -- Success criteria - -**2. Parallel Ideation** - -- **Architecture Track**: Technical approaches with trade-offs -- **UX Track**: Interface paradigms and user journeys -- **Integration Track**: System connection patterns -- **Value Track**: Feature prioritization and delivery sequences - -**3. Solution Synthesis** - -- Evaluate feasibility and impact -- Align with strategic objectives -- Surface hidden assumptions -- Generate recommendations with rationale - -### Inputs - -| Input | Type | Purpose | -| ----------------- | -------- | --------------------------------------------- | -| Project Context | Document | Business objectives, environment, constraints | -| Problem Statement | Optional | Core challenge or opportunity to address | - -### Outputs - -| Output | Content | -| ------------------------ | ------------------------------------------- | -| Architecture Proposals | Multiple approaches with trade-off analysis | -| Value Framework | Prioritized features aligned to objectives | -| Risk Analysis | Dependencies, challenges, opportunities | -| Strategic Recommendation | Synthesized direction with rationale | - -### Example Scenario - -**Starting Point:** -"We need a customer dashboard for our SaaS product" - -**After brainstorm-project:** - -- **Architecture Option A**: Monolith with server-side rendering (faster to market, easier ops) -- **Architecture Option B**: Microservices + SPA (better scalability, more complex) -- **Architecture Option C**: Hybrid approach (SSR shell + client-side islands) -- **Recommendation**: Option A for MVP, with clear path to Option C as we scale -- **Risk**: Option A may require rewrite if we hit 10K+ concurrent users - -### Related Workflows - -- **research** - Deep investigation of market/technical options -- **product-brief** - Strategic planning document -- **prd** (Phase 2) - Requirements document from chosen approach +**Example:** "We need a customer dashboard" → Options: Monolith SSR (faster), Microservices SPA (scalable), Hybrid (balanced) with recommendation. --- -## brainstorm-game +### brainstorm-game -### Purpose - -Generate and refine game concepts through systematic creative exploration using five distinct brainstorming techniques, grounded in practical constraints. +**Purpose:** Generate game concepts through systematic creative exploration using five brainstorming techniques. **Agent:** Analyst -**Phase:** 1 (Analysis) -**Required:** No -### When to Use +**When to Use:** - Generating original game concepts -- Exploring variations on a theme +- Exploring variations on themes - Breaking creative blocks - Validating game ideas against constraints -### Prerequisites +**Techniques Used:** -- Platform specifications (mobile, PC, console, web) -- Genre preferences or inspirations -- Technical constraints understood -- Target audience defined -- Core design pillars identified (at least preliminary) +- SCAMPER (systematic modification) +- Mind Mapping (hierarchical exploration) +- Lotus Blossom (radial expansion) +- Six Thinking Hats (multi-perspective) +- Random Word Association (lateral thinking) -### Process Overview +**Key Outputs:** -**Five Brainstorming Methods** (applied in isolation, then synthesized): +- Method-specific artifacts (5 separate documents) +- Consolidated concept document with feasibility +- Design pillar alignment matrix -| Method | Focus | Output Characteristics | -| ----------------------- | ------------------------ | ---------------------------------- | -| SCAMPER | Systematic modification | Structured transformation analysis | -| Mind Mapping | Hierarchical exploration | Visual concept relationships | -| Lotus Blossom | Radial expansion | Layered thematic development | -| Six Thinking Hats | Multi-perspective | Balanced evaluation framework | -| Random Word Association | Lateral thinking | Unexpected conceptual combinations | - -Each method generates distinct artifacts that are then evaluated against design pillars, technical feasibility, and market positioning. - -### Inputs - -- **Game Context Document**: Platform specs, genre, technical constraints, target audience, monetization approach, design pillars -- **Initial Concept Seed** (optional): High-level game idea or theme - -### Outputs - -- **Method-Specific Artifacts**: Five separate brainstorming documents -- **Consolidated Concept Document**: Synthesized game concepts with feasibility assessments and unique value propositions -- **Design Pillar Alignment Matrix**: Evaluation of concepts against stated objectives - -### Example Scenario - -**Starting Point:** -"A roguelike with psychological themes" - -**After brainstorm-game:** - -- **SCAMPER Result**: "What if standard roguelike death → becomes emotional regression?" -- **Mind Map Result**: Emotion types (anger, fear, joy) as character classes -- **Lotus Blossom Result**: Inner demons as enemies, therapy sessions as rest points -- **Six Thinking Hats Result**: White (data) - mental health market growing; Red (emotion) - theme may alienate hardcore players -- **Random Word Association Result**: "Mirror" + "Roguelike" = reflection mechanics that change gameplay - -**Synthesized Concept:** -"Mirror of Mind: A roguelike card battler where you play as emotions battling inner demons. Deck composition affects narrative, emotional theme drives mechanics, 3 characters representing anger/fear/joy, target audience: core gamers interested in mental health themes." - -### Related Workflows - -- **game-brief** - Capture validated concept in structured brief -- **gdd** (Phase 2) - Full game design document +**Example:** "Roguelike with psychological themes" → Emotions as characters, inner demons as enemies, therapy sessions as rest points, deck composition affects narrative. --- -## product-brief +### research -### Purpose - -Interactive product brief creation that guides users through defining their product vision with multiple input sources and conversational collaboration. +**Purpose:** Comprehensive multi-type research system consolidating market, technical, competitive, user, and domain analysis. **Agent:** Analyst -**Phase:** 1 (Analysis) -**Required:** Recommended (skip only if PRD already exists) -### When to Use - -- Starting a new product or major feature initiative -- Aligning stakeholders before detailed planning -- Transitioning from exploration to strategy -- Creating executive-level product documentation - -### Prerequisites - -- Business context understood -- Problem or opportunity identified -- Stakeholders accessible for input -- Strategic objectives defined - -### Modes of Operation - -**Interactive Mode** (Recommended): - -- Step-by-step collaborative development -- Probing questions to refine thinking -- Deep exploration of problem/solution fit -- High-quality output with thorough exploration - -**YOLO Mode**: - -- AI generates complete draft from initial context -- User reviews and refines sections iteratively -- Faster for rapid draft generation -- Best for time-constrained situations or when you have clear vision - -### Process Overview - -**Phase 1: Initialization and Context (Steps 0-2)** - -- Project setup and context capture -- Input document gathering -- Mode selection -- Context extraction - -**Phase 2: Interactive Development (Steps 3-12) - Interactive Mode** - -- Problem definition and pain points -- Solution articulation and value proposition -- User segmentation -- Success metrics and KPIs -- MVP scoping (ruthlessly defined) -- Financial planning and ROI -- Technical context -- Risk assessment and assumptions - -**Phase 3: Rapid Generation (Steps 3-4) - YOLO Mode** - -- Complete draft generation from context -- Iterative refinement of sections -- Quality validation - -**Phase 4: Finalization (Steps 13-15)** - -- Executive summary creation -- Supporting materials compilation -- Final review and handoff preparation - -### Inputs - -- Optional: Market research, competitive analysis, brainstorming results -- User input through conversational process -- Business context and objectives - -### Outputs - -**Primary Output:** `product-brief-{project_name}-{date}.md` - -**Output Structure:** - -1. Executive Summary -2. Problem Statement (with evidence) -3. Proposed Solution (core approach and differentiators) -4. Target Users (primary and secondary segments) -5. Goals and Success Metrics -6. MVP Scope (must-have features) -7. Post-MVP Vision -8. Financial Impact (investment and ROI) -9. Strategic Alignment -10. Technical Considerations -11. Constraints and Assumptions -12. Risks and Open Questions -13. Supporting Materials - -### Example Scenario - -**Starting Point:** -"We see customers struggling with project tracking" - -**After product-brief (Interactive Mode):** - -- **Problem**: Teams using 3+ tools for project management, causing 40% efficiency loss -- **Solution**: Unified workspace combining tasks, docs, and communication -- **Target Users**: 10-50 person product teams, SaaS-first companies -- **MVP Scope**: Task management + Real-time collaboration + Integrations (GitHub, Slack) -- **Success Metrics**: 30% reduction in tool-switching time, 20% faster project completion -- **Financial Impact**: $2M investment, $10M ARR target year 2 - -### Related Workflows - -- **brainstorm-project** - Generate solution approaches first -- **research** - Gather market/competitive intelligence -- **prd** (Phase 2) - Detailed requirements from product brief - ---- - -## game-brief - -### Purpose - -Lightweight, interactive brainstorming and planning session that captures game vision before diving into detailed Game Design Documents. - -**Agent:** Game Designer -**Phase:** 1 (Analysis) -**Required:** Recommended for game projects - -### When to Use - -- Starting a new game project from scratch -- Exploring a game idea before committing -- Pitching a concept to team/stakeholders -- Validating market fit and feasibility -- Preparing input for GDD workflow - -**Skip if:** - -- You already have a complete GDD -- Continuing an existing project -- Prototyping without planning needs - -### Comparison: Game Brief vs GDD - -| Aspect | Game Brief | GDD | -| ------------ | --------------------------- | ------------------------- | -| Purpose | Validate concept | Design for implementation | -| Detail Level | High-level vision | Detailed specifications | -| Audience | Self, team, stakeholders | Development team | -| Scope | Concept validation | Implementation roadmap | -| Format | Conversational, exploratory | Structured, comprehensive | -| Output | Concise vision document | Comprehensive design doc | - -### Comparison: Game Brief vs Product Brief - -| Aspect | Game Brief | Product Brief | -| ------------- | ---------------------------- | --------------------------------- | -| Focus | Player experience, fun, feel | User problems, features, value | -| Metrics | Engagement, retention, fun | Revenue, conversion, satisfaction | -| Core Elements | Gameplay pillars, mechanics | Problem/solution, user segments | -| References | Other games | Competitors, market | -| Vision | Emotional experience | Business outcomes | - -### Workflow Structure - -**Interactive Mode** (Recommended): - -1. Game Vision (concept, pitch, vision statement) -2. Target Market (audience, competition, positioning) -3. Game Fundamentals (pillars, mechanics, experience goals) -4. Scope and Constraints (platforms, timeline, budget, team) -5. Reference Framework (inspiration, competitors, differentiators) -6. Content Framework (world, narrative, volume) -7. Art and Audio Direction -8. Risk Assessment (risks, challenges, mitigation) -9. Success Criteria (MVP, metrics, launch goals) -10. Next Steps - -**YOLO Mode**: AI generates complete draft, then you refine iteratively - -### Inputs - -Optional: - -- Market research -- Brainstorming results -- Competitive analysis -- Design notes -- Reference game lists - -### Outputs - -**Primary Output:** `game-brief-{game_name}-{date}.md` - -**Sections:** - -- Executive summary -- Complete game vision -- Target market analysis -- Core gameplay definition -- Scope and constraints -- Reference framework -- Art/audio direction -- Risk assessment -- Success criteria -- Next steps - -### Example Scenario - -**Starting Point:** -"I want to make a roguelike card game with a twist" - -**After Game Brief:** - -- **Core Concept**: Roguelike card battler where you play as emotions battling inner demons -- **Target Audience**: Core gamers who love Slay the Spire, interested in mental health themes -- **Differentiator**: Emotional narrative system where deck composition affects story -- **MVP Scope**: 3 characters, 80 cards, 30 enemy types, 3 bosses, 6-hour first run -- **Platform**: PC (Steam) first, mobile later -- **Timeline**: 12 months with 2-person team -- **Key Risk**: Emotional theme might alienate hardcore roguelike fans -- **Mitigation**: Prototype early, test with target audience, offer "mechanical-only" mode - -**Next Steps:** - -1. Build card combat prototype (2 weeks) -2. Test emotional resonance with players -3. Proceed to GDD workflow if prototype validates - -### Related Workflows - -- **brainstorm-game** - Generate initial concepts -- **gdd** (Phase 2) - Full game design document -- **narrative** (Phase 2) - For story-heavy games - ---- - -## research - -### Purpose - -Comprehensive, adaptive multi-type research system that consolidates various research methodologies into a single powerful tool. - -**Agent:** Analyst -**Phase:** 1 (Analysis) -**Required:** No - -### Research Types - -**6 Research Types Available:** +**Research Types:** | Type | Purpose | Use When | | --------------- | ------------------------------------------------------ | ----------------------------------- | -| **market** | Market intelligence, TAM/SAM/SOM, competitive analysis | Need market viability validation | -| **deep_prompt** | Generate optimized research prompts for AI platforms | Need AI to research deeper topics | -| **technical** | Technology evaluation, architecture decisions | Choosing frameworks/platforms | +| **market** | TAM/SAM/SOM, competitive analysis | Need market viability validation | +| **technical** | Technology evaluation, ADRs | Choosing frameworks/platforms | | **competitive** | Deep competitor analysis | Understanding competitive landscape | | **user** | Customer insights, personas, JTBD | Need user understanding | | **domain** | Industry deep dives, trends | Understanding domain/industry | - -### Market Research (Type: market) +| **deep_prompt** | Generate AI research prompts (ChatGPT, Claude, Gemini) | Need deeper AI-assisted research | **Key Features:** - Real-time web research -- TAM/SAM/SOM calculations with multiple methodologies -- Competitive landscape analysis -- Customer persona development -- Porter's Five Forces and strategic frameworks -- Go-to-market strategy recommendations +- Multiple analytical frameworks (Porter's Five Forces, SWOT, Technology Adoption Lifecycle) +- Platform-specific optimization for deep_prompt type +- Configurable research depth (quick/standard/comprehensive) -**Inputs:** - -- Product or business description -- Target customer hypotheses (optional) -- Known competitors list (optional) - -**Outputs:** - -- Market size analysis (TAM/SAM/SOM) -- Competitive positioning -- Customer segments and personas -- Market trends and opportunities -- Strategic recommendations -- Financial projections (optional) - -### Deep Research Prompt (Type: deep_prompt) - -**Key Features:** - -- Optimized for AI research platforms (ChatGPT Deep Research, Gemini, Grok, Claude Projects) -- Prompt engineering best practices -- Platform-specific optimization -- Context packaging for optimal AI understanding -- Research question refinement - -**Inputs:** - -- Research question or topic -- Background context documents (optional) -- Target AI platform preference (optional) - -**Outputs:** - -- Platform-optimized research prompt -- Multi-stage research workflow -- Context documents packaged -- Execution guidance - -### Technical Research (Type: technical) - -**Key Features:** - -- Technology evaluation and comparison matrices -- Architecture pattern research -- Framework/library assessment -- Technical feasibility studies -- Cost-benefit analysis -- Architecture Decision Records (ADR) - -**Inputs:** - -- Technical requirements -- Current architecture (if brownfield) -- Technical constraints - -**Outputs:** - -- Technology comparison matrix -- Trade-off analysis -- Cost-benefit assessment -- ADR with recommendation -- Implementation guidance - -### Configuration Options - -Can be customized through workflow.yaml: - -- **research_depth**: `quick`, `standard`, or `comprehensive` -- **enable_web_research**: Enable real-time data gathering -- **enable_competitor_analysis**: Competitive intelligence -- **enable_financial_modeling**: Financial projections - -### Frameworks Available - -**Market Research:** - -- TAM/SAM/SOM Analysis -- Porter's Five Forces -- Jobs-to-be-Done (JTBD) -- Technology Adoption Lifecycle -- SWOT Analysis -- Value Chain Analysis - -**Technical Research:** - -- Trade-off Analysis Matrix -- Architecture Decision Records (ADR) -- Technology Radar -- Comparison Matrix -- Cost-Benefit Analysis -- Technical Risk Assessment - -### Example Scenario - -**Type: market** - -**Input:** -"SaaS project management tool for remote teams" - -**Output:** - -- **TAM**: $50B (global project management software) -- **SAM**: $5B (remote-first teams 10-50 people) -- **SOM**: $50M (achievable in year 3) -- **Top Competitors**: Asana, Monday.com, ClickUp -- **Positioning**: "Real-time collaboration focused, vs async-first competitors" -- **Customer Personas**: Product Managers (primary), Engineering Leads (secondary) -- **Key Trends**: Remote work permanence, tool consolidation, AI features -- **Go-to-Market**: PLG motion, free tier, viral invite mechanics - -### Related Workflows - -- **product-brief** - Use research to inform brief -- **prd** (Phase 2) - Research feeds requirements -- **architecture** (Phase 3) - Technical research informs design +**Example (market):** "SaaS project management tool" → TAM $50B, SAM $5B, SOM $50M, top competitors (Asana, Monday), positioning recommendation. --- -## Best Practices for Phase 1 +### product-brief -### 1. Don't Over-Invest in Analysis +**Purpose:** Interactive product brief creation that guides strategic product vision definition. -Analysis workflows are optional for a reason. If you already know what you're building and why, skip to Phase 2 (Planning). +**Agent:** Analyst -### 2. Iterate Between Workflows +**When to Use:** -It's common to: +- Starting new product/major feature initiative +- Aligning stakeholders before detailed planning +- Transitioning from exploration to strategy +- Need executive-level product documentation -1. Run **brainstorm-project** to explore -2. Use **research** to validate -3. Create **product-brief** to synthesize +**Modes:** -### 3. Document Assumptions +- **Interactive Mode** (Recommended): Step-by-step collaborative development with probing questions +- **YOLO Mode**: AI generates complete draft from context, then iterative refinement -Analysis phase is about surfacing and validating assumptions. Document them explicitly so planning can challenge them. +**Key Outputs:** -### 4. Keep It Strategic +- Executive summary +- Problem statement with evidence +- Proposed solution and differentiators +- Target users (segmented) +- MVP scope (ruthlessly defined) +- Financial impact and ROI +- Strategic alignment +- Risks and open questions -Analysis workflows focus on "what" and "why", not "how". Leave implementation details for Planning and Solutioning phases. - -### 5. Involve Stakeholders - -Analysis workflows are collaborative. Use them to align stakeholders before committing to detailed planning. +**Integration:** Feeds directly into PRD workflow (Phase 2). --- -## Decision Guide: Which Analysis Workflow? +### 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 -1. **brainstorm-project** (if unclear solution) → **research** (market/technical) → **product-brief** +``` +brainstorm-project (if unclear) → research (market/technical) → product-brief → Phase 2 (prd) +``` ### Starting a Game Project -1. **brainstorm-game** (if generating concepts) → **research** (market/competitive) → **game-brief** +``` +brainstorm-game (if generating concepts) → research (market/competitive) → game-brief → Phase 2 (gdd) +``` ### Validating an Idea -1. **research** (market type) → **product-brief** or **game-brief** +``` +research (market type) → product-brief or game-brief → Phase 2 +``` -### Technical Decision +### Technical Decision Only -1. **research** (technical type) → Use ADR in **architecture** (Phase 3) +``` +research (technical type) → Use findings in Phase 3 (architecture) +``` ### Understanding Market -1. **research** (market or competitive type) → **product-brief** - -### Generating Deep Research - -1. **research** (deep_prompt type) → External AI research platform → Return with findings +``` +research (market/competitive type) → product-brief → Phase 2 +``` --- ## Integration with Phase 2 (Planning) -Analysis workflows feed directly into Planning: +Analysis outputs feed directly into Planning: | Analysis Output | Planning Input | | --------------------------- | -------------------------- | @@ -689,18 +272,99 @@ Analysis workflows feed directly into Planning: | technical-research.md | **architecture** (Phase 3) | | competitive-intelligence.md | **prd** positioning | -The Planning phase (Phase 2) will load these documents automatically if they exist in the output folder. +Planning workflows automatically load these documents if they exist in the output folder. --- -## Summary +## Best Practices -Phase 1 Analysis workflows are your strategic thinking tools. Use them to: +### 1. Don't Over-Invest in Analysis -- **Explore** problem spaces and solutions -- **Validate** ideas before heavy investment -- **Align** stakeholders on vision -- **Research** markets, competitors, and technologies -- **Document** strategic thinking for future reference +Analysis is optional. If requirements are clear, skip to Phase 2 (Planning). -Remember: **These workflows are optional.** If you know what you're building and why, skip to Phase 2 (Planning) to define requirements and create your PRD/GDD. +### 2. Iterate Between Workflows + +Common pattern: brainstorm → research (validate) → brief (synthesize) + +### 3. Document Assumptions + +Analysis surfaces and validates assumptions. Document them explicitly for planning to challenge. + +### 4. Keep It Strategic + +Focus on "what" and "why", not "how". Leave implementation for Planning and Solutioning. + +### 5. Involve Stakeholders + +Use analysis workflows to align stakeholders before committing to detailed planning. + +--- + +## Common Patterns + +### Greenfield Software (Full Analysis) + +``` +1. brainstorm-project - explore approaches +2. research (market) - 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) + +``` +→ Phase 2: prd or tech-spec directly +``` + +### Technical Research Only + +``` +1. research (technical) - evaluate technologies +2. → Phase 3: architecture (use findings in ADRs) +``` + +--- + +## Related Documentation + +- [Phase 2: Planning Workflows](./workflows-planning.md) - Next phase +- [Phase 3: Solutioning Workflows](./workflows-solutioning.md) +- [Phase 4: Implementation Workflows](./workflows-implementation.md) +- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding project complexity +- [Agents Guide](./agents-guide.md) - Complete agent reference + +--- + +## Troubleshooting + +**Q: Do I need to run all analysis workflows?** +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`. + +**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). + +**Q: How long should Analysis take?** +A: Typically hours to 1-2 days. If taking longer, you may be over-analyzing. Move to Planning. + +**Q: What if I discover problems during Analysis?** +A: That's the point! Analysis helps you fail fast and pivot before heavy planning investment. + +**Q: Should brownfield projects do Analysis?** +A: Usually no. Start with `document-project` (Phase 0), then skip to Planning (Phase 2). + +--- + +_Phase 1 Analysis - Optional strategic thinking before commitment._ diff --git a/src/modules/bmm/docs/workflows-planning.md b/src/modules/bmm/docs/workflows-planning.md index ca830f88..19b32876 100644 --- a/src/modules/bmm/docs/workflows-planning.md +++ b/src/modules/bmm/docs/workflows-planning.md @@ -1,61 +1,77 @@ # 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 that guide implementation. BMM uses a **scale-adaptive planning system** where the workflow automatically selects the right level of detail 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. -**Key principle:** One workflow to rule them all - `plan-project` intelligently routes to the appropriate planning flow based on project characteristics. +**Key principle:** One unified entry point (`workflow-init`) intelligently routes to the appropriate planning methodology - from quick tech-specs to comprehensive PRDs. + +**When to use:** All projects require planning. The system adapts depth automatically based on complexity. --- -## Phase 2 Planning Flow +## Phase 2 Planning Workflow Map ```mermaid %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%% graph TB - Entry["START: plan-project
Discovery and routing"] + Start["START: workflow-init
Discovery + routing"] - subgraph QuickFlow["QUICK FLOW (Levels 0-1)"] - TechSpec["PM: tech-spec
Lightweight spec for simple changes"] + subgraph QuickFlow["QUICK FLOW (Simple Planning)"] + direction TB + TechSpec["PM: tech-spec
Technical document
→ Story or Epic+Stories
1-15 stories typically"] end - subgraph StandardFlow["STANDARD PLANNING (Levels 2-4)"] + subgraph BMadMethod["BMAD METHOD (Recommended)"] + direction TB PRD["PM: prd
Strategic PRD"] - GDD["Game Designer: gdd
Game design document"] + GDD["Game Designer: gdd
Game design doc"] Narrative["Game Designer: narrative
Story-driven design"] - UXDesign["UX Designer: ux
UX-first specification"] - Epics["PM: create-epics-and-stories
Break requirements into epics and stories"] + Epics["PM: create-epics-and-stories
Epic+Stories breakdown
10-50+ stories typically"] + + UXDesign["UX Designer: ux
Optional UX specification"] end - subgraph Updates["STORY UPDATES (Anytime After Epics Created)"] - CorrectCourse["PM/SM: correct-course
Update epics/stories mid-stream"] + subgraph Enterprise["ENTERPRISE METHOD"] + direction TB + EntNote["Uses BMad Method Planning
+
Extended Phase 3 workflows
(Architecture + Security + DevOps)
30+ stories typically"] end - Entry -->|Level 0-1
Simple| QuickFlow - Entry -->|Level 2-4
Software| PRD - Entry -->|Level 2-4
Game| GDD - Entry -->|Level 2-4
Story-driven| Narrative - Entry -->|Level 2-4
UX-first| UXDesign + subgraph Updates["MID-STREAM UPDATES (Anytime)"] + direction LR + CorrectCourse["PM/SM: correct-course
Update requirements/stories"] + end + + Start -->|Bug fix, simple| QuickFlow + Start -->|Software product| PRD + Start -->|Game project| GDD + Start -->|Story-driven| Narrative + Start -->|Enterprise needs| Enterprise PRD --> Epics GDD --> Epics Narrative --> Epics + Epics -.->|Optional| UXDesign UXDesign -.->|May update| Epics - Epics --> Phase3["Phase 3: Architecture"] - Phase3 -.->|May update| Epics - QuickFlow --> Phase4["Phase 4: Implementation"] + Epics --> Phase3["Phase 3: Architecture"] + Enterprise -.->|Uses BMad planning| Epics + Enterprise --> Phase3Ext["Phase 3: Extended
(Arch + Sec + DevOps)"] Phase3 --> Phase4 + Phase3Ext --> Phase4 Phase4 -.->|Significant changes| CorrectCourse CorrectCourse -.->|Updates| Epics - style Entry fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000 + style Start fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000 style QuickFlow fill:#c5e1a5,stroke:#33691e,stroke-width:3px,color:#000 - style StandardFlow fill:#e1bee7,stroke:#6a1b9a,stroke-width:3px,color:#000 - style Updates fill:#ffcdd2,stroke:#c62828,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 @@ -65,324 +81,161 @@ graph TB 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 CorrectCourse fill:#ef5350,stroke:#c62828,stroke-width:2px,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 -| Workflow | Agent | Project Levels | Purpose | -| ---------------------------- | ------------- | -------------- | ---------------------------------------------------- | -| **prd** | PM | 2-4 | Strategic PRD | -| **create-epics-and-stories** | PM | 2-4 | Break PRD/GDD into epics and stories (standalone OK) | -| **tech-spec** | PM | 0-1 | Lightweight technical specification | -| **gdd** | Game Designer | 2-4 (games) | Complete game design document | -| **narrative** | Game Designer | 2-4 (story) | Story-driven game/experience design | -| **ux** | UX Designer | 2-4 (UX-heavy) | UX-first design specification | +| 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 | 10-50+ | +| **gdd** | Game Designer | BMad Method | Game Design Document | 10-50+ | +| **narrative** | Game Designer | BMad Method | Story-driven game/experience design | 10-50+ | +| **create-epics-and-stories** | PM | BMad Method | Break PRD/GDD into Epic+Stories | N/A | +| **ux** | UX Designer | BMad Method | Optional UX specification | N/A | +| **correct-course** | PM/SM | All | Mid-stream requirement changes | N/A | -**Note:** The `plan-project` workflow is your single entry point. It automatically routes to the right planning workflow based on your answers to discovery questions. - -**Critical:** After PRD/GDD/Narrative complete, you must run `create-epics-and-stories` to generate user stories (can be done in same chat or separate chat later). These stories can be updated anytime via UX-Design, Architecture decisions, or `correct-course` during implementation. +**Note:** Story counts are guidance based on typical usage, not strict definitions. --- -## Understanding Scale-Adaptive Planning +## Scale-Adaptive Planning System -### Project Complexity Levels +BMM uses three distinct planning tracks that adapt to project complexity: -BMM categorizes projects into 5 levels (0-4) to determine the appropriate planning detail: +### Track 1: Quick Flow -| Level | Scope | Planning Workflow | Examples | -| ----------- | ----------------------- | -------------------------- | ------------------------------------------------------------ | -| **Level 0** | Single atomic change | **tech-spec** (Quick Spec) | Bug fix, single endpoint, config change | -| **Level 1** | Simple isolated feature | **tech-spec** (Quick Spec) | Add validation rule, new API field, small UI component | -| **Level 2** | Medium feature | **prd** (Lightweight) | User profile page, search feature, data export | -| **Level 3** | Large feature set | **prd** (Standard) | Complete authentication system, admin dashboard | -| **Level 4** | Multi-phase initiative | **prd** (Comprehensive) | Platform migration, new product line, enterprise integration | +**Best For:** Bug fixes, simple features, clear scope, enhancements -### How Scale-Adaptive Planning Works +**Planning:** Tech-spec only → Implementation -**Step 1: Intent Discovery** -The `plan-project` workflow asks you questions to understand: +**Time:** Hours to 1 day -- What are you building? -- How complex is it? -- Is this greenfield or brownfield? -- What are the primary concerns? (features, UX, story, technical architecture) +**Story Count:** Typically 1-15 (guidance) -**Step 2: Intelligent Routing** -Based on your answers, the workflow routes to: +**Documents:** tech-spec.md + story files -- **tech-spec** (Levels 0-1): Quick Spec Flow for simple changes -- **prd** (Levels 2-4): Strategic PRD with epic breakdown -- **gdd** (Levels 2-4, games): Game Design Document -- **narrative** (Levels 2-4, story-heavy): Narrative-first design -- **ux** (Levels 2-4, UX-first): UX specification with prototypes - -**Step 3: Adaptive Detail** -Each workflow adjusts its depth based on level: - -- Level 2: Lightweight documentation -- Level 3: Standard documentation with multiple epics -- Level 4: Comprehensive documentation with phased delivery +**Example:** "Fix authentication bug", "Add OAuth social login" --- -## plan-project (Entry Point) +### Track 2: BMad Method (RECOMMENDED) -### Purpose +**Best For:** Products, platforms, complex features, multiple epics -Single unified entry point for all planning workflows. Uses conversational discovery to understand your project and intelligently route to the appropriate planning flow. +**Planning:** PRD + Architecture → Implementation -**Agent:** PM (orchestrates other agents as needed) -**Phase:** 2 (Planning) -**Required:** Yes (for all projects) +**Time:** 1-3 days -### When to Use +**Story Count:** Typically 10-50+ (guidance) -**Always use this as your planning starting point.** Do not call prd, gdd, narrative, ux, or tech-spec directly unless you explicitly want to skip discovery. +**Documents:** PRD.md (or GDD.md) + architecture.md + epic files + story files -### Process Overview +**Greenfield:** Product Brief (optional) → PRD → UX (optional) → Architecture → Implementation -**Phase 1: Discovery (Steps 1-3)** +**Brownfield:** document-project → PRD → Architecture (recommended) → Implementation -- Understand project context -- Assess complexity level (0-4) -- Identify primary concerns (features, UX, story, technical) +**Example:** "Customer dashboard", "E-commerce platform", "Add search to existing app" -**Phase 2: Routing Decision (Step 4)** - -- Determine target workflow -- Explain routing rationale -- Confirm with user - -**Phase 3: Execute Target Workflow (Steps 5-6)** - -- Invoke appropriate planning workflow -- Pass context and decisions -- Return to plan-project for completion - -**Phase 4: Handoff (Step 7)** - -- Document planning decisions -- Recommend next phase workflows -- Update workflow status - -### Discovery Questions - -**Project Type:** - -- What are you building? (software product, game, internal tool, etc.) -- Is this greenfield (new) or brownfield (existing)? - -**Complexity Assessment:** - -- How would you describe the scope? (single change, simple feature, medium feature, large feature set, multi-phase initiative) -- How many user-facing features are involved? -- How many systems or integrations are affected? - -**Primary Concerns:** - -- What's most important for this project? (feature functionality, user experience, narrative/story, technical architecture, performance) - -**Special Characteristics:** - -- Is this a game project? -- Is storytelling central to the experience? -- Is UX innovation the primary differentiator? -- Are there unique technical constraints? - -### Routing Logic - -``` -IF game_project AND level >= 2: - → Route to gdd - -ELSE IF story_central AND level >= 2: - → Route to narrative - -ELSE IF ux_innovation AND level >= 2: - → Route to ux - -ELSE IF level <= 1: - → Route to tech-spec (Quick Spec Flow) - -ELSE: - → Route to prd (with level-appropriate depth) -``` - -### Outputs - -- Planning decision document (routing rationale) -- Output from target workflow (PRD, GDD, Tech Spec, etc.) -- Handoff recommendations for Phase 3 - -### Example Scenarios - -**Scenario 1: Bug Fix** - -- **Input**: "Fix null pointer exception in user service" -- **Discovery**: Level 0 (single atomic change) -- **Route**: tech-spec (Quick Spec Flow) - -**Scenario 2: E-commerce Checkout** - -- **Input**: "Build complete checkout flow with payment processing" -- **Discovery**: Level 3 (large feature set), feature-focused -- **Route**: prd (Standard depth) - -**Scenario 3: Roguelike Card Game** - -- **Input**: "Roguelike card battler with emotional narrative" -- **Discovery**: Level 3 (large feature set), game project -- **Route**: gdd - -**Scenario 4: Story-Driven Adventure** - -- **Input**: "Narrative adventure game with branching story" -- **Discovery**: Level 3, story-central -- **Route**: narrative (then gdd for mechanics) +**Why Architecture for Brownfield?** Distills massive codebase context into focused solution design for your specific project. --- -## tech-spec (Quick Spec Flow) +### Track 3: Enterprise Method -### Purpose +**Best For:** Enterprise requirements, multi-tenant, compliance, security-sensitive -Lightweight technical specification for Levels 0-1 projects (single changes, simple features). Focuses on implementation details without heavy strategic planning. +**Planning (Phase 2):** Uses BMad Method planning (PRD + Epic+Stories) -**Agent:** Architect -**Phase:** 2 (Planning) -**Project Levels:** 0-1 +**Solutioning (Phase 3):** Extended workflows (Architecture + Security + DevOps + SecOps as optional additions) -### When to Use +**Time:** 3-7 days total (1-3 days planning + 2-4 days extended solutioning) + +**Story Count:** Typically 30+ (but defined by enterprise needs) + +**Documents Phase 2:** PRD.md + epics + epic files + story files + +**Documents Phase 3:** architecture.md + security-architecture.md (optional) + devops-strategy.md (optional) + secops-strategy.md (optional) + +**Example:** "Multi-tenant SaaS", "HIPAA-compliant portal", "Add SOC2 audit logging" + +--- + +## How Track Selection Works + +`workflow-init` guides you through educational choice: + +1. **Description Analysis** - Analyzes project description for complexity +2. **Educational Presentation** - Shows all three tracks with trade-offs +3. **Recommendation** - Suggests track based on keywords and context +4. **User Choice** - You select the track that fits + +The system guides but never forces. You can override recommendations. + +--- + +## Workflow Descriptions + +### workflow-init (Entry Point) + +**Purpose:** Single unified entry point for all planning. Discovers project needs and intelligently routes to appropriate track. + +**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. + +**Process:** + +1. Discovery (understand context, assess complexity, identify concerns) +2. Routing Decision (determine track, explain rationale, confirm) +3. Execute Target Workflow (invoke planning workflow, pass context) +4. Handoff (document decisions, recommend next phase) + +--- + +### tech-spec (Quick Flow) + +**Purpose:** Lightweight technical specification for simple changes (Quick Flow track). Produces technical document and story or epic+stories structure. + +**Agent:** PM + +**When to Use:** - Bug fixes - Single API endpoint additions - Configuration changes - Small UI component additions - Isolated validation rules -- Single-file modifications -**When NOT to use:** +**Key Outputs:** -- Multiple interconnected changes → Use **prd** -- User-facing feature with multiple screens → Use **prd** -- Requires epic breakdown → Use **prd** +- **tech-spec.md** - Technical document containing: + - Problem statement and solution + - Source tree changes + - Implementation details + - Testing strategy + - Acceptance criteria +- **Story file(s)** - Single story OR epic+stories structure (1-15 stories typically) -### Process Overview +**Skip To Phase:** 4 (Implementation) - no Phase 3 architecture needed -**Step 1: Problem Definition** - -- What's broken or missing? -- What's the desired behavior? -- What are the constraints? - -**Step 2: Technical Analysis** - -- Current state assessment -- Root cause (if bug) -- Dependencies identified - -**Step 3: Solution Design** - -- Implementation approach -- Code changes required -- Test strategy -- Rollback plan - -**Step 4: Documentation** - -- Quick Spec document generated -- Handoff to implementation - -### Inputs - -- Problem description or feature request -- Current codebase context (if brownfield) -- Technical constraints -- Acceptance criteria (simple) - -### Outputs - -**Primary Output:** `tech-spec-{feature-name}-{date}.md` - -**Document Structure:** - -1. Problem Statement -2. Current State Analysis -3. Proposed Solution -4. Implementation Details - - Files to modify - - API changes - - Database changes (if any) - - Configuration changes -5. Test Strategy -6. Rollback Plan -7. Acceptance Criteria -8. Risk Assessment (lightweight) - -### Example Output - -**Problem:** Null pointer exception when user has no profile image - -**Solution:** - -```markdown -# Quick Spec: Fix Profile Image Null Pointer - -## Problem - -Users without profile images cause NPE in UserProfileService.java:line 42 - -## Root Cause - -Method assumes profileImageUrl is never null, but DB allows NULL - -## Solution - -1. Add null check in UserProfileService -2. Return default placeholder image URL -3. Add unit test for null case - -## Implementation - -- File: `UserProfileService.java` -- Change: Add null guard: `if (user.profileImageUrl == null) return DEFAULT_AVATAR_URL;` -- Test: `UserProfileServiceTest.java` - new test case -- No DB migration needed - -## Acceptance Criteria - -- AC-1: Users with null profile image see default avatar -- AC-2: No NPE in logs -- AC-3: Unit test passes - -## Risk: LOW - -- Isolated change, single method -- Backward compatible -``` - -### Related Workflows - -- **dev-story** (Phase 4) - Implement the spec -- **prd** - Use for more complex features +**Example:** "Fix null pointer when user has no profile image" → Single file change, null check, unit test, no DB migration. --- -## prd (Product Requirements Document) +### prd (Product Requirements Document) -### Purpose - -Strategic PRD with tactical epic breakdown for Levels 2-4 projects. Unified workflow that adapts depth based on project complexity. +**Purpose:** Strategic PRD with epic breakdown for software products (BMad Method track). **Agent:** PM (with Architect and Analyst support) -**Phase:** 2 (Planning) -**Project Levels:** 2-4 -### When to Use +**When to Use:** - Medium to large feature sets - Multi-screen user experiences @@ -390,689 +243,288 @@ Strategic PRD with tactical epic breakdown for Levels 2-4 projects. Unified work - Multiple system integrations - Phased delivery required -### Scale-Adaptive Structure +**Scale-Adaptive Structure:** -**Level 2 (Lightweight PRD):** +- **Light:** Single epic, 5-10 stories, simplified analysis (10-15 pages) +- **Standard:** 2-4 epics, 15-30 stories, comprehensive analysis (20-30 pages) +- **Comprehensive:** 5+ epics, 30-50+ stories, multi-phase, extensive stakeholder analysis (30-50+ pages) -- Single epic with 5-10 stories -- Simplified competitive analysis -- Basic technical considerations -- 10-15 pages +**Key Outputs:** -**Level 3 (Standard PRD):** +- PRD.md (complete requirements) +- epics.md (epic breakdown) +- Epic files (epic-1-_.md, epic-2-_.md, etc.) -- 2-4 epics with 15-30 stories -- Comprehensive competitive analysis -- Detailed technical requirements -- Risk assessment -- 20-30 pages +**Integration:** Feeds into Architecture (Phase 3) -**Level 4 (Comprehensive PRD):** - -- 5+ epics with 30-50+ stories -- Multi-phase delivery plan -- Enterprise architecture considerations -- Extensive stakeholder analysis -- Success metrics framework -- 30-50+ pages - -### Process Overview - -**Phase 1: Strategic Foundation (Steps 1-4)** - -- Problem and opportunity definition -- User research and personas -- Competitive analysis -- Success criteria and metrics - -**Phase 2: Solution Definition (Steps 5-8)** - -- Core capabilities and features -- User experience principles -- Technical requirements -- Integration points - -**Phase 3: Epic Breakdown (Steps 9-12)** - -- Identify epics (level-appropriate count) -- Define user stories per epic -- Prioritize stories (P0/P1/P2/P3) -- Sequence for delivery - -**Phase 4: Planning and Risks (Steps 13-15)** - -- Resource estimation -- Risk assessment -- Assumptions and dependencies -- Success metrics finalized - -**Phase 5: Documentation (Step 16)** - -- Generate final PRD -- Create epic files -- Handoff preparation - -### Inputs - -Optional: - -- product-brief.md (from Phase 1) -- market-research.md (from Phase 1) -- competitive-analysis.md (from Phase 1) -- User input through conversational process - -### Outputs - -**Primary Outputs:** - -1. **PRD.md**: Complete product requirements document -2. **epics.md**: All epics with story breakdown -3. **Epic Files**: Individual files per epic (e.g., `epic-1-authentication.md`) - -**PRD Structure:** - -1. Executive Summary -2. Problem Statement (with evidence) -3. Goals and Success Metrics -4. User Personas and Scenarios -5. Competitive Landscape -6. Feature Requirements - - Core capabilities - - User stories (organized by epic) - - Acceptance criteria -7. User Experience Requirements -8. Technical Requirements -9. Integration Requirements -10. Non-Functional Requirements (NFRs) -11. Assumptions and Constraints -12. Risks and Mitigation -13. Success Metrics -14. Glossary - -**Epic File Structure:** - -- Epic overview and objectives -- User stories with acceptance criteria -- Story priorities (P0/P1/P2/P3) -- Dependencies and sequencing -- Technical notes -- Success criteria - -### Example: Level 3 PRD for E-commerce Checkout - -**Strategic Section:** - -- **Problem**: 68% cart abandonment rate vs 45% industry average -- **Goal**: Reduce abandonment to 50% in 6 months -- **Users**: Primary (buyers), Secondary (guest checkout) -- **Competitors**: Shopify (1-click), Amazon (save payment) - -**Epic Breakdown:** - -1. **Epic 1: Guest Checkout** (7 stories) - - P0: Guest can checkout without account - - P1: Email receipt sent - - P2: Optional account creation -2. **Epic 2: Payment Processing** (8 stories) - - P0: Credit card integration (Stripe) - - P1: Saved payment methods - - P2: Alternative payments (PayPal, Apple Pay) -3. **Epic 3: Order Management** (6 stories) - - P0: Order confirmation - - P1: Order history - - P2: Order tracking - -**Total:** 3 epics, 21 stories, 4-6 week delivery - -### Related Workflows - -- **product-brief** (Phase 1) - Strategic input -- **architecture** (Phase 3) - Technical design -- **tech-spec** (Phase 3) - Detailed specifications -- **create-epics-and-stories** (Phase 4) - If manual epic creation needed +**Example:** E-commerce checkout → 3 epics (Guest Checkout, Payment Processing, Order Management), 21 stories, 4-6 week delivery. --- -## gdd (Game Design Document) +### gdd (Game Design Document) -### Purpose +**Purpose:** Complete game design document for game projects (BMad Method track). -Complete game design document for Levels 2-4 game projects, adapted from industry-standard GDD formats with practical scoping. +**Agent:** Game Designer -**Agent:** PM (Game Designer persona) -**Phase:** 2 (Planning) -**Project Levels:** 2-4 (games) +**When to Use:** -### When to Use - -- Designing a game (any genre) +- Designing any game (any genre) - Need comprehensive design documentation - Team needs shared vision - Publisher/stakeholder communication -### Comparison to Traditional GDD +**BMM GDD vs Traditional:** -**Traditional GDD Weaknesses:** - -- Too detailed too early -- Assumes waterfall delivery -- No connection to implementation tracking -- No epic/story breakdown - -**BMM GDD Improvements:** - -- Scale-adaptive detail +- Scale-adaptive detail (not waterfall) - Agile epic structure -- Direct handoff to implementation (Phase 4) +- Direct handoff to implementation - Integrated with testing workflows -### Process Overview +**Key Outputs:** -**Phase 1: Core Concept (Steps 1-4)** +- GDD.md (complete game design) +- Epic breakdown (Core Loop, Content, Progression, Polish) -- High concept and elevator pitch -- Core gameplay loop -- Design pillars -- Player experience goals +**Integration:** Feeds into Architecture (Phase 3) -**Phase 2: Game Systems (Steps 5-10)** - -- Mechanics definition -- Progression systems -- Economy and balance -- Combat/interaction systems -- Level/world design -- Art and audio direction - -**Phase 3: Content Scope (Steps 11-13)** - -- Content volume (levels, characters, items) -- Narrative overview (if applicable) -- Monetization strategy (if F2P/premium) - -**Phase 4: Technical and Production (Steps 14-16)** - -- Platform and technical requirements -- Team and timeline -- Risks and challenges -- Success metrics - -**Phase 5: Epic Breakdown (Step 17)** - -- Convert design into epics -- Create user stories per epic -- Prioritize features (MVP vs post-launch) -- Sequence delivery - -### Inputs - -Optional: - -- game-brief.md (from Phase 1) -- brainstorm-game results (from Phase 1) -- market-research.md (from Phase 1) -- Reference game analysis - -### Outputs - -**Primary Output:** `GDD-{game-name}-{date}.md` - -**GDD Structure:** - -1. Executive Summary -2. Core Concept - - High concept - - Elevator pitch - - Design pillars -3. Gameplay - - Core loop - - Mechanics - - Player actions - - Progression -4. Game Systems - - Combat/interaction - - Economy - - Progression - - Customization -5. World and Narrative - - Setting - - Story (if applicable) - - Characters -6. Content Scope - - Levels/missions - - Characters/enemies - - Items/abilities - - Estimated play time -7. Art Direction -8. Audio Direction -9. User Interface/UX -10. Technical Requirements -11. Platforms and Performance -12. Monetization (if applicable) -13. Epic Breakdown -14. Success Metrics -15. Risks and Mitigations - -**Epic Breakdown** (unique to BMM GDD): - -- **Epic 1: Core Loop** (foundational mechanics) -- **Epic 2: Content** (levels, enemies, items) -- **Epic 3: Progression** (unlocks, upgrades) -- **Epic 4: Polish** (VFX, audio, UI) - -### Example: Level 3 GDD for Roguelike Card Game - -**Core Concept:** - -- **High Concept**: Slay the Spire meets Hades with emotional narrative -- **Elevator Pitch**: Roguelike card battler where you play as emotions fighting inner demons -- **Design Pillars**: Strategic depth, emotional resonance, replayability - -**Gameplay:** - -- **Core Loop**: Draw cards → Play cards → Resolve combat → Choose path → Repeat -- **Progression**: Unlock new cards, characters, and story branches -- **Run Length**: 45-60 minutes per run - -**Content Scope:** - -- 3 playable characters (Anger, Fear, Joy) -- 120 cards total (40 per character) -- 50 enemy types -- 10 bosses -- 4 zones (acts) - -**Epic Breakdown:** - -1. **Epic 1: Core Combat** (8 stories) - - P0: Card playing and resolution - - P0: Enemy AI - - P1: Card effects and combos -2. **Epic 2: Meta Progression** (6 stories) - - P0: Unlock system - - P1: Character progression -3. **Epic 3: Content** (12 stories) - - P1: Character 1 (Anger) complete - - P1: Character 2 (Fear) complete - - P2: Character 3 (Joy) complete - -**Estimated Timeline:** 12 months with 3-person team - -### Related Workflows - -- **game-brief** (Phase 1) - Strategic input -- **narrative** (Phase 2) - If story-heavy game -- **architecture** (Phase 3) - Technical design +**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) +### narrative (Narrative Design) -### Purpose +**Purpose:** Story-driven design workflow for games/experiences where narrative is central (BMad Method track). -Story-driven design workflow for games and experiences where narrative is central. Creates comprehensive narrative documentation including story structure, character arcs, dialogue systems, and narrative implementation guidance. +**Agent:** Game Designer (Narrative Designer persona) + Creative Problem Solver (CIS) -**Agent:** PM (Narrative Designer persona) + Creative Problem Solver (CIS) -**Phase:** 2 (Planning) -**Project Levels:** 2-4 (story-driven projects) +**When to Use:** -### When to Use - -- Story is central to the experience +- Story is central to experience - Branching narrative with player choices - Character-driven games - Visual novels, adventure games, RPGs -- Interactive fiction -**When to combine with GDD:** +**Combine with GDD:** -1. Run **narrative** workflow first (get story structure) -2. Then run **gdd** workflow (integrate story with gameplay) +1. Run `narrative` first (story structure) +2. Then run `gdd` (integrate story with gameplay) -### Process Overview - -**Phase 1: Story Foundation (Steps 1-4)** - -- Story premise and themes -- Setting and world-building -- Narrative structure (linear, branching, open) -- Tone and emotional beats - -**Phase 2: Character Development (Steps 5-7)** - -- Protagonist and supporting cast -- Character arcs and motivations -- Relationships and dynamics - -**Phase 3: Story Structure (Steps 8-11)** - -- Act breakdown (3-act, 5-act, hero's journey) -- Key narrative beats -- Choice points and consequences -- Branching paths (if applicable) - -**Phase 4: Dialogue and Implementation (Steps 12-15)** +**Key Outputs:** +- narrative-design.md (complete narrative spec) +- Story structure (acts, beats, branching) +- Characters (profiles, arcs, relationships) - Dialogue system design -- Voice and writing style -- Narrative implementation approach -- Asset requirements (VO, cutscenes, etc.) +- Implementation guide -**Phase 5: Integration Planning (Step 16)** +**Integration:** Combine with GDD, then feeds into Architecture (Phase 3) -- How narrative integrates with gameplay -- Pacing and player agency -- Narrative-gameplay harmony - -### Inputs - -Optional: - -- Story outlines or treatments -- Character sketches -- World-building documents -- Reference stories - -### Outputs - -**Primary Output:** `narrative-design-{project-name}-{date}.md` - -**Document Structure:** - -1. Narrative Overview - - Premise - - Themes - - Tone -2. Story Structure - - Act breakdown - - Key beats - - Branching diagram (if applicable) -3. Characters - - Character profiles - - Arcs - - Relationships -4. World-Building - - Setting - - Lore - - History -5. Dialogue System - - Dialogue structure - - Choice mechanics - - Consequence tracking -6. Implementation Guide - - Narrative assets needed - - Integration with gameplay - - Technical requirements -7. Narrative Content Scope - - Total word count - - Number of scenes/beats - - Number of endings (if branching) - - VO line count (if voiced) - -### Example: Level 3 Narrative for Choice-Driven RPG - -**Story Premise:** -You play as a wandering medic in a post-apocalyptic world where healing is outlawed. Each patient you treat changes the world. - -**Structure:** - -- 3 acts, 12 chapters -- 5 major choice points with persistent consequences -- 3 possible endings (altruistic, pragmatic, corrupted) - -**Characters:** - -- **Protagonist**: Dr. Elara Chen (complex moral compass) -- **Antagonist**: The Overseer (believes healing prolongs suffering) -- **Supporting**: 8 recurring characters - -**Branching:** - -``` -Chapter 1 → Choice: Save child or save supplies - ├─ Save child → Village trusts you (Path A) - └─ Save supplies → Village fears you (Path B) - -Chapter 5 → Paths converge, new choice: Reveal or hide ability - ├─ Reveal → Public hero route - └─ Hide → Underground resistance route -``` - -**Implementation:** - -- Total word count: ~60,000 words -- 40 narrative scenes -- 15 hours of gameplay -- 200+ dialogue nodes -- Optional VO (2,000 lines) - -**Epic Breakdown:** - -1. **Epic 1: Act 1 Narrative** (6 stories) -2. **Epic 2: Act 2 Narrative** (8 stories) -3. **Epic 3: Act 3 Narrative** (7 stories) -4. **Epic 4: Branching Implementation** (5 stories) - -### Related Workflows - -- **gdd** (Phase 2) - Combine narrative with gameplay -- **ux** (Phase 2) - Narrative UI/UX design +**Example:** Choice-driven RPG → 3 acts, 12 chapters, 5 choice points, 3 endings, 60K words, 40 narrative scenes. --- -## ux (UX-First Design) +### ux (UX-First Design) -### Purpose - -UX specification workflow for projects where user experience is the primary differentiator or innovation area. Facilitates visual exploration and informed decision-making rather than template-driven design. +**Purpose:** UX specification for projects where user experience is the primary differentiator (BMad Method track). **Agent:** UX Designer -**Phase:** 2 (Planning) -**Project Levels:** 2-4 (UX-heavy projects) -### When to Use +**When to Use:** -- UX is the primary competitive advantage +- UX is primary competitive advantage - Complex user workflows needing design thinking - Innovative interaction patterns - Design system creation - Accessibility-critical experiences -**When NOT to use:** +**Collaborative Approach:** -- Standard CRUD interfaces → Use **prd** -- Gameplay-first games → Use **gdd** -- Backend-focused APIs → Use **tech-spec** +1. Visual exploration (generate multiple options) +2. Informed decisions (evaluate with user needs) +3. Collaborative design (refine iteratively) +4. Living documentation (evolves with project) -### Collaborative UX Design Approach +**Key Outputs:** -**This is NOT a template filler.** The UX workflow facilitates: - -1. **Visual Exploration**: Generate multiple design options -2. **Informed Decisions**: Evaluate options with user needs -3. **Collaborative Design**: Work with AI to refine iteratively -4. **Living Documentation**: UX spec evolves with project - -### Process Overview - -**Phase 1: UX Foundation (Steps 1-4)** - -- User research and personas -- User journeys and workflows -- Pain points and opportunities -- UX principles and goals - -**Phase 2: Design Exploration (Steps 5-8)** - -- Generate multiple design directions +- ux-spec.md (complete UX specification) +- User journeys - Wireframes and mockups -- Interaction patterns -- Visual design options +- Interaction specifications +- Design system (components, patterns, tokens) +- Epic breakdown (UX stories) -**Phase 3: Design Refinement (Steps 9-12)** +**Integration:** Feeds PRD or updates epics, then Architecture (Phase 3) -- Collaborative iteration -- Accessibility validation -- Responsive design considerations -- Component library definition - -**Phase 4: Specification (Steps 13-15)** - -- Detailed interaction specs -- Design system documentation -- Handoff to development -- Epic breakdown with UX stories - -### Inputs - -Optional: - -- User research data -- Analytics and heatmaps -- Competitor UX analysis -- Brand guidelines -- Accessibility requirements - -### Outputs - -**Primary Output:** `ux-spec-{project-name}-{date}.md` - -**Document Structure:** - -1. UX Vision and Principles -2. User Research Summary -3. User Journeys -4. Information Architecture -5. Wireframes and Mockups -6. Interaction Specifications - - Screen-by-screen flows - - Micro-interactions - - Error states - - Loading states -7. Design System - - Components - - Patterns - - Tokens (colors, typography, spacing) -8. Accessibility Requirements -9. Responsive Behavior -10. Epic Breakdown (UX Stories) - -### Example: Level 3 UX Spec for Dashboard Redesign - -**UX Vision:** -"Information at a glance with progressive disclosure" - -**User Journey:** - -1. User lands on dashboard -2. Scans key metrics (glanceable) -3. Drills into details (progressive disclosure) -4. Takes action (in-context controls) - -**Wireframes Generated:** - -- Option A: Card-based layout (familiar, modular) -- Option B: Single-column feed (mobile-first) -- Option C: Split-pane (power user) - -**Decision:** Option A (card-based) with Option C (split-pane) for power users via toggle - -**Design System:** - -- 5 card components (metric, chart, table, activity, action) -- 12 color tokens (accessible contrast ratios) -- Responsive grid (12-column) - -**Epic Breakdown:** - -1. **Epic 1: Core Layout** (4 stories) - - P0: Responsive grid system - - P0: Card component library -2. **Epic 2: Data Visualization** (6 stories) - - P1: Chart components - - P1: Real-time updates -3. **Epic 3: Accessibility** (3 stories) - - P0: Keyboard navigation - - P1: Screen reader support - -### Related Workflows - -- **prd** (Phase 2) - UX spec feeds feature requirements -- **architecture** (Phase 3) - Frontend architecture decisions +**Example:** Dashboard redesign → Card-based layout with split-pane toggle, 5 card components, 12 color tokens, responsive grid, 3 epics (Layout, Visualization, Accessibility). --- -## Decision Guide: Which Planning Workflow? +### create-epics-and-stories -### Use `plan-project` (Recommended) +**Purpose:** Break PRD/GDD requirements into bite-sized stories organized in epics (BMad Method track). -Let the workflow discover your needs and route appropriately. +**Agent:** PM -### Direct Workflow Selection (Advanced) +**When to Use:** -**For bug fixes or single changes:** -→ **tech-spec** (Quick Spec Flow) +- After PRD/GDD complete (often run automatically) +- Can also run standalone later to re-generate epics/stories +- When planning story breakdown outside main PRD workflow -**For software products (Levels 2-4):** -→ **prd** +**Key Outputs:** -**For games (Levels 2-4):** -→ **gdd** (if gameplay-first) -→ **narrative** + **gdd** (if story-first) +- epics.md (all epics with story breakdown) +- Epic files (epic-1-\*.md, etc.) -**For story-driven experiences (non-games):** -→ **narrative** + **prd** +**Note:** PRD workflow often creates epics automatically. This workflow can be run standalone if needed later. -**For UX-first projects:** -→ **ux** + **prd** +--- + +### correct-course + +**Purpose:** Handle significant requirement changes during implementation (all tracks). + +**Agent:** PM, Architect, or SM + +**When to Use:** + +- Priorities change mid-project +- New requirements emerge +- Scope adjustments needed +- Technical blockers require replanning + +**Process:** + +1. Analyze impact of change +2. Propose solutions (continue, pivot, pause) +3. Update affected documents (PRD, epics, stories) +4. Re-route for implementation + +**Integration:** Updates planning artifacts, may trigger architecture review + +--- + +## Decision Guide + +### Which Planning Workflow? + +**Use `workflow-init` (Recommended):** Let the system discover needs and route appropriately. + +**Direct Selection (Advanced):** + +- **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) +- **Enterprise with compliance** → Choose track in `workflow-init` → Enterprise Method --- ## Integration with Phase 3 (Solutioning) -Planning workflows produce requirements that feed into Solutioning: +Planning outputs feed into Solutioning: -| Planning Output | Solutioning Input | -| -------------------- | ------------------------------------- | -| PRD.md | **architecture** workflow (Level 3-4) | -| epics.md | **tech-spec** workflow (Level 3-4) | -| GDD.md | **architecture** workflow (game tech) | -| narrative-design.md | **architecture** (narrative systems) | -| ux-spec.md | **architecture** (frontend design) | -| tech-spec.md (Quick) | **dev-story** (Level 0-1) | +| 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) | -**Key Decision Point:** +**Key Decision Points:** -- **Levels 0-1**: Skip Solutioning, go directly to Phase 4 (Implementation) -- **Levels 2**: Optional Solutioning (simple architecture) -- **Levels 3-4**: **Required** Solutioning (architecture + tech-spec) +- **Quick Flow:** Skip Phase 3 entirely → Phase 4 (Implementation) +- **BMad Method:** Optional Phase 3 (simple), Required Phase 3 (complex) +- **Enterprise:** Required Phase 3 (architecture + extended planning) See: [workflows-solutioning.md](./workflows-solutioning.md) --- -## Best Practices for Phase 2 +## Best Practices -### 1. Always Start with `plan-project` +### 1. Always Start with workflow-init -Unless you're absolutely certain which workflow you need, use the entry point. It will save time and ensure you get the right level of detail. +Let the entry point guide you. It prevents over-planning simple features or under-planning complex initiatives. -### 2. Level Honestly +### 2. Trust the Recommendation -Don't over-plan simple features or under-plan complex initiatives. Be honest about project complexity. +If `workflow-init` suggests BMad Method, there's likely complexity you haven't considered. Review carefully before overriding. ### 3. Iterate on Requirements -Planning documents are living. You can refine PRDs/GDDs as you learn more during Solutioning and Implementation. +Planning documents are living. Refine PRDs/GDDs as you learn during Solutioning and Implementation. ### 4. Involve Stakeholders Early -Review PRDs/GDDs with stakeholders before proceeding to Solutioning. Catch misalignment early. +Review PRDs/GDDs with stakeholders before Solutioning. Catch misalignment early. ### 5. Focus on "What" Not "How" Planning defines **what** to build and **why**. Leave **how** (technical design) to Phase 3 (Solutioning). +### 6. Document-Project First for Brownfield + +Always run `document-project` before planning brownfield projects. AI agents need existing codebase context. + +--- + +## Common Patterns + +### Greenfield Software (BMad Method) + +``` +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 +``` + +### Brownfield Software (BMad Method) + +``` +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) +``` + +### Bug Fix (Quick Flow) + +``` +1. workflow-init → routes to tech-spec +2. Architect: 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) + +``` +1. (Recommended) Analysis: research (compliance, security) +2. workflow-init → routes to Enterprise Method +3. PM: prd workflow +4. (Optional) UX Designer: ux workflow +5. PM: create-epics-and-stories +6. → Phase 3: architecture + security + devops + test strategy +``` + --- ## Common Anti-Patterns @@ -1080,46 +532,70 @@ Planning defines **what** to build and **why**. Leave **how** (technical design) ### ❌ Skipping Planning "We'll just start coding and figure it out." -→ **Result**: Scope creep, rework, missed requirements +**Result:** Scope creep, rework, missed requirements ### ❌ Over-Planning Simple Changes "Let me write a 20-page PRD for this button color change." -→ **Result**: Wasted time, analysis paralysis +**Result:** Wasted time, analysis paralysis ### ❌ Planning Without Discovery "I already know what I want, skip the questions." -→ **Result**: Solving wrong problem, missing opportunities +**Result:** Solving wrong problem, missing opportunities ### ❌ Treating PRD as Immutable "The PRD is locked, no changes allowed." -→ **Result**: Ignoring new information, rigid planning +**Result:** Ignoring new information, rigid planning ### ✅ Correct Approach -- Use scale-adaptive planning (right level for complexity) +- Use scale-adaptive planning (right depth for complexity) - Involve stakeholders in review - Iterate as you learn - Keep planning docs living and updated +- Use `correct-course` for significant changes --- -## Summary +## Related Documentation -Phase 2 Planning workflows transform vision into actionable requirements: +- [Phase 1: Analysis Workflows](./workflows-analysis.md) - Optional discovery phase +- [Phase 3: Solutioning Workflows](./workflows-solutioning.md) - Next phase +- [Phase 4: Implementation Workflows](./workflows-implementation.md) +- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding the three tracks +- [Quick Spec Flow](./quick-spec-flow.md) - Quick Flow track details +- [Agents Guide](./agents-guide.md) - Complete agent reference -| Input | Planning Workflow | Output | -| ----------------- | ----------------- | ---------------- | -| Product idea | **prd** | PRD + Epics | -| Game concept | **gdd** | GDD + Epics | -| Story idea | **narrative** | Narrative Design | -| UX innovation | **ux** | UX Specification | -| Bug/simple change | **tech-spec** | Quick Spec | +--- -**Key Takeaway:** Planning is **required** for all projects, but the **depth adapts** to project complexity. Trust the scale-adaptive system to guide the right level of detail. +## Troubleshooting -**Next Phase:** Solutioning (Phase 3) - Technical architecture and detailed specifications +**Q: Which workflow should I run first?** +A: Run `workflow-init`. It analyzes your project and routes to the right planning workflow. -See: [workflows-solutioning.md](./workflows-solutioning.md) +**Q: Do I always need a PRD?** +A: No. Simple changes use `tech-spec` (Quick Flow). Only BMad Method and Enterprise tracks create PRDs. + +**Q: Can I skip Phase 3 (Solutioning)?** +A: Yes for Quick Flow. Optional for BMad Method (simple projects). Required for BMad Method (complex projects) and Enterprise. + +**Q: How do I know which track to choose?** +A: Use `workflow-init` - it recommends based on your description. Story counts are guidance, not definitions. + +**Q: What if requirements change mid-project?** +A: Run `correct-course` workflow. It analyzes impact and updates planning artifacts. + +**Q: Do brownfield projects need architecture?** +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. + +**Q: Should I use product-brief before PRD?** +A: Optional but recommended for greenfield. Helps strategic thinking. `workflow-init` offers it based on context. + +--- + +_Phase 2 Planning - Scale-adaptive requirements for every project._ diff --git a/src/modules/bmm/docs/workflows-solutioning.md b/src/modules/bmm/docs/workflows-solutioning.md index 5f54991d..875301ff 100644 --- a/src/modules/bmm/docs/workflows-solutioning.md +++ b/src/modules/bmm/docs/workflows-solutioning.md @@ -1,83 +1,120 @@ # 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 is **required for Levels 3-4** and **optional for Level 2** projects. +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. -**Key principle:** Prevent agent conflicts by making architectural decisions explicit and documented before implementation begins. +**Key principle:** Make technical decisions explicit and documented so all agents implement consistently. Prevent one agent choosing REST while another chooses GraphQL. + +**Required for:** BMad Method (complex projects), Enterprise Method + +**Optional for:** BMad Method (simple projects), Quick Flow (skip entirely) --- -## Phase 3 Solutioning Flow +## Phase 3 Solutioning Workflow Map ```mermaid %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%% graph TB - FromPRD["FROM Phase 2
PRD/GDD/Narrative/UX complete"] + FromPlanning["FROM Phase 2 Planning
PRD/GDD/Tech-Spec complete"] - subgraph Solutioning["PHASE 3: SOLUTIONING"] + subgraph QuickFlow["QUICK FLOW PATH"] direction TB - Architecture["Architect: architecture
Technical design and decisions"] - GateCheck["Architect: solutioning-gate-check
Validation before implementation"] + SkipArch["Skip Phase 3
Go directly to Implementation"] end - subgraph Optional["OPTIONAL PATHS"] + subgraph BMadEnterprise["BMAD METHOD + ENTERPRISE (Same Start)"] + direction TB + Architecture["Architect: architecture
System design + ADRs"] + + subgraph Optional["ENTERPRISE ADDITIONS (Optional)"] + direction LR + TestArch["TEA: test-architecture
(Future)"] + SecArch["Architect: security-architecture"] + DevOps["Architect: devops-strategy"] + end + + GateCheck["Architect: solutioning-gate-check
Validation before Phase 4"] + + Architecture -.->|Enterprise only| Optional + Architecture --> GateCheck + Optional -.-> GateCheck + end + + subgraph Result["GATE CHECK RESULTS"] direction LR - Level2Skip["Level 2:
Skip if straightforward"] + Pass["✅ PASS
Proceed to Phase 4"] + Concerns["⚠️ CONCERNS
Proceed with caution"] + Fail["❌ FAIL
Resolve issues first"] end - FromPRD --> Architecture - Architecture --> GateCheck - GateCheck -->|PASS| Phase4["Phase 4: Implementation"] - GateCheck -->|CONCERNS/FAIL| Architecture - FromPRD -.->|Level 2 only| Level2Skip - Level2Skip -.-> Phase4 + FromPlanning -->|Quick Flow| QuickFlow + FromPlanning -->|BMad Method
or Enterprise| Architecture - style FromPRD fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px,color:#000 - style Solutioning fill:#90caf9,stroke:#0d47a1,stroke-width:3px,color:#000 - style Optional fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000 + 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 Architecture fill:#64b5f6,stroke:#0d47a1,stroke-width:2px,color:#000 - style GateCheck fill:#64b5f6,stroke:#0d47a1,stroke-width:2px,color:#000 - style Level2Skip fill:#fff59d,stroke:#f57f17,stroke-width:2px,color:#000 + style SkipArch fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000 + style Architecture fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000 + style TestArch fill:#ef9a9a,stroke:#c62828,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 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 ``` --- ## Quick Reference -| Workflow | Project Levels | Purpose | -| -------------------------- | -------------- | ------------------------------------------- | -| **architecture** | 2-4 | Technical architecture and design decisions | -| **solutioning-gate-check** | 3-4 | Validate planning/solutioning completeness | +| Workflow | Agent | Track | Purpose | +| -------------------------- | --------- | ------------------------ | ------------------------------------------- | +| **architecture** | Architect | BMad Method, Enterprise | Technical architecture and design decisions | +| **solutioning-gate-check** | Architect | BMad Complex, Enterprise | Validate planning/solutioning completeness | **When to Skip Solutioning:** -- **Level 0-1**: Simple changes don't need architecture → Skip to Phase 4 (Implementation) -- **Level 2**: Optional - use if technically complex, skip if straightforward +- **Quick Flow:** Simple changes don't need architecture → Skip to Phase 4 **When Solutioning is Required:** -- **Level 3-4**: Multi-epic, multi-agent projects → Architecture prevents conflicts +- **BMad Method:** Multi-epic projects need architecture to prevent conflicts +- **Enterprise:** Same as BMad Method, plus optional extended workflows (test architecture, security architecture, devops strategy) added AFTER architecture but BEFORE gate check --- -## Understanding the Solutioning Phase +## Why Solutioning Matters -### Why Solutioning Matters +### The Problem Without Solutioning -**Problem Without Solutioning:** +``` +Agent 1 implements Epic 1 using REST API +Agent 2 implements Epic 2 using GraphQL +Result: Inconsistent API design, integration nightmare +``` -1. DEV agent implements Epic 1 using REST API -2. DEV agent implements Epic 2 using GraphQL -3. **Conflict**: Inconsistent API design, integration nightmare +### The Solution With Solutioning -**Solution With Solutioning:** - -1. **architecture** workflow decides: "Use GraphQL for all APIs" -2. All DEV agents follow architecture decisions -3. **Result**: Consistent implementation, no conflicts +``` +architecture workflow decides: "Use GraphQL for all APIs" +All agents follow architecture decisions +Result: Consistent implementation, no conflicts +``` ### Solutioning vs Planning @@ -90,221 +127,81 @@ graph TB | Document | PRD/GDD | Architecture + Tech Spec | | Level | Business logic | Implementation detail | -### Scale-Adaptive Solutioning - -**Level 0-1 (Skip Solutioning):** - -- Planning: Quick Spec (tech-spec workflow) -- Solutioning: **None** -- Implementation: dev-story directly - -**Level 2 (Optional Solutioning):** - -- Planning: Lightweight PRD -- Solutioning: **Optional** architecture -- Implementation: dev-story with or without architecture - -**Level 3-4 (Required Solutioning):** - -- Planning: Standard/Comprehensive PRD -- Solutioning: **Required** architecture + epic-tech-context -- Gate Check: **Required** solutioning-gate-check -- Implementation: dev-story guided by architecture - --- -## architecture +## Workflow Descriptions -### Purpose +### architecture -Collaborative architectural decision facilitation that produces a decision-focused architecture document optimized for preventing agent conflicts. Replaces template-driven architecture with intelligent, adaptive conversation. +**Purpose:** Make technical decisions explicit to prevent agent conflicts. Produces decision-focused architecture document optimized for AI consistency. **Agent:** Architect -**Phase:** 3 (Solutioning) -**Project Levels:** 2-4 -**Required:** Level 3-4, Optional Level 2 -### When to Use +**When to Use:** -- Multi-epic projects (Level 3-4) +- Multi-epic projects (BMad Complex, Enterprise) - Cross-cutting technical concerns -- Multiple agents will implement different parts +- Multiple agents implementing different parts - Integration complexity exists - Technology choices need alignment **When to Skip:** -- Level 0-1 (simple changes) -- Level 2 with straightforward tech stack +- Quick Flow (simple changes) +- BMad Method Simple with straightforward tech stack - Single epic with clear technical approach -### Adaptive Conversation Approach +**Adaptive Conversation Approach:** -**This is NOT a template filler.** The architecture workflow: +This is NOT a template filler. The architecture workflow: -1. **Discovers** your technical needs through conversation +1. **Discovers** technical needs through conversation 2. **Proposes** architectural options with trade-offs 3. **Documents** decisions that prevent agent conflicts 4. **Focuses** on decision points, not exhaustive documentation -### Process Overview +**Key Outputs:** -**Phase 1: Context Discovery (Steps 1-3)** +**architecture.md** containing: -- Load PRD/GDD for requirements -- Understand project level and complexity -- Identify technical constraints -- Determine existing architecture (if brownfield) +1. **Architecture Overview** - System context, principles, style +2. **System Architecture** - High-level diagram, component interactions, communication patterns +3. **Data Architecture** - Database design, state management, caching, data flow +4. **API Architecture** - API style (REST/GraphQL/gRPC), auth, versioning, error handling +5. **Frontend Architecture** (if applicable) - Framework, state management, component architecture, routing +6. **Integration Architecture** - Third-party integrations, message queuing, event-driven patterns +7. **Security Architecture** - Auth/authorization, data protection, security boundaries +8. **Deployment Architecture** - Deployment model, CI/CD, environment strategy, monitoring +9. **Architecture Decision Records (ADRs)** - Key decisions with context, options, trade-offs, rationale +10. **Epic-Specific Guidance** - Technical notes per epic, implementation priorities, dependencies +11. **Standards and Conventions** - Directory structure, naming conventions, code organization, testing -**Phase 2: Architecture Definition (Steps 4-10)** - -- System architecture (monolith, microservices, etc.) -- Data architecture (database, state management) -- API design (REST, GraphQL, gRPC) -- Frontend architecture (if applicable) -- Integration patterns -- Security architecture -- Deployment architecture - -**Phase 3: Decision Documentation (Steps 11-13)** - -- Architecture Decision Records (ADRs) -- Trade-off analysis -- Technology selections with rationale -- Non-negotiable standards - -**Phase 4: Implementation Guidance (Step 14)** - -- Epic-specific technical notes -- Directory structure -- Coding standards -- Testing strategy - -### Inputs - -Required: - -- **PRD.md** or **GDD.md** (from Phase 2) -- **epics.md** (epic breakdown) - -Optional: - -- Existing architecture documentation (brownfield) -- Technical constraints document -- Infrastructure requirements -- Security requirements - -### Outputs - -**Primary Output:** `architecture-{project-name}-{date}.md` - -**Document Structure:** - -**1. Architecture Overview** - -- System context -- Key principles -- Architectural style - -**2. System Architecture** - -- High-level system diagram -- Component interactions -- Communication patterns - -**3. Data Architecture** - -- Database design approach -- State management -- Caching strategy -- Data flow - -**4. API Architecture** - -- API style (REST/GraphQL/gRPC) -- Authentication/authorization -- Versioning strategy -- Error handling patterns - -**5. Frontend Architecture** (if applicable) - -- Framework selection -- State management -- Component architecture -- Routing approach - -**6. Integration Architecture** - -- Third-party integrations -- Message queuing -- Event-driven patterns -- API gateways - -**7. Security Architecture** - -- Authentication/authorization -- Data protection -- Security boundaries -- Compliance requirements - -**8. Deployment Architecture** - -- Deployment model -- CI/CD pipeline -- Environment strategy -- Monitoring and observability - -**9. Architecture Decision Records (ADRs)** - -- Key decisions with context -- Options considered -- Trade-off analysis -- Rationale for choices - -**10. Epic-Specific Guidance** - -- Technical notes per epic -- Implementation priorities -- Dependency sequencing - -**11. Standards and Conventions** - -- Directory structure -- Naming conventions -- Code organization -- Testing requirements - -### Architecture Decision Records (ADRs) - -**Purpose:** Document **why** decisions were made, not just what was decided. - -**ADR Template:** +**ADR Format (Brief):** ```markdown ## ADR-001: Use GraphQL for All APIs -**Status:** Accepted -**Date:** 2025-11-02 +**Status:** Accepted | **Date:** 2025-11-02 + **Context:** PRD requires flexible querying across multiple epics **Decision:** Use GraphQL for all client-server communication **Options Considered:** -1. REST API - Familiar, well-understood, but requires multiple endpoints -2. GraphQL - Flexible querying, single endpoint, learning curve -3. gRPC - High performance, but poor browser support +1. REST - Familiar but requires multiple endpoints +2. GraphQL - Flexible querying, learning curve +3. gRPC - High performance, poor browser support **Rationale:** -- PRD requires flexible data fetching (Epic 1, Epic 3) +- PRD requires flexible data fetching (Epic 1, 3) - Mobile app needs bandwidth optimization (Epic 2) -- Team has GraphQL experience from previous project -- Allows frontend flexibility without backend changes +- Team has GraphQL experience **Consequences:** -- Positive: Flexible querying, reduced API versioning +- Positive: Flexible querying, reduced versioning - Negative: Caching complexity, N+1 query risk - Mitigation: Use DataLoader for batching @@ -312,93 +209,40 @@ Optional: - Epic 1: User Management → GraphQL mutations - Epic 2: Mobile App → Optimized queries -- Epic 3: Admin Dashboard → Complex nested queries ``` -### Example: Level 3 Architecture for E-Commerce Platform +**Example:** E-commerce platform → Monolith + PostgreSQL + Redis + Next.js + GraphQL, with ADRs explaining each choice and epic-specific guidance. -**System Architecture:** - -- Monolith (early stage, < 50K users) -- PostgreSQL database -- Redis for caching and sessions -- Next.js for frontend -- Deployed on Vercel + Railway - -**Key ADRs:** - -1. **ADR-001**: Use Next.js (vs React + Express) - - Rationale: SEO critical, SSR needed, unified codebase -2. **ADR-002**: Use GraphQL (vs REST) - - Rationale: Flexible querying for dashboard, mobile optimization -3. **ADR-003**: Use Stripe (vs PayPal + Stripe) - - Rationale: Simpler integration, lower fees, better UX - -**Epic Guidance:** - -- **Epic 1 (Auth)**: NextAuth.js with PostgreSQL adapter -- **Epic 2 (Products)**: GraphQL with DataLoader for categories -- **Epic 3 (Cart)**: Redis for session-based cart (no DB writes) -- **Epic 4 (Checkout)**: Stripe webhooks for payment confirmation - -**Standards:** - -``` -Directory Structure: -/pages - Next.js routes -/components - Reusable UI components -/lib - Business logic - /graphql - GraphQL schema and resolvers - /db - Prisma models and migrations - /services - Third-party integrations -/tests - Test files mirror /lib -``` - -### Related Workflows - -- **prd/gdd** (Phase 2) - Requirements input -- **solutioning-gate-check** (Phase 3) - Validate completeness -- **tech-spec** (Phase 3) - Epic-level specifications (optional) -- **sprint-planning** (Phase 4) - Implementation tracking +**Integration:** Feeds into Phase 4 (Implementation). All dev agents reference architecture during implementation. --- -## solutioning-gate-check +### solutioning-gate-check -### Purpose +**Purpose:** Systematically validate that planning and solutioning are complete and aligned before Phase 4 implementation. Ensures PRD, architecture, and stories are cohesive with no gaps. -Systematically validate that all planning and solutioning phases are complete and properly aligned before transitioning to Phase 4 implementation. Ensures PRD, architecture, and stories are cohesive with no gaps or contradictions. +**Agent:** Architect -**Agent:** SM (Scrum Master) -**Phase:** 3 (Solutioning) -**Project Levels:** 3-4 -**Required:** Level 3-4 only - -### When to Use - -**Always run before starting Phase 4** for Level 3-4 projects. - -**Trigger Points:** +**When to Use:** +- **Always** before Phase 4 for BMad Complex and Enterprise projects - After architecture workflow completes - Before sprint-planning workflow - When stakeholders request readiness check -- Before kicking off implementation -**Skip if:** +**When to Skip:** -- Level 0-2 (no solutioning phase) -- Exploratory prototype (no formal planning) +- Quick Flow (no solutioning) +- BMad Simple (no gate check required) -### Purpose of Gate Check +**Purpose of Gate Check:** -**Prevents Common Issues:** +**Prevents:** - ❌ Architecture doesn't address all epics - ❌ Stories conflict with architecture decisions - ❌ Requirements ambiguous or contradictory - ❌ Missing critical dependencies -- ❌ Unclear success criteria **Ensures:** @@ -406,268 +250,150 @@ Systematically validate that all planning and solutioning phases are complete an - ✅ All epics have clear technical approach - ✅ No contradictions or gaps - ✅ Team ready to implement -- ✅ Stakeholders aligned -### Process Overview - -**Phase 1: Document Loading (Step 1)** - -- Load PRD/GDD -- Load architecture document -- Load epic files -- Load story files (if created) - -**Phase 2: Completeness Check (Steps 2-4)** - -- **PRD Completeness**: All required sections present -- **Architecture Completeness**: All technical areas addressed -- **Epic Completeness**: All epics from PRD have stories - -**Phase 3: Alignment Check (Steps 5-7)** - -- **PRD ↔ Architecture**: Architecture addresses all requirements -- **Architecture ↔ Epics**: Epics align with architecture decisions -- **Cross-Epic**: No contradictions between epics - -**Phase 4: Quality Check (Steps 8-10)** - -- **Acceptance Criteria**: All stories have clear AC -- **Dependencies**: Dependencies identified and sequenced -- **Risks**: High-risk items have mitigation plans - -**Phase 5: Reporting (Step 11)** - -- Generate gate check report -- List gaps and blockers -- Provide recommendations -- Issue PASS/CONCERNS/FAIL decision - -### Gate Check Criteria +**Check Criteria:** **PRD/GDD Completeness:** -- [ ] Problem statement clear and evidence-based -- [ ] Success metrics defined -- [ ] User personas identified -- [ ] Feature requirements complete -- [ ] All epics defined with objectives -- [ ] Non-functional requirements (NFRs) specified -- [ ] Risks and assumptions documented +- Problem statement clear and evidence-based +- Success metrics defined +- User personas identified +- Feature requirements complete +- All epics defined with objectives +- Non-functional requirements (NFRs) specified +- Risks and assumptions documented **Architecture Completeness:** -- [ ] System architecture defined -- [ ] Data architecture specified -- [ ] API architecture decided -- [ ] Key ADRs documented -- [ ] Security architecture addressed -- [ ] Epic-specific guidance provided -- [ ] Standards and conventions defined +- System architecture defined +- Data architecture specified +- API architecture decided +- Key ADRs documented +- Security architecture addressed +- Epic-specific guidance provided +- Standards and conventions defined **Epic/Story Completeness:** -- [ ] All PRD features mapped to stories -- [ ] Stories have acceptance criteria -- [ ] Stories prioritized (P0/P1/P2/P3) -- [ ] Dependencies identified -- [ ] Story sequencing logical +- All PRD features mapped to stories +- Stories have acceptance criteria +- Stories prioritized (P0/P1/P2/P3) +- Dependencies identified +- Story sequencing logical **Alignment Checks:** -- [ ] Architecture addresses all PRD requirements -- [ ] Stories align with architecture decisions -- [ ] No contradictions between epics -- [ ] NFRs have technical approach -- [ ] Integration points clear +- Architecture addresses all PRD requirements +- Stories align with architecture decisions +- No contradictions between epics +- NFRs have technical approach +- Integration points clear -**Quality Checks:** +**Gate Decision Logic:** -- [ ] Acceptance criteria testable -- [ ] Stories appropriately sized (<5 days) -- [ ] High-risk items have mitigation -- [ ] Success metrics measurable +**✅ PASS** -### Gate Decision Logic - -**PASS** ✅ - -- All critical criteria met (PRD, Architecture, Epic completeness) +- All critical criteria met - Minor gaps acceptable with documented plan -- **Action**: Proceed to Phase 4 (Implementation) +- **Action:** Proceed to Phase 4 -**CONCERNS** ⚠️ +**⚠️ CONCERNS** - Some criteria not met but not blockers - Gaps identified with clear resolution path -- Risks documented with mitigation -- **Action**: Proceed with caution, address gaps in parallel +- **Action:** Proceed with caution, address gaps in parallel -**FAIL** ❌ +**❌ FAIL** - Critical gaps or contradictions - Architecture missing key decisions - Stories conflict with PRD/architecture -- **Action**: BLOCK Phase 4, resolve issues first +- **Action:** BLOCK Phase 4, resolve issues first -### Inputs +**Key Outputs:** -Required: - -- PRD.md or GDD.md -- architecture.md -- epics.md -- Epic files (epic-1-_.md, epic-2-_.md, etc.) - -Optional: - -- Story files (if already created) -- Tech spec documents - -### Outputs - -**Primary Output:** `solutioning-gate-check-{date}.md` - -**Document Structure:** +**solutioning-gate-check.md** containing: 1. Executive Summary (PASS/CONCERNS/FAIL) -2. Completeness Assessment - - PRD/GDD Score - - Architecture Score - - Epic/Story Score -3. Alignment Assessment - - PRD ↔ Architecture alignment - - Architecture ↔ Epic alignment - - Cross-epic consistency -4. Quality Assessment - - Story quality - - Dependency clarity - - Risk mitigation -5. Gaps and Recommendations - - Critical gaps (blockers) - - Minor gaps (address in parallel) - - Recommendations for remediation -6. Gate Decision (PASS/CONCERNS/FAIL) +2. Completeness Assessment (scores for PRD, Architecture, Epics) +3. Alignment Assessment (PRD↔Architecture, Architecture↔Epics, cross-epic consistency) +4. Quality Assessment (story quality, dependencies, risks) +5. Gaps and Recommendations (critical/minor gaps, remediation) +6. Gate Decision with rationale 7. Next Steps -### Example: Gate Check for E-Commerce Platform - -**Result:** CONCERNS ⚠️ - -**Completeness:** - -- ✅ PRD complete (18/18 criteria) -- ⚠️ Architecture missing security section (15/18 criteria) -- ✅ Epics complete (24/24 criteria) - -**Alignment:** - -- ✅ PRD ↔ Architecture aligned -- ⚠️ Epic 4 (Checkout) has payment gateway undefined in architecture -- ✅ No cross-epic contradictions - -**Quality:** - -- ✅ Stories have acceptance criteria -- ⚠️ Epic 2, Story 3 is too large (10 day estimate) -- ✅ Dependencies identified - -**Gaps Identified:** - -1. **Critical**: Architecture missing security architecture section - - **Impact**: Epic 1 (Auth) and Epic 4 (Checkout) lack security guidance - - **Recommendation**: Complete security architecture - -2. **High**: Payment gateway not selected - - **Impact**: Epic 4 (Checkout) cannot proceed - - **Recommendation**: Add ADR for payment gateway selection - -3. **Medium**: Epic 2, Story 3 too large - - **Impact**: Risk of story scope creep - - **Recommendation**: Split into 2 stories - -**Gate Decision:** CONCERNS ⚠️ - -- **Rationale**: Critical and high gaps block Epic 1 and Epic 4 -- **Action**: Resolve gaps #1 and #2 before starting implementation - -**Next Steps:** - -1. Complete security architecture section -2. Document payment gateway ADR -3. Split Epic 2, Story 3 -4. Re-run solutioning-gate-check -5. If PASS → Proceed to sprint-planning - -### Related Workflows - -- **architecture** (Phase 3) - Must complete before gate check -- **prd/gdd** (Phase 2) - Input to gate check -- **sprint-planning** (Phase 4) - Runs after PASS decision +**Example:** E-commerce platform → CONCERNS ⚠️ due to missing security architecture and undefined payment gateway. Recommendation: Complete security section and add payment gateway ADR before proceeding. --- -## Integration with Phase 2 (Planning) and Phase 4 (Implementation) +## Integration with Planning and Implementation ### Planning → Solutioning Flow -**Level 0-1:** +**Quick Flow:** ``` -Planning (tech-spec Quick Spec) +Planning (tech-spec by PM) → Skip Solutioning - → Implementation (dev-story) + → Phase 4 (Implementation) ``` -**Level 2:** +**BMad Method:** ``` -Planning (prd Lightweight) - → Optional: architecture (if complex) - → Implementation (sprint-planning → dev-story) +Planning (prd by PM) + → architecture (Architect) + → solutioning-gate-check (Architect) + → Phase 4 (Implementation) ``` -**Level 3-4:** +**Enterprise:** ``` -Planning (prd Standard/Comprehensive) - → architecture (Required) - → solutioning-gate-check (Required) - → Implementation (sprint-planning → dev-story) +Planning (prd by PM - same as BMad Method) + → architecture (Architect) + → Optional: test-architecture (TEA, future) + → Optional: security-architecture (Architect) + → Optional: devops-strategy (Architect) + → solutioning-gate-check (Architect) + → Phase 4 (Implementation) ``` +**Note:** Enterprise uses the same planning and architecture as BMad Method. The only difference is optional extended workflows added AFTER architecture but BEFORE gate check. + ### Solutioning → Implementation Handoff **Documents Produced:** -1. `architecture.md` → Guides all dev-story workflows -2. `ADRs` (in architecture) → Referenced by agents during implementation -3. `solutioning-gate-check.md` → Confirms readiness +1. **architecture.md** → Guides all dev agents during implementation +2. **ADRs** (in architecture) → Referenced by agents for technical decisions +3. **solutioning-gate-check.md** → Confirms readiness for Phase 4 **How Implementation Uses Solutioning:** -- **sprint-planning**: Loads architecture for epic sequencing -- **dev-story**: References architecture decisions and ADRs -- **code-review**: Validates code follows architectural standards +- **sprint-planning** - Loads architecture for epic sequencing +- **dev-story** - References architecture decisions and ADRs +- **code-review** - Validates code follows architectural standards --- -## Best Practices for Phase 3 +## Best Practices ### 1. Make Decisions Explicit -Don't leave technology choices implicit. Document decisions with rationale so future agents understand context. +Don't leave technology choices implicit. Document decisions with rationale in ADRs so agents understand context. ### 2. Focus on Agent Conflicts -Architecture's primary job is preventing conflicting implementations by different agents. Focus on cross-cutting concerns. +Architecture's primary job is preventing conflicting implementations. Focus on cross-cutting concerns. ### 3. Use ADRs for Key Decisions -Every significant technology choice should have an ADR explaining the "why", not just the "what". +Every significant technology choice should have an ADR explaining "why", not just "what". ### 4. Keep It Practical -Don't over-architect Level 2 projects. Simple projects need simple architecture. +Don't over-architect simple projects. BMad Simple projects need simple architecture. ### 5. Run Gate Check Before Implementation @@ -679,78 +405,96 @@ Architecture documents are living. Update them as you learn during implementatio --- +## Decision Guide + +### Quick Flow + +- **Planning:** tech-spec (PM) +- **Solutioning:** Skip entirely +- **Implementation:** sprint-planning → dev-story + +### BMad Method + +- **Planning:** prd (PM) +- **Solutioning:** architecture (Architect) → solutioning-gate-check (Architect) +- **Implementation:** sprint-planning → epic-tech-context → dev-story + +### Enterprise + +- **Planning:** prd (PM) - same as BMad Method +- **Solutioning:** architecture (Architect) → Optional extended workflows (test-architecture, security-architecture, devops-strategy) → solutioning-gate-check (Architect) +- **Implementation:** sprint-planning → epic-tech-context → dev-story + +**Key Difference:** Enterprise adds optional extended workflows AFTER architecture but BEFORE gate check. Everything else is identical to BMad Method. + +--- + ## Common Anti-Patterns -### ❌ Skipping Architecture for Level 3-4 +### ❌ Skipping Architecture for Complex Projects "Architecture slows us down, let's just start coding." -→ **Result**: Agent conflicts, inconsistent design, rework +**Result:** Agent conflicts, inconsistent design, massive rework -### ❌ Over-Architecting Level 2 +### ❌ Over-Engineering Simple Projects "Let me design this simple feature like a distributed system." -→ **Result**: Wasted time, over-engineering +**Result:** Wasted time, over-engineering, analysis paralysis ### ❌ Template-Driven Architecture "Fill out every section of this architecture template." -→ **Result**: Documentation theater, no real decisions made +**Result:** Documentation theater, no real decisions made ### ❌ Skipping Gate Check "PRD and architecture look good enough, let's start." -→ **Result**: Gaps discovered mid-sprint, wasted implementation time +**Result:** Gaps discovered mid-sprint, wasted implementation time ### ✅ Correct Approach -- Use architecture for Level 3-4 (required) -- Keep Level 2 architecture simple (if used) +- Use architecture for BMad Method and Enterprise (both required) - Focus on decisions, not documentation volume +- Enterprise: Add optional extended workflows (test/security/devops) after architecture - Always run gate check before implementation --- -## Decision Guide: When to Use Solutioning Workflows +## Related Documentation -### Level 0-1 Projects - -- **Planning**: tech-spec (Quick Spec) -- **Solutioning**: **Skip entirely** -- **Implementation**: dev-story directly - -### Level 2 Projects (Simple) - -- **Planning**: prd (Lightweight) -- **Solutioning**: **Skip** if straightforward tech -- **Implementation**: sprint-planning → dev-story - -### Level 2 Projects (Technically Complex) - -- **Planning**: prd (Lightweight) -- **Solutioning**: architecture (simplified) -- **Gate Check**: Optional -- **Implementation**: sprint-planning → dev-story - -### Level 3-4 Projects - -- **Planning**: prd/gdd (Standard/Comprehensive) -- **Solutioning**: architecture (comprehensive) → **Required** -- **Gate Check**: solutioning-gate-check → **Required** -- **Implementation**: sprint-planning → epic-tech-context → dev-story +- [Phase 2: Planning Workflows](./workflows-planning.md) - Previous phase +- [Phase 4: Implementation Workflows](./workflows-implementation.md) - Next phase +- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding tracks +- [Agents Guide](./agents-guide.md) - Complete agent reference --- -## Summary +## Troubleshooting -Phase 3 Solutioning workflows bridge planning and implementation: +**Q: Do I always need architecture?** +A: No. Quick Flow skips it. BMad Method and Enterprise both require it. -| Workflow | Purpose | When Required | -| -------------------------- | ------------------------------------- | ---------------------------------------- | -| **architecture** | Make technical decisions explicit | Level 3-4 (required), Level 2 (optional) | -| **solutioning-gate-check** | Validate readiness for implementation | Level 3-4 only | +**Q: How do I know if I need architecture?** +A: If you chose BMad Method or Enterprise track in planning (workflow-init), you need architecture to prevent agent conflicts. -**Key Takeaway:** Solutioning prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins. +**Q: What's the difference between architecture and tech-spec?** +A: Tech-spec is implementation-focused for simple changes. Architecture is system design for complex multi-epic projects. -**Next Phase:** Implementation (Phase 4) - Sprint-based story development +**Q: Can I skip gate check?** +A: Only for Quick Flow. BMad Method and Enterprise both require gate check before Phase 4. -See: [workflows-implementation.md](./workflows-implementation.md) +**Q: What if gate check fails?** +A: Resolve the identified gaps (missing architecture sections, conflicting requirements) and re-run gate check. + +**Q: How long should architecture take?** +A: BMad Method: 1-2 days for architecture. Enterprise: 2-3 days total (1-2 days architecture + 0.5-1 day optional extended workflows). If taking longer, you may be over-documenting. + +**Q: Do ADRs need to be perfect?** +A: No. ADRs capture key decisions with rationale. They should be concise (1 page max per ADR). + +**Q: Can I update architecture during implementation?** +A: Yes! Architecture is living. Update it as you learn. Use `correct-course` workflow for significant changes. + +--- + +_Phase 3 Solutioning - Technical decisions before implementation._