- 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.
Agent Mail: CLI Primary, MCP Fallback
This skill uses a lazy-load pattern for Agent Mail:
| Priority | Tool | When Available |
|---|---|---|
| Primary | bun toolboxes/agent-mail/agent-mail.js | Always (via Bash) |
| Fallback | MCP tools (via mcp.json) | When skill loaded + MCP server running |
Detection flow:
1. Try CLI: bun toolboxes/agent-mail/agent-mail.js health-check
↓ success? → Use CLI for all Agent Mail operations
↓ fails?
2. Fallback: MCP tools (lazy-loaded via skills/orchestrator/mcp.json)CLI benefits: Zero token cost until used, no MCP server dependency.
Core Principles
- Load core first - Load maestro-core for routing table and fallback policies
- CLI first - Use
bun toolboxes/agent-mail/agent-mail.jsCLI before falling back to MCP tools - 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" |
| See also | ca for autonomous execution |
Auto-Trigger Behavior
Parallel execution starts automatically when detected - no confirmation needed:
📊 Parallel execution detected:
- Track A: 2 tasks (src/api/)
- Track B: 2 tasks (lib/)
- Track C: 1 task (schemas/)
⚡ Spawning workers...Quick Reference
| Action | Tool |
|---|---|
| Parse plan.md | Read("conductor/tracks/<id>/plan.md") |
| Initialize | bun toolboxes/agent-mail/agent-mail.js macro-start-session |
| Spawn workers | Task() for each track |
| Monitor | bun toolboxes/agent-mail/agent-mail.js fetch-inbox |
| Resolve blockers | bun toolboxes/agent-mail/agent-mail.js reply-message |
| Complete | bun toolboxes/agent-mail/agent-mail.js send-message, bd close epic |
| Track threads | bun toolboxes/agent-mail/agent-mail.js summarize-thread |
| Auto-routing | Auto-detect parallel via metadata.json.beads |
8-Phase Orchestrator Protocol
- Preflight - Session identity, detect active sessions
- Read Plan - Parse Track Assignments from plan.md
- Validate - Health check Agent Mail CLI (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
- 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 - bun toolboxes/agent-mail/agent-mail.js macro-start-session │
│ STEP 2: EXECUTE - claim beads, do work, close beads │
│ STEP 3: REPORT - bun toolboxes/agent-mail/agent-mail.js send-message │
│ STEP 4: CLEANUP - bun toolboxes/agent-mail/agent-mail.js release-file-reservations │
└──────────────────────────────────────────────────────────────────────────────┘| Step | Tool | Required |
|---|---|---|
| 1 | bun toolboxes/agent-mail/agent-mail.js macro-start-session | ✅ FIRST |
| 2 | bd update, bd close | ✅ |
| 3 | bun toolboxes/agent-mail/agent-mail.js send-message | ✅ LAST |
| 4 | bun toolboxes/agent-mail/agent-mail.js release-file-reservations | ✅ |
Critical rules:
- ❌ Never start work before
macro-start-session - ❌ Never return without
send-messageto 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 |
| Agent Mail CLI | agent-mail-cli.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 - tracking - Issue tracking,
bdcommands