BMad Method

BMad Method Skill

> Use BMad framework for AI-driven development with autonomous agent workflows.

For detailed reference, see:

DEPENDENCY

This skill requires coding-agent skill with Claude Code installed.

Description

BMad (Breakthrough Method of Agile AI Driven Development) is a 4-phase framework: 1. Analysis — Explore the problem space 2. Planning — Define what to build 3. Solutioning — Decide how to build it 4. Implementation — Build it

Each phase produces documents that become context for the next phase.

Installation

To use BMad in a project:

> ⚠️ Security Note: npx bmad-method install fetches code from npm. Only run this if you trust the BMad package. Review the package before installing.

cd ~/project && npx bmad-method install

Select Claude Code when prompted.

⚠️ Installation is Interactive

⚠️ npx bmad-method install asks questions!

For installation:

| Prompt in Log | Expected Answer | Notes | |---------------|----------------|-------| | "Where should BMad be installed?" | . or ~path/to/project | Current directory | | "Which AI tool are you using?" | Claude Code or number | Select Claude | | "Select modules to install" | a or enter | Select all/default | | "Install BMad in current directory?" | y or enter | Confirm |

# Installation must be interactive!
bash pty:true workdir:~/project command:"cd ~/project && npx bmad-method install"
Stay present, answer each prompt:
- Monitor log for prompts
- Submit answer via: process action:submit sessionId:XXX data:"y"

⚠️ Pre-Flight Check

Before running any /bmad- command, verify BMad is installed:

ls -la ~/project/_bmad/  # or _bmad-output/

If not found → run installation first:

bash pty:true workdir:~/project command:"cd ~/project && npx bmad-method install"

Model Selection

Strategic model selection for efficiency:

| Model | Best Use Cases | |-------|----------------| | Sonnet | Architecture, Solutioning, Quick-dev (complex tasks) | | Haiku | Brainstorming, Story generation, Code review (repetitive/structured) | | Opus | Large refactoring, complex architecture decisions |

# Examples
claude --model sonnet "Create the architecture"
claude --model haiku "Generate stories from the epic"

Available Commands (via /bmad-)

| Command | Purpose | Output | |---------|---------|--------| | /bmad-help | Interactive guide | - | | /bmad-brainstorming | Brainstorm project ideas (use sparingly - see Notes) | brainstorming-report.md | | /bmad-bmm-create-prd | Define requirements | PRD.md | | /bmad-bmm-create-ux-design | Design UX | ux-spec.md | | /bmad-bmm-create-architecture | Technical decisions | architecture.md + ADRs | | /bmad-bmm-create-epics-and-stories | Break into stories | Epic files in _bmad-output/ | | /bmad-bmm-check-implementation-readiness | Gate check | PASS/CONCERNS/FAIL | | /bmad-bmm-sprint-planning | Initialize sprint | sprint-status.yaml | | /bmad-bmm-create-story | Prepare next story | story-[slug].md | | /bmad-bmm-dev-story | Implement story | Working code + tests | | /bmad-bmm-code-review | Validate quality | Approved/changes requested | | /bmad-bmm-quick-spec | Quick spec (skip phases 1-3) | tech-spec.md | | /bmad-bmm-quick-dev | Quick implementation | Working code |

⚠️ Important: Claude Code Execution

Use Non-Interactive Mode When Possible

For commands that don't need real-time interaction:

# Non-interactive (recommended for most BMad workflows)
claude -p --dangerously-skip-permissions "Your prompt"

When to Use Background Mode

Use background:true only when:

Always monitor with process action:log every 10-30 seconds to detect if Claude Code is waiting for input.

Permission Configuration

To avoid Claude Code blocking on permission requests:

> ⚠️ Security Note: Using --dangerously-skip-permissions or --permission-mode bypassPermissions suppresses permission checks. Use with caution - only for trusted code execution. For production workflows, prefer default permissions or validate the code first.

# Skip all permission prompts (use with caution!)
claude --dangerously-skip-permissions "prompt"
Or use specific permission mode
claude --permission-mode bypassPermissions "prompt"

Permission Loop Detection

If Claude Code waits for confirmation (Y/n, Commit, etc.):

1. Check the log: process action:log sessionId:XXX 2. Identify the type of prompt: - Shell command (Y/n): → submit "y" - Git commit proposal: → submit "n" (see below) - Other: → evaluate if you know the answer, otherwise ask user

Task Completion Detection (Background Mode)

How to know Claude Code is really done:

1. Success message in log: Look for "Task completed", "Done!", "All tasks finished" 2. Prompt available: The command prompt is back 3. Timeout: If log is silent for 2+ minutes without completion message → check process:

   ps aux | grep claude
   process action:log sessionId:XXX
   

⚠️ Only consider task complete when you see explicit success message or prompt is back.

Session Heartbeat (Long Running Tasks)

For workflows lasting 5+ minutes (/bmad-bmm-dev-story, large refactoring):

Every 60 seconds with no new log output:

# Check if process is still alive
ps aux | grep claude
If stalled but alive → check if waiting for input
process action:log sessionId:XXX
If process died → trigger recovery (see below)

Autonomous Workflow Patterns

Pattern 1: Full Analysis + Planning Request

User says: "Analyze the current architecture and generate the product brief for project X"

Agent should: 1. Pre-flight check: Verify BMad installed (ls _bmad/) 2. Check project-context.md: If absent or outdated, generate it first (see below) 3. Launch Claude Code in the project directory:

   bash pty:true workdir:~/path/to/project background:true command:"claude --dangerously-skip-permissions '/bmad-bmm-create-architecture'"
   

Pattern 2: Sprint Preparation with Story Generation

User says: "Prepare sprint 1 and add tasks to OCM (OpenClaw Mission Center)"

Agent should: 1. Pre-flight check: Verify BMad installed 2. Launch Claude Code:

   bash pty:true workdir:~/path/to/project background:true command:"claude --dangerously-skip-permissions '/bmad-bmm-sprint-planning && /bmad-bmm-create-epics-and-stories'"
   

#### OCM Task Traceability

When creating OCM tasks, ALWAYS include the BMad story reference:

Task: Implement login form validation
Description: [full story content]

Ref: _bmad-output/epics/auth/stories/story-login-validation.md
Epic: auth
Created from: BMad Sprint 1

Why: This links the OCM task back to the source story for traceability.

Pattern 3: Quick Feature Implementation

User says: "Implement feature X using quick-dev"

Agent should: 1. Launch Claude Code with quick-dev:

   bash pty:true workdir:~/path/to/project command:"claude --dangerously-skip-permissions '/bmad-bmm-quick-dev [feature description]'"
   

⚠️ Quick-Dev vs Standard: The Red Line

Quick-dev is faster but lacks safeguards. Use wisely.

| ✅ OK with Quick-Dev | ❌ NEVER with Quick-Dev | |---------------------|------------------------| | UI tweaks | Authentication changes | | Bug fixes | Encryption/Security | | New endpoints | Database migrations | | Simple features | Payment logic | | | Breaking schema changes |

Rule: If the change touches security, auth, encryption, or database migrations → Use full BMad cycle (Analysis → Solutioning → Implementation)

project-context.md Management

BMad relies on project-context.md as the project's "brain". It's the persistent context that guides all decisions.

Before /bmad-bmm-create-prd

Always check:

ls ~/project/project-context.md

If Missing or Outdated

Generate or update it:

# Option 1: Generate from codebase
bash pty:true workdir:~/project command:"claude '/bmad-bmm-generate-project-context'"
Option 2: Update manually with user's latest direction
Ask user: "What's the current vision for this project?"
Then create/update project-context.md with that info

When User Changes Direction

If user pivots mid-project (new features, different direction): 1. Update project-context.md with new intentions 2. Regenerate architecture.md if architecture is affected 3. Proceed with updated context

Reading Stories Safely (Avoid Context Overflow)

Don't dump all stories at once! Follow this process:

1. List first:

   ls _bmad-output/epics/*/stories/
   

2. Check each story header before reading full:

   head -10 _bmad-output/epics/*/stories/story-*.md
   

3. Read one at a time for task creation: - Read story 1 → create OCM task - Read story 2 → create OCM task - etc.

4. For batch operations, group by epic:

   for f in _bmad-output/epics/*/stories/*.md; do head -20 "$f"; done | head -100
   

Command Chain Safety

❌ Avoid This (Silent Failures)

claude "/bmad-cmd1 && /bmad-cmd2"  # If cmd1 fails, cmd2 still runs

✅ Prefer Sequential Execution

# Step 1: Run cmd1
bash pty:true background:true command:"claude '/bmad-cmd1'"
Step 2: Verify output exists
ls _bmad-output/required-file.md
grep -q "expected content" _bmad-output/required-file.md || { echo "FAILED"; exit 1; }
Step 3: Run cmd2 only if cmd1 succeeded
bash pty:true command:"claude '/bmad-cmd2'"

Rule: Verify each step before proceeding to the next.

Recovery After Crash

Scenario: Claude Code crashes (API error 500, timeout, killed process)

Step 0: Kill Zombie Processes (BEFORE Restart!)

⚠️ Always check for stale processes first:

# Check if Claude is still running
ps aux | grep claude
Kill any zombie processes for this project
pkill -f "claude.*projects/roundvision" || echo "No zombie processes"
Also kill any hanging node processes
pkill -f "npx.*bmad" || echo "No zombie npx"

Step 1: Check what was generated

1. Check what was generated:

   ls -lt _bmad-output/*.md | head -10
   

2. Find the last valid file:

   # Read the most recently modified output
   ls -t _bmad-output/*.md | head -1 | xargs head -30
   

3. Resume from where it stopped: - If architecture.md exists but stories/ missing → run story generation - If stories/ exist but no OCM tasks → create tasks from existing stories - If partial output → check coherence, regenerate only what's missing

4. Never restart from zero if partial output exists

Handling Claude Code Questions

When Claude Code asks questions during execution:

1. Check the log first with process action:log sessionId:XXX to see what it asked 2. If you know the answer → provide it via process action:submit 3. If you need to ask the user → pause and get clarification first 4. If Claude Code is blocked → tell it to ask for what it needs, then come back to you

Example:

# Claude asks: "What's your preferred authentication provider?"
If you don't know → ask user: "Claude needs to know auth provider - Auth0, Firebase, or Supabase?"
Then provide the answer:
process action:submit sessionId:XXX data:"Auth0"

When to Use BMad vs Direct Coding-Agent

Use BMad for:

Use coding-agent directly (without BMad) for:

Rule of thumb: If it needs a story breakdown and sprint planning → BMad. If it's a simple edit → coding-agent directly.

Reading BMad Outputs

After BMad workflows complete, documents are in:

project/
├── _bmad/
│   └── config.yaml
├── _bmad-output/
│   ├── brainstorming-report.md
│   ├── product-brief.md
│   ├── PRD.md
│   ├── ux-spec.md
│   ├── architecture.md
│   ├── epics/
│   │   └── epic-[name]/
│   │       └── stories/
│   │           └── story-[slug].md
│   └── sprint-status.yaml
└── project-context.md

⚠️ Always verify files exist by running ls _bmad-output/ or ls -R _bmad-output/ after each workflow.

Verify output validity before reading:

# Quick check
ls -la _bmad-output/architecture.md
Validate content
head -20 _bmad-output/architecture.md
Check for errors
grep -i "error\|fail" _bmad-output/architecture.md

Cache Refresh (Perception Reset)

⚠️ After Claude Code modifies source files, your cached view is stale!

Rule: After each successful Claude Code intervention on source code: 1. Don't assume your previous read of a file is still valid 2. Re-read the file if you need to work on it further 3. Clear mental cache - explicitly read the file again

# Bad: Assuming old read is still valid
read path:"~/project/src/auth.js"  # ❌ May be outdated
Good: Read fresh after Claude modified it
exec command:"cat ~/project/src/auth.js"  # ✅ Fresh content

Validation Step

Before moving to Implementation phase:

1. Read the generated architecture.md (or tech-spec.md for quick-dev) 2. Verify it aligns with user's original request 3. If misaligned → regenerate or clarify with user

Error Handling

| Error | Solution | |-------|----------| | Command not found | Check PATH: echo $PATH and which claude | | npx: command not found | Install Node.js 20+ | | _bmad/ not found | Run npx bmad-method install first | | Claude stuck on permission | Use --dangerously-skip-permissions | | API 500 error | Trigger recovery (see "Recovery After Crash") | | Session timeout | Check if process still running, resume if possible |

⚠️ Safety Rules

Git Commit Handling

Claude Code often asks: "Do you want to commit these changes? [y/N]"

# When Claude asks to commit, default to "n"
process action:submit sessionId:XXX data:"n"

Examples

Example 1: Architecture Analysis + Product Brief (Sequential)

User: "On project PingRoot, analyze the current architecture and generate the product brief"

Agent does:

# 1. Pre-flight check
ls ~/projects/pingroot/_bmad/ || echo "Need to install BMad"
2. Check/update project-context.md
ls ~/projects/pingroot/project-context.md || echo "Need to create project-context.md"
3. Launch architecture workflow
bash pty:true workdir:~/projects/pingroot background:true command:"claude --dangerously-skip-permissions '/bmad-bmm-create-architecture'"
4. Monitor, wait for completion
process action:poll sessionId:XXX
5. Verify output
ls _bmad-output/architecture.md
head -20 _bmad-output/architecture.md
grep -i "error" _bmad-output/architecture.md || echo "OK"
6. If OK, verify coherence with user request
7. If coherent, launch product brief
bash pty:true workdir:~/projects/pingroot command:"claude --dangerously-skip-permissions '/bmad-bmm-create-product-brief'"
8. Deliver outputs

Example 2: Sprint Preparation + OCM Tasks (with safety checks)

User: "Prepare sprint 1 for RoundVision and add tasks to OCM"

Agent does:

# 1. Pre-flight check
ls ~/projects/roundvision/_bmad/ || npx bmad-method install
2. Check project-context.md
ls ~/projects/roundvision/project-context.md || echo "Update this first!"
3. Launch sprint planning + story creation
bash pty:true workdir:~/projects/roundvision background:true command:"claude --dangerously-skip-permissions '/bmad-bmm-sprint-planning && /bmad-bmm-create-epics-and-stories'"
4. Monitor and wait for completion
process action:poll sessionId:XXX  # repeat until done
5. Refresh context - verify files exist
ls -R ~/projects/roundvision/_bmad-output/epics/
6. List stories first (don't dump all at once!)
ls ~/projects/roundvision/_bmad-output/epics/*/stories/
7. Read and process stories one by one
for story in ~/projects/roundvision/_bmad-output/epics/*/stories/*.md; do
  echo "=== $(basename $story) ==="
  head -20 "$story"
  # Create OCM task from this story
done
8. Report: "Created X tasks in OCM for Sprint 1"
   IMPORTANT: Each OCM task must include story path as reference!

Example 3: Quick Fix (No BMad Needed)

User: "Fix the typo in the login page"

Agent does:

# Direct coding-agent, no BMad workflow needed
bash pty:true workdir:~/projects/login command:"claude 'Fix the typo on line 42: \"Passowrd\" → \"Password\"'"

Example 4: Recovery After Crash

Scenario: Claude Code crashes during story generation

Agent does:

# 0. Cleanup zombies FIRST!
ps aux | grep claude
pkill -f "claude.*projects/roundvision" || echo "Clean"
1. Check what was generated
ls -lt ~/project/_bmad-output/ | head -10
2. Find last valid file
ls -t ~/project/_bmad-output/epics/*/stories/ | head -1
3. Check if partial stories exist
ls ~/project/_bmad-output/epics/*/stories/*.md | wc -l
4. If partial → resume from last point
If 3 stories out of 5 → generate remaining 2
If 0 stories → restart story generation
5. Continue without restarting from zero

⚠️ CRITICAL: Sub-Agent (Minion) Access

The minion does NOT automatically have access to project files! sub-agent to implement

When spawning a a task, you MUST provide:

1. Project Directory Access

# Minion needs workdir to access project files
sessions_spawn workdir:"~/projects/roundvision" ...

2. Story + Context + Architecture

⚠️ NEVER give only the story to a minion!

The story says "Add a login button" but doesn't say:

You MUST provide:

1. Story (what to build) 2. project-context.md (project rules, tech stack) 3. architecture.md (technical decisions)

# Step 1: Read all three
cat ~/projects/roundvision/project-context.md
cat ~/projects/roundvision/_bmad-output/architecture.md  
cat ~/projects/roundvision/_bmad-output/epics/auth.md
Step/stories/story-login 2: Combine into a comprehensive prompt
sessions_spawn task:"You are implementing this story: [STORY]. 
Project context: [CONTEXT].
Architecture: [ARCHITECTURE].
Follow the patterns defined in architecture.md."

3. OCM Task Should Include Story Path

{
  "title": "Implement login form validation",
  "description": "Full story content...",
  "source": "_bmad-output/epics/auth/stories/story-login.md"
}

⚠️ Without workdir + story content + context + architecture, the minion is blind and cannot implement anything!

Notes

Related Skills

Example 1: Architecture Analysis + Product Brief (Sequential)

User: "On project PingRoot, analyze the current architecture and generate the product brief"

Agent does:

# 1. Pre-flight check
ls ~/projects/pingroot/_bmad/ || echo "Need to install BMad"
2. Check/update project-context.md
ls ~/projects/pingroot/project-context.md || echo "Need to create project-context.md"
3. Launch architecture workflow
bash pty:true workdir:~/projects/pingroot background:true command:"claude --dangerously-skip-permissions '/bmad-bmm-create-architecture'"
4. Monitor, wait for completion
process action:poll sessionId:XXX
5. Verify output
ls _bmad-output/architecture.md
head -20 _bmad-output/architecture.md
grep -i "error" _bmad-output/architecture.md || echo "OK"
6. If OK, verify coherence with user request
7. If coherent, launch product brief
bash pty:true workdir:~/projects/pingroot command:"claude --dangerously-skip-permissions '/bmad-bmm-create-product-brief'"
8. Deliver outputs

Example 2: Sprint Preparation + OCM Tasks (with safety checks)

User: "Prepare sprint 1 for RoundVision and add tasks to OCM"

Agent does:

# 1. Pre-flight check
ls ~/projects/roundvision/_bmad/ || npx bmad-method install
2. Check project-context.md
ls ~/projects/roundvision/project-context.md || echo "Update this first!"
3. Launch sprint planning + story creation
bash pty:true workdir:~/projects/roundvision background:true command:"claude --dangerously-skip-permissions '/bmad-bmm-sprint-planning && /bmad-bmm-create-epics-and-stories'"
4. Monitor and wait for completion
process action:poll sessionId:XXX  # repeat until done
5. Refresh context - verify files exist
ls -R ~/projects/roundvision/_bmad-output/epics/
6. List stories first (don't dump all at once!)
ls ~/projects/roundvision/_bmad-output/epics/*/stories/
7. Read and process stories one by one
for story in ~/projects/roundvision/_bmad-output/epics/*/stories/*.md; do
  echo "=== $(basename $story) ==="
  head -20 "$story"
  # Create OCM task from this story
done
8. Report: "Created X tasks in OCM for Sprint 1"
   IMPORTANT: Each OCM task must include story path as reference!

Example 3: Quick Fix (No BMad Needed)

User: "Fix the typo in the login page"

Agent does:

# Direct coding-agent, no BMad workflow needed
bash pty:true workdir:~/projects/login command:"claude 'Fix the typo on line 42: \"Passowrd\" → \"Password\"'"

Example 4: Recovery After Crash

Scenario: Claude Code crashes during story generation

Agent does:

# 0. Cleanup zombies FIRST!
ps aux | grep claude
pkill -f "claude.*projects/roundvision" || echo "Clean"
1. Check what was generated
ls -lt ~/project/_bmad-output/ | head -10
2. Find last valid file
ls -t ~/project/_bmad-output/epics/*/stories/ | head -1
3. Check if partial stories exist
ls ~/project/_bmad-output/epics/*/stories/*.md | wc -l
4. If partial → resume from last point
If 3 stories out of 5 → generate remaining 2
If 0 stories → restart story generation
5. Continue without restarting from zero