waves-codex

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.