bmad-skill

name

bmad-skill

description

This skill should be used when working with BMAD (BMad-CORE) v6-alpha projects. BMAD is a universal human-AI collaboration platform with specialized modules for software development (BMM), agent building (BMB), creative intelligence (CIS), and project management (BMD). Use this skill to understand agent workflows, command patterns, scale-adaptive methodology, and effective utilization of the four-phase development system.

BMAD v6-Alpha Skill

What is BMAD-CORE?

BMAD-CORE (Collaboration Optimized Reflection Engine) is a revolutionary framework that amplifies human potential through specialized AI agents. Unlike traditional AI tools that replace human thinking, BMAD-CORE guides through reflective workflows that bring out the best ideas in both human and AI.

Core Philosophy:

• Collaboration: Human-AI partnership where both contribute unique strengths
• Optimized: Refined processes for maximum effectiveness
• Reflection: Guided thinking that unlocks better solutions
• Engine: Powerful framework orchestrating specialized agents and workflows

BMAD v6-Alpha Architecture

Module System

BMAD organizes capabilities into four main modules:

1. Core Module (Always Installed)

Foundation powering all modules:

• BMad Master Agent - Universal orchestrator and task executor
• Party Mode - Multi-agent collaborative sessions
• Brainstorming Workflow - Core ideation capabilities
• Configuration System - User preferences and settings

Location: bmad/core/

2. BMM Module - BMad Method (Software Development)

Revolutionary agile software development with Scale Adaptive Workflow Engine™:

• 10 Specialized Agents: Analyst, PM, Architect, SM, Dev, Game Designer, Game Architect, Game Dev, UX Designer, TEA (Test Architect)
• Four-Phase Methodology: Analysis → Planning → Solutioning → Implementation
• Scale Levels 0-4: From single changes to enterprise projects
• Just-In-Time Design: Create specs one epic at a time
• Story State Machine: Automated story progression (BACKLOG → TODO → IN PROGRESS → DONE)

Location: bmad/bmm/ (if installed)

3. BMB Module - BMad Builder (Custom Development)

Tools for creating custom agents, workflows, and modules:

• Builder Agent - Guides creation of custom components
• 7 Builder Workflows: create-agent, create-workflow, create-module, audit-workflow, edit-workflow, module-brief, redoc
• Three Agent Types: Full module agents, hybrid agents, standalone agents

Location: bmad/bmb/ (if installed)

4. CIS Module - Creative Intelligence Suite

Innovation and creative problem-solving:

• 5 Specialized Agents: Brainstorming Coach (Carson), Design Thinking Coach (Maya), Problem Solver (Dr. Quinn), Innovation Strategist (Victor), Storyteller (Sophia)
• 150+ Creative Techniques: Across brainstorming, design thinking, problem-solving, innovation strategy, storytelling
• Energy-Aware Sessions: Adapts to user engagement

Location: bmad/cis/ (shared resources appear even if not explicitly selected)

5. BMD Module - BMad Development (Project Management)

Internal tools for BMAD development itself:

• CLI Chief - Command-line management
• Doc Keeper - Documentation management
• Release Chief - Release management

Location: bmd/ (development only)

Installation Structure

All modules install to a single unified bmad/ folder:

your-project/
└── bmad/
    ├── core/           # Core framework (always present)
    ├── bmm/            # BMad Method (if selected)
    ├── bmb/            # BMad Builder (if selected)
    ├── cis/            # Creative Intelligence (shared resources)
    ├── _cfg/           # Your customizations
    │   ├── agents/     # Agent sidecar files
    │   └── manifest.yaml
    └── [module]/config.yaml  # Per-module configuration

Working with BMAD Agents

Agent Activation Methods

Method 1: Claude Code Slash Commands (Recommended)

When BMAD is installed locally in .claude/commands/bmad/, use these slash commands:

# Core Module
/bmad:bmad:core:agents:bmad-master
/bmad:bmad:core:workflows:brainstorming
/bmad:bmad:core:workflows:party-mode

# BMM Module Agents
/bmad:bmad:bmm:agents:analyst      # Business Analyst - Phase 1
/bmad:bmad:bmm:agents:pm           # Product Manager - Phase 2
/bmad:bmad:bmm:agents:architect    # Architect - Phase 3
/bmad:bmad:bmm:agents:sm           # Scrum Master - Phase 4
/bmad:bmad:bmm:agents:dev          # Developer - Phase 4
/bmad:bmad:bmm:agents:game-designer    # Game projects
/bmad:bmad:bmm:agents:game-architect   # Game architecture
/bmad:bmad:bmm:agents:game-dev         # Game development
/bmad:bmad:bmm:agents:ux-designer      # UX design
/bmad:bmad:bmm:agents:tea              # Test Architect

# BMB Module
/bmad:bmad:bmb:agents:bmad-builder     # Builder agent

# BMB Workflows (Direct Access)
/bmad:bmad:bmb:workflows:create-agent
/bmad:bmad:bmb:workflows:create-workflow
/bmad:bmad:bmb:workflows:create-module
/bmad:bmad:bmb:workflows:audit-workflow
/bmad:bmad:bmb:workflows:edit-workflow
/bmad:bmad:bmb:workflows:module-brief
/bmad:bmad:bmb:workflows:redoc
/bmad:bmad:bmb:workflows:convert-legacy

# BMD Module (Development/Management)
/bmad:bmad:bmd:agents:cli-chief
/bmad:bmad:bmd:agents:doc-keeper
/bmad:bmad:bmd:agents:release-chief

Local Installation Location: /Users/mikhail/.claude/commands/bmad/

Method 2: Direct File Loading

• Drag and drop agent file from .claude/commands/bmad/
• Use @ mention with agent file path
• Navigate to agent file in your IDE's file browser

Method 3: BMad Master Orchestrator Load BMad Master first, then use menu to access specific agents or workflows.

Agent Structure

All BMAD agents follow a consistent YAML structure:

agent:
  metadata:
    id: bmad/[module]/agents/[name].md
    name: AgentName
    title: Agent Title
    icon: 🎯
    module: [bmm|bmb|cis|core]

  persona:
    role: Primary Role + Secondary Expertise
    identity: Background and experience description
    communication_style: How the agent communicates
    principles:
      - Guiding principle 1
      - Guiding principle 2

  menu:
    - trigger: command-name
      workflow: "{project-root}/bmad/[module]/workflows/[workflow]/workflow.yaml"
      description: What this command does

Common Agent Commands

Every agent has these built-in commands:

• *help - Show agent's menu
• *exit - Exit agent with confirmation

Module-specific commands use asterisk prefix:

• Analyst: *workflow-status, *brainstorm-project, *research, *product-brief
• PM: *workflow-status, *prd, *tech-spec, *gdd (games)
• Architect: *architecture, *tech-spec
• SM: *create-story, *story-ready, *story-context, *story-done, *retrospective
• Dev: *dev-story, *review-story, *story-done

BMM: The Four-Phase Software Development Methodology

Universal Entry Point: workflow-status

ALWAYS START HERE! Before beginning any workflow:

# Load Analyst or PM agent, then:
*workflow-status

What it does:

• ✅ Checks for existing workflow status file
• ✅ Displays current phase, progress, and next action
• ✅ Guides new projects to appropriate workflows
• ✅ Routes brownfield projects to documentation first
• ✅ Provides clear recommendations for next steps

Phase 1: Analysis (Optional)

Purpose: Project discovery and requirements gathering

Agents: Analyst, Game Designer

Workflows:

• brainstorm-project - Software solution exploration
• brainstorm-game - Game concept ideation (5 methodologies)
• research - Multi-mode research (market/technical/deep)
• product-brief - Strategic product planning
• game-brief - Structured game design foundation

When to use: New projects needing concept development

Phase 2: Planning (Required)

Purpose: Scale-adaptive planning with appropriate documentation

Agents: PM, Game Designer

Scale Levels:

Level	Scope	Stories	Outputs	Next Phase
0	Single atomic change	1	tech-spec.md + story	Implementation
1	Simple feature	2-10	tech-spec.md + epic + stories	Implementation
2	Focused project	5-15 (1-2 epics)	PRD.md + epics.md	Tech-spec → Implementation
3	Complex project	12-40 (2-5 epics)	PRD.md + epics.md	Solutioning → Implementation
4	Enterprise scale	40+ (5+ epics)	PRD.md + epics.md	Solutioning → Implementation

Software Projects:

• Level 0-1: *tech-spec (Architect) → Implementation
• Level 2: *prd (PM) → *tech-spec → Implementation
• Level 3-4: *prd (PM) → Solutioning → Implementation

Game Projects:

• All Levels: *gdd (Game Designer) → Optional narrative → Solutioning or Implementation

Key Outputs:

• bmm-workflow-status.md - Versioned workflow state with story backlog
• PRD.md - Product Requirements (L2-4)
• epics.md - Epic breakdown (L2-4)
• tech-spec.md - Technical specification (L0-2)
• story-*.md - User story files

Phase 3: Solutioning (Levels 3-4 Only)

Purpose: Architecture and technical design for complex projects

Agents: Architect, Game Architect

Workflows:

• architecture - Create overall architecture.md with ADRs
• tech-spec - Create epic-specific tech specs (JIT - Just-In-Time)

Just-In-Time Approach:

FOR each epic in sequence:
    WHEN ready to implement epic:
        Architect: Run *tech-spec for THIS epic only
        → Creates tech-spec-epic-N.md
    IMPLEMENT epic completely
    THEN move to next epic

Critical: Tech specs created ONE AT A TIME, not all upfront. This prevents over-engineering and incorporates learning.

Phase 4: Implementation (Iterative)

Purpose: Transform requirements into working software

Agents: SM (Scrum Master), Dev (Developer)

The Story State Machine:

BACKLOG → TODO → IN PROGRESS → DONE

State Definitions:

• BACKLOG: Ordered list of stories awaiting drafting (populated at phase transition)
• TODO: Single story needing drafting or awaiting approval
• IN PROGRESS: Single story approved for development
• DONE: Completed stories with dates and points

Implementation Loop:

1. SM: *create-story (drafts story from TODO)
   → Story file created with Status="Draft"

2. USER REVIEWS STORY

3. SM: *story-ready (approves story)
   → TODO → IN PROGRESS
   → BACKLOG → TODO (next story)
   → Story Status = "Ready"

4. SM: *story-context (optional but recommended)
   → Generates expertise injection XML

5. DEV: *dev-story (implements story)
   → Reads IN PROGRESS section
   → Implements with context guidance

6. USER REVIEWS IMPLEMENTATION

7. DEV: *story-done (marks complete)
   → IN PROGRESS → DONE
   → TODO → IN PROGRESS (if exists)
   → BACKLOG → TODO (if exists)
   → Story Status = "Done"

8. REPEAT until all stories complete

9. SM: *retrospective (after epic complete)
   → Captures learnings for next epic

Key Workflows:

• create-story - SM drafts story from TODO
• story-ready - SM approves story for dev (after user review)
• story-context - SM generates contextual expertise
• dev-story - DEV implements story
• story-done - DEV marks story complete (after user confirms DoD)
• review-story - Quality validation (optional)
• correct-course - Handle issues/changes
• retrospective - Capture epic learnings

Critical Rule: Agents NEVER search for "next story" - they ALWAYS read from status file.

Working with Workflows

Workflow Execution

Workflows are executed through agent menus:

1. Load agent (Analyst, PM, Architect, SM, Dev, etc.)
2. Agent shows menu with available commands
3. Enter command (e.g., *prd, *create-story)
4. Agent loads and executes workflow.yaml
5. Workflow guides through structured steps

Workflow Structure

All workflows are YAML-based with consistent structure:

workflow:
  metadata:
    id: workflow-unique-id
    name: Workflow Name
    version: 1.0.0

  config:
    output_folder: "{output_folder}"

  steps:
    - name: Step Name
      prompt: |
        Detailed instructions for this step

Key Workflow Patterns

Validation Workflows: Use validate-workflow handler

- trigger: validate-tech-spec
  validate-workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
  checklist: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/checklist.md"
  document: "{output_folder}/tech-spec.md"

Data-Driven Workflows: Use data parameter

- trigger: command-name
  workflow: "{project-root}/bmad/[module]/workflows/[name]/workflow.yaml"
  data: "{output_folder}/context.md"

BMB: Building Custom Components

Creating Custom Agents

Load BMad Builder agent, then use:

• *create-agent - Design and implement custom agents
• *create-workflow - Build new workflow definitions
• *create-module - Design custom modules

Agent Types

1. Full Module Agents: Complete agents embedded in modules

• Location: src/modules/[module]/agents/
• Example: PM, Analyst, Architect

2. Hybrid Agents: Shared across modules

• Location: Shared agent directories
• Example: Brainstorming agents used by multiple modules

3. Standalone Agents: Tiny, specialized agents

• Location: Independent of modules
• Example: Single-purpose utility agents

Builder Workflows

• audit-workflow - Review and validate workflows
• edit-workflow - Modify existing workflows
• module-brief - Document module specifications
• redoc - Regenerate documentation
• convert-legacy - Migrate legacy formats

CIS: Creative Intelligence

CIS Agents and Workflows

5 Specialized Agents with unique personas:

• Carson - Brainstorming Coach (energetic facilitator)
• Maya - Design Thinking Maestro (jazz-like improviser)
• Dr. Quinn - Problem Solver (detective-scientist)
• Victor - Innovation Strategist (strategic precision)
• Sophia - Storyteller (whimsical narrator)

5 Interactive Workflows:

• brainstorming - 36 creative techniques across 7 categories
• design-thinking - 5-phase human-centered design
• problem-solving - Root cause analysis and solution generation
• innovation-strategy - Business model innovation
• storytelling - 25 story frameworks

Using CIS

CIS workflows can be:

1. Invoked directly via CIS agents
2. Embedded in other modules (BMM uses brainstorming)
3. Used standalone for creative sessions

Best Practices

DO's

✅ Always start with *workflow-status - Universal entry point ✅ Respect the scale levels - Don't over-document small projects ✅ Use Just-In-Time design - Create tech specs one epic at a time ✅ Follow the story state machine - Never skip state transitions ✅ Run retrospectives - After each epic for continuous learning ✅ Generate story-context - Provides targeted expertise ✅ Validate before advancing - User reviews stories and implementations ✅ Document brownfield first - Never plan without understanding existing code

DON'Ts

❌ Don't skip workflow-status check - It guides your entire journey ❌ Don't create all tech specs upfront - Use JIT approach ❌ Don't batch story creation - One at a time through state machine ❌ Don't manually track stories - Let state machine manage progression ❌ Don't plan brownfield without docs - Run analysis first ❌ Don't over-document Level 0-1 - Simple projects need minimal docs ❌ Don't skip Phase 3 for Level 3-4 - Architecture is critical

Configuration and Customization

Module Configuration

Each module has config.yaml with:

project_name: "Your Project"
output_folder: "./docs/bmad"
user_name: "Your Name"
communication_language: "English"
technical_level: "intermediate"  # BMM specific

Location: bmad/[module]/config.yaml

Agent Customization (Sidecar Files)

Customize any agent via sidecar files in bmad/_cfg/agents/:

# bmad/_cfg/agents/core-bmad-master.customize.yaml
customizations:
  persona:
    name: "CustomName"
    communication_style: "Your preferred style"

  menu:
    - trigger: custom-command
      workflow: "{project-root}/path/to/custom/workflow.yaml"
      description: "Custom functionality"

Update-Safe: Customizations persist through BMAD updates

Multi-Language Support

Agents communicate in configured language:

• Set in module config.yaml: communication_language: "Spanish"
• Agents automatically adapt communication
• Documentation output can use different language

Troubleshooting Common Issues

"Workflow status file not found"

→ Run *workflow-status first to initialize

"Story not in expected state"

→ Check bmm-workflow-status.md - verify story is in correct section

"Can't find next story"

→ Agents don't search - they read from status file sections

"Brownfield planning fails"

→ Run documentation workflow first (coming soon: brownfield-analysis)

"Over-documented small project"

→ Check scale level - Level 0-1 should skip PRD and architecture

"Tech specs created all at once"

→ Use JIT approach - one epic at a time during implementation

Quick Reference

Essential Commands by Agent

Analyst:

• *workflow-status - Check status
• *brainstorm-project - Ideation
• *research - Market/technical research
• *product-brief - Product strategy

PM:

• *workflow-status - Check status
• *prd - Create PRD (L2-4)
• *tech-spec - Create tech spec (L0-2)
• *gdd - Game design document

Architect:

• *architecture - Overall architecture (L3-4)
• *tech-spec - Epic-specific specs (JIT)

SM:

• *create-story - Draft story
• *story-ready - Approve story
• *story-context - Generate expertise
• *retrospective - Capture learnings

Dev:

• *dev-story - Implement story
• *review-story - Quality check
• *story-done - Mark complete

BMad Builder:

• *create-agent - Build custom agent
• *create-workflow - Build workflow
• *create-module - Build module

File Locations

Config: bmad/[module]/config.yaml Agents: bmad/[module]/agents/ Workflows: bmad/[module]/workflows/ Tasks: bmad/core/tasks/ Customizations: bmad/_cfg/agents/ Status Tracking: {output_folder}/bmm-workflow-status.md

Support Resources

• 💬 Discord Community
• 🐛 Issue Tracker
• 🎥 YouTube Tutorials
• 📚 Full Documentation

---

Framework: BMAD-CORE v6-alpha | Version: Alpha | Branch: v6-alpha