Review Multi Agent Orchestration

Review Multi-Agent Orchestration

Overview

Review an orchestration as a distributed state machine, not as a list of agent roles. The goal is to prove that every task has one owner, every state transition has one authority, and every terminal outcome is reachable without duplicate effects, lost work, or unbounded loops.

This skill reviews a design or implementation. Do not launch workers, mutate queues, cancel runs, change production configuration, or deploy fixes unless the user separately requests implementation.

When to Use

• Reviewing supervisor/worker, planner/executor, debate, swarm, graph, or hierarchical Agent designs.
• Introducing parallel branches, subagents, MCP tools, durable execution, memory, checkpoints, or human-in-the-loop gates.
• Diagnosing duplicate work, stale context, deadlocks, livelocks, branch races, runaway retries, or ambiguous ownership.
• Deciding whether a complex task should be parallel, sequential, delegated, or kept in one agent.

Do not use it for a single independent tool call or a simple pipeline with no concurrency, shared state, retry, or delegation boundary.

Capture the Orchestration Contract

Request or derive:

• business goal, success criteria, and non-goals;
• task graph with stable task IDs and dependency edges;
• agent roles, capabilities, permissions, tools, and sandbox boundaries;
• state schema, source of truth, ownership, versioning, and persistence;
• message envelopes and artifact handoff contracts;
• dispatch, join, retry, timeout, cancellation, compensation, and escalation policies;
• token, cost, concurrency, wall-clock, and external-effect budgets;
• terminal states and evidence required to enter them.

Mark each field as declared, inferred, or missing. Never invent framework behavior from role names such as "supervisor" or "validator."

Decide Whether Multi-Agent Execution Is Justified

Multi-agent execution is justified when tasks have independently verifiable outputs and can be isolated by files, artifacts, permissions, or read-only scopes. Keep work sequential when one branch consumes another's evolving output, all workers must edit the same state, or coordination cost exceeds the expected parallel gain.

Score each candidate task:

If any dimension is unresolved, recommend serialization or an explicit coordination mechanism rather than optimistic concurrency.

Model the State Machine

Represent task state explicitly:

pending -> ready -> leased -> running -> succeeded
                         |        |-> retry_wait -> ready
                         |        |-> needs_human
                         |        |-> failed
                         |        |-> cancelled
                         |-> lease_expired -> ready

For every transition record:

• authorized actor;
• compare-and-set precondition or expected state version;
• persisted fields and artifact references;
• emitted event and deduplication key;
• budget consumed;
• timeout or lease behavior;
• compensation or recovery path.

Reject designs where workers overwrite the whole shared state object or where "done" is a free-form message rather than a validated transition.

Review Task and State Ownership

Each task needs one active lease owner, a fencing token or monotonically increasing attempt, and a stable idempotency key for external effects. A retry may repeat computation, but it must not repeat a committed effect.

Use one of these state patterns deliberately:

• Single-writer coordinator: workers return proposals or artifacts; only the coordinator mutates canonical state.
• Partitioned state: each worker owns a disjoint namespace; a joiner writes the aggregate.
• Event log with reducers: workers append immutable events; deterministic reducers derive state.

Flag shared checkout edits, last-write-wins JSON blobs, mutable global memory, and unversioned summaries as collision risks.

Review Dispatch and Handoffs

A dispatch envelope should bind:

{
  "run_id": "run-7",
  "task_id": "backend-3",
  "attempt": 2,
  "parent_task_id": "migration-1",
  "input_artifacts": [{"uri": "artifact://schema", "digest": "sha256:..."}],
  "expected_output": "backend-contract-v1",
  "deadline": "RFC3339 timestamp",
  "budgets": {"tokens": 20000, "tool_calls": 40},
  "permissions": ["repo:backend:write", "tests:run"],
  "idempotency_key": "run-7:backend-3",
  "trace_parent": "trace-12"
}

Handoffs should pass the minimum sufficient context plus immutable artifact references. Verify that summaries preserve decisions, assumptions, unresolved questions, source citations, and version identity. Do not rely on shared conversational context as durable state.

Review Joins and Completion

Name the join rule for every fan-out:

• all_required: continue only when every required branch succeeds;
• quorum(k): continue after k valid results and cancel or ignore the rest by policy;
• first_valid: continue after the first result that passes an acceptance predicate;
• best_effort: collect until deadline and report missing branches;
• manual_select: a human chooses among complete candidates.

first_finished is not first_valid. Define how late results, duplicate completions, branch cancellation, partial failure, and incompatible artifacts are handled. The joiner must validate artifact versions before moving the parent task to a terminal state.