Command Overview#

Purpose: Set up BMAD Method v6 structure and configuration in the current project

Agent: BMad Master (Core Orchestrator)

Output:

• bmad/config.yaml - Project configuration
• .bmad/bmm-workflow-status.yaml - Workflow status tracking
• Directory structure for BMAD artifacts

Execution Steps#

Step 1: Check for Existing Installation#

1. Check if bmad/config.yaml exists
2. If exists:
   • Read current config
   • Ask: "BMAD already initialized. Reinitialize (overwrites config)?"
   • If no → Exit
   • If yes → Continue

Step 2: Create Directory Structure#

Create the following directories using Write/Bash tool:

bmad/
├── config.yaml
└── agent-overrides/

.bmad/
├── bmm-workflow-status.yaml
└── stories/
    └── (story directories created as needed)

.claude/
└── commands/
    └── bmad/
        └── (commands auto-registered by Claude Code)

Note: Only create directories that don't exist. Use mkdir -p to be safe.

Step 3: Collect Project Information#

Ask user these questions (one at a time):

Q1: Project Name

" What is your project name? " 

 Examples:  " MyApp " ,  " E-Commerce Platform " ,  " Mobile Game " 
 Default: Use directory name if user skips

Q2: Project Type

" What type of project is this? " 

 Options (present as menu):
1. Web Application
2. Mobile App (iOS/Android)
3. API / Backend Service
4. Game
5. Library / Framework
6. Other

Store as:  " web-app " ,  " mobile-app " ,  " api " ,  " game " ,  " library " ,  " other "

Q3: Project Level

" What is the project complexity level? " 

 Explain levels:
- Level 0: Single atomic change (1 story)
- Level 1: Small feature set (1-10 stories)
- Level 2: Medium feature set (5-15 stories)
- Level 3: Complex integration (12-40 stories)
- Level 4: Enterprise expansion (40+ stories)

Options (present as menu):
0. Level 0 - Single story
1. Level 1 - Small (1-10 stories)
2. Level 2 - Medium (5-15 stories)
3. Level 3 - Complex (12-40 stories)
4. Level 4 - Enterprise (40+ stories)

Store as: 0, 1, 2, 3, or 4

Step 4: Create Project Config#

1. Load global config from ~/.claude/config/bmad/config.yaml per helpers.md#Load-Global-Config

2. Load template from ${CLAUDE_PLUGIN_ROOT}/references/project-config-template.md

3. Substitute variables:

   • {{PROJECT_NAME}} → User input from Step 3
   • {{PROJECT_TYPE}} → User input from Step 3
   • {{PROJECT_LEVEL}} → User input from Step 3

4. Write to bmad/config.yaml using Write tool

Example output:

project_name:  " MyApp " 
 project_type:  " web-app " 
 project_level: 2
output_folder:  " .bmad " 
 bmm:
  workflow_status_file:  " .bmad/bmm-workflow-status.yaml " 
   sprint_status_file:  " .bmad/sprint-status.yaml " 
 paths:
  docs:  " .bmad " 
   stories:  " .bmad/stories " 
   tests:  " tests "

Step 5: Create Workflow Status File#

1. Load template from ${CLAUDE_PLUGIN_ROOT}/references/templates/bmm-workflow-status-template.md

2. Determine conditional statuses based on project level:

       Level 0-1:
     - PRD:  " recommended "   (optional for level 0)
     - Tech-spec:  " required " 
      - Architecture:  " optional " 
   
    Level 2+:
     - PRD:  " required " 
      - Tech-spec:  " optional " 
      - Architecture:  " required " 
   

3. Substitute variables:

   • {{TIMESTAMP}} → Current ISO timestamp
   • {{PROJECT_NAME}} → From project config
   • {{PROJECT_TYPE}} → From project config
   • {{PROJECT_LEVEL}} → From project config
   • {{PRD_STATUS}} → Conditional per above
   • {{TECH_SPEC_STATUS}} → Conditional per above
   • {{ARCHITECTURE_STATUS}} → Conditional per above

4. Write to .bmad/bmm-workflow-status.yaml using Write tool

Step 5.5: ZenHub Integration Setup (Optional)#

Ask user:

" Would you like to set up ZenHub integration? " 

 ZenHub integration enables:
- Automatic issue creation (Epics, Stories, Sub-tasks)
- Pipeline management (Sprint Backlog → In Progress → Done)
- Sprint assignment and tracking
- Sub-task decomposition for complex stories

Options:
1. Yes - Set up ZenHub integration
2. No - Skip (can be configured later)

If yes:

1. Check MCP availability:

   • Attempt helpers.md#Load-ZenHub-Context
   • If MCP available:
     • Auto-discover workspace IDs
     • Auto-generate bmad/zenhub-conventions.yaml from MCP data
     • Log: "✓ ZenHub conventions auto-generated from workspace"
   • If MCP not available:
     • Copy template: ${CLAUDE_PLUGIN_ROOT}/references/templates/zenhub-conventions-template.md → bmad/zenhub-conventions.yaml
     • Log: "⚠ ZenHub MCP not available. Template created — fill in IDs manually or run again when MCP is configured."

2. Ask about Sub-tasks:

       " Does your ZenHub workspace support Sub-tasks (Task issue type)? " 
   
    Options:
   1. Yes - Enable sub-task decomposition
   2. No / Not sure - Disable (can enable later)
   

3. Update project config (bmad/config.yaml):

       zenhub:
     conventions_file:  " bmad/zenhub-conventions.yaml " 
      sub_tasks:
       enabled: {true|false}
       auto_generate: false
       min_story_points: 5
   

If no: Skip — ZenHub integration can be configured later by:

• Creating bmad/zenhub-conventions.yaml from template
• Adding zenhub: section to bmad/config.yaml

Step 6: Confirm Initialization#

Display success message:

✓ BMAD Method v6 initialized successfully!

Project Configuration:
  Name: {project_name}
  Type: {project_type}
  Level: {project_level}

Files Created:
  ✓ bmad/config.yaml
  ✓ .bmad/bmm-workflow-status.yaml
  ✓ Directory structure
  ✓ bmad/zenhub-conventions.yaml  (if ZenHub setup chosen)

Workflow Path for Level {project_level}:
  {Display path based on level - see Step 7}

Recommended Next Step:
  {Recommend workflow - see helpers.md#Determine-Next-Workflow}

Step 7: Recommend Workflow Path#

Based on project level, show recommended path:

Level 0:

Phase 1 (Optional): /product-brief
Phase 2 (Required): /tech-spec
Phase 4 (Required): /create-story → /dev-story

Level 1:

Phase 1 (Recommended): /product-brief
Phase 2 (Required): /tech-spec
Phase 4 (Required): /sprint-planning → stories

Level 2+:

Phase 1 (Recommended): /product-brief
Phase 2 (Required): /prd
Phase 3 (Required): /architecture
Phase 4 (Required): /sprint-planning → stories

Step 8: Offer to Start#

Ask user:

" Would you like to start with the recommended workflow? " 

 If Phase 1 recommended:  " I can help you create a product brief. " 
 If Phase 2 required:  " I can help you create a [PRD/tech-spec]. "

If yes: Hand off to appropriate agent (Analyst for brief, PM for PRD/tech-spec) If no: "Run /workflow-status anytime to check your progress."

Helper References#

• Load global config: helpers.md#Load-Global-Config
• Load template: helpers.md#Load-Template
• Apply variables: helpers.md#Apply-Variables-to-Template
• Save document: helpers.md#Save-Output-Document
• Determine next: helpers.md#Determine-Next-Workflow
• Load ZenHub context: helpers.md#Load-ZenHub-Context

Error Handling#

If BMAD already initialized:

• Inform user
• Offer to reinitialize (overwrites config)
• Offer to check status instead (/workflow-status)

If directory creation fails:

• Show error
• Check permissions
• Suggest manual directory creation

If template missing:

• Use inline fallback template
• Log warning
• Continue initialization

Notes for LLMs#

• Use TodoWrite to track 8 steps
• Create directories with mkdir -p (safe for existing dirs)
• Be clear about conditional requirements based on level
• Present options as numbered menus for clarity
• Use Write tool for config/status files
• Maintain BMad Master persona (helpful, organized, clear)
• Don't skip steps - initialization must be complete

Remember: This is the entry point for BMAD. Set users up for success with clear explanation of their path forward.