A comprehensive AI-agent-driven workflow system (BMAD Framework v6.0.0-Beta.8) for end-to-end product development. This guide covers the full lifecycle, ad-hoc processes, and how to handle every scenario you'll encounter.
- The Full Lifecycle
- Phase 1: Analysis
- Phase 2: Planning
- Phase 3: Solutioning
- Phase 4: Implementation
- Workflow Decision Guide
- Ad-Hoc & Lightweight Workflows
- Mid-Sprint Changes
- Agents & Roles
- Commands Reference
- Key Files & Artifacts
Product Brief ──► PRD ──► UX Design ──► Architecture ──► Epics & Stories
(1) (2) (2) (3) (3)
│
▼
Implementation Readiness Check
│
▼
Sprint Planning ──► Create Story ──► Dev Story
(4) (4) (4)
│
▼
Code Review ──► Ship Story
(4) (4)
Phase numbers in parentheses. Each phase builds on artifacts from the previous one. Documents are dual-audience: human-readable AND LLM-consumable for downstream agent use.
| Command | /bmad-bmm-create-product-brief |
| Agent | Analyst (Mary) |
| Output | planning_artifacts/product-brief.md |
Collaborative discovery session to capture the core product concept: problem statement, target users, key differentiators, and vision. This is the seed document everything else grows from.
| Command | /bmad-bmm-create-prd |
| Agent | Product Manager (John) |
| Output | planning_artifacts/prd.md |
12-step guided workflow producing a comprehensive Product Requirements Document. Covers: executive summary, success criteria (SMART), user journeys, domain requirements, functional requirements (FRs), and non-functional requirements (NFRs).
Variants:
- Create (
/bmad-bmm-create-prd) - New PRD from scratch - Edit (
/bmad-bmm-edit-prd) - Modify existing PRD - Validate (
/bmad-bmm-validate-prd) - Check PRD against BMAD standards (13 validation steps)
| Command | /bmad-bmm-create-ux-design |
| Agent | UX Designer (Sally) |
| Output | planning_artifacts/ux-design-specification.md |
14-step workflow producing UX specifications: core experience, emotional design, design system foundations, user journeys, component strategy, responsive/accessibility requirements (WCAG).
| Command | /bmad-bmm-create-architecture |
| Agent | Architect (Winston) |
| Output | planning_artifacts/architecture.md |
| Requires | PRD (mandatory), UX Design (optional) |
8-step workflow producing architecture decisions: data architecture, auth/security, API design, frontend architecture, infrastructure/deployment. Decision-focused, not template-driven.
| Command | /bmad-bmm-create-epics-and-stories |
| Agent | Product Manager (John) |
| Output | planning_artifacts/epics.md |
| Requires | PRD + Architecture (mandatory), UX Design (optional) |
Transforms requirements into implementation-ready work items. Epics are organized by user value, not technical layers. Each story uses BDD format (Given/When/Then) acceptance criteria.
| Command | /bmad-bmm-check-implementation-readiness |
| Agent | Architect (Winston) |
| Requires | PRD + Architecture + Epics |
Adversarial validation ensuring PRD, Architecture, UX, and Epics are aligned before development begins. Produces a readiness report with gaps and issues.
| Command | /bmad-bmm-sprint-planning or /init-sprint |
| Agent | Scrum Master (Bob) |
| Output | sprint-status.yaml |
Parses epic files, discovers story status, and generates the master tracking file. All stories start as backlog.
| Command | /bmad-bmm-create-story or /make-stories |
| Agent | Scrum Master (Bob) |
| Output | Story file in implementation_artifacts/ |
Prepares individual stories with full dev context: tasks/subtasks, Dev Notes, architecture references, previous story learnings. Status becomes ready-for-dev.
| Command | /bmad-bmm-dev-story |
| Agent | Developer (Amelia) |
Implements the story using red-green-refactor TDD cycle. Follows tasks/subtasks exactly. Runs all validations. Updates status to review when complete.
| Command | /bmad-bmm-code-review |
| Agent | Code Review Auditor (fresh context) |
Adversarial review finding minimum 3 issues. Checks: AC implementation, task completion claims, security, performance, test quality. Issues categorized as CRITICAL/HIGH/MEDIUM/LOW.
| Command | /bmad-bmm-ship-story or /ship-story |
| Agent | Developer (orchestrator) |
End-to-end wrapper: dev-story → validate → commit → code-review → fix → commit → update AGENTS.md. The "one command to rule them all" for story completion.
backlog → ready-for-dev → in-progress → review → done
This is the key question: "How much process do I need?"
What are you doing?
│
┌───────────────┼───────────────┐
▼ ▼ ▼
New Product New Feature Bug / Hotfix
│ │ │
│ How big is it? │
│ │ │ │
▼ ▼ ▼ ▼
Full Lifecycle Large Small /bugfix
(Phase 1→4) │ │ (see below)
│ │
▼ ▼
Mini-PRD Ad-Hoc Dev
Flow Flow
(see below) (see below)
| Scenario | Workflow | Artifacts Produced |
|---|---|---|
| New product from scratch | Full lifecycle (Phase 1→4) | Brief, PRD, UX, Architecture, Epics, Stories |
| Large feature (multi-epic) | Mini-PRD flow (see below) | PRD update or mini-PRD, Architecture update, New epics/stories |
| Small feature (1-3 stories) | Ad-hoc dev flow (see below) | Story file(s), updated sprint-status |
| Bug fix | /bugfix command |
Bug story file, fix, commit |
| Mid-sprint scope change | Correct Course workflow | Sprint Change Proposal |
| Tweak/config change | Direct edit + commit | None required |
For shipping a bug fix end-to-end without full ceremony:
/bugfix <story-file-path>
Flow: Investigate → Fix → Update story → Code review → Commit
The story file should describe the failing tests/issues. The agent investigates root cause, fixes the code (not blindly changing tests), runs the auditor, and commits only when all tests pass. Commit format: [story-id] fix: description.
For adding a small feature mid-sprint (1-3 stories) that doesn't warrant a full PRD:
Step 1: Write a minimal story file using the story-minimal template (_bmad/bmm/templates/story-minimal.md):
# <story-key>: <title>
Status: ready-for-dev
## Story
As a <persona>, I want <goal>, so that <benefit>.
## Acceptance Criteria
1. Given <context> When <action> Then <outcome>
## Constraints
- <any unusual constraints>
## Tasks
- [ ] Task 1
- [ ] Task 2
## Log
- <date>: Created (ad-hoc addition)Step 2: Add to sprint tracking - Update sprint-status.yaml with the new story.
Step 3: Develop - Use /bmad-bmm-dev-story or /ship-story to implement it through the standard dev → test → review → commit cycle.
Step 4: Update docs - If the feature touches architecture decisions or PRD scope, update those artifacts. The ship-story workflow handles AGENTS.md updates automatically.
For features too large for ad-hoc but not warranting a full product lifecycle:
- Scope the change - Write a focused addition to the existing PRD (
/bmad-bmm-edit-prd), or create a standalone requirements section in a new story's Dev Notes - Update architecture if needed - If new technical decisions are required, update
planning_artifacts/architecture.md - Create epics/stories - Either:
- Add stories to an existing epic in
planning_artifacts/epics.md - Create a new epic section
- Use
/bmad-bmm-create-epics-and-storiesto regenerate from updated PRD
- Add stories to an existing epic in
- Update sprint - Run
/init-sprintto refreshsprint-status.yaml - Develop normally -
/ship-storythrough the standard cycle
| Change Size | Min Required Artifacts | Commands |
|---|---|---|
| Config tweak | None | Direct edit + git commit |
| Bug fix | Bug story file | /bugfix |
| Small feature (1 story) | Story file + sprint-status update | /make-stories → /ship-story |
| Medium feature (2-5 stories) | Updated PRD section + new stories | /bmad-bmm-edit-prd → /make-stories → /ship-story |
| Large feature (new epic) | PRD update + architecture review + new epic | Full Phase 2-4 |
| New product | Everything | Full Phase 1-4 |
| Command | /bmad-bmm-correct-course |
| Agents | Scrum Master or Product Manager |
| Triggers | Technical limitation discovered, new requirements, failed approach, strategic pivot |
Analyzes impact across all artifacts (PRD, Architecture, UX, Epics) and produces a Sprint Change Proposal with scope-based routing:
- Minor scope → Dev team implements directly (fastest)
- Moderate scope → Backlog reorganization with SM/PO coordination
- Major scope → Fundamental replan with PM/Architect
- Use Correct Course when the change affects existing stories, epics, or architecture decisions
- Just add a story when the change is additive and doesn't conflict with existing work
- Update PRD first when the change represents a new requirement not captured anywhere
| Agent | Persona | Role | Key Workflows |
|---|---|---|---|
| Analyst (Mary) | Excited pattern-finder | Business Analyst | Product Brief, Document Project |
| PM (John) | "WHY?" detective | Product Manager | PRD, Epics & Stories, Course Correction |
| Architect (Winston) | Calm pragmatist | System Architect | Architecture, Implementation Readiness |
| UX Designer (Sally) | Visual storyteller | UX Specialist | UX Design |
| Scrum Master (Bob) | Checklist-driven | Sprint Manager | Sprint Planning, Create Story, Course Correction |
| Developer (Amelia) | Ultra-succinct | Senior Engineer | Dev Story, Code Review, Ship Story |
| Tech Writer (Paige) | Patient educator | Documentation | Document Project, Reference Docs |
Additionally, two custom agents in .opencode/agents/:
- Code Review Auditor - Fresh-context adversarial reviewer (used by ship-story)
- Documenter - Project documentation specialist
| Command | Description |
|---|---|
/bmad-bmm-create-product-brief |
Start product analysis |
/bmad-bmm-create-prd |
Create new PRD |
/bmad-bmm-validate-prd |
Validate existing PRD |
/bmad-bmm-edit-prd |
Edit existing PRD |
/bmad-bmm-create-ux-design |
Create UX specification |
/bmad-bmm-create-architecture |
Create architecture decisions |
/bmad-bmm-create-epics-and-stories |
Generate epics and stories from PRD |
/bmad-bmm-check-implementation-readiness |
Validate readiness for dev |
/bmad-bmm-sprint-planning |
Initialize sprint tracking |
/bmad-bmm-sprint-status |
Check sprint progress |
/bmad-bmm-create-story |
Prepare single story for dev |
/bmad-bmm-dev-story |
Implement a story |
/bmad-bmm-code-review |
Run adversarial code review |
/bmad-bmm-ship-story |
End-to-end story completion |
/bmad-bmm-correct-course |
Mid-sprint change management |
/bmad-bmm-document-project |
Scan and document project |
/bmad-bmm-generate-project-context |
Generate LLM-optimized context |
| Command | Description |
|---|---|
/init-sprint |
Quick sprint initialization |
/make-stories |
Story generation shortcut |
/ship-story |
Ship story wrapper |
/bugfix <path> |
End-to-end bug fix |
/test-review |
5-dimension test quality scoring |
/create-component |
Component creation |
/document |
Project documentation |
/understand-context |
Load reference context |
_bmad/
core/tasks/workflow.xml # Workflow execution engine
bmm/
agents/ # 7 agent persona definitions
workflows/
1-analysis/ # Product Brief
2-plan-workflows/ # PRD, UX Design
3-solutioning/ # Architecture, Epics, Readiness
4-implementation/ # Sprint, Stories, Dev, Review, Ship
correct-course/ # Mid-sprint change management
document-project/ # Project documentation
templates/story-minimal.md # Lightweight story template
config.yaml # Module configuration
_config/
manifest.yaml # Module registry
agent-manifest.csv # Agent definitions
workflow-manifest.csv # Workflow registry
.opencode/
commands/ # 25 command definitions
agents/ # Custom agents (auditor, documenter)
planning_artifacts/ # Phase 1-3 outputs
product-brief.md
prd.md
ux-design-specification.md
architecture.md
epics.md
implementation_artifacts/ # Phase 4 outputs (story files)
sprint-status.yaml # Sprint tracking (project root)
AGENTS.md # Root context (updated after each ship)
product-brief.md ──► prd.md ──────────────────► epics.md
│ ▲
├──► ux-design-spec.md ──────┤
│ │
└──► architecture.md ────────┘
Each downstream document references and builds on its predecessors. The traceability chain ensures every story traces back to a functional requirement, which traces back to a user journey, which traces back to a success criterion.