julianobarbosa/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

| 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.