| name | orchestrator |
| description | Multi-agent parallel execution with autonomous workers. Use when plan.md has Track Assignments section or user triggers /conductor-orchestrate, "run parallel", "spawn workers". MUST load maestro-core skill first for routing. |
Orchestrator - Multi-Agent Parallel Execution
Spawn autonomous workers to execute tracks in parallel using Agent Mail coordination.
Core Principles
- Load core first - Load maestro-core for routing table and fallback policies
- Pre-register workers before spawning (Agent Mail validates recipients)
- Workers own their beads - can
bd claim/closedirectly (unlike sequential mode) - File reservations prevent conflicts - reserve before edit, release on complete
- Summary before exit - all workers MUST send completion message
- TDD by default - workers follow RED → GREEN → REFACTOR cycle (use
--no-tddto disable)
When to Use
| Trigger | Condition |
|---|---|
| Auto-routed | /conductor-implement when plan has Track Assignments |
| File-scope | /conductor-implement when ≥2 non-overlapping file groups detected |
| Direct | /conductor-orchestrate or co |
| Phrase | "run parallel", "spawn workers", "dispatch agents" |
Confirmation Prompt
Before spawning parallel workers, orchestrator displays a confirmation:
📊 Parallel execution detected:
- Track A: 2 tasks (src/api/)
- Track B: 2 tasks (lib/)
- Track C: 1 task (schemas/)
Run parallel? [Y/n]:
See implement.md Phase 2b for full confirmation flow.
Quick Reference
| Action | Tool |
|---|---|
| Parse plan.md | Read("conductor/tracks/<id>/plan.md") |
| Initialize | ensure_project, register_agent |
| Spawn workers | Task() for each track |
| Monitor | fetch_inbox, search_messages |
| Resolve blockers | reply_message |
| Complete | Send summary, bd close epic |
| Track threads | summarize_thread(thread_id=TRACK_THREAD) |
| Auto-routing | Auto-detect parallel via metadata.json.beads |
8-Phase Workflow
- Preflight - Session identity, detect active sessions
- Read Plan - Parse Track Assignments from plan.md
- Validate - Health check Agent Mail (HALT if unavailable)
- Initialize - ensure_project, register orchestrator + all workers
- Spawn Workers - Task() for each track (parallel)
- Monitor + Verify - fetch_inbox, verify worker summaries
- Workers use track threads (
TRACK_THREAD) for bead-to-bead context
- Workers use track threads (
- Resolve - reply_message for blockers
- Complete - Send summary, close epic,
rbreview
See references/workflow.md for full protocol.
Worker 4-Step Protocol
All workers MUST follow this exact sequence:
┌─────────────────────────────────────────────────────────────┐
│ STEP 1: INITIALIZE - macro_start_session() FIRST │
│ STEP 2: EXECUTE - claim beads, do work, close beads │
│ STEP 3: REPORT - send_message() to orchestrator │
│ STEP 4: CLEANUP - release_file_reservations() │
└─────────────────────────────────────────────────────────────┘
| Step | Tool | Required |
|---|---|---|
| 1 | macro_start_session() |
✅ FIRST |
| 2 | bd update, bd close |
✅ |
| 3 | send_message() |
✅ LAST |
| 4 | release_file_reservations() |
✅ |
Critical rules:
- ❌ Never start work before
macro_start_session() - ❌ Never return without
send_message()to orchestrator - ❌ Never touch files outside assigned scope
See references/worker-prompt.md for full template.
Agent Routing
| Intent Keywords | Agent Type | File Reservation |
|---|---|---|
research, find, locate |
Research | None (read-only) |
review, check, audit |
Review | None (read-only) |
plan, design, architect |
Planning | conductor/tracks/** |
implement, build, create |
Execution | Task-specific scope |
fix, debug, investigate |
Debug | None (read-only) |
See references/intent-routing.md for mappings.
Anti-Patterns
| ❌ Don't | ✅ Do |
|---|---|
| Spawn workers without pre-registration | Register all workers BEFORE spawning |
| Skip completion summary | Always send_message before exit |
| Ignore file reservation conflicts | Wait or resolve before proceeding |
| Use orchestration for simple tasks | Use sequential /conductor-implement |
Lazy References
Load references only when needed:
| Phase | Trigger Condition | Reference |
|---|---|---|
| Always | On skill load | SKILL.md (this file) |
| Phase 3 (Initialize) | Setting up Agent Mail, project registration | agent-mail.md |
| Phase 4 (Spawn) | Before dispatching worker agents | worker-prompt.md |
| Phase 6 (Handle Issues) | Cross-track dependencies, blocker resolution | agent-coordination.md |
All References
| Topic | File |
|---|---|
| Full workflow | workflow.md |
| Architecture | architecture.md |
| Coordination modes | coordination-modes.md |
| Agent Mail protocol | agent-mail.md |
| Worker prompt template | worker-prompt.md |
| Preflight/session brain | preflight.md |
| Intent routing | intent-routing.md |
| Summary format | summary-protocol.md |
| Auto-routing | auto-routing.md |
| Track threads | track-threads.md |
Related
- maestro-core - Routing and fallback policies
- conductor - Track management,
/conductor-implement - beads - Issue tracking,
bdcommands