multi-model-orchestrator
Decompose. Execute. Synthesize.
A lightweight skill for coordinating work across multiple AI agents (Claude, Opus, Haiku, Codex, or any agent) using a single handoff document as the source of truth.
Why This Skill
Complex work often requires:
- High-level planning — breaking down a big goal into concrete subtasks
- Parallel execution — different agents handling different task types simultaneously
- Feedback synthesis — collecting results and iterating intelligently
- Full traceability — understanding who did what, why, and what changed
This skill provides the structure and templates to do this cleanly.
Operating Contract
Direct actions: create or update one handoff document as the source of truth, decompose the goal into executor-ready subtasks, assign explicit dependencies, record execution results, and synthesize feedback into next steps.
Escalate before: starting execution when the goal, constraints, executor choice, writable scope, or done criteria are ambiguous.
Evidence-backed pushback: reject unverified completion claims, vague agent outputs, missing acceptance criteria, or parallel assignments that touch shared writable files without explicit ordering.
Feedback loop: after each execution round, update the handoff with result, evidence, blockers, and next action before assigning follow-up work.
When to Use
✅ Use when:
- A single-agent conversation would be too long or unfocused
- You want to parallelize work across multiple specialized agents
- You need to decompose a vague goal into specific, executor-ready tasks
- You want to track decisions, changes, and feedback in one place
- You're exploring multiple approaches simultaneously (A/B/C branches)
❌ Don't use when:
- The task is simple and one agent can handle it end-to-end
- You don't need to track who did what
- Execution is strictly sequential with no parallelization
- The task is exploratory with no clear structure
Core Concepts
Handoff Document (Handoff)
A YAML file that serves as the single source of truth. It contains:
- Goal — what are we trying to accomplish?
- Subtasks — who does what, and what does success look like?
- Context — code references, prior decisions, constraints
- Execution Tracking — who executed, what was the result, what blockers?
- Feedback — iterations, changes, and learnings
Agent Roles
You choose which agents execute which subtasks. Examples:
| Agent | Best For |
|---|
| Claude (or Fable) | Planning, decomposition, architecture review, high-level strategy |
| Opus | Complex reasoning, deep analysis, novel problem-solving |
| Haiku | Fast iteration, simple fixes, quick validation |
| Codex | Code generation, refactoring, technical implementation |
| Claude Code | Interactive development, running code, verification |
The Loop
1. Define Goal
↓
2. Fable/Claude decomposes into Handoff subtasks
↓
3. You assign subtasks to agents
↓
4. Agents execute in parallel or sequence
↓
5. You record results in Handoff
↓
6. Review, iterate, or complete
Quick Start
The full five-step walkthrough with copy-paste templates lives in references/quick-start.md. Summary:
- Create handoff — copy
templates/handoff-template.yaml to .claude/handoffs/my-task.yaml.
- Decompose — ask Fable/Claude to break the goal into 3-5 subtasks; paste into
subtasks.
- Execute — give each subtask's
input to its assigned executor.
- Record — append the result to
execution.rounds.
- Iterate or complete — update
metadata.status toward complete.
Field-by-field reference: references/handoff-structure.md.
Complete Example
See references/add-auth-to-api.yaml for a real-world multi-agent execution walkthrough.
Using with Claude Code
- Save your handoff to
.claude/handoffs/task.yaml
- Run:
cat .claude/handoffs/task.yaml to load it in conversation
- Ask Claude to execute a subtask
- When done, update the handoff manually or using a script
For automation, see references/advanced-sync.md.
Using with Codex
Codex does not have handoff-specific subcommands. Use codex exec with a focused prompt that names the handoff file and the exact subtask:
codex exec "Read .claude/handoffs/task.yaml. Execute subtask task-1 only. Return the result, blockers, files changed, and verification evidence."
For decomposition:
codex exec "Read .claude/handoffs/task.yaml. Propose 3-5 YAML subtasks using goal.summary, goal.context, and goal.acceptance_criteria. Do not edit files."
Resources
Status: Production ready · License: MIT