Bmad Method

BMad Method Skill

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

For detailed reference, see:

• docs/reference/commands.md - Complete command reference
• docs/reference/agents.md - Available agents
• docs/how-to/install-bmad.md - Detailed installation guide
• docs/tutorials/getting-started.md - Quick start

DEPENDENCY

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

• Claude Code must be installed (~/.local/bin/claude)
• Use bash pty:true for all Claude Code invocations

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:

• DO NOT use background:true - you need to respond to prompts
• Stay in the session and answer each question
• Monitor the log for these common prompts:

# 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:

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

Available Commands (via /bmad-)

⚠️ 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:

• Running multiple BMad workflows in sequence
• The workflow is expected to take a long time

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'"

4. Monitor progress with process action:log (check every 10-30s)
5. If Claude Code needs information → ask the user directly
6. When complete → run: ls _bmad-output/ to confirm files generated
7. Verify output: grep -i "error" _bmad-output/architecture.md || head -20 _bmad-output/architecture.md
8. Read architecture.md to verify coherence with user's request
9. Then launch product brief: /bmad-bmm-create-product-brief

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'"

3. Wait for stories to be generated in _bmad-output/epics/
4. Refresh context: run ls -R _bmad-output/ to confirm files exist
5. Read stories efficiently (see "Reading Stories Safely" below)
6. Create OCM tasks from each story (use task-manager skill)
7. Report completion with task list

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.

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"