/ia-orchestrating-swarms

name: ia-orchestrating-swarms
class: workflow
description: >-
  Coordinate multi-agent swarms for parallel and pipeline workflows. Use when
  coordinating multiple agents, running parallel reviews, building pipeline
  workflows, or implementing divide-and-conquer patterns with subagents.

Swarm orchestration

Primitives

For Claude Code teams, see [primitives.md](./references/primitives.md). In Codex, use the active collaboration-tool schemas and [codex-quick-reference.md](./references/codex-quick-reference.md); do not assume Claude's team files or task store exist.

---

Two Ways to Spawn Agents

Resolve the host primitives before dispatching:

• **Claude Code:** `Task(...)` for short-lived subagents; `Teammate(...)` plus named `Task(...)` for persistent teams.
• **Codex:** `spawn_agent(...)` for short-lived subagents; `send_message(...)`, `followup_task(...)`, and `wait_agent(...)` for coordination. Use persistent teammates only when the active Codex environment exposes that capability.
• **Other harnesses:** use their native subagent surface. If none exists, execute the units sequentially in the main thread.

The comparison and examples immediately below describe Claude's two dispatch modes. Codex uses `spawn_agent` for both one-shot and follow-up work:

spawn_agent({ task_name: "find_auth", fork_turns: "all", message: "Find the auth entry points and return paths only." })

Never emit a tool name or argument the active harness does not expose.

| Aspect | Task (subagent) | Task + team_name + name (teammate) | |--------|-----------------|-----------------------------------| | Lifespan | Until task complete | Until shutdown requested | | Communication | Return value | Inbox messages | | Task access | None | Shared task list | | Team membership | No | Yes | | Coordination | One-off | Ongoing | | Best for | Searches, analysis, focused work | Parallel work, pipelines, collaboration |

**Subagent** (short-lived, returns result):

Task({ subagent_type: "Explore", description: "Find auth files", prompt: "..." })

**Teammate** (persistent, communicates via inbox):

Teammate({ operation: "spawnTeam", team_name: "my-project" })
Task({ team_name: "my-project", name: "worker", subagent_type: "general-purpose",
       prompt: "...", run_in_background: true })

For detailed agent type descriptions, see [agent-types.md](./references/agent-types.md).

Parallel Fan-Out (for independent work)

When dispatching independent read-only or worktree-isolated agents, issue the harness's native spawn calls without waiting between them. In Claude Code, place all `Task` calls in one assistant message. In Codex, issue the `spawn_agent` calls concurrently up to the active-agent limit. Waiting for one result before spawning the next serializes the fan-out.

// Correct: one message, multiple Task tool uses
Task({ subagent_type: "security-sentinel", ... })
Task({ subagent_type: "performance-oracle", ... })
Task({ subagent_type: "architecture-strategist", ... })

Sequential dispatch (each Task in its own message, waiting on the previous to return) is a serialization bug, not a coordination pattern. If agents truly depend on each other's output, that is a pipeline -- see Coordination Models below.

**Bounded parallelism when the harness caps active subagents.** Single-message fan-out (above) tells Opus to dispatch in parallel; the harness then decides how many to *run* concurrently. When the harness accepts the dispatch but caps active execution, queue the overflow rather than failing. Dispatch as many as the harness accepts in the first batch, treat transient capacity-related spawn errors as backpressure (any retryable error indicating the limiter rejected the dispatch — exact wording varies across harness versions and platforms; do not pattern-match on a fixed string list), and re-dispatch queued agents as active ones complete. Record an agent as failed only after a successful dispatch times out or returns an error, or when dispatch fails for a non-capacity reason (bad tool name, malformed prompt, missing permission). The fan-out is still parallel — it is just rate-capped to whatever the harness can run concurrently.

---

Quick Reference

Load the reference for the active harness: [quick-reference.md](./references/quick-reference.md) for Claude Code or [codex-quick-reference.md](./references/codex-quick-reference.md) for Codex.

---

Dispatch Discipline

Rules for when and how to dispatch agents. Getting these wrong wastes tokens and creates hard-to-debug failures.

**When to dispatch a team vs. do it yourself:**

Assess 5 signals: file count, module span, dependency chain, risk surface, parallelism potential. If 3+ fall in the "complex" column, dispatch a team. Below 3, do it yourself. When in doubt, prefer the simple path -- team overhead is only justified when parallelism provides a real speedup.

**Task description template (for every dispatched task):**

Every task prompt must include these fields to prevent integration failures:

• **Objective**: what to accomplish (one sentence)
• **Owned Files**: files this agent creates or modifies (exclusive -- no file assigned to multiple agents)
• **Interface Contracts**: what to import from other agents' work, what to export for downstream agents
• **Acceptance Criteria**: how the agent knows the task is correct
• **Out of Scope**: what NOT to touch, even if it looks related
• **Validation Assignment**: which checks this agent runs, and which it must not

**One owner per aggregate check.** Exclusive file ownership has a verification counterpart: assign the aggregate checks -- full test suite, whole-package typecheck, repo-wide lint -- to exactly one owner per dispatch. That is the integration agent where one exists, otherwise the orchestrator at post-wave reconciliation. Every other agent's Acceptance Criteria names the *narrowest* checks that prove its own edits (lint/format/t