orchestrator

# 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](../maestro-core/SKILL.md) for routing table and fallback policies
- **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" |

## 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](../conductor/references/workflows/implement.md) 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

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

See [references/workflow.md](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](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](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](references/agent-mail.md) |
| Phase 4 (Spawn) | Before dispatching worker agents | [worker-prompt.md](references/worker-prompt.md) |
| Phase 6 (Handle Issues) | Cross-track dependencies, blocker resolution | [agent-coordination.md](references/agent-coordination.md) |

### All References

| Topic | File |
|-------|------|
| Full workflow | [workflow.md](references/workflow.md) |
| Architecture | [architecture.md](references/architecture.md) |
| Coordination modes | [coordination-modes.md](references/coordination-modes.md) |
| Agent Mail protocol | [agent-mail.md](references/agent-mail.md) |
| Worker prompt template | [worker-prompt.md](references/worker-prompt.md) |
| Preflight/session brain | [preflight.md](references/preflight.md) |
| Intent routing | [intent-routing.md](references/intent-routing.md) |
| Summary format | [summary-protocol.md](references/summary-protocol.md) |
| Auto-routing | [auto-routing.md](references/auto-routing.md) |
| Track threads | [track-threads.md](references/track-threads.md) |

## Related

- [maestro-core](../maestro-core/SKILL.md) - Routing and fallback policies
- [conductor](../conductor/SKILL.md) - Track management, `/conductor-implement`
- [beads](../beads/SKILL.md) - Issue tracking, `bd` commands