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-03: 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. The documented collaboration tools are spawn_agent, send_input, resume_agent, wait_agent, and close_agent; spawning an unknown agent_type fails with an error rather than silently falling back (fallback in Step 2). 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.

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.
3. One worker owns one slice and returns one handoff.
4. Verify before you trust. A worker's Status: success is a claim, not evidence.
5. Parallel reads are the default safe case.
6. Parallel writes require disjoint ownership or isolated worktrees. Codex is safer than a shared local-only model when workers run in separate sandboxes or worktrees, but write conflicts are still a coordination problem.
7. Continuous motion (within the wave caps). Handoffs reveal new work; treat each open question or suggested follow-up as a candidate second-wave task and spawn it. Keep going until every slice is terminal and the synthesis is complete -- stopping early while genuine follow-ups remain is the failure mode this skill guards against. (Stay within the depth/width caps in "Bounded Waves.")
8. Decomposition is entropy reduction. A vague goal is high-entropy: many plausible plans still fit. Shrink that space -- dig locally, then pull from attached resources, then ask the user only if it pays -- before you slice it. See "Entropy-First Decomposition."

Bounded Waves - Size, Caps, and When to Stop

A wave is bounded on purpose. Unbounded "loop-until-done" burns tokens for little gain: candidate generation is cheap, selection plateaus, and extra rounds are non-monotonic (more iterations can lower quality, not just cost). Keep the exploration, drop the runaway.

• Width: 3-8 workers per wave (and within agents.max_threads); size it so you can fully verify all of them. Go wider only with a cheap automatic check (tests, codex exec --output-schema, schema/exec) gating results.
• Depth: <= 2-3 waves, capped up front. Stop on stagnation (nothing new + outputs near-duplicate the last wave) or a quality drop versus the prior wave.
• Budget ~60% generation / 40% verification; selection is the scarce resource.
• Match width to difficulty: easy -> 1 + light refine; medium -> 3-5; hard/open-ended -> 5-8 for diversity; hardest/novel -> escalate reasoning/model, don't loop.
• Anti-poisoning: carry only a distilled, verified handoff (winner + short critique) into the next wave, never raw transcripts or losing candidates.

Loop-until-done is justified only when ALL hold: a cheap reliable ~ground-truth verifier exists; the signal is crisp/actionable (a failing test, not "try harder"); each iteration shows measurable progress; easy-medium difficulty; still hard-capped. Fits code-with-tests/exec-feedback; misfits open-ended research/writing/design.

Entropy-First Decomposition

Before you fan out, treat the goal as an entropy-reduction problem: shrink how many plausible interpretations and plans still fit what you know. A vague, high-entropy request ("build a Flappy Bird game", "make my app faster") does not slice cleanly yet -- reduce the uncertainty first, then decompose the low-entropy version. Name what is uncertain, because the two kinds resolve differently:

• Specification uncertainty -- what the user wants (ambiguous goal, missing acceptance criteria, unstated constraints). Resolve by stating an explicit assumption and proceeding, or -- only when a wrong guess is expensive -- by asking.
• Environment / knowledge uncertainty -- facts you do not have yet but can get (repo shape, schema, API behavior, current docs, data size). Resolve by gathering, not by asking.

Spend the cheapest action that buys the most certainty first -- an information-gain ladder -- and aim each probe at the unknown whose answer eliminates the most plans (the highest-information question splits the surviving interpretations roughly in half):

1. Dig locally first (cheap): inspect local state in the manager thread (list, read schema/README, grep, sample data). This is Step 0; it often collapses most of the uncertainty for free.
2. Then pull from attached resources: if local state lacks the answer, spawn a small scouting wave of explorer/research workers to fetch it (docs, MCP, web) on a fast low-effort model (gpt-5.5 at low; see Step 2).
3. Ask the user last, and only when it pays: when residual specification uncertainty is high and a question's expected information gain beats its cost. Most requests carry enough to proceed on a stated assumption.

Then cascade: one request becomes a decomposition wave (understand -> locate unknowns -> draft the plan) -> verify -> an execution wave that builds the subtasks least-to-most (each verified result lowering uncertainty for the next), with more scouting sub-waves wherever entropy stays high. Track the living plan with update_plan; stop reducing when entropy is low enough to act -- the verification gate doubles as "is the uncertainty low enough to commit?" (Worked example: references/examples.md.)

The Loop

Track the run with Codex's plan mechanism (update_plan) whenever the workflow has more than a couple of moving parts.

Step 0 - Discover Serially

Do not fan out blind. First inspect enough local state to learn the natural shape of the work:

• List directories or data sources.
• Read schemas, manifests, READMEs, package boundaries, or route maps.
• Sample representative records/files.
• Count rows, files, modules, routes, messages, or scope size.
• Identify likely independent slices and risky overlap.

This manager-side discovery prevents duplicate worker scopes, blind spots, and mis-sized chunks.

Step 0.5 - Stage and Verify Coverage

Codex subagents inherit the current sandbox, approvals, MCP, and tool access, so remote or messy data does not always need to be staged locally first. Still stage data when it reduces risk or repeated work:

• Export remote/database data once if credentials, rate limits, or query cost would make every worker redo the same setup.
• Normalize noisy inputs once: strip wrappers, binary blobs, boilerplate, and irrelevant logs.
• Pre-chunk huge corpora into exact per-worker files or ranges.
• Keep one scratch dir per run (e.g. .waves/<run>/ with staging/, handoffs/, synthesis-wave-N.md) so prompts cite paths instead of pasting content and later waves re-read files, not chat history.

Then run a pre-fan-out gate:

• Total rows, files, messages, modules, routes, or records.
• One line per slice with ID/range/path/date bounds and item count.
• Partition-sum check: slice counts add back to the total.
• Duplicate/gap check: no overlapping ranges, missing IDs, bad sort, or empty chunks.
• Central fix-and-recheck if any anomaly appears.

This serial prep is often the largest phase. The parallel fan-out is fast once inputs are clean and coverage is proven.

Step 1 - Decompose into Independent Slices

Size the run itself first, out loud: weigh breadth (how many independent slices), depth (reasoning per slice), ambiguity (see "Entropy-First Decomposition"), and stakes (this sets verification tiers), then state the chosen shape in one line before spawning -- e.g. Run shape: one wave, 4 workers; second wave only if handoffs expose gaps. On the fence between two shapes, pick the smaller and say so. If no wave is needed, do the task in the manager thread and say that -- never present inline work as wave coverage.

Choose the split axis that gives each worker clear ownership:

• Data chunks: disjoint ID ranges, date ranges, files, or CSV rows.
• Workstreams: separate technologies, product areas, research questions.
• Repo modules: non-overlapping path sets or package boundaries.
• Audit dimensions: security, performance, correctness, tests, maintainability.
• Verification rows: one claim, citation group, or metric per verifier task.
• Code edits: disjoint file/module ownership, preferably in worktrees for heavier changes.

For a large wave, usually 5 or more workers, state the decomposition plan and the pre-fan-out coverage gate to the user before spawning so they can redirect cheaply.

Respect agents.max_threads. Current Codex docs say it defaults to 6 when unset. If you need more slices than available threads, batch them into waves.

Then triage each slice on three axes (classify-and-act): the Codex role (table in Step 2), its dependencies (which slices it needs verified output from -- most have none; a real dependency edge is what separates waves), and a verification tier - auto-accept (low-stakes, corroborated) -> single verifier -> multi-model/multi-pass panel (high-stakes) -> debate (contested, no ground truth). Spend verification where a wrong claim is expensive, not uniformly.

Record the triage as a wave manifest - one row per slice (slice | scope | role | effort | depends_on | verification tier), written to the plan or .waves/<run>/manifest.md before spawning. depends_on defines the wave boundaries: a wave is every not-yet-run slice whose dependencies are all met, and a dependency is met only when its handoff has been verified (Step 3), not merely returned. Launch wave 1 (no dependencies) in parallel; launch each dependent slice with the distilled, verified findings (or their .waves/<run>/ path) folded into its self-contained prompt, and keep unrelated slices parallel. The manifest doubles as the completion gate: N rows spawned means N handoffs collected and checked off before synthesis (Step 3).

Step 2 - Fan Out with Codex Subagents

Spawn all workers whose dependencies are met (handoffs verified, not just returned) in the same manager turn when possible. In Codex, the stable interaction is explicit: "spawn one agent per slice, wait for all of them, then summarize/synthesize." When the active tool surface exposes direct subagent tools, use those. If the surface names are visible, they may include spawn_agent, wait_agent, send_input, resume_agent, and close_agent.

Pick the smallest capable role:

A missing role is not permission to skip it. Spawning an unknown agent_type fails with an error rather than falling back, and .codex/agents/ roles load only in trusted projects -- so when a custom role you want is unavailable in the active surface, spawn default (or worker/explorer) with that role's instructions inlined in the worker prompt instead of dropping the role.

Use gpt-5.5 for manager and worker roles by default, and route cost/speed/capability with reasoning effort rather than older model families: low for the fast scouting/decomposition reads that reduce entropy (scans, greps, counting, doc lookups; gpt-5.4-mini is even lighter), medium for all-around work and research, high for coding and verifying, xhigh for orchestration, deep problem solving, and pre-fan-out synthesis. The live per-spawn field is reasoning_effort; the config / custom-agent TOML key is model_reasoning_effort -- set effort on each worker, not only in config. Speed tier is a user preference: honor /fast / service_tier if the user enabled it and don't force it; honor any model/effort the user named, and if a requested model is unavailable, say so rather than substituting.

Step 3 - Collect and Verify Handoffs

Codex handles spawning, routing follow-ups, waiting, and closing in the manager workflow. Current docs say when many agents are running, Codex waits until all requested results are available and returns a consolidated response.

Completion gate first: check every handoff off against the wave manifest - N spawned means N accounted for. A worker that never returns, errors out, or comes back partial/blocked is a hole in the wave. Worker failure ladder: (1) re-task once, narrower -- steer or resume the same worker (send_input, resume_agent) when the slice just needs continuation, or re-spawn fresh with a narrower scope and a note about what came back; (2) if it fails again, do that slice in the manager thread; (3) if it stays blocked, carry the slice into the synthesis explicitly as not-covered - never average over a missing slice as if coverage were complete.

Avoid manual polling loops. Continue non-overlapping local work while workers run; wait only when synthesis is blocked on their results. For each handoff:

• Check Status.
• Check Coverage against the assigned slice.
• Extract Key findings, evidence, confidence tags, and source paths/URLs.
• Preserve Sources and Confidence & verification.
• Treat each Open questions and Suggested follow-ups bullet as a candidate second-wave task: accept, reject, or consolidate it. Spawning a focused follow-up wave for real gaps is the normal path, not an exception.
• Reconcile contradictions across workers before presenting claims as settled.

Run cheap checks on every important finding:

• Evidence is present.
• Cited path/URL/range resolves.
• Evidence actually supports the claim.
• Scope matches the assigned slice.
• Headline counts can be re-counted from source.
• Confidence labels are preserved.

Accept only evidence-backed, scope-correct, non-contradicted findings. Demote, re-task, or verify the rest. Then compress at the barrier: write the distilled synthesis to .waves/<run>/synthesis-wave-N.md and work from that file - next-wave prompts cite paths, never re-paste raw handoffs.

Step 3.5 - Spawn Verifier Passes When Needed

Verification is the manager's highest-leverage job: checking a claim is usually cheaper than generating it, and unchecked errors compound across waves.

Use a dedicated verifier when a claim is high-stakes, contested, surprising, citation-heavy, single-sourced, or low-confidence. Give the verifier:

• The atomic claim.
• The cited source paths/URLs/commands.
• The acceptance question.
• No generator reasoning, and no authorship labels (judges favor output marked as their own; blind them).

The verifier returns supported, partly-supported, unsupported, or source-not-found per claim. For many claims, prefer spawn_agents_on_csv when available: one claim per row, fixed JSON result via report_agent_job_result. If the CSV tool is unavailable, spawn normal verifier subagents in waves under agents.max_threads.

Step 4 - Second Waves (continuous motion)

Multi-wave is the normal shape, not an exception: a realistic run is often 12 + 3 + 1 workers across three waves rather than one giant burst. Spawn another wave whenever first-wave handoffs expose:

• Missing coverage.
• Conflicting findings.
• A specialized follow-up that was out of scope.
• A verification task that can run while you synthesize.
• A dependent manifest slice whose depends_on handoffs just verified.
• A bounded implementation task after research converged.
• A new user request that narrows or redirects the scope.

Repeat until no slice is pending and nothing new surfaces (within the "Bounded Waves" depth/width caps).

Sequential second and third waves are spawned by the manager at depth 1 and are encouraged -- they are NOT what max_depth limits. agents.max_depth (default 1) governs recursion only: a worker spawning its own sub-workers. Keep recursion off by default and raise agents.max_depth deliberately and tightly only if a recursive subplanner is truly needed; manager-driven waves need no such change.

Step 5 - Deliver One Synthesized Artifact

Do not forward raw handoffs as the final answer. Produce the user's requested artifact: report, roadmap, code patch, audit, decision memo, or implementation plan. Cite worker evidence when it helps, especially file paths, line numbers, data ranges, URLs, and unresolved uncertainties. Carry confidence into the final output: verified, single-sourced, or unverified. Never turn a low-confidence handoff into a confident sentence.

If implementation is required after the research wave, either:

• Make the edits yourself in the manager thread after reading all handoffs.
• Spawn a bounded implementation wave with disjoint file ownership.
• Use Codex app worktrees or codex exec in separate git worktrees for heavier parallel code attempts.

Verify the deliverable itself:

• Run tests, validators, curl, screenshots, parsers, or smoke checks as appropriate.
• Regression-check sibling routes/files touched by the work.
• Re-read or grep critical files you wrote before relying on them.
• For generated artifacts, prefer a deterministic validator script or schema.

Worker Prompt Contract

Every worker prompt includes:

1. Overall goal as context only.
2. The worker's exact slice and ownership.
3. Where to look: paths, data ranges, URLs, MCP/docs sources, commands, or repo modules.
4. Coverage rule: read the assigned slice completely when feasible, report counts read such as 388/388, and call out skipped files/ranges.
5. Evidence rule: cite-or-drop every important claim, tag confidence (high|med|low), and say what would change the conclusion.
6. What not to do: avoid owning the whole task, avoid sibling scopes, avoid editing unless explicitly assigned.
7. The required handoff format from references/handoff-format.md - and keep it a digest: roughly 15 findings max with one-line evidence each; large artifacts (tables, logs, full lists) go to a file, cite the path.

End every worker prompt with the copy-paste ending for its worker type (generic, research, implementation, or verifier) from references/handoff-format.md § "Prompt endings per worker type".

CSV Fan-Out

Use spawn_agents_on_csv when the work is naturally one row per worker: files, incidents, packages, PRs, migration targets, messages, customer records, or claims to verify.

Manager responsibilities:

• Create a CSV with a stable id_column.
• Put enough per-row context in columns for a self-contained prompt.
• Provide an instruction template with {column_name} placeholders.
• Provide an output_schema when downstream synthesis needs machine-readable results.
• Require each worker to call report_agent_job_result exactly once.
• Set output_csv_path; use max_concurrency below or equal to agents.max_threads.

For a verifier pass, build claims.csv with claim_id, claim, sources, acceptance_question, and optional stakes. Require JSON fields: verdict, evidence, source_status, correction, confidence, and gaps.

If the CSV tool is unavailable in the active Codex surface, split the CSV into normal worker or verifier slices and use the handoff format.

Generate-and-Filter and Tournaments

For open-ended ideation or "produce the single best X", generate several candidates and filter rather than trusting one attempt:

• Cheap filter first: gate candidates through a near-ground-truth check (tests, codex exec --output-schema, schema/exec, dedup/clustering) before spending judge tokens. Generation is cheap; judging is not.
• Selection ladder, not all-pairs: dedup/cluster -> shortlist -> pairwise-judge only among finalists. A naive O(N^2) tournament wastes tokens on also-rans.
• Competing implementations: use Codex app Worktree mode or git worktree plus one codex exec per attempt, then inspect/test/merge the winner.
• Budget check: at equal cost, k independent attempts plus a majority vote or cheap filter usually beats critique/debate loops -- benchmark any iterative loop against that baseline before paying for it.

Parallel Writes in Codex

Codex subagents are a good fit for parallel write work when you use worktrees, separate sandboxes, or disjoint ownership. Still treat write coordination as a real merge problem:

• Read/research/test/log analysis: safe default.
• Disjoint edits in one checkout: acceptable when ownership is explicit and paths do not overlap.
• Overlapping edits: avoid. Have workers propose handoffs, then implement serially.
• Competing implementations: use Codex app Worktree mode, or plain git worktree plus one codex exec run per attempt.
• Always inspect and test the merged result in the manager thread.

Native Verification Surfaces in Codex

Use these where they fit:

• Tests, validators, type checks, linters, browser checks, and direct source recounts are the strongest verification signals.
• Custom verifier agents are the Codex-native replacement for a dedicated verifier worker.
• spawn_agents_on_csv is ideal for a verifier-per-row pass when exposed.
• codex exec --output-schema gives machine-readable verification in scripted fleets.
• Codex /review, GitHub code review, and reviewer custom agents help for code risk review.
• approvals_reviewer = "auto_review" is an approval/security reviewer only; it is not a general claim-verification hook.
• Lifecycle hooks exist in config, but current public docs do not confirm a general eval/critic hook for arbitrary worker findings.

Escalating Beyond One Interactive Thread

Use this skill for interactive, bounded fan-out inside one Codex task.

For scripted or CI-style fleets, use codex exec with explicit sandbox and model settings, often one process per git worktree. codex exec --json and --output-schema are useful when another script needs stable events or machine-readable results.

For always-on, team-scale orchestration, use the Symphony pattern: an issue tracker or queue as the control plane, one agent workspace per item, bounded concurrency, retries, observability, and human review. Treat Symphony as a reference/spec pattern, not a drop-in replacement for this interactive skill.

Checklist

• Used update_plan for multi-wave work.
• Discovered the shape of the problem before decomposing.
• Reduced entropy before slicing (dug locally -> pulled from attached resources -> asked the user only if it paid); sliced the low-entropy goal.
• Stated the run shape in one line before spawning (on the fence -> the smaller shape); never presented inline work as wave coverage.
• Staged or normalized inputs when it materially helps.
• Verified coverage before spawning: counts, bounds, partition-sum, gaps/duplicates.
• Slices are independent (or their depends_on edges recorded) and sized to agents.max_threads.
• Wrote the wave manifest (slice / role / effort / depends_on / verification tier) before spawning; launched dependent slices only after their dependencies' handoffs were verified; checked every row off at collection (completion gate); ran the failure ladder on missing/blocked slices.
• Each worker prompt is self-contained and ends with the handoff contract.
• Picked explorer, worker, default, custom agents, verifier agents, or spawn_agents_on_csv deliberately.
• Routed scouting / read-heavy waves to a fast low-effort model (gpt-5.5 low); reserved high effort for coding, verification, and synthesis.
• Avoided manual polling loops; waited only when synthesis was blocked.
• Read every handoff and resolved conflicts.
• Preserved per-finding confidence labels.
• Carried only distilled, verified syntheses between waves (no raw transcripts or losing candidates).
• Treated each open question / follow-up bullet as a candidate second-wave task; spawned waves for the ones that change the deliverable, coverage, or confidence.
• Verified high-stakes, conflicting, low-confidence, or uncited findings before synthesizing.
• Verified the final deliverable: re-ran/validated and re-read critical writes.
• Produced one synthesized deliverable.
• For edits, verified disjoint ownership or used worktrees.