LogoSkills

bmad-integration Reference

Detailed reference document for the BMAD framework.

BMAD Reference#

Detailed reference document for the BMAD framework.

Persona Details#

Analyst#

File: .claude/personas/analyst.md

ItemContent
PhaseAnalysis
RoleRequirements analysis, Acceptance Criteria definition, feasibility review
Review Items Requirements clarity, scope appropriateness, Acceptance Criteria testability
Linked Agentsfigma-analyzer-agent, bdd-scenario-agent

Product Manager (PM)#

File: .claude/personas/product-manager.md

ItemContent
PhasePlanning
RoleIssue structuring, Story Point estimation, priority setting
Review ItemsEpic/Story structure, Story Point (1-8), labeling, dependencies
Linked Agentszenhub-integration-agent

Architect#

File: .claude/personas/architect.md

ItemContent
PhaseSolutioning
RoleArchitecture design, API design, technology selection
Review ItemsClean Architecture, DI structure, API design, security
Linked Agentscode-review

UX Designer#

File: .claude/personas/ux-designer.md

ItemContent
PhaseSolutioning
RoleUI/UX review, accessibility review
Review ItemsCoUI compliance, layout, interaction, accessibility
Linked Agentsflutter-ui, widgetbook-agent

Flutter Developer#

File: .claude/personas/flutter-developer.md

ItemContent
PhaseImplementation
RoleUI implementation, BLoC state management, test creation
Review ItemsBLoC pattern, CoUI usage, widget patterns, routing, i18n
Linked Agentsfeature-orchestrator-agent, presentation-layer-agent

Backend Developer#

File: .claude/personas/backend-developer.md

ItemContent
PhaseImplementation
RoleOpenAPI client integration, data mapping
Review ItemsMapper definition, API communication, error handling
Linked Agentsdata-layer-agent

Scrum Master#

File: .claude/personas/scrum-master.md

ItemContent
PhaseImplementation
RoleWorkflow management, blocker resolution, status sync
Review ItemsStep progress, verification gates, Pipeline status, blockers
Linked Agentssequential-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.json does 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#

OptionDefaultDescription
enabledtrueEnable BMAD framework
defaultMode optional Default mode (optional, mandatory, disabled)
gates.{phase}.enabledtrueEnable 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.maxRetries3Maximum retry count
feedback.autoFix.enabledtrueEnable 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#

OptionDefaultDescription
quickMode.enabledtrueEnable Quick mode
quickMode.skipPhases["planning"]Phases to skip
quickMode.simplifyPhases ["analysis", "solutioning"] Phases to streamline
prCycle.autoCreatetrueAuto-create PR
prCycle.autoReviewtrueAuto-execute code review
prCycle.autoFix true Auto-apply review improvements
prCycle.autoMergetrueAuto-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#

CodeDescriptionResolution
BMAD_001 Analysis Gate failure Clarify requirements, then re-review
BMAD_002 Planning Gate failure Fix issue structure, then re-review
BMAD_003Solutioning Gate failureFix design, then re-review
BMAD_004Implementation Gate failureFix code, then re-review
BMAD_010Persona disabledEnable persona in configuration
BMAD_011 Parallel execution failure Switch to sequential execution
BMAD_020Emergency mode abuseAdmin approval required
BMAD_030 Quick mode PR creation failure Check branch/commit status
BMAD_031 Quick mode review failure Code quality improvement needed
BMAD_032Quick mode merge failureConflict resolution needed

Best Practices#

  • ✅ 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

  • .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