Bootstrap iOS

Use this as the single entry point before touching an Apple-platform app. It is a router skill: discover the project, load only the references needed for the current job, verify that build/test tools exist, then act.

The default posture is conservative:

• Build and test before judging code.
• Prefer modern Swift, SwiftUI, Observation, Swift Concurrency, Swift Testing, SwiftData, and current Xcode APIs.
• Avoid deprecated APIs unless the deployment target requires them.
• Use XcodeBuildMCP or an agent-friendly build script instead of raw, unfiltered xcodebuild output when possible.
• Load focused skill packs on demand. Do not dump every Swift rule into context.

First move

1. Detect surfaces: iOS, iPadOS, macOS, mixed web/native, SwiftPM, Xcode project/workspace, Tuist, XcodeGen, CocoaPods, or buildable folders.
2. Read references/workflow.md.
3. If the task involves setup or machine bootstrap, read references/install-and-bootstrap.md.
4. If the task involves building, running, simulator, tests, or debugging, read references/xcodebuildmcp.md.
5. Pick only the external skill packs relevant to the current task from references/skill-map.md.

Mode picker

When installing external skills

Do not silently modify the user's machine. If the user asks to install or bootstrap, explain what will be installed, then use the helper script in dry-run first:

bash scripts/bootstrap-ios-skills.sh --dry-run --agent cursor

After the user confirms, run without --dry-run. The helper is idempotent and keeps optional/non-GitHub sources as instructions instead of pretending it can install them.

Verification

Before reporting an Apple-platform task done:

• Confirm the scheme/project/workspace you used.
• Run the smallest meaningful build or test command.
• Capture build errors from clean output, not raw wall-of-text logs.
• If using XcodeBuildMCP, name the tool/command used.
• If build/test is blocked by signing, missing simulator, or missing Xcode, report the blocker with the exact next command to fix it.
• For UI work, run in Simulator when feasible and capture enough evidence for the next agent to verify.

Sources

This skill synthesizes Paul Solt's X article "Install These Skills Before Codex Touches Your Xcode Project", the linked community skill repos, official OpenAI plugin references, Merowing rules, AppCreator notes, and getsentry/XcodeBuildMCP. See references/sources.md.

Running the Bug Review Board (BRB) QA pass

This skill runs a real-user QA pass on an app and feeds the output into a Bug Review Board: a folder of structured bug reports, per-pass run reports, a self-contained HTML dashboard, and a final YES/NO sign-off the team can act on. Engineering's tracker (Linear / GitHub / Jira / Notion) syncs bi-directionally so QA and engineering stay in step.

It generalizes a battle-tested workflow that already shipped phase QA on Mokuhoe — the techniques are repo-agnostic.

Why this exists

Most engineers test their own code. They confirm what they wrote works. That misses the bugs real users hit first — stale state across flows, mobile overflow, copy that lies, paths that 404 mid-onboarding, race conditions between auth and routing.

This skill simulates a real user. The QA agent acts like a careful, mildly unforgiving customer who does not read the source code.

Two workflows — Auto QA and Interactive BRB

The skill splits the work into two distinct modes that share artifacts but run in separate sessions on purpose:

• Auto QA pass — the agent drives the app, runs scenarios, files bugs, generates the HTML report, writes a verdict. Optimized for thoroughness and speed.
• Interactive BRB — a different agent meets with the user to triage open / in-progress / fixed bugs. Runs the bi-directional pull first, applies pattern-based heuristics to surface duplicates and clusters, walks each bug, flips statuses, syncs to the tracker, regenerates HTML, writes minutes. Optimized for shared judgment.

Keep them separate. Running BRB inside an auto pass lets triage bias contaminate discovery and confuses attribution. See references/brb-interactive.md.

The trifecta — three hats, one pass

For every pass, wear all three hats:

• Product Manager. Confirm the build delivers the user-visible promise documented in the product spec or phase doc. If it does not, that is a product gap, not a bug — flag it in the run report.
• QA. Execute every scenario from a real user's perspective on the primary supported viewport(s). Capture evidence (snapshot, console, server data when relevant). Pass / Fail / Blocked.
• Engineer. Watch for invalidated assumptions: phase doc says "X uses function Y" but Y was renamed; new client orchestration appeared in a flow the docs say is server-driven; fields exist in UI that aren't in the spec. Finding gaps is the point — don't reverse- engineer the docs to match buggy behavior.

Do not fix product code unless the user explicitly asks. Test, document, file bugs, hand off.

Discover the app first (or you'll write bad tests)

Before writing a single test, understand the intent of the app — what the customer is hired to do with it. See references/discovering-the-app.md for the full investigation playbook. The short version:

1. Read the product spec / README / landing page / pitch deck (in that priority order) for what the app promises.

2. Read the phase doc (or current sprint plan) for what was just built.

3. Read prior QA gates / checklists for what passed before — regressions are your highest-value finds.

4. Read the bug-reports index — open bugs are scenarios you must re-test first.

5. Detect the project type(s). A repo can ship more than one app — a web + iOS monorepo is common — so collect every surface whose signals are present instead of stopping at the first hit. Two disambiguation rules resolve overlapping signals inside a single app; they are not a reason to skip a genuinely separate surface:

   • Electron / Tauri beats Web app for the same app. An Electron / Tauri project (electron, @electron/, @tauri-apps/ in package.json, or electron-builder.yml / tauri.conf.json) also contains package.json and web framework deps, but those deps belong to the desktop app — count it once as a desktop app, do not also count it as a separate Web app.
   • macOS vs iOS on a shared *.xcodeproj / *.xcworkspace. A bare Xcode project is shared between the two, so don't classify on it alone — require a platform-specific marker (below).

   The surfaces, with the playbook each activates:

   • Electron / Tauri desktop app → use computer-use-playbook.md. (On non-macOS hosts where Computer Use is unavailable, the playbook's graceful-degradation table directs you to drive the app's dev-server URL via browser-playbook.md instead.)
   • Web app (web framework deps without Electron / Tauri markers) → use browser-playbook.md.
   • iOS / iPadOS app (an iOS-specific marker is present — .iOS(...), platform :ios, UIDeviceFamily, or an ios/ directory) → use ios-simulator-playbook.md.
   • Native macOS app (a macOS-specific marker is present — .macOS(...), a .app bundle, or LSMinimumSystemVersion — and no iOS marker) → use computer-use-playbook.md.
   • Mixed (monorepo) — signals for two or more distinct surfaces above (e.g. web framework deps and an iOS marker) → run every matched playbook; the test plan gets per-platform scenario blocks. A web match must never short-circuit a co-located iOS (or macOS) pass.
   • Other (no UI signals) → no UI playbook activates.

   Also note whether Codex Computer Use is available (macOS only) — it enables a human-fidelity pass on web apps and is the only way to reach a native Mac or Electron/Tauri app. Most VMs (Cursor cloud, CI) won't have it, so never make the pass depend on it.

6. Detect the issue tracker (Linear, GitHub, Jira, Notion, or none). Surface every signal found and ask the user to confirm before writing qa-config.json. See issue-trackers.md.

7. List the public routes / surfaces / entry points and decide which a real new user would touch.

If the user says "QA this app" but no docs exist, ask — see references/discovering-the-app.md § Asking the user.

Workflow (any phase, any repo)

1. Scope        → which surface / phase / build
2. Discover     → product intent + recent change + open bugs
                + project type + issue tracker (confirmed)
3. Plan         → manual test plan (scenarios, IDs, expected, gates)
4. Prepare      → env, build, test accounts, viewport / device matrix
5. Mode         → parallel coordinator OR sequential wrap-up
6. Execute      → real-user scenarios with evidence
7. File bugs    → P0/P1/P2 with reproduction steps
8. Merge        → results + verdict (YES/NO + open P0/P1)
9. Generate HTML → apply html-report-style-guide.md
10. Hand off    → next QA agent (if NO) or engineering (if blockers)
11. Schedule BRB → separate session for interactive triage

Detail in references/workflow.md.

Mode picker

Surfaces — which playbook activates

Detected during the discovery step. Match repo signals to the playbook(s) for every surface present — usually one, but a monorepo matches more than one (see Mixed below). Record the choice(s) in docs/qa/qa-config.json so later passes don't re-litigate it.

For iOS app QA, our skill orchestrates (discovery, test plan, bug filing, BRB) and defers the simulator driving to one of the iOS community's purpose-built skills — AXe (Cameron Cooke), XcodeBuildMCP (Cameron Cooke / Sentry), ios-simulator-skill (Conor Luddy), ios-build-verify (Josh Adams), baguette (tddworks), ios-idb-skill (Hao Wu), serve-sim-skill (malopezr7), swiftui-autotest-skill (Yusuf Karan), xcode-build-skill (pzep1), and App Store Connect CLI + skills (Rudrank Riyam) for the TestFlight hand-off. See the playbook for the recommended-stack table.

Issue tracker integration

The skill discovers and confirms — it never assumes. The discovery ceremony probes signals (LINEAR_API_KEY, gh auth status, Atlassian URL, registered MCP servers, etc.) and surfaces every finding to the user before writing docs/qa/qa-config.json. Once confirmed, the agent files bugs locally and syncs to the tracker (push at file time or BRB time per config) and pulls engineering's status changes back (default ON for BRB start). Bi-directional reconciliation rules are spelled out in the reference so divergences surface as user-decision diffs, never silent overwrites.

Tracker IDs live in the bug front-matter — Tracker / Linear, Tracker / GitHub, Tracker / Jira, Tracker / Notion, Tracker / lastSyncedAt. The HTML report renders them as tags on every bug card.

Helpers: scripts/bugs-needing-sync.sh lists bugs missing tracker IDs (push candidates). scripts/bugs-needing-pull.sh lists bugs whose Tracker / lastSyncedAt is stale (pull candidates).

HTML report (Zite + Dieter Rams)

At the end of every pass and every BRB session, regenerate docs/qa/report/index.html plus per-bug and per-run detail pages by applying html-report-style-guide.md.

The report reads like a magazine, not a Kanban board. Typography does the work — priority is the word P0 in small caps, status is the word Open, verdict is a single display-type word (YES or NO). One ink colour for body, one quiet terracotta accent for links and CTAs, hairline rules for separation. No coloured chips, no pills, no shadows. A 640px reading column on every screen size; on desktop, bug detail pages add a quiet right rail for metadata. On mobile, a sticky thumb-zone duplicates the primary action so the reader doesn't have to scroll back up.

The information hierarchy is engineered for the engineer-reviewer's sweep: Title → Deck → Impact → Actual / Expected → Risk to fix → Steps → Evidence. The bug template grew Impact and Risk to fix sections in v0.3 (additive — old bugs render gracefully without them).

Markdown stays the source of truth. HTML is read-only and regenerated. Never edit the HTML to change bug state — edit the markdown and regenerate. The dashboard is what stakeholders open during BRB and ship reviews.

Pattern-based triage suggestions

The Interactive BRB opens with a Suggestions card surfaced by a catalog of named heuristics in triage-heuristics.md — same suspect file, steps-prefix overlap, same console error, same persona+surface+ outcome, phase cascade, cosmetic cluster, regression marker, same owner. Every suggestion cites a heuristic name and the matching text so the user always sees why something was flagged. No embeddings, no LLM API, no auto-merge. The agent suggests; the user decides.

The same heuristics are also opt-in during the auto pass at file time (triage.runHeuristicsOnFile, default false) so the pass can ask "file new, or update BUG-007?" instead of double-filing.

Scaffold folders if missing

If the target repo has no QA folder structure yet, run the bundled scaffolder to create it:

bash <skill>/scripts/scaffold-qa.sh "$REPO_ROOT" PHASE_NUM [SLUG]

It creates (idempotent — won't overwrite existing files):

<repo>/docs/qa/
├── README.md                         # how QA works in this repo
├── qa-config.json                    # stub; discovery rewrites once user confirms
├── phase-NN-<slug>-manual-test-plan.md  # filled-in skeleton (if PHASE_NUM given)
├── report/                           # HTML report destination (agent generates)
├── bug-reports/
│   ├── README.md                     # index + status workflow
│   ├── _template.md                  # bug template
│   └── assets/                       # screenshots (incl. ios/ for iOS QA)
└── runs/                             # per-shard + coordinator merges + BRB minutes

If a different layout already exists in the repo (e.g. tests/manual/, qa/, an issue tracker), adopt that layout — do not duplicate it.

Always

• Real user perspective. Drive the app, not the source. Test from URLs and clicks (or simulator taps), not from convex/users.ts or the API layer alone.
• Test mobile, tablet, and desktop. Real users arrive on all three, and layout / overflow / tap-target bugs hide at the breakpoint you skip. Cover all three modes for web apps — reference sizes mobile 375 × 812, tablet 768 × 1024, desktop 1280 × 800 (adjust to the spec's breakpoints). Lead with the app's primary target: take it from the product spec; if the spec is unclear, ask the user which mode matters most; if the user isn't available, infer the most likely primary from what you discovered in the repo (responsive CSS / breakpoints, framework defaults, marketing copy) and note the assumption. Record the modes and the chosen primary in qa-config.json#platforms.web so later passes don't re-litigate it. For iOS apps, the device matrix comes from qa-config.json#platforms.ios.devices.
• One browser tab per agent. Parallel agents on a shared tab cause auth-provider rate limits and stale sessions.
• Capture evidence. Snapshot or screenshot at the moment of failure, console errors verbatim, server data row when relevant.
• File bugs immediately on FAIL — see references/bug-filing.md. Do not wait until end of pass.
• Use the test account playbook. See references/test-accounts.md. If none documented, ask the user before guessing.
• Session hygiene between scenarios. See references/session-hygiene.md. Stale storage / cookies / +test email reuse silently poisons fresh-user flows.
• Run the discovery ceremony in issue-trackers.md once per repo before filing bugs.
• Regenerate the HTML report at the end of every pass and every BRB session per html-report-style-guide.md.
• For iOS app QA, defer the actual simulator driving to a companion skill from ios-simulator-playbook.md; do not reinvent boot / tap / screenshot.

Never

• Mark a scenario PASS from code inspection alone. The user does not experience source — they experience the app.
• Mark a phase gate ☑ without evidence (snapshot, server row, console clean).
• Fix product code unprompted. Document. File. Hand off.
• Skip the Known issues / deferrals section in the phase doc — those drive your scope and prevent false bugs.
• Rename phase docs or specs to match buggy behavior. Hides regressions.
• Run multiple QA browser sub-agents on one cursor-ide-browser tab.
• Reuse a previously-failed test email without changing the run-tag suffix.
• Assume an issue tracker without asking the user — even when signals are obvious.
• Run Interactive BRB in the same session as an auto QA pass — they are intentionally separate to keep triage bias out of discovery.
• Auto-import tracker-only bugs into local markdown without asking the user (default pull.createLocalForUntracked: "ask").
• Auto-merge bugs the heuristics flag as duplicates — every merge / dedup needs user confirmation.
• Edit the HTML to change bug state. Edit the markdown; regenerate.
• Use the iOS simulator playbook for web-app QA. It's for iOS app projects only. Mobile web QA stays in the browser playbook.

Bug priority (BRB taxonomy)

When in doubt between P0 and P1, choose P0 if a user could land in a non-recoverable state or lose data.

Pass criteria (any phase)

• All scenarios in the phase manual test plan PASS (or are explicitly deferred with reason in the phase doc).
• Phase gate / checklist all green.
• No open P0 or P1 bugs against this phase.
• For phases that touch auth / invites / notifications: the regression matrix is green.

Definition of done

Every pass ends with a coordinator merge doc whose top line reads:

Phase N ready? YES — all gates ☑, no open P0/P1. Phase N ready? NO — list open P0/P1 + remaining unrun scenarios

• a one-paragraph handoff prompt for the next QA agent.

If NO, the merge doc must be paste-ready into a new conversation. The next agent should not need to rediscover state. See references/gate-merge.md.

The HTML report (docs/qa/report/index.html) is also regenerated and committed.

Browser tools (cursor-first, fallback ladder)

Default to cursor-ide-browser MCP when running inside Cursor. If the session is in another tool or browser MCP is missing, fall back per the ladder in references/browser-playbook.md:

1. cursor-ide-browser MCP (Cursor / Claude Code)
2. Chrome DevTools for agents (chrome-devtools-mcp) — auto-waits for results and adds DevTools-grade network / console / Lighthouse / a11y inspection; can attach to your real signed-in Chrome so auth flows don't get bot-flagged
3. browser-use MCP (provider-agnostic)
4. Playwright (CLI or MCP)
5. Codex Computer Use (macOS) — human-fidelity pass on the real signed-in app; see computer-use-playbook.md
6. Driving manually + asking user to paste console errors / screenshots

Whatever tool, the playbook is the same: navigate → snapshot → act on fresh refs → capture evidence → unlock when done. The reference covers each tool's specifics, including how to drive like a human so the app doesn't trip on bot detection or timing races. The pass must succeed with whatever the environment has — don't depend on Computer Use, which most VMs lack.

Deliverables per pass

Adapt paths to whatever the target repo already uses.

References (load on demand)

• references/workflow.md — full PM/QA/Eng decision tree
• references/discovering-the-app.md — investigate intent + ask user when docs missing
• references/test-plan.md — derive a phase manual test plan from spec + phase doc + gate
• references/test-accounts.md — Clerk / Auth0 / Supabase / custom — and the "ask the user" pattern
• references/session-hygiene.md — stale storage, rate limits, persona suffixing
• references/browser-playbook.md — cursor-ide-browser, Chrome DevTools MCP, browser-use, Playwright recipes + how to drive like a human (web apps)
• references/computer-use-playbook.md — Codex Computer Use for web and native macOS apps (macOS; graceful fallback to a browser driver elsewhere)
• references/ios-simulator-playbook.md — iOS / iPadOS app QA, curated companion-skill ladder (AXe, baguette, XcodeBuildMCP, ios-simulator-skill, ios-build-verify, …)
• references/parallel-coordinator.md — shard map, write-path-first rule, copy-paste shard prompts, and running the pass as a bounded wave when waves / waves-codex is installed
• references/sequential-wrapup.md — single-agent finish; copy-paste prompt
• references/bug-filing.md — bug template, severity, evidence rules, status transitions
• references/gate-merge.md — merge shard reports → gates + verdict
• references/issue-trackers.md — discover-and-confirm ceremony, Linear / GitHub / Jira / Notion adapters, bi-directional sync
• references/brb-interactive.md — Interactive Bug Review Board workflow (separate session)
• references/triage-heuristics.md — named heuristics catalog for duplicate / cluster detection
• references/html-report-style-guide.md — Apple-language tokens, components, rendering rules
• references/extending-the-skill.md — add a tracker, heuristic, surface, or mode without rewriting
• references/templates/ — bug-report, test-plan, run-report, coordinator-merge, brb-interactive-prompt, brb-minutes, qa-config.example.json, html-report/ skeletons

Scripts

• scripts/scaffold-qa.sh REPO_ROOT PHASE_NUM [SLUG] — creates the QA folder layout, qa-config stub, and report folder in any repo.
• scripts/bugs-needing-sync.sh REPO_ROOT [--tracker …] — lists bugs missing a tracker ID; the agent reads the list and pushes per issue-trackers.md.
• scripts/bugs-needing-pull.sh REPO_ROOT [--threshold 24h] [--tracker …] — lists bugs whose Tracker / lastSyncedAt is stale; the agent reads the list and pulls per issue-trackers.md.

Extending this skill

Adding a new issue tracker, triage heuristic, surface playbook, or mode is additive — copy a section, fill it in, the agent picks it up on the next session. Forward-compatible qa-config.json schema (version: 1, unknown fields ignored), additive bug front-matter, versioned HTML report marker. See references/extending-the-skill.md.

Anti-patterns to avoid

When a QA pass reveals work bigger than QA

If during the pass you find:

• A missing feature the phase claims exists (no code path at all)
• A schema diverging from the spec across multiple scenarios
• A P0 blocking every remaining scenario

Stop testing. Surface the finding. The user decides whether to escalate to engineering or carve a smaller phase. Continuing wastes time on a foundation that needs replacing.

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.

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

Run wave-based orchestration inside one local Cursor session. A wave is a bounded round of isolated agents working in parallel, then a round that verifies what came back, then a deliberate decision to build on it — not an open-ended loop. You are the orchestrator: you discover, decompose the goal into independent slices, fan them out to parallel workers (the Task tool, run in the background = "Multitask Mode"), read each worker's structured handoff, verify it, and synthesize one deliverable. Workers are isolated and return exactly one handoff.

The shape of every wave — WAVE:

• W — Workers. Fan out isolated workers across disjoint slices (the bounded parallel round).
• A — Aggregate. Wait for all of them and merge their structured handoffs at the synthesize barrier.
• V — Verify. The moat: check the evidence behind each handoff before you trust it.
• E — Extend. Decide — deliberately — whether to launch another wave, or stop.

A loop doesn't know when to stop; a wave does, because verification is the stop function. (Invoked explicitly with /waves: a run spawns more agents than usual, so it's opt-in, not auto-triggered.)

This is the local, zero-setup adaptation of the Cursor team's orchestrate plugin (which spawns cloud agents over the Cursor SDK). Same principles — planners plan, workers hand off up, no cross-talk — without any of that cloud setup. For heavyweight cloud fan-out, see "Escalating" below.

When to use

• A large goal that splits into independent slices (research areas, data chunks, files/modules, audit dimensions).
• The work is mostly read / research / analysis — the safest thing to parallelize locally (see "Parallel writes" for why).
• A single linear pass would be slow and you want real speedup from concurrency.

When to skip

• Small or linear tasks (just do them — fan-out overhead isn't worth it).
• Work needing tight back-and-forth or shared mutable state between steps.
• Parallel edits to the same files — local workers share one filesystem.

Core principles

Adapted from orchestrate. These keep the run converging without coordination.

1. Orchestrator plans and synthesizes; it does not do the heavy lifting. Discovering, decomposing, reading handoffs, and writing the final deliverable are your job. The bulk reading/research/analysis is delegated to workers.
2. Workers are isolated. A subagent has no access to the user's message, your prior steps, or sibling workers. Every worker prompt must be fully self-contained: goal context, its exact slice, where to look, what to return.
3. One worker, one slice, one handoff. The worker's final message is the only thing you read back. Define its exact shape (see references/handoff-format.md).
4. Parallelism is for reading, not writing. Local workers share the workspace; concurrent writes to overlapping paths corrupt each other.
5. Continuous motion. A handoff can reveal new work. Spawn a second wave (driven by a handoff gap or a new user request). Stop only when every slice is terminal and the synthesis is complete.
6. Verify before you trust. A worker's Status: success is a claim, not evidence. Check each handoff against something re-openable before folding it into the synthesis. See "Verification" below and references/verification.md.
7. Decomposition is entropy reduction. A vague goal is high-entropy — many plausible plans still fit it. Your first job is to shrink that space (dig locally, then pull from attached resources, then ask the user only if it pays) before you slice it; slicing a high-entropy goal yields overlapping, mis-sized slices. See "Entropy-first decomposition."

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") doesn't slice cleanly yet — reduce the uncertainty first, then decompose the low-entropy version. Name what's 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 don't 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 is the one that splits the surviving interpretations roughly in half, not the one easiest to look up.

1. Dig locally first (cheap). Tool calls in the main session (list, read the schema/README, grep, sample data). This is Step 0, framed as entropy reduction; it often collapses most of the uncertainty for free.
2. Then pull from attached resources. If the environment doesn't hold the answer, spawn a small scouting wave of research workers to fetch it (web, Exa/Ref MCP, docs) — route these read-heavy slices to the cheap, fast model (see "Picking the model per slice").
3. Ask the user last, and only when it pays. Ask only when residual specification uncertainty is high and the question's expected information gain clearly beats its cost. Most requests carry enough to proceed on a stated assumption; over-asking is its own failure mode.

Then cascade: one high-level request becomes a decomposition wave (understand → locate unknowns → draft the plan) → verify → an execution wave that builds the ordered subtasks, with more scouting sub-waves wherever entropy stays high. Order the plan least-to-most — do the first-order subtasks first and let each verified result lower the uncertainty for the next. Keep the living plan in TodoWrite, and stop reducing when entropy is low enough to act: the verification gate doubles as "is the uncertainty low enough to commit?" One caution: a plan-then-execute pass fixes missing steps, not a misread goal — only the specification check above catches wrong framing, which is why it comes before planning. (Worked example + wave shape + paper grounding: references/examples.md.)

The loop

Track it with TodoWrite so the waves stay visible.

Step 0 — Discover first (serial, in the main session)

Do not fan out blind. Spend a few cheap tool calls in the main session to learn the shape of the problem: list the directory, read the schema, sample the data, confirm coverage/size. This is what tells you the natural decomposition (how many chunks, which workstreams). Skipping discovery produces overlapping or mis-sized slices.

Step 0.5 — Stage the data (when it's remote or messy)

explore workers are read-only with no MCP or internet access, so they can't reach remote hosts, databases, or networked sources. If the source is remote or wrapped in noise, the orchestrator must stage clean inputs before fanning out:

• Pull remote → local. SSH/rsync/export the relevant data to a local scratch dir so read-only workers can read it (e.g. query a remote SQLite read-only, export the rows, rsync the markdown).
• Clean + normalize once, centrally. Strip wrappers, boilerplate, and binary blobs (base64, logs); fix timestamps. Doing this once beats making every worker re-derive it (and keeps noise out of their context).
• Pre-chunk for the workers. Split into the exact per-worker files/ranges so each prompt can point at one path.
• One scratch dir per run. Keep staged inputs, worker artifacts, and between-wave syntheses in one place (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.
• Verify before you spawn. Print counts and per-slice bounds; confirm the partition sums to the total (e.g. 8 chunks × ~388 = 3,097) so no slice is a silent blind spot. Fix anomalies (bad sort, dups) centrally, then re-check. (Details: references/verification.md §1.)

In practice this serial prep is often the largest phase; the parallel fan-out is fast once inputs are clean.

Step 0.7 — Triage: size the run, then classify each slice

Size the run first, out loud. Weigh breadth (how many independent slices), depth (how much reasoning each needs), ambiguity (how well-formed the goal is — see "Entropy-first decomposition"), and stakes (how costly a wrong answer is — this sets verification tiers), then state the chosen shape in one line before spawning — e.g. Run shape: one wave, 4 workers (3 research + 1 data chunk); second wave only if handoffs expose gaps. On the fence between two shapes, pick the smaller and say so. And if triage says no wave is needed, do the task inline and say that — never present inline work as wave coverage.

Then classify each slice on three axes — this is the classify-and-act pattern, routing the right work to the right handler:

• Worker type — read-only (explore) / web-research (generalPurpose) / shell / competing-attempt (best-of-n-runner) / specialized review (bugbot, security-review). (See the table under "Choosing subagent_type".)
• Dependencies — which slices (if any) this one needs verified output from. Most slices should have none; a real dependency edge is what separates waves.
• Verification tier — how much checking the slice's stakes justify: auto-accept (low-stakes, corroborated) → single verifier (medium) → multi-model panel (high-stakes) → debate (contested, no ground truth). Spend the verification budget where a wrong claim is expensive, not uniformly.

Record the triage as a wave manifest — one row per slice, written before you spawn (in TodoWrite or .waves/<run>/manifest.md):

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 unrelated slices stay parallel. The manifest is also your completion gate: N rows spawned means N handoffs collected and checked off before synthesis — a wave with a missing handoff has a silent hole in it (Step 3).

Step 1 — Decompose into independent slices

Split along whichever axis makes slices independent:

• Data chunks — partition large data and give each worker a disjoint range (e.g. messages 1–500, 501–1000, …).
• Workstreams — separate research/analysis areas (e.g. "research voice stack", "research the Notion SDK", "audit auth code").
• Files / modules — disjoint, non-overlapping path sets.

Each slice needs: a one-line scope, what to look at, and a defined output. For a big wave (roughly 5+ workers), state the decomposition plan to the user before spawning so they can redirect cheaply. If you have many slices, fan out in waves (launch a batch, let it complete, launch the next) rather than all at once, so you stay within practical concurrency limits.

Step 2 — Fan out in parallel

Send one message with multiple Task tool calls — one per slice whose dependencies are met (handoffs verified, not just returned) — that is what makes them run concurrently. Set run_in_background: true on each (Multitask Mode). Pick subagent_type per slice (table below). Give each a 3-5 word description and a self-contained prompt ending with the required handoff format.

Then end your turn. You are notified as each background worker completes — do not AwaitShell, poll, or read output files in a loop. The Task call itself confirms the launch.

Step 3 — Collect and synthesize

Completion gate first: check off every handoff 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, and synthesizing around it silently drops a slice. Worker failure ladder: (1) re-task once, narrower — resume the same worker (each Task returns an agent ID that resumes with context preserved) 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 yourself in the main session; (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.

As handoffs arrive, read each one: note Status, extract Key findings, and mine Open questions / Suggested follow-ups — each bullet may become a second-wave task. Reconcile conflicts across workers.

Don't trust a handoff because it says success. Verify each finding's evidence (cited file:line / URL / metric resolves and says what's claimed), recount headline numbers from the source, and route low-confidence, conflicting, or citation-heavy claims to a verifier (Step 3.5). See "Verification" below. A wave's handoffs count as verified only when these checks pass and every claim whose manifest tier demands a verifier has its verdict back — cheap checks alone don't clear a single verifier or higher tier.

Only 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 into the scratch dir, never re-paste raw handoffs. This file is what dependent slices and later waves consume, so nothing unverified enters it as a finding: a claim still awaiting its verdict is carried only as an explicit pending-verification line.

Step 3.5 — Verifier pass (when the tier demands it)

Before writing the wave synthesis, spawn dedicated verifier workers for every claim whose manifest tier is single verifier or higher — and for anything that arrived contested, surprising, single-sourced, or low-confidence. Give each verifier the claim + its cited sources, no generator reasoning, no authorship labels (see "Verification"). Verifiers can run while you draft around them, but their verdicts gate the wave synthesis itself, not just the final deliverable: until its verdict returns, a claim may sit in synthesis-wave-N.md only as an explicit pending-verification line — never as a settled finding, and never in a dependent slice's prompt (Step 0.7's met-only-when-verified rule).

Step 4 — Second waves (continuous motion)

If handoffs exposed gaps or follow-ups — or verified handoffs just unblocked dependent manifest slices — spawn another parallel wave the same way. Repeat until no slice is pending and nothing new surfaced.

Step 5 — Deliver

Synthesize all handoffs into the single artifact the user asked for (roadmap, report, summary, plan). Cite which worker produced which finding when it helps, and carry each claim's confidence through (verified / single-sourced / unverified) — never launder a low into a confident sentence.

Then write any code/files yourself, or spawn a dedicated implementation wave (mind "Parallel writes"). Verify the deliverable, not just the handoffs: re-run/curl/validate served artifacts, regression-check sibling routes, and re-read the critical files you wrote (see references/verification.md §6).

Bounded waves — size, caps, and when to stop

A wave is bounded on purpose. "Loop-until-done" (spawn until a stop condition) is a real pattern, but unbounded it burns tokens for little gain: candidate generation is cheap, but selection plateaus, and extra rounds are non-monotonic — more iterations can lower quality, not just cost. Bounded waves keep the exploration and drop the runaway.

• Width: N = 3–8 workers per wave. Size N so you can fully verify all N. Go wider only when a cheap automatic check (tests, schema, exec) gates the results.
• Depth: ≤ 2–3 waves, capped up front. Stop when a wave surfaces nothing new and its outputs are near-duplicates of the last (stagnation), or when quality dropped versus the prior wave.
• Budget: ~60% generation / 40% verification. Selection is the scarce resource; spend there.
• Match width to difficulty: easy → 1 + a light refine; medium → 3–5; hard/open-ended → 5–8 for approach diversity; hardest/novel → don't loop, escalate the model.
• Anti-poisoning handoff: carry only a distilled, verified handoff (the winner + a short critique) into the next wave — never raw transcripts or losing candidates. Long, irrelevant context measurably degrades reasoning.

Loop-until-done is justified only when ALL hold: a cheap, reliable ~ground-truth verifier exists; the signal is crisp and actionable (a failing test, not "try harder"); each iteration shows measurable progress; the work is easy–medium difficulty; and it stays hard-capped. That fits code-with-tests and exec-feedback pipelines; it misfits open-ended research/writing/design (verify in bounded waves instead).

Verification

The orchestrator's highest-leverage job. You can't make a worker smarter at inference time, but verifying a handoff is far cheaper than producing it, and in a multi-wave run one unchecked bad handoff compounds into the synthesis.

• Gate before spawn — counts, coverage, partition-sums (Step 0.5).
• Cheap checks every handoff — evidence present + resolves, scope match, contradiction skim, citations actually support the claim.
• Self-checks in the prompt — cite-or-drop, confidence tags, "read COMPLETELY", live sources, flag-unverified. (Don't rely on freeform "double-check yourself"; give an oracle or a separate verifier.)
• Dedicated verifier worker for high-stakes / contested / citation-heavy claims — give it the claim + sources but not the generator's reasoning nor any authorship label (judges favor output marked as their own; blind them), and have it reason against a rubric/reference before its verdict (reference-guided + CoT is the cheapest reliable judge upgrade). Never show the generator the verifier's rubric (anti-gaming). For the highest-stakes calls, a multi-model panel + synthesis checks harder still (see "Multi-model fan-out").
• Measure & cross-check — re-run the oracle, recount from source, require ≥2 independent sources that actually entail the claim (a citation being present ≠ the claim being supported).
• Escalate low-confidence / conflicting findings (re-task with a tighter prompt → dedicated verifier → ask the user, who may choose a stronger model) instead of folding them in.

Strongest on objective, checkable work (counts, code, facts-with-sources); on taste/judgment, verify the sub-claims, don't fake a grade. Keep claims honest: isolation reduces error propagation / path dependency, but don't claim a quantified "prevents poisoning" — there's no isolation-only ablation. Full playbook: references/verification.md.

Choosing subagent_type

Custom subagents and the missing-type fallback. Custom subagents (project .cursor/agents/, user ~/.cursor/agents/, or plugin-provided) show up as their own subagent_type values — worth defining when a role repeats across runs (a verifier, a docs researcher) so its prompt and pinned model live in one file. Two verified gotchas: new agent files register only after a Cursor restart, and a type missing from the enum is not permission to skip the role — run it as generalPurpose with the role's instructions inlined in the worker prompt (passing the intended model on the call) instead.

Picking the model per slice (cost / speed routing)

Model choice is a cost/speed lever — route it, don't put every slice on a frontier model:

• Scouting / decomposition / read-heavy exploration → the cheap, fast model. Cursor's built-in explore and search subagents already default to the Composer fast family (e.g. composer-2.5-fast) for exactly this: fast, cheap, and tuned for codebase understanding and tool use — so read waves are cheap by default and you often need not set model at all. To pin it, pass model: "composer-2.5" (or composer-2.5-fast) on the Task worker, or set the model field (inherit | fast | a slug) on a custom .cursor/agents/ subagent. This is the entropy-reduction workhorse.
• High-stakes verification, synthesis, or a multi-model panel → stronger reasoning, chosen deliberately. For a user-requested or high-stakes multi-model panel, ask which models to use; don't guess slugs (see "Multi-model fan-out").
• Otherwise honor a model the user named; if a requested model is unavailable, say so rather than silently substituting.

Caveats: availability varies (Max Mode, plan, or admin restrictions can force a fallback to a compatible model); slugs drift, so read them off Cursor's model picker rather than hardcoding volatile ones; inherit can be unreliable in some surfaces (omit model to inherit). When a custom agent's model matters, pin it in the frontmatter and pass the matching model on the Task call — the field has been ignored under some conditions (documented fallbacks plus confirmed bug reports), so if a worker's output quality looks off, consider that the intended model may not have run. Respect the user's cost and model preferences over any default here.

For review/audit slices, Cursor also exposes specialized subagents when available (e.g. bugbot, security-review, ci-investigator, ci-watcher) — prefer them for those slice types.

Multi-model fan-out (panel + synthesize)

The default fan-out runs each slice on one model. A high-stakes slice — an architecture/design call, a risky correctness question, a security or audit pass, or a key research synthesis — fan the same slice out to a panel of different models, then act as judge and synthesizer.

Reconcile; don't concatenate. Label CONSENSUS (2+ models agree) vs lone-model findings, resolve contradictions, dedupe overlap, and carry each claim's confidence into one answer. The synthesis is where most of the value lives — per OpenRouter's Fusion research, roughly three-quarters of the gain comes from the synthesis step, not the model diversity — so invest there rather than stapling outputs together. Evidence: a panel of independent models + a judge + a synthesizer matched and surpassed a single top-tier model on hard, deep-research problems (OpenRouter, Surpassing Frontier Performance with Fusion, openrouter.ai/blog/announcements/fusion-beats-frontier/).

Run it in Cursor: pass a different model to each sibling Task worker on the same slice, launch them in one message with run_in_background: true (parallel), then synthesize. This is the high-stakes end of model routing — the orchestrator picks frontier models only when the user asks for a multi-model pass or the slice is explicitly high-stakes — so ask which models to use; don't guess slugs. (The cheap end — routing scouting and read-heavy waves to Composer 2.5 — is under "Picking the model per slice.")

Caveat: a panel multiplies token cost (you pay every worker) and adds latency — reserve it for high-stakes slices, not routine ones. The adversarial multi-model review (a panel of reviewer models + one synthesized verdict) is this same pattern applied to code review. For grading panels specifically, judges drawn from disjoint model families beat a single frontier judge on human agreement while cutting self-preference bias and cost (PoLL) — the family diversity, not the head count, is what does the work.

Generate-and-filter & tournaments

For open-ended ideation or "produce the single best X", generate several candidates and filter — don't trust one attempt:

• Cheap filter first. Gate candidates through a near-ground-truth check (tests, schema/exec, dedup/clustering) before spending judge tokens — generation is cheap, judging is not. (AlphaCode's shape: generate many → filter ~99% by tests → cluster → submit a few.)
• Selection ladder, not all-pairs. Dedup/cluster → shortlist → pairwise-judge only among finalists. A naive O(N²) tournament spends most of its tokens comparing also-rans.
• Use best-of-n-runner for competing implementation attempts (each in its own git worktree), then inspect/test/merge the winner yourself.
• For high-stakes judgment calls, the multi-model panel (above) is the generate-and-filter of verification.
• Budget check. At equal cost, k independent attempts + a majority vote or cheap filter usually beats critique/debate loops — benchmark any iterative loop against that baseline before paying for it.

Worker prompt = the contract

A worker cannot ask follow-up questions. Under-specified prompts drift silently. Write each as if you get one shot. Every worker prompt includes:

1. Overall goal (context only — "don't try to own the whole goal").
2. This worker's exact slice (the disjoint range / area / paths).
3. Where to look (dirs, files, data ranges, which MCP/tools to use).
4. What to return — the structured handoff from references/handoff-format.md.
5. Self-verify rules — cite-or-drop every claim, tag confidence (high|med|low), and state what you could not verify. Analysis workers: "read COMPLETELY (N lines) and report the count." Research workers: "use live sources, not training data."
6. Scope boundaries — what's explicitly OUT of scope (so it doesn't overlap a sibling worker).
7. Return only the handoff, and keep it a digest. The worker's entire final message becomes your context — tell it to return only the structured handoff, capped at roughly 15 findings with one-line evidence each, and to write any large artifact (tables, logs, full lists) to a file and cite the path instead of pasting it inline.
8. Edit workers: you are not alone. For implementation slices, warn the worker that siblings may be active: own only the listed paths, don't revert others' changes, and never spawn its own subagents (only the orchestrator fans out).

See references/handoff-format.md for the copy-paste worker handoff template and references/examples.md for a full worked run (the health-coach research job in the screenshots) plus reusable decomposition recipes.

Parallel writes (the local gotcha)

Local subagents share one working directory. Concurrent writes to overlapping files clobber each other.

• Parallel reads/research/analysis: always safe. This is the default use.
• Disjoint edits you keep all of: use regular workers only when path sets are strictly disjoint, or do the edits serially after the research waves finish.
• Competing attempts at the same task: use best-of-n-runner (each in its own git worktree/branch), then inspect, test, and merge the chosen result yourself — worktrees prevent clobbering, not the merge.

Escalating to cloud orchestration

For genuinely large builds (many concurrent code-writing agents, runs that outlive this session, PRs per task), escalate to the Cursor team's orchestrate plugin if it's installed. It spawns cloud agents via the Cursor SDK, isolates each on its own branch, and reconciles handoffs from disk/git. It requires its own setup (credentials and a runtime, plus optional Slack) — check its docs — and is invoked explicitly (e.g. /orchestrate <goal>).

Cursor subagent mechanics here were checked on 2026-07-03 (custom-agent registration-after-restart, resume-by-agent-ID, and the model-fallback conditions re-verified against current docs and bug reports). The details most likely to drift: the cloud orchestrate plugin's setup, and whether Cursor caps concurrent background subagents (not officially documented). Re-verify those if they matter to your run.

Checklist

• Discovered the problem shape 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.
• Triaged each slice (worker type + dependencies + verification tier).
• Routed scouting / read-heavy waves to the cheap fast model (Composer 2.5); reserved frontier / panel models for high-stakes slices.
• Slices are independent (disjoint data/areas/paths), or their depends_on edges are recorded in the manifest.
• Wrote the wave manifest (slice / worker type / model / depends_on / verification tier) before spawning; launched dependent slices only after their dependencies' handoffs were verified (distilled findings fed into their prompts).
• Each worker prompt is fully self-contained (no reliance on chat history).
• Each wave's Task calls sent in one message, run_in_background: true.
• Ended turn to await completions — no polling loop.
• No two parallel workers write the same paths.
• Verified coverage before spawning (counts/bounds/partition-sum).
• Checked every manifest row off at collection (completion gate); ran the failure ladder on missing/blocked slices — no slice silently dropped.
• Read every handoff; spawned follow-ups for open questions.
• Wave bounded (width ≈3–8, ≤2–3 waves); carried only distilled handoffs forward.
• Verified each handoff's evidence (not just its Status); escalated low-confidence / conflicting / uncited findings; wrote synthesis-wave-N.md only from verdict-cleared findings (pending claims tagged pending-verification, never fed to dependent slices).
• Verified the final deliverable (re-ran/validated; re-read critical writes).
• Synthesized one deliverable from the handoffs.