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:

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.js CLI before falling back to MCP tools
• Pre-register workers before spawning (Agent Mail validates recipients)
• Workers own their beads - can bd claim/close directly (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-tdd to disable)

When to Use

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

8-Phase Orchestrator Protocol

1. Preflight - Session identity, detect active sessions
2. Read Plan - Parse Track Assignments from plan.md
3. Validate - Health check Agent Mail CLI (HALT if unavailable)
4. Initialize - ensure_project, register orchestrator + all workers
5. Spawn Workers - Task() for each track (parallel)
6. Monitor + Verify - fetch_inbox, verify worker summaries
7. Workers use track threads (TRACK_THREAD) for bead-to-bead context
8. Resolve - reply_message for blockers
9. Complete - Send summary, close epic, rb review

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 │
└──────────────────────────────────────────────────────────────────────────────┘

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

See references/intent-routing.md for mappings.

Anti-Patterns

Lazy References

Load references only when needed:

All References

Related

• maestro-core - Routing and fallback policies
• conductor - Track management, /conductor-implement
• tracking - Issue tracking, bd commands