Use BMad (Breakthrough Method of Agile AI Driven Development) framework for AI-driven development. Use for: architecture analysis, sprint planning, story generation, PRD creation, and full development workflows. Requires coding-agent skill with Claude Code.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use BMad (Breakthrough Method of Agile AI Driven Development) framework for AI-driven development. Use for: architecture analysis, sprint planning, story generation, PRD creation, and full development workflows. Requires coding-agent skill with Claude Code.
BMad Method Skill
Use BMad framework for AI-driven development with autonomous agent workflows.
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:
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.):
Check the log: process action:log sessionId:XXX
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:
Success message in log: Look for "Task completed", "Done!", "All tasks finished"
Prompt available: The command prompt is back
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"
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):
Update project-context.md with new intentions
Regenerate architecture.md if architecture is affected
Proceed with updated context
Reading Stories Safely (Avoid Context Overflow)
Don't dump all stories at once! Follow this process:
List first:
ls _bmad-output/epics/*/stories/
Check each story header before reading full:
head -10 _bmad-output/epics/*/stories/story-*.md
Read one at a time for task creation:
Read story 1 → create OCM task
Read story 2 → create OCM task
etc.
For batch operations, group by epic:
for f in _bmad-output/epics/*/stories/*.md; dohead -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:truecommand:"claude '/bmad-cmd1'"# Step 2: Verify output existsls _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:truecommand:"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
Check what was generated:
ls -lt _bmad-output/*.md | head -10
Find the last valid file:
# Read the most recently modified outputls -t _bmad-output/*.md | head -1 | xargs head -30
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
Never restart from zero if partial output exists
Handling Claude Code Questions
When Claude Code asks questions during execution:
Check the log first with process action:log sessionId:XXX to see what it asked
If you know the answer → provide it via process action:submit
If you need to ask the user → pause and get clarification first
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.
⚠️ After Claude Code modifies source files, your cached view is stale!
Rule: After each successful Claude Code intervention on source code:
Don't assume your previous read of a file is still valid
Re-read the file if you need to work on it further
Clear mental cache - explicitly read the file again
# Bad: Assuming old read is still validread path:"~/project/src/auth.js"# ❌ May be outdated# Good: Read fresh after Claude modified itexeccommand:"cat ~/project/src/auth.js"# ✅ Fresh content
Validation Step
Before moving to Implementation phase:
Read the generated architecture.md (or tech-spec.md for quick-dev)
Verify it aligns with user's original request
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
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 checkls ~/projects/pingroot/_bmad/ || echo"Need to install BMad"# 2. Check/update project-context.mdls ~/projects/pingroot/project-context.md || echo"Need to create project-context.md"# 3. Launch architecture workflow
bash pty:true workdir:~/projects/pingroot background:truecommand:"claude --dangerously-skip-permissions '/bmad-bmm-create-architecture'"# 4. Monitor, wait for completion
process action:poll sessionId:XXX
# 5. Verify outputls _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 checkls ~/projects/roundvision/_bmad/ || npx bmad-method install
# 2. Check project-context.mdls ~/projects/roundvision/project-context.md || echo"Update this first!"# 3. Launch sprint planning + story creation
bash pty:true workdir:~/projects/roundvision background:truecommand:"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 existls -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 onefor story in ~/projects/roundvision/_bmad-output/epics/*/stories/*.md; doecho"=== $(basename $story) ==="head -20 "$story"# Create OCM task from this storydone# 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 generatedls -lt ~/project/_bmad-output/ | head -10
# 2. Find last valid filels -t ~/project/_bmad-output/epics/*/stories/ | head -1
# 3. Check if partial stories existls ~/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
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:
Story (what to build)
project-context.md (project rules, tech stack)
architecture.md (technical decisions)
# Step 1: Read all threecat ~/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
