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

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

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

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, bd commands