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"

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:

• New features or epics
• Architecture changes or refactoring
• Sprint planning with story generation
• Technical documentation (PRD, architecture)
• Anything security-sensitive

Use coding-agent directly (without BMad) for:

• Quick fixes and small corrections
• Simple code reviews
• One-file changes
• Experiments/prototyping

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

⚠️ Safety Rules

• Never run rm -rf via Claude Code without explicit human validation
• Never use quick-dev for security-sensitive changes
• Default Git answer: "n" (let OpenClaw handle commits)

---

Git Commit Handling

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

• Reply "n" to keep Git control with OpenClaw
• Reply "y" ONLY if user explicitly requested full Git autonomy

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

• Is this React, Vue, or vanilla JS?
• Does it use Tailwind or Bootstrap?
• What's the existing auth pattern?

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

• BMad brainstorming: Use sparingly. OpenClaw itself is a brainstorming agent. Use BMad for technical structuring, keep high-level strategy with OpenClaw.
• BMad generates files in _bmad-output/
• project-context.md is the project's brain - keep it updated
• /bmad-help provides interactive guidance
• Always use pty:true with Claude Code
• For model restrictions, use --model <sonnet|haiku|opus>
• Token efficiency: Use direct coding-agent for small tasks, reserve BMad for complex workflows
• Sequential over chained: Verify each step before proceeding

---

Related Skills

• coding-agent — Required for launching Claude Code
• task-manager — For creating OCM tasks from BMad stories