BMAD Reference#
Detailed reference document for the BMAD framework.
Persona Details#
Analyst#
File: .claude/personas/analyst.md
| Item | Content |
|---|---|
| Phase | Analysis |
| Role | Requirements analysis, Acceptance Criteria definition, feasibility review |
| Review Items | Requirements clarity, scope appropriateness, Acceptance Criteria testability |
| Linked Agents | figma-analyzer-agent, bdd-scenario-agent |
Product Manager (PM)#
File: .claude/personas/product-manager.md
| Item | Content |
|---|---|
| Phase | Planning |
| Role | Issue structuring, Story Point estimation, priority setting |
| Review Items | Epic/Story structure, Story Point (1-8), labeling, dependencies |
| Linked Agents | zenhub-integration-agent |
Architect#
File: .claude/personas/architect.md
| Item | Content |
|---|---|
| Phase | Solutioning |
| Role | Architecture design, API design, technology selection |
| Review Items | Clean Architecture, DI structure, API design, security |
| Linked Agents | code-review |
UX Designer#
File: .claude/personas/ux-designer.md
| Item | Content |
|---|---|
| Phase | Solutioning |
| Role | UI/UX review, accessibility review |
| Review Items | CoUI compliance, layout, interaction, accessibility |
| Linked Agents | flutter-ui, widgetbook-agent |
Flutter Developer#
File: .claude/personas/flutter-developer.md
| Item | Content |
|---|---|
| Phase | Implementation |
| Role | UI implementation, BLoC state management, test creation |
| Review Items | BLoC pattern, CoUI usage, widget patterns, routing, i18n |
| Linked Agents | feature-orchestrator-agent, presentation-layer-agent |
Backend Developer#
File: .claude/personas/backend-developer.md
| Item | Content |
|---|---|
| Phase | Implementation |
| Role | OpenAPI client integration, data mapping |
| Review Items | Mapper definition, API communication, error handling |
| Linked Agents | data-layer-agent |
Scrum Master#
File: .claude/personas/scrum-master.md
| Item | Content |
|---|---|
| Phase | Implementation |
| Role | Workflow management, blocker resolution, status sync |
| Review Items | Step progress, verification gates, Pipeline status, blockers |
| Linked Agents | sequential-workflow, issue-state-agent |
Gate Details#
Analysis Gate#
gate: analysis
persona: analyst
required_checks:
- requirement_clarity:
description: " Are requirements specific and measurable? "
failure_action: " Redefine requirements "
- scope_appropriateness:
description: " Is it an appropriate size for a single issue? "
failure_action: " Split or adjust "
- ac_testability:
description: " Are Acceptance Criteria automatable for testing? "
failure_action: " Revise Acceptance Criteria "
Planning Gate#
gate: planning
persona: product-manager
required_checks:
- epic_story_structure:
description: " Is the hierarchy structure appropriate? "
failure_action: " Redesign structure "
- story_point:
description: " Is it within 1-8 SP range? "
failure_action: " Re-estimate or split "
threshold:
min: 1
max: 8
split_required: 13
- labeling:
description: " Are Type and Scope labels present? "
required_labels: [ " type " , " scope " ]
failure_action: " Add labels "
- dependencies:
description: " Are blockers resolvable? "
failure_action: " Resolve dependencies "
Solutioning Gate#
gate: solutioning
personas: [architect, ux-designer]
execution: parallel
required_checks:
architect:
- clean_architecture:
description: " Is layer separation correct? "
layers: [presentation, domain, data]
- di_structure:
description: " Is Injectable registration complete? "
- api_design:
description: " Are naming/error handling standardized? "
condition: " when backend changes "
- security:
description: " Is authentication/authorization appropriate? "
ux_designer:
- coui_compliance:
description: " Are standard components used? "
- layout:
description: " Is spacing/alignment consistent? "
- interaction:
description: " Are loading/error/empty states handled? "
- accessibility:
description: " Does it meet WCAG 2.1 AA standards? "
required: false # recommended
Implementation Gate#
gate: implementation
personas: [flutter-developer, backend-developer, scrum-master]
sub_gates:
- step_4_branch:
description: " Is it a feature branch? "
pattern: " ^(feature|fix|refactor|chore)/[0-9]+ "
blocked_branches: [development, main]
- step_8_5_lint:
description: " dart/dcm analyze pass? "
commands:
- " dart format "
- " dcm format "
- " dart fix --apply "
- " dart analyze --no-fatal-infos "
- " dcm analyze --no-fatal-style "
- step_9_pr:
description: " PR creation conditions met? "
checks:
- branch_format
- issue_linked
- commits_exist
- lint_passed
MCP Tool Reference#
ZenHub Tools#
// Dynamic workspace info query (once per session)
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const repoId = workspace.repositories.find(r = > /* select GitHub repo */).id;
const issueTypes = await mcp__zenhub__getIssueTypes();
// Issue creation
mcp__zenhub__createGitHubIssue({
repositoryId: repoId,
title: " {type}({scope}): {gitmoji} {description} " ,
body: " ## Summary\n{content} " ,
issueTypeId: issueTypes.find(t = > t.name === " Feature " ).id,
labels: [ " {type} " , " {scope} " ],
})
// Pipeline movement
const inProgress = workspace.pipelines.find(p = > p.name === " In Progress " );
mcp__zenhub__moveIssueToPipeline({
issueId: " {issue.graphqlId} " ,
pipelineId: inProgress.id,
})
// Story Point setting
mcp__zenhub__setIssueEstimate({
issueId: " {issue_id} " ,
estimate: 5,
})
// Dependency setting
mcp__zenhub__createBlockage({
blockedIssueId: " {blocked_id} " ,
blockingIssueId: " {blocking_id} " ,
})
Pipeline Query#
Pipeline IDs differ per workspace. Use getWorkspacePipelinesAndRepositories() for dynamic lookup.
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
// workspace.pipelines â [{ id, name }, ...]
// Find by name: " Icebox " , " Product Backlog " , " Sprint Backlog " , " In Progress " , " Review/QA " , " Done "
Configuration Options#
Configuration File Location#
BMAD configuration is managed in a separate config file:
- Config file:
.claude/config/bmad.json - Schema file:
.claude/config/bmad-schema.json
â ď¸ Claude Code's
settings.jsondoes not allow custom fields due to schema validation. BMAD settings must use.claude/config/bmad.json.
bmad.json Configuration Example#
{
" version " : " 1.0.0 " ,
" 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, " phase " : " analysis " },
" product-manager " : { " enabled " : true, " phase " : " planning " },
" architect " : { " enabled " : true, " phase " : " solutioning " },
" ux-designer " : { " enabled " : true, " phase " : " solutioning " },
" flutter-developer " : { " enabled " : true, " phase " : " implementation " },
" backend-developer " : { " enabled " : true, " phase " : " implementation " },
" scrum-master " : { " enabled " : true, " phase " : " implementation " }
},
" emergency " : {
" allowBypass " : true,
" requireApproval " : true
},
" parallelExecution " : {
" enabled " : true,
" maxConcurrency " : 2
}
}
Options Description#
| Option | Default | Description |
|---|---|---|
enabled | true | Enable BMAD framework |
defaultMode |
optional |
Default mode (optional, mandatory, disabled) |
gates.{phase}.enabled | true | Enable the gate |
gates.{phase}.mandatory |
true |
Whether the gate is mandatory |
gates.solutioning.parallelPersonas |
["architect", "ux-designer"] |
Parallel execution personas |
personas.{persona}.enabled |
true |
Enable the persona |
personas.{persona}.phase |
Assigned phase | Phase the persona is responsible for |
personas.{persona}.linkedAgents |
Linked agents | List of agents linked to persona |
emergency.allowBypass |
true |
Allow gate bypass in emergency mode |
emergency.requireApproval |
true |
Require admin approval for emergency mode |
parallelExecution.enabled |
true |
Enable parallel execution |
parallelExecution.maxConcurrency |
2 |
Maximum concurrent executions |
feedback.maxRetries | 3 | Maximum retry count |
feedback.autoFix.enabled | true | Enable auto-fix |
Quick Mode Configuration#
bmad.json Quick Mode Configuration#
{
" quickMode " : {
" enabled " : true,
" skipPhases " : [ " planning " ],
" simplifyPhases " : [ " analysis " , " solutioning " ],
" prCycle " : {
" autoCreate " : true,
" autoReview " : true,
" autoFix " : true,
" autoMerge " : true,
" mergeMethod " : " squash " ,
" deleteSourceBranch " : true
},
" review " : {
" categories " : [
" architecture " ,
" state-management " ,
" security " ,
" performance " ,
" testing " ,
" readability " ,
" i18n " ,
" accessibility "
],
" autoFixSeverity " : [ " critical " , " improvements " ],
" skipSeverity " : [ " suggestions " ]
}
}
}
Quick Mode Option Details#
| Option | Default | Description |
|---|---|---|
quickMode.enabled | true | Enable Quick mode |
quickMode.skipPhases | ["planning"] | Phases to skip |
quickMode.simplifyPhases |
["analysis", "solutioning"] |
Phases to streamline |
prCycle.autoCreate | true | Auto-create PR |
prCycle.autoReview | true | Auto-execute code review |
prCycle.autoFix |
true |
Auto-apply review improvements |
prCycle.autoMerge | true | Auto-merge |
prCycle.mergeMethod |
"squash" |
Merge method (squash/merge/rebase) |
prCycle.deleteSourceBranch |
true |
Delete source branch after merge |
review.autoFixSeverity |
["critical", "improvements"] |
Severity levels to auto-fix |
review.skipSeverity |
["suggestions"] |
Severity levels to skip auto-fix |
Error Codes#
| 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 |
BMAD_030 |
Quick mode PR creation failure | Check branch/commit status |
BMAD_031 |
Quick mode review failure | Code quality improvement needed |
BMAD_032 | Quick mode merge failure | Conflict resolution needed |
Best Practices#
Do (Recommended)#
- â Clearly define Acceptance Criteria before starting work
- â Estimate Story Points based on team consensus
- â Execute parallelizable tasks in parallel
- â Carefully review gate failure feedback
- â Apply all feedback before requesting re-review
Don't (Prohibited)#
- â Attempting forced gate bypass
- â Emergency mode abuse
- â Skipping persona reviews
- â Requesting re-review without applying feedback
- â Direct commits to development/main
Related Documents#
.claude/config/bmad.json- BMAD configuration file.claude/config/bmad-schema.json- BMAD configuration schema.claude/orchestrators/bmad-orchestrator.md- Orchestrator.claude/orchestrators/phase-gates.md- Gate definitions.claude/personas/- Persona definitions.claude/skills/dev/SKILL.md- Existing workflow.claude/references/PERSONA_MATRIX.md- Persona responsibility matrix