---
name: bmad-orchestrate
description: Parallel BMAD workflow orchestration using git worktrees and tmux. USE WHEN BMAD parallel, orchestrate sprint, run stories in parallel, worktree orchestration, sprint acceleration, parallel dev stories, bmad worktree, parallelize BMAD, accelerate epic.
---

# BmadOrchestrate

Accelerates BMAD sprints by analyzing story dependencies, identifying parallelization opportunities, and orchestrating concurrent execution across git worktrees with tmux and Claude Code.

## Customization

**Before executing, check for user customizations at:**
`~/.claude/skills/PAI/USER/SKILLCUSTOMIZATIONS/BmadOrchestrate/`

If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.

## Voice Notification

**When executing a workflow, do BOTH:**

1. **Send voice notification**:
   ```bash
   curl -s -X POST http://localhost:8888/notify \
     -H "Content-Type: application/json" \
     -d '{"message": "Running WORKFLOWNAME in BmadOrchestrate to ACTION"}' \
     > /dev/null 2>&1 &
   ```

2. **Output text notification**:
   ```
   Running the **WorkflowName** workflow in the **BmadOrchestrate** skill to ACTION...
   ```

**Full documentation:** `~/.claude/skills/PAI/THENOTIFICATIONSYSTEM.md`

## Workflow Routing

| Workflow | Trigger | File |
|----------|---------|------|
| **Analyze** | "analyze for parallelization", "find parallel stories", "dependency graph" | `Workflows/Analyze.md` |
| **Execute** | "execute parallel", "launch worktrees", "run stories in parallel" | `Workflows/Execute.md` |
| **Merge** | "merge worktrees", "combine branches", "merge parallel work" | `Workflows/Merge.md` |

## Examples

**Example 1: Full orchestration from bmad-help output**
```
User: "Parallelize the remaining Epic 4 stories"
→ Invokes Analyze workflow
→ Reads sprint-status.yaml + epics.md
→ Builds dependency graph, identifies 4-2 ‖ 4-4 as independent
→ Presents phase plan with parallel tracks
→ User approves → Invokes Execute workflow
→ Creates worktrees, launches tmux + Claude Code instances
```

**Example 2: Analyze only**
```
User: "Which stories can I run in parallel?"
→ Invokes Analyze workflow
→ Reads sprint status and epic definitions
→ Returns dependency graph + parallelization opportunities
→ Does NOT execute (analysis only)
```

**Example 3: Merge completed worktrees**
```
User: "Merge the parallel story branches back"
→ Invokes Merge workflow
→ Lists worktree branches with changes
→ Merges sequentially, resolving sprint-status.yaml conflicts
→ Cleans up worktrees
```

## Quick Reference

- **Dependency detection:** Reads acceptance criteria for cross-story references
- **Conflict hotspot:** `sprint-status.yaml` — always needs manual merge
- **Worktree location:** `.claude/worktrees/` (Claude Code default)
- **tmux session name:** `bmad-epic-{N}` where N is the active epic number

**Full Documentation:**
- Dependency patterns: `DependencyPatterns.md`

### Execution Modes

| Mode | Method | Requirement | Isolation |
|------|--------|-------------|-----------|
| **Agent Teams** (preferred) | `Agent` tool with `isolation: "worktree"` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var set | Automatic git worktree per agent |
| **tmux** (fallback) | Manual worktree + tmux panes | tmux installed, no `CLAUDECODE` env var blocking | Manual git worktree creation |

Agent Teams is preferred when available — it handles worktree creation, isolation, and cleanup automatically.

---

## Gotchas

- **Parallel-story orchestration assumes disjoint file ownership** — overlapping edits at story boundaries cause merge conflicts that need manual triage.
- **`sprint-status.yaml` is a merge conflict hotspot** — every parallel agent updates it; serialize updates or use append-only patterns to avoid races.
- **Voice notifications fire per worktree** — multiple parallel agents drown each other out; configure quiet hours or single-channel notification.
- **Default worktree location (`.claude/worktrees/`) collides if multiple BMAD invocations run simultaneously** — namespace by sprint or session ID.
- **Cross-story refs**: a story that references another story's output assumes the other completed — failed cross-refs need explicit detection.