Skill: leonaaardob/lb-bmad-skill (version 1.0.2)

--- name: bmad-method description: "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. **For detailed reference, see:** - [docs/reference/commands.md](docs/reference/commands.md) - Complete command reference - [docs/reference/agents.md](docs/reference/agents.md) - Available agents - [docs/how-to/install-bmad.md](docs/how-to/install-bmad.md) - Detailed installation guide - [docs/tutorials/getting-started.md](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. ```bash 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: | 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 | ```bash # 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:** ```bash ls -la ~/project/_bmad/ # or _bmad-output/ ``` If not found → run installation first: ```bash 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 | ```bash # 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 | | [REDACTED_SECRET] | Break into stories | Epic files in `_bmad-output/` | | [REDACTED_SECRET] | 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: ```bash # 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. ```bash # 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: ```bash 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:** ```bash # 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 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 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 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:** ```bash ls ~/project/project-context.md ``` ### If Missing or Outdated **Generate or update it:** ```bash # Option 1: Generate from codebase bash pty:true workdir:~/project command:"claude [REDACTED_SECRET]" # 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:** ```bash ls _bmad-output/epics/*/stories/ ``` 2. **Check each story header** before reading full: ```bash 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: ```bash for f in _bmad-output/epics/*/stories/*.md; do head -20 "$f"; done | head -100 ``` --- ## Command Chain Safety ### ❌ Avoid This (Silent Failures) ```bash claude "/bmad-cmd1 && /bmad-cmd2" # If cmd1 fails, cmd2 still runs ``` ### ✅ Prefer Sequential Execution ```bash # 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:** ```bash # 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:** ```bash ls -lt _bmad-output/*.md | head -10 ``` 2. **Find the last valid file:** ```bash # 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: ```bash # 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: ```bash # 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 ```bash # 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 - **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 ```bash # 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:** ```bash # 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:** ```bash # 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:** ```bash # 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:** ```bash # 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 ```bash # 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) ```bash # 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 ```json { "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


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)