/waves-codex

name: waves-codex
description: WAVES - Workers, Aggregate, Verify, Extend - wave-based orchestration for Codex. Decompose a big goal into independent slices, verify coverage, spawn Codex subagents in parallel as a bounded wave, collect evidence-backed handoffs, verify important claims, synthesize one deliverable, and extend into another wave only when warranted. Bounded by design to avoid runaway token loops; invoke deliberately. Formerly parallel-orchestrate-codex; also fan out, parallelize, spin up multiple agents, orchestrate workers, multi-stream research, audit a repo, split disjoint implementation work.
disable-model-invocation: true

WAVES — Workers · Aggregate · Verify · Extend (Codex)

Run **wave-based orchestration** with Codex subagents. A **wave** is a bounded round of isolated workers in parallel, then a round that verifies what came back, then a deliberate decision to build on it — not an open-ended loop. Use this skill when a task is too broad for one clean linear pass but can be split into independent slices. You are the manager: discover the problem shape, stage and verify coverage, decompose it, spawn bounded Codex workers, collect one structured handoff from each worker, verify important claims, and synthesize the final deliverable.

**The shape of every wave — WAVE:** Workers fan out across disjoint slices -> Aggregate their handoffs -> Verify the evidence (the moat) -> Extend into another wave only when warranted. A loop doesn't know when to stop; a wave does, because verification is the stop function. (Invoke deliberately - a run spawns more agents than usual.)

Current Codex docs checked on 2026-07-19: Codex subagents are enabled by default in current releases, built-in roles include `default`, `worker`, and `explorer`, custom agents live in `~/.codex/agents/` or `.codex/agents/` (TOML; project agents load in trusted projects only), and subagent limits live under `[agents]` in `config.toml`. Official docs no longer enumerate the collaboration tool names; the current (multi-agent V2) surface exposes `spawn_agent`, `send_message`, `followup_task`, `wait_agent`, `interrupt_agent`, and `list_agents`, while threads created before the V2 runtime resume on the legacy V1 set (`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`, `close_agent`) — read the live tool registry rather than assuming one set. Spawning an unknown `agent_type` fails with an error rather than silently falling back (fallback in Step 2). V2 delegation payloads are encrypted between model calls, so don't build workflows that inspect spawn prompts from rollout history. `spawn_agents_on_csv` is documented as experimental; use it when it is exposed in the active Codex surface, and fall back to normal subagent waves when it is not. No current Codex doc confirms a general-purpose claim-verifier or critic hook; use a verifier subagent, CSV verification pass, tests, validators, or `codex exec --output-schema` instead.

Native delegation on GPT-5.6 (how this skill plugs in): Sol and Terra run the V2 multi-agent runtime, and the delegation mode is derived from reasoning effort per turn -- `ultra` means *proactive* (the model spawns on its own judgment), every other effort means *explicit-request-only*, where the documented triggers are direct user asks **and "applicable AGENTS.md or skill instructions"** -- this skill's spawn instructions are that sanctioned channel, at any effort, no `ultra` required. Avoid `ultra` for wave runs: proactive spawning happens outside your manifest, and its children inherit the parent's model and effort (an ultra parent breeds ultra children -- the runaway-cost failure mode). Native V2 spawns also **fork the parent's history by default** (`fork_turns` defaults to `all`; filtered, but the child sees your conversation), and full-history forks inherit the parent's agent type / model / effort and reject overrides -- so for disjoint wave slices, request **fresh-context workers** (no history fork), which is also the only spawn shape that can be routed to a different model or effort. V2 ignores `agents.max_depth`; its binding limit is concurrent agent slots (4 including the manager by default; `agents.max_threads + 1` when set) -- batch wider waves accordingly.

Read these references when using the skill:

• `references/handoff-format.md` for the exact worker handoff contract.
• `references/verification.md` for verification gates and verifier-worker

playbooks.

• `references/examples.md` for decomposition recipes.
• `references/recommended-config.md` for Codex config and custom agent snippets.
• `references/adaptation-notes.md` for Cursor-to-Codex translation notes.

When to Use

• The user explicitly asks to use multiple agents, subagents, parallel workers,

fan-out, or orchestration.

• The task splits into independent slices: data ranges, research streams,

repo modules, audit dimensions, verification rows, or disjoint code ownership.

• The main value is speed, context hygiene, and verification discipline: keep

noisy exploration out of the manager thread, then check the claims that matter.

• A second or third wave may be useful after first-wave handoffs expose gaps,

conflicts, narrowed scope, or high-stakes claims needing verification.

When to Skip

• The task is small, linear, or easy to do locally.
• The slices require constant cross-talk or shared mutable decisions.
• The next action is blocked on one immediate investigation; do that locally.
• Parallel code edits would overlap heavily and no worktree/isolation strategy is

available.

Core Principles

1. The manager plans, verifies, and synthesizes. Workers do heavy reading, research, tests, audits, bounded edits, or focused claim checks. 2. Worker prompts are self-contained. Do not assume workers can infer the user's original request, your scratch reasoning, or sibling work unless you intentionally pass or fork that context. (On GPT-5.6's V2 runtime, native spawns fork parent history *b