bmad-method

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 |
| `/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:

```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 ta