BMAD-METHOD/bmad-guide.md at 486196cd4fe2d0efaa75a5b75a31da4718aa3966

13 KiB

Raw Blame History

You are working within the BMAD Method (BMM) - a 4-phase AI-powered agile development framework. This guide helps you stay on track and use the correct workflows.

🚨 CRITICAL RULES

NEVER skip phases - Each phase builds on the previous (except Phase 1 which is optional)
ALWAYS check project level - This determines which workflows to use
ALWAYS use workflows - Don't implement features manually without BMAD workflows
ALWAYS consult workflow docs - Located in src/modules/bmm/workflows/
STAY IN PHASE - Complete current phase before moving to next

📍 WHERE AM I? - Quick Phase Check

Phase 0: Brownfield Documentation

You're here if: Working with existing codebase that needs documentation Workflow: document-project Next: Phase 2 (skip Phase 1)

Phase 1: Analysis (Optional)

You're here if: Need strategic exploration, research, or vision definition Workflows:

brainstorm-project - Explore multiple solution approaches
research - Market/technical/competitive research
create-product-brief - Define product vision

Next: Phase 2 (Planning)

Phase 2: Planning (REQUIRED)

You're here if: Need to define requirements and scope Workflows:

Level 0-1: bmad-quick-flow/create-tech-spec (quick technical spec)
Level 2+: 2-plan-workflows/prd (full Product Requirements Document)
Optional: create-ux-design (UX/UI specification - after PRD)

Next:

Level 0-1: Skip to Phase 4 (Implementation)
Level 2: Phase 4 if simple, Phase 3 if needs architecture
Level 3-4: Phase 3 (Solutioning)

Phase 3: Solutioning (Conditional)

You're here if: Need architectural decisions and epic breakdown Workflows:

create-architecture - Make architectural decisions
create-epics-and-stories - Break requirements into implementable stories
check-implementation-readiness - Gate check validation

Next: Phase 4 (Implementation)

Phase 4: Implementation (REQUIRED)

You're here if: Ready to implement stories Core Loop:

sprint-planning (once) - Initialize sprint tracking
For each story:
- create-story - Create individual story
- dev-story or super-dev-story - Implement with tests
- code-review - Quality review
- Mark story as DONE
retrospective (per epic) - Review and extract lessons
push-all - Stage & push all changes when ready

Advanced/Automated:

autonomous-epic - Fully automated epic completion
super-dev-story - Enhanced dev with pre/post validation
gap-analysis - Validate story against codebase
create-story-with-gap-analysis - Combined create + validate

🎯 PROJECT LEVEL DETECTION

ALWAYS determine project level first to route to correct planning track:

Level	Name	Stories	Detection Keywords	Planning Track
0	Atomic	1	"bug", "fix", "typo", "update", "quick"	Tech spec only
1	Small	1-10	"small feature", "add button", "simple"	Tech spec only
2	Medium	5-15	"feature", "module", "component"	PRD (skip arch)
3	Complex	12-40	"system", "integration", "api", "architecture"	PRD + Architecture
4	Enterprise	40+	"platform", "enterprise", "multiple products"	PRD + Architecture

How to detect:

# Use workflow-init to automatically detect level
/workflow-init

🔍 WORKFLOW DECISION TREE

┌─ START: What do you need to do?
│
├─ "I need to explore solutions" → Phase 1: brainstorm-project
│
├─ "I need requirements"
│  ├─ Level 0-1? → Phase 2: bmad-quick-flow/create-tech-spec
│  └─ Level 2+? → Phase 2: 2-plan-workflows/prd
│
├─ "I have PRD, need architecture" → Phase 3: create-architecture
│
├─ "I have PRD, need stories" → Phase 3: create-epics-and-stories
│
├─ "I'm ready to implement"
│  ├─ First time? → sprint-planning (initialize)
│  ├─ Need new story? → create-story
│  ├─ Implement story? → dev-story or super-dev-story
│  ├─ Automate epic? → autonomous-epic
│  └─ Review story? → code-review
│
└─ "Epic is done" → retrospective

⚠️ COMMON MISTAKES TO AVOID

❌ DON'T:

Skip Phase 2 - Requirements are ALWAYS required
Jump to coding without workflows
Create architecture for Level 0-2 projects (overkill)
Skip sprint-planning before dev-story
Mix phases - finish current phase first
Implement manually - use dev-story/super-dev-story
Forget retrospectives - extract lessons after each epic

✅ DO:

Check phase progression - Am I in the right phase?
Consult workflow docs - Read the .md files in workflows/
Use workflow-init - Let BMAD detect level
Follow story lifecycle - create → dev → review → done
One story at a time - Complete before moving to next
Use autonomous-epic - For efficient bulk processing
Validate with gap-analysis - Before and after development

📚 HOW TO LOOK UP WORKFLOW INFO

Method 1: Read Workflow Documentation

# Read workflow guide for current phase
cat src/modules/bmm/workflows/README.md
cat src/modules/bmm/docs/workflows-{phase}.md

# Example: Planning phase
cat src/modules/bmm/docs/workflows-planning.md

# Example: Implementation phase
cat src/modules/bmm/docs/workflows-implementation.md

Method 2: Read Specific Workflow

# Read workflow details
cat src/modules/bmm/workflows/{phase}/{workflow-name}/README.md

# Example: PRD workflow
cat src/modules/bmm/workflows/2-plan-workflows/prd/README.md

# Example: Dev story workflow
cat src/modules/bmm/workflows/4-implementation/dev-story/README.md

Method 3: Check Workflow Configuration

# See workflow config
cat src/modules/bmm/workflows/{phase}/{workflow-name}/workflow.yaml

Method 4: Use Explore Agent

Use Task tool with subagent_type=Explore to search for workflow info:
"Find documentation about {workflow-name} in BMAD workflows"

🎬 TYPICAL PROJECT FLOWS

Small Change (Level 0-1)

tech-spec → dev-story → code-review → done

Medium Feature (Level 2)

prd → [optional: create-ux-design] → create-epics-and-stories
→ sprint-planning → (create-story → dev-story → code-review)* → retrospective

Complex System (Level 3-4)

[optional: brainstorm/research] → prd → [optional: create-ux-design]
→ create-architecture → create-epics-and-stories → check-implementation-readiness
→ sprint-planning → (create-story → super-dev-story)* → retrospective

Automated Epic Processing (Any Level)

[Phase 2-3 complete] → sprint-planning → autonomous-epic {epic_number}
→ (auto: create-story → super-dev-story → commit)* → retrospective

🚀 WORKFLOW EXECUTION PATTERNS

Pattern 1: Step-File Workflows (PRD, Architecture, Epics)

Sequential execution - Can't skip steps
One step at a time - Load step file, execute, move to next
User approval gates - Wait for approval between steps
Append-only building - Never overwrite previous sections
State tracking - Uses frontmatter stepsCompleted array

Example:

step-01-init.md → step-02-discovery.md → step-03-requirements.md → ...

Pattern 2: YAML Configuration Workflows (Dev, Review, Sprint)

Full config in workflow.yaml
Auto-discovery - Finds story files automatically
System execution - Agent-driven, not user-interactive
Config inheritance - Reads from project config

🔧 ADVANCED FEATURES

Autonomous Epic Processing

When to use: Want to automate entire epic completion

# After sprint-planning, automate all stories in epic
/autonomous-epic 2

What it does:

Creates story → Develops with super-dev-story → Commits → Repeat
Includes pre/post gap analysis
Includes code review
Creates git commit per story
Continues on failures (configurable)

Super-Dev-Story

When to use: Want enhanced development with validation

# Instead of dev-story, use super-dev-story
/super-dev-story

What it does:

Pre-dev gap analysis (validate story before coding)
Implement with tests
Post-dev gap analysis (validate implementation)
Built-in code review
Fail-on-critical-issues (auto-fix loops)

Gap Analysis

When to use: Validate story against actual codebase

# Standalone validation
/gap-analysis

What it checks:

Missing infrastructure before implementation
Implementation matches story requirements
All tasks from story are actually completed

📋 WORKFLOW STATUS & TRACKING

Check Current Status

# View sprint status
cat {project-root}/_bmad/bmm/implementation/sprint-status.yaml

# View workflow status
cat {project-root}/_bmad/bmm/workflow-status.yaml

Story States

TODO - Not started
IN PROGRESS - Currently being developed
READY FOR REVIEW - Implemented, needs review
DONE - Complete and reviewed

🎯 WHEN TO USE EACH WORKFLOW - QUICK REFERENCE

I need to...	Use this workflow	Phase
Explore solutions	brainstorm-project	1
Research market/tech	research	1
Define product vision	create-product-brief	1
Write requirements (quick)	bmad-quick-flow/create-tech-spec	2
Write requirements (full)	2-plan-workflows/prd	2
Design UX/UI	create-ux-design	2
Make architecture decisions	create-architecture	3
Break into stories	create-epics-and-stories	3
Validate readiness	check-implementation-readiness	3
Start sprint	sprint-planning	4
Create individual story	create-story	4
Implement story	dev-story or super-dev-story	4
Automate epic	autonomous-epic	4
Validate against code	gap-analysis	4
Review quality	code-review	4
Review epic completion	retrospective	4
Push changes	push-all	4

💡 TROUBLESHOOTING

"I'm not sure which phase I'm in"

→ Check for existing artifacts:

PRD exists? You're past Phase 2
Architecture exists? You're past Phase 3
Sprint-status.yaml exists? You're in Phase 4
No artifacts? Start with Phase 2 (or Phase 1 if exploring)

"I'm not sure which workflow to use"

→ Use this guide's decision tree or consult phase-specific docs:

workflows-planning.md - Phase 2 workflows
workflows-solutioning.md - Phase 3 workflows
workflows-implementation.md - Phase 4 workflows

"Workflow isn't working"

→ Check these:

Is config.yaml set up? (project-root/_bmad/bmm/config.yaml)
Are you in the right phase?
Did you complete prerequisite workflows?
Check workflow README for requirements

"I want to automate everything"

→ Use autonomous-epic after completing Phase 2-3:

/sprint-planning  # Initialize once
/autonomous-epic 1  # Automate epic 1
/autonomous-epic 2  # Automate epic 2

🎓 KEY PRINCIPLES

Scale-Adaptive - Same system works for 1 story or 100 stories
Phase-Gated - Complete phases in order (except Phase 1 optional)
Story-Centric - Everything revolves around implementing stories
Validation-First - Gap analysis prevents mismatched implementations
Automation-Friendly - Can automate entire epics with autonomous workflows
Quality-Built-In - Code review and retrospectives are mandatory
Documentation-Driven - Every phase produces artifacts

📖 ADDITIONAL RESOURCES

Core Documentation

src/modules/bmm/docs/workflows-analysis.md - Phase 1 guidance
src/modules/bmm/docs/workflows-planning.md - Phase 2 guidance
src/modules/bmm/docs/workflows-solutioning.md - Phase 3 guidance
src/modules/bmm/docs/workflows-implementation.md - Phase 4 guidance
src/modules/bmm/docs/scale-adaptive-system.md - Level detection
src/modules/bmm/docs/brownfield-guide.md - Existing codebases

Specialized Guides

src/modules/bmm/docs/test-architecture.md - TestArch workflows
src/modules/bmm/docs/agents-guide.md - All 12 specialized agents

✅ CHECKLIST: Am I Following BMAD?

Before proceeding, check:

I know what phase I'm in
I know what project level this is (0-4)
I've completed prerequisite phases
I'm using a workflow (not coding manually)
I've read the workflow documentation
I'm following the story lifecycle (if Phase 4)
I'm validating with gap analysis (if Phase 4)
I'm doing code reviews (if Phase 4)
I'm completing retrospectives (if finishing epic)

If any are unchecked, STOP and fix it before proceeding.

🚨 EMERGENCY: I Went Off Track

Identify where you are:
- Check existing artifacts (PRD? Architecture? Sprint status?)
- Determine current phase
Determine where you should be:
- What was the original request?
- What phase should that be in?
Course correct:
- Use correct-course workflow if in Phase 4
- Otherwise, restart the appropriate workflow for current phase
Prevent future derailment:
- Consult this guide before starting work
- Read workflow docs before executing
- Use TodoWrite to track workflow steps

🎯 REMEMBER

BMAD is a methodology, not a suggestion.

When in doubt:

Check this guide
Read workflow documentation
Ask the user for clarification
Use explore agent to find info

DO NOT improvise. Follow the process.

13 KiB Raw Blame History

BMAD Method Guide - Process Navigation & Workflow Selection