BMAD Framework Usage Guide

BMAD (Breakthrough Method for Agile AI-Driven Development) is an AI-driven development framework where 7 specialized personas review through 4 phase gates to ensure quality.

Table of Contents#

Quick Start
Phase Overview
Persona Introduction
Command Reference
Workflow Examples
Configuration Customization
Troubleshooting

Quick Start#

Basic Usage#

# Develop new feature with BMAD workflow
/bmad  " Add author list screen " 

 # Activate BMAD on existing workflow
/dev:run --bmad  " Add author list screen "

First BMAD Workflow#

Enter task description: /bmad "desired feature description"
Analysis phase: Analyst analyzes requirements
Planning phase: PM creates issues and estimates Story Points
Solutioning phase: Architect and UX Designer review in parallel
Implementation phase: Code implementation, testing, PR creation
Complete: PR merge and issue close

Phase Overview#

4-Phase Flow#

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   Analysis   │ → │   Planning   │ → │ Solutioning  │ → │Implementation│
│              │    │              │    │  (parallel)  │    │              │
│  • Requirements│    │  • Issue create│    │  • Architecture│    │  • Code impl  │
│  • AC define  │    │  • SP estimate│    │  • UX review  │    │  • Tests      │
│  • Feasibility│    │  • Labeling   │    │              │    │  • PR/merge   │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
       │                  │                   │                   │
       ▼                  ▼                   ▼                   ▼
   [Gate 1]           [Gate 2]            [Gate 3]            [Gate 4]

Phase Details#

Phase	Responsible Persona	Gate Verification Items
Analysis	Analyst	Requirements clarity, scope appropriateness, AC BDD Gherkin format ⭐
Planning	Product Manager	Epic/Story structure, Story Point (1-8), labeling, dependencies
Solutioning	Architect + UX Designer (parallel)	Clean Architecture, DI structure, CoUI compliance, layout
Implementation	Flutter/Backend Developer, Scrum Master	Branch rules, lint pass, tests, code review

Persona Introduction#

7 Specialized Personas#

Persona	Role	Assigned Phase
Analyst	Requirements analysis, BDD Gherkin AC creation ⭐, feasibility review	Analysis
Product Manager	Issue structuring, Story Point estimation, priority setting	Planning
Architect	Architecture design review, API design, security review	Solutioning
UX Designer	UI/UX review, CoUI compliance, accessibility review	Solutioning
Flutter Developer	UI implementation, BLoC state management, test creation	Implementation
Backend Developer	Serverpod implementation, DB design, API development	Implementation
Scrum Master	Workflow management, blocker resolution, status sync	Implementation

Persona Definition Files#

Detailed definitions for each persona are located in the .claude/personas/ directory:

.claude/personas/
├── analyst.md
├── product-manager.md
├── architect.md
├── ux-designer.md
├── flutter-developer.md
├── backend-developer.md
└── scrum-master.md

Command Reference#

Main Commands#

`/bmad` - Execute full workflow

# Basic usage
/bmad  " Add author list screen " 

 # Activate specific gates only
/bmad --gates analysis,planning  " simple task " 

 # Emergency mode (streamlined gates, admin approval required)
/bmad --emergency  " production emergency fix " 

 # Disable parallel execution
/bmad --no-parallel  " sequential processing needed " 

 # Skip specific persona
/bmad --skip-persona ux-designer  " backend-only task "

`/dev:run --bmad` - Existing workflow integration

# Apply BMAD phase gates to existing dev:run
/dev:run --bmad  " Add author list screen "

Supporting Commands#

`/bmad:review` - Persona-specific review

# Request specific persona review
/bmad:review --persona architect  " current code review " 

 # Multi-persona simultaneous review
/bmad:review --persona architect,ux-designer  " design review " 

 # Re-review request (after failure)
/bmad:review --persona architect --retry

`/bmad:status` - Status check

# Check overall status
/bmad:status

# Check specific phase details
/bmad:status --phase solutioning

# Check specific issue status
/bmad:status --issue 1810

`/bmad:gate` - Gate verification

# Verify specific phase gate
/bmad:gate --phase analysis
/bmad:gate --phase solutioning

# Re-verification request
/bmad:gate --phase solutioning --retry

# Check all gate status
/bmad:gate --all

Options Summary#

Option	Default	Description
`--bmad`	`false`	Activate BMAD phase gates
`--gates`	All gates	Activate specific gates only
`--emergency`	`false`	Emergency mode (streamlined gates)
`--skip-persona`	-	Skip specific persona
`--no-parallel`	`false`	Disable parallel execution
`--retry`	`false`	Re-review/re-verification mode

Workflow Examples#

Example 1: New Feature Development#

# 1. Start BMAD workflow
/bmad  " Add author list screen " 

 # 2. Check Analysis result (auto-proceeds)
# - Analyst analyzes requirements
# - 3 AC defined
# - Gate 1 passed

# 3. Check Planning result (auto-proceeds)
# - PM creates issue #1810
# - Story Point: 5
# - Gate 2 passed

# 4. Check Solutioning result (parallel execution)
# - Architect: Clean Architecture review ✅
# - UX Designer: CoUI compliance review ✅
# - Gate 3 passed

# 5. Implementation proceeds (auto-proceeds)
# - Branch creation: feature/1810-author-list
# - Code implementation
# - Test creation/execution
# - PR #1815 created
# - Code review complete
# - Gate 4 passed

# 6. Complete
# - PR merge
# - Issue close

Example 2: Gate Failure and Re-review#

# 1. Solutioning Gate failure during workflow
# Output:
# ╔════════════════════════════════════════════════════════════════╗
# ║  Solutioning Gate: ❌ FAILED                                   ║
# ╠════════════════════════════════════════════════════════════════╣
# ║  🏗️ Architect review: ❌ FAILED                                  ║
# ║  ├── ❌ DI structure: BLoC directly accesses Repository           ║
# ║  └── Required actions: Create UseCase and change dependency          ║
# ╚════════════════════════════════════════════════════════════════╝

# 2. Fix code based on feedback
# (Create UseCase, fix BLoC)

# 3. Request re-review
/bmad:review --persona architect --retry

# 4. Auto-proceed to next step on re-review pass

Example 3: Emergency Fix#

# Run workflow in emergency mode
# (Analysis, Planning gates streamlined)
/bmad --emergency  " production payment bug emergency fix " 

 # ⚠️ Note: Emergency mode requires admin approval
# ⚠️ Post-review required

Configuration Customization#

Configuration File Location#

.claude/config/bmad.json       # BMAD configuration
.claude/config/bmad-schema.json # Configuration schema

Key Configuration Items#

{
   " enabled " : true,
   " defaultMode " :  " optional " ,

   " gates " : {
     " analysis " : {  " enabled " : true,  " mandatory " : true },
     " planning " : {  " enabled " : true,  " mandatory " : true },
     " solutioning " : {
       " enabled " : true,
       " mandatory " : true,
       " parallelPersonas " : [ " architect " ,  " ux-designer " ]
    },
     " implementation " : {  " enabled " : true,  " mandatory " : true }
  },

   " personas " : {
     " analyst " : {  " enabled " : true },
     " product-manager " : {  " enabled " : true },
     " architect " : {  " enabled " : true },
     " ux-designer " : {  " enabled " : true },
     " flutter-developer " : {  " enabled " : true },
     " backend-developer " : {  " enabled " : true },
     " scrum-master " : {  " enabled " : true }
  },

   " emergency " : {
     " allowBypass " : true,
     " requireApproval " : true
  },

   " parallelExecution " : {
     " enabled " : true,
     " maxConcurrency " : 2
  }
}

Configuration Change Examples#

Disable a Specific Persona

{
   " personas " : {
     " ux-designer " : {  " enabled " : false }
  }
}

Disable Parallel Execution

{
   " parallelExecution " : {
     " enabled " : false
  }
}

Troubleshooting#

Frequently Asked Questions#

Q: The gate keeps failing

A: Check the feedback, fix all items, then request a re-review.

# Check feedback
/bmad:status --phase solutioning

# Re-review after fixing
/bmad:review --persona architect --retry

Q: I want to skip a specific persona review

A: Use the --skip-persona option or disable it in configuration.

# Via command option
/bmad --skip-persona ux-designer  " backend-only task " 

 # Or in configuration file
# .claude/config/bmad.json
{
   " personas " : {
     " ux-designer " : {  " enabled " : false }
  }
}

Q: I want to bypass gates in an emergency

A: Use the --emergency option. Note that admin approval and post-review are required.

/bmad --emergency  " emergency fix "

Error Code Reference#

Code	Description	Resolution
`BMAD_001`	Analysis Gate failure	Clarify requirements, then re-review
`BMAD_002`	Planning Gate failure	Fix issue structure, then re-review
`BMAD_003`	Solutioning Gate failure	Fix design, then re-review
`BMAD_004`	Implementation Gate failure	Fix code, then re-review
`BMAD_010`	Persona disabled	Enable persona in configuration
`BMAD_011`	Parallel execution failure	Switch to sequential execution
`BMAD_020`	Emergency mode abuse	Admin approval required

User Guide#

Document	Description
`BMAD_QUICKREF.md`	5-minute quick reference guide
`BMAD_TUTORIAL.md`	Step-by-step tutorial

Developer Reference#

Document	Description
`.claude/skills/bmad/SKILL.md`	BMAD skill definition
`.claude/skills/bmad/REFERENCE.md`	Detailed reference
`.claude/orchestrators/bmad-orchestrator.md`	Orchestrator
`.claude/orchestrators/phase-gates.md`	Gate definitions
`.claude/references/PERSONA_MATRIX.md`	Persona responsibility matrix
`.claude/personas/`	Persona definition directory (7 files)