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; 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
Check what was generated:
ls -lt _bmad-output/*.md | head -10
Find the last valid file:
# Read the most recently modified output
ls -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.
⚠️ 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:
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 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:
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 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
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 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
