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:

Load agent (Analyst, PM, Architect, SM, Dev, etc.)
Agent shows menu with available commands
Enter command (e.g., *prd, *create-story)
Agent loads and executes workflow.yaml
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:

Invoked directly via CIS agents
Embedded in other modules (BMM uses brainstorming)
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

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

bmad-skill