multi-model-orchestrator

# 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:
1. **High-level planning** — breaking down a big goal into concrete subtasks
2. **Parallel execution** — different agents handling different task types simultaneously
3. **Feedback synthesis** — collecting results and iterating intelligently
4. **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 (10 minutes)

### Step 1: Create Handoff Template

Copy the template below and save as `.claude/handoffs/my-task.yaml`:

```yaml
metadata:
  name: "descriptive name of task"
  created: "2026-06-12"
  goal: "What are we trying to accomplish?"
  status: "planning"  # planning → executing → review → complete

goal:
  summary: |
    Clear, specific goal statement.
  acceptance_criteria:
    - "Testable criterion 1"
    - "Testable criterion 2"
  context: |
    Any background, constraints, or prior decisions.

subtasks:
  - id: "task-1"
    title: "Clear description"
    type: "code | analysis | design | research | validation"
    executor: "Opus | Haiku | Codex | Claude | Claude Code"
    input: |
      What does the executor need to know?
      Include code refs, examples, constraints.
    acceptance: |
      How do we know this is done?
    depends_on: []  # other task IDs this depends on
    status: "pending"  # pending → in-progress → done → blocked

  - id: "task-2"
    title: "Another task"
    type: "code"
    executor: "Codex"
    input: |
      [...]
    depends_on: ["task-1"]
    status: "pending"

execution:
  rounds: []

feedback:
  synthesis: |
    Overall: what worked? what didn't? what changed?
  improvements:
    - "Improvement 1"
    - "Improvement 2"
  decision_log: |
    Why did we make X choice? What was the tradeoff?
```

### Step 2: Decompose with Fable/Claude

**Prompt for Fable/Claude:**

```
I have a complex goal that needs to be decomposed into subtasks for different agents.

Goal: [copy your goal from handoff]

Here's my context: [copy goal.context from handoff]

Please decompose this into 3-5 concrete subtasks that can be executed in parallel or sequence.
For each subtask:
1. Give it a clear title and type (code | analysis | design | research | validation)
2. Write the detailed input/requirements the executor needs
3. Define specific acceptance criteria
4. Suggest which agent type would be best (Opus for deep reasoning, Haiku for quick iteration, Codex for code, Claude for planning, Claude Code for interactive dev)
5. List any dependencies on other subtasks

Format as YAML subtasks I can copy into my handoff.yaml.
```

Fable generates the subtasks → you copy them into your handoff.

### Step 3: Execute One Subtask

Pick the first subtask. Copy its `input` section and give it to the assigned executor:

**For Opus/Haiku/Codex:**

```
[Copy the subtask.input here]

Success criteria:
[Copy the subtask.acceptance here]

Please execute and provide:
1. What you delivered
2. Any issues or blockers
3. What should happen next
```

**For Claude Code or interactive dev:**

```
I'm using the multi-model-orchestrator skill.

Subtask: [title]
Input: [input]
Acceptance: [acceptance]

Please execute this subtask. When done, I'll record the result in m