Bmad Orchestrate

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:

   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

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

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.

Dependency Patterns

Common patterns for detecting independent vs. dependent BMAD stories. Used by the Analyze workflow.

Infrastructure Domain Classification

Stories that operate on different infrastructure domains are typically independent:

Independence Signals

Stories are likely independent when they:

1. Touch different Terraform modules — e.g., terraform/modules/ci/ vs terraform/modules/monitoring/ (safe for parallelization if using per-module state; shared state requires serialized terraform apply) 2. Use different Terraform providers — e.g., azuredevops provider vs helm provider 3. Create files in different directories — e.g., pipelines/ vs k8s/argocd/ 4. Have no "Given X from Story N" in acceptance criteria 5. Operate at different layers — e.g., infrastructure provisioning vs application deployment

Dependency Signals

Stories are likely dependent when they:

1. Acceptance criteria reference another story's output — "Given pipeline from Story 4-2..." 2. Both modify the same Terraform module — same main.tf or variables.tf 3. One extends what the other creates — "extend the CI pipeline to also..." 4. Share a Terraform state file — the default in most projects; both stories' resources live in the same state, causing lock contention on terraform apply 5. Have explicit ordering in the epics doc — "after Story N.M is complete"

Common Parallel Patterns in BMAD Projects

Pattern: CI Pipeline + GitOps Deployment

CI Pipeline (Azure DevOps)  ──┐
                               ├── Image Push (depends on CI)
GitOps (ArgoCD on K8s)     ──┘   (depends on both)

CI and GitOps are independent until the image push story connects them.

Pattern: Monitoring + Security

Monitoring Stack (Helm)     ── independent ──  Security Policies (Terraform)

Both deploy to the same cluster but touch completely different resources.

Pattern: Multiple Namespace Setups

Namespace A setup  ── independent ──  Namespace B setup

Each creates its own resources in its own namespace.

Pattern: Dashboard + Alert Rules

Dashboard creation  ── independent ──  Alert rule configuration

Both use Grafana but configure different resource types.

Conflict Hotspots

Files that commonly cause merge conflicts when stories run in parallel:

Terraform State Considerations

Most projects use a single shared state file (key = "terraform.tfstate"). This means terraform apply from parallel worktrees will cause state lock contention — only one apply can run at a time.

Shared State (Default)

Check the backend configuration:

grep "key" terraform/backend.tf

If key = "terraform.tfstate" (single key for all modules):

• BMAD steps that DON'T run `terraform apply` are always safe to parallelize:
• Create Story (CS) — only writes markdown spec files
• Code Review (CR) — read-only analysis
• Retrospective (ER) — only writes markdown
• BMAD steps that DO run `terraform apply` (Dev Story for Terraform modules) must be serialized — schedule them in sequential phases
• Stories touching non-Terraform domains (Helm charts, K8s manifests, pipeline YAML) do not hit Terraform state and remain fully parallelizable even during Dev Story

Per-Module State (Alternative)

If the project uses per-module state (key = "module-name/terraform.tfstate"):

• Parallel stories modifying different modules are safe to parallelize
• Parallel stories modifying the same module still require serialization

Analyze Workflow

Analyze BMAD sprint status for parallelization opportunities by building a story dependency graph.

Voice Notification

curl -s -X POST http://localhost:8888/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running Analyze in BmadOrchestrate to find parallelization opportunities"}' \
  > /dev/null 2>&1 &

Running the Analyze workflow in the BmadOrchestrate skill to find parallelization opportunities...

Step 1: Load Sprint State

Read the sprint status file to understand current progress:

Read {project-root}/_bmad-output/implementation-artifacts/sprint-status.yaml

Identify:

• Which epic is in-progress
• Which stories are backlog or ready-for-dev (candidates for work)
• Which stories are already done or in-progress

Step 1a: Cross-Validate Status

For each story NOT in backlog status:

1. If a story file exists at {project-root}/_bmad-output/implementation-artifacts/{story-slug}.md, compare its Status: header to the status in sprint-status.yaml 2. If mismatch detected → WARN the user: _"Story N.M shows '{sprint-status}' in sprint-status.yaml but '{story-file-status}' in the story file."_ 3. Use the story file as source of truth (it's updated during Dev Story execution) 4. Recommend updating sprint-status.yaml before proceeding to avoid incorrect parallelization decisions (e.g., re-running a story that's already done)

Step 2: Load Epic Definitions

Read the epics document for the active epic:

Read {project-root}/_bmad-output/planning-artifacts/epics.md

For each candidate story, extract:

• Story title and description
• Acceptance criteria (look for cross-story references like "Given X from Story N.M")
• Infrastructure domain (what system does this story touch: Terraform, Kubernetes, Helm, Azure DevOps, etc.)

Step 2a: Resolve Story Detail Source

For each candidate story identified in Steps 1–2:

1. Check if a story file exists at {project-root}/_bmad-output/implementation-artifacts/{story-slug}.md 2. If EXISTS → read it for detailed acceptance criteria, tasks, dev notes, and infrastructure domain 3. If NOT EXISTS (typical for backlog stories) → extract acceptance criteria from epics.md by searching for the ### Story N.M: heading under the active epic 4. Flag reduced precision when analyzing from epics.md only — epic-level AC may be less granular than a fully elaborated story file

This distinction matters because backlog stories haven't been through Create Story yet and only exist as narrative descriptions in the epics document.

Step 3: Build Dependency Graph

For each pair of candidate stories (using detail resolved in Step 2a), determine if they are:

Independent (can parallelize) when:

• They operate on different infrastructure planes (e.g., Azure DevOps pipelines vs. Kubernetes/Helm)
• They create separate files that don't overlap (different Terraform modules, different directories)
• Their acceptance criteria have no cross-references to each other's outputs
• They don't modify the same Terraform state file

Dependent (must be sequential) when:

• Story B's acceptance criteria explicitly reference Story A's outputs ("Given pipeline from 4-2...")
• They modify the same files (e.g., both edit terraform/main.tf)
• Story B extends or modifies infrastructure that Story A creates
• They share a Terraform state file and would cause state lock contention

Reference: Common Dependency Patterns

Load ~/.claude/skills/bmad-orchestrate-skill/DependencyPatterns.md for detailed patterns.

Step 4: Identify BMAD Workflow Parallelization

Beyond story dependencies, analyze which BMAD workflow steps can overlap:

Step 5: Design Phase Plan

Organize work into phases where each phase's items can run in parallel:

Phase 1 (parallel): [items that have no dependencies on each other]
Phase 2 (parallel): [items that depend on Phase 1 but not on each other]
Phase 3 (sequential): [items that depend on Phase 2 outputs]
...
Final: [Retrospective, sprint status update]

For each phase, specify:

• What runs in parallel (with worktree names)
• Which BMAD command each worktree should execute
• Conflict hotspots (files that multiple worktrees might touch)

Step 6: Calculate Speedup

Compare:

• Serial time: Total number of sequential context windows needed
• Parallel time: Number of phase rounds needed
• Speedup factor: Serial / Parallel

Step 7: Present Analysis

Output the analysis in this format:

## Dependency Graph

[ASCII or description of story dependencies]

## Parallelization Plan

### Phase N: [Description] — [N worktrees in parallel]

| Worktree | BMAD Command | Story | Domain |
|----------|-------------|-------|--------|
| wt-{name} | /bmad-bmm-{cmd} | {story} | {domain} |

### Conflict Hotspots
- {file}: touched by {worktrees} — merge strategy: {strategy}

## Speedup
- Serial: {N} context windows
- Parallel: {M} phase rounds
- Speedup: ~{N/M}x

Step 8: Ask for Approval

Present the plan and ask: "Ready to execute this parallel plan? I'll set up worktrees and tmux."

If approved, hand off to the Execute workflow.

Execute Workflow

Set up git worktrees and tmux sessions to run BMAD workflows in parallel via Claude Code.

Voice Notification

curl -s -X POST http://localhost:8888/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running Execute in BmadOrchestrate to launch parallel worktrees"}' \
  > /dev/null 2>&1 &

Running the Execute workflow in the BmadOrchestrate skill to launch parallel worktrees...

Prerequisites

• The Analyze workflow has been run and a phase plan exists
• Or the user provides explicit instructions on what to parallelize
• Git working tree is clean (no uncommitted changes that would block worktree creation)

Configuration

• Worktree root: .claude/worktrees/ (Claude Code default, adjustable per project)
• Execution state: {worktree-root}/execution-state.yaml
• Worktree naming: {worktree-root}/wt-{story-id}
• Branch naming: bmad/story-{story-id}

Step 1: Verify Clean State

git status --porcelain

If dirty, ask the user to commit or stash before proceeding. Worktrees share the same Git repository, so uncommitted changes in the main tree can cause confusion.

Step 2: Determine Active Phase

From the Analyze output, identify the current phase to execute. Each phase contains N parallel items.

Example phase structure:

Phase 1:
  - Worktree A: /bmad-bmm-create-story → Story 4-2
  - Worktree B: /bmad-bmm-create-story → Story 4-3
  - Worktree C: /bmad-bmm-create-story → Story 4-4

Step 3: Create Git Worktrees

For each parallel item in the phase, create a worktree:

# Pattern: git worktree add <path> -b <branch-name>
git worktree add .claude/worktrees/wt-{story-id} -b bmad/{story-id}

Example:

git worktree add .claude/worktrees/wt-4-2 -b bmad/story-4-2
git worktree add .claude/worktrees/wt-4-4 -b bmad/story-4-4

Record the worktree paths for the merge step.

Step 4: Determine Execution Mode

Check for Agent Teams support:

echo "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-not_set}"

If Agent Teams available (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set): use Agent tool with worktree isolation (preferred). If not available: fall back to tmux approach (Step 4b).

Step 4a: Agent Teams Execution (Preferred)

For each parallel item, spawn an Agent with worktree isolation:

Agent tool call:
  subagent_type: general-purpose
  isolation: "worktree"
  prompt: "cd to worktree root. Run /{bmad-command} with story_key={story-id}"
  run_in_background: true

Each agent gets its own isolated worktree automatically — no manual git worktree add needed when using Agent Teams.

Step 4b: tmux Execution (Fallback)

If Agent Teams is not available, set up a tmux session with one pane per parallel worktree:

# Create named session for the epic
EPIC_NUM={active_epic_number}
tmux new-session -d -s "bmad-epic-${EPIC_NUM}" -c ".claude/worktrees/wt-{first-story}"

# Split for additional worktrees
tmux split-window -h -t "bmad-epic-${EPIC_NUM}" -c ".claude/worktrees/wt-{second-story}"
# Add more splits as needed for additional parallel items

For 3 parallel items, use:

tmux new-session -d -s "bmad-epic-${EPIC_NUM}" -c ".claude/worktrees/wt-{first}"
tmux split-window -h -t "bmad-epic-${EPIC_NUM}" -c ".claude/worktrees/wt-{second}"
tmux split-window -v -t "bmad-epic-${EPIC_NUM}" -c ".claude/worktrees/wt-{third}"
tmux select-layout -t "bmad-epic-${EPIC_NUM}" tiled

Step 5: Launch Execution

Agent Teams Mode

Agents launch automatically when spawned in Step 4a. Monitor via Agent tool responses — each agent reports back when complete.

tmux Mode

Send the BMAD command to each tmux pane:

tmux send-keys -t "bmad-epic-${EPIC_NUM}:0.0" \
  "claude --dangerously-skip-permissions '/{bmad-command} {story-context}'" Enter

tmux send-keys -t "bmad-epic-${EPIC_NUM}:0.1" \
  "claude --dangerously-skip-permissions '/{bmad-command} {story-context}'" Enter

IMPORTANT: The --dangerously-skip-permissions flag is optional. If the user prefers interactive approval, omit it.

Step 6: Monitor Progress

Agent Teams Mode

Background agents automatically notify when complete. Check status via TaskList if using team coordination.

tmux Mode

Attach to the tmux session to monitor:

tmux attach -t "bmad-epic-${EPIC_NUM}"

Key tmux navigation:

• Ctrl-b then arrow keys to switch panes
• Ctrl-b then z to zoom a pane (toggle fullscreen)
• Ctrl-b then d to detach (processes continue in background)

Step 7: Record Execution State

Create a tracking file in the project:

cat > {worktree-root}/execution-state.yaml << 'EOF'
phase: {phase_number}
epic: {epic_number}
tmux_session: bmad-epic-{epic_number}
worktrees:
  - path: .claude/worktrees/wt-{id}
    branch: bmad/story-{id}
    command: /bmad-bmm-{command}
    story: "{story_title}"
    status: running
    agent_type: native  # native (Agent Teams) or tmux
EOF

This file is consumed by the Merge workflow.

Step 8: Wait and Verify

Once all panes show completion:

1. Check each worktree for changes:

   cd .claude/worktrees/wt-{id} && git log --oneline main..HEAD

2. Verify expected artifacts were created (story files, terraform configs, etc.)

3. Update execution-state.yaml status to completed for each worktree

4. Hand off to the Merge workflow when ready.

Merge Workflow

Merge parallel worktree branches back into main, resolving conflicts and cleaning up.

Voice Notification

curl -s -X POST http://localhost:8888/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running Merge in BmadOrchestrate to combine parallel branches"}' \
  > /dev/null 2>&1 &

Running the Merge workflow in the BmadOrchestrate skill to combine parallel branches...

Step 1: Read Execution State

Load the tracking file created by the Execute workflow (default path: .claude/worktrees/):

cat {worktree-root}/execution-state.yaml

Identify all worktrees that need merging and their branches.

If no execution-state.yaml exists, list worktrees manually:

git worktree list

Step 2: Verify All Worktrees Complete

For each worktree, verify it has commits beyond main:

for wt in .claude/worktrees/wt-*; do
  branch=$(cd "$wt" && git rev-parse --abbrev-ref HEAD)
  commits=$(git log --oneline main.."$branch" | wc -l)
  echo "$branch: $commits commits"
done

If any worktree has 0 commits, it either wasn't started or had no changes. Confirm with the user before proceeding.

Step 3: Preview Changes Per Branch

For each branch, show what changed:

git diff --stat main..bmad/story-{id}

Pay special attention to:

• sprint-status.yaml — multiple branches likely modified this (CONFLICT EXPECTED)
• terraform/main.tf — if multiple stories add Terraform modules
• Any shared configuration files

Step 4: Determine Merge Order

Merge in dependency order (independent stories first):

1. Stories with no dependencies on other parallel stories → merge first 2. Stories that depend on already-merged stories → merge next

If all stories were truly independent (no file overlap except sprint-status.yaml), order doesn't matter.

Step 5: Merge Each Branch

For each branch, in order:

# Ensure we're on main
git checkout main

# Merge the branch
git merge bmad/story-{id} --no-ff -m "feat: merge story {id} - {title}"

Handling sprint-status.yaml Conflicts

This file WILL conflict if multiple branches updated it. Resolution strategy:

1. Open the conflicted file 2. Accept ALL story status changes (each branch updated different story lines) 3. Keep the latest generated date 4. Verify the combined result makes sense

# After resolving conflicts
git add _bmad-output/implementation-artifacts/sprint-status.yaml
git commit --no-edit

Handling Terraform Conflicts

If multiple branches modified terraform/main.tf (adding modules):

1. Accept both module blocks (they're additive) 2. Ensure no duplicate resource names 3. Run terraform validate after resolution

Handling Other Conflicts

For unexpected conflicts: 1. Show the diff to the user 2. Ask which version to keep 3. Never auto-resolve without understanding

Step 5a: Self-Healing Merge (Auto-Resolution)

Before prompting for manual intervention, attempt automatic resolution for known-safe patterns:

sprint-status.yaml conflicts:

# Accept all status line changes (different lines = always safe)
# Each branch updates different story keys, so accept both sides
git checkout --theirs _bmad-output/implementation-artifacts/sprint-status.yaml
# Then manually merge any metadata changes (generated date, etc.)

terraform/main.tf conflicts (additive modules):

# If both branches add new module blocks (no overlapping resources):
# 1. Accept both module blocks
# 2. Verify no duplicate resource names
terraform validate

Auto-resolution retry pattern: 1. Attempt git merge — if conflict detected on known-safe files, auto-resolve as above 2. If auto-resolution fails → git merge --abort 3. Attempt git rebase instead: git rebase main bmad/story-{id} 4. If rebase also fails → git rebase --abort → flag for manual intervention:

   ⚠️ Auto-resolution failed for bmad/story-{id}
   Conflicting files: {list}
   Manual intervention required — showing diff for review.

Step 6: Verify Merged State

After all branches are merged:

# Check the combined sprint status
cat _bmad-output/implementation-artifacts/sprint-status.yaml

# Verify all expected artifacts exist
ls _bmad-output/implementation-artifacts/

# If Terraform was involved
cd terraform && terraform validate

Step 7: Clean Up Worktrees

Remove the worktrees and their branches:

# Remove each worktree
for wt in .claude/worktrees/wt-*; do
  git worktree remove "$wt"
done

# Delete the tracking branches
git branch -d bmad/story-{id}  # repeat for each

# Remove execution state
rm -f {worktree-root}/execution-state.yaml

Step 8: Kill tmux Session

tmux kill-session -t "bmad-epic-{N}"

Step 9: Summary

Output a merge summary:

## Merge Complete

| Branch | Commits | Files Changed | Conflicts |
|--------|---------|---------------|-----------|
| bmad/story-{id} | {N} | {M} | {resolved/none} |

### Combined Changes
- {total files changed} files modified
- {new artifacts created}
- sprint-status.yaml: {stories updated}

### Next Steps
- Run next phase (if more phases remain)
- Or proceed to: /bmad-bmm-{next-command}