Immutable. This exact content is served forever at /api/v1/blob/ee547cf4ebf79fa7.
--- name: agent-swarm-orchestration description: "🐝 Coordinate many workers on split tasks." --- # Make parallel cognition answer to one mind Hold one user-authorized mission. Use multiple agents only when divided cognition is expected to improve accepted outcome after startup, duplicated reading, coordination, merge, verification, latency, and token cost. Keep one root coordinator accountable for mission truth, authority, shared state, integration, and the final answer. Start from the work already present. Recover the outcome, acceptance, current evidence, constraints, user corrections, authority, budgets, and live host affordances. Ask only when an unknown changes the goal, risk, architecture, authority, or next consequential move. Preserve the difference between a stated premise and an absent dependency. If the task states that artifacts, inputs, workers, or returns exist, reason from that premise even when their bytes are not pasted into the prompt; do not reclassify them as missing. If a required source is actually unavailable, stop the dependent slice before designing it. Return only the missing source, the exact method that would identify or read it, the name and objective of the downstream slice held pending that source, and any independent authority conclusion. Do not fill the hold with generic tests, schemas, paths, endpoints, acceptance criteria, sample data, or implementation ideas. Continue every safe, authorized part of the mission without asking for permission already granted. When one proposed action crosses an authority edge, refuse or reserve that action while completing and reporting the in-bounds analysis, preparation, or comparison. When the user expressly prohibits an action, close that branch; do not draft it, preserve it as a future option, or propose later reauthorization unless the user reopens it. Do not turn a narrow authority limit into a full-task stop. Distinguish missing authority from a missing source, tool, or execution primitive. Never report AWAITING AUTHORITY when the user already authorized the action but the host cannot perform it. In a non-interactive or tool-limited episode, do not ask a question that cannot be answered there: return the exact prepared patch, packet, comparison method, or next executable action; name the unavailable dependency; and use the corresponding truthful degraded state. Never claim to have inspected content that was not observed. The absence of live mutation is not an authoritative post-state readback: do not say no files changed, nothing changed, or the target is unchanged; say no mutation was executed in this episode and the target state remains unobserved. When any required task source is absent, use `PARTIAL — DEPENDENCY UNAVAILABLE` and stop artifact-specific claims at that evidence boundary. Do not invent or guess an owner, path, parser, component, test target, finding, patch, or completion state. Do not draft generic or hypothetical downstream content, acceptance criteria, test structures, or substitute packets; hold that slice entirely. Return only the named missing source, the exact read or identification method, the downstream packet held pending that source, and any independent authority conclusion. Read `references/operating-doctrine.md` for every admitted swarm. Load the smallest additional doctrine that changes the live decision: - `references/topology-and-admission.md` for direct-versus-swarm judgment, dependency graphs, concurrency, and ownership; - `references/delegation-and-context.md` for worker selection, context forks, packets, isolation, and return contracts; - `references/coordination-and-control.md` for live Codex tool semantics, messages, waits, interruption, corrections, and closure; - `references/evidence-merge-and-review.md` for returned claims, shared artifacts, conflict, synthesis, verification, and independent challenge; - `references/cost-authority-and-recovery.md` for model routing, permissions, sensitive material, stalls, collisions, capability loss, and changed-route recovery; - `references/source-and-currentness-register.md` before relying on a named host primitive or vendor-specific behavior whose contract may have changed. ## Admit the lightest capable topology Choose one regime for the next reasoning horizon: - **Direct:** the root completes small, sequential, tightly coupled, latency-sensitive, or shared-context-heavy work. - **Enlist:** one bounded worker returns a result while the root retains the main task. - **Assemble:** independent ready slices run concurrently under explicit ownership and a named merge plan. - **Chain:** one specialist’s accepted return becomes another’s exact input. When the prerequisite is missing or unaccepted, hold the dependent slice at that boundary; never substitute a generic or hypothetical downstream artifact. - **Recover:** a failed, stale, conflicting, or cancelled swarm preserves useful state, changes premise or route, and resumes from the first unearned edge. Use these regime names literally. Direct has no worker, Enlist has exactly one worker, Assemble has at least two independent workers, and Chain has at least two sequential workers whose accepted returns form the handoff. Do not combine contradictory labels such as “Direct with a worker.” Do not spawn merely because agents are available or the user said “parallel” when the tasks share a write surface, depend on one another, or cost more to explain and merge than to perform. When the swarm is not earned, proceed directly and keep the explanation brief. For mixed inventory-and-interpretation work, keep deterministic listing, counting, hashing, and obvious metadata classification at the root or in tools. Route a small ambiguous semantic batch through one qualified worker and root review before adding workers; shard it further only when a stated latency or coverage gain exceeds every extra packet, duplicated context read, review, correction, and merge cost. Do not claim savings from a cheaper model or parallelism alone. For consequential, multi-turn, or recovery-prone work, resolve `assets/swarm-plan.template.json` from the directory containing this `SKILL.md`. Validate the working plan by resolving the packaged script from that same skill root, independent of the task working directory: `python <skill-root>/scripts/validate_swarm_plan.py <swarm-plan.json>` The validator checks declared structure, dependency references and cycles, terminal consistency, and simultaneous active write-surface collisions. Never present a `cd-agent-swarm-plan/v1` object unless it satisfies that validator: `direct` has zero workers, `enlist` exactly one, and `assemble` or `chain` at least two. Returned or historical agents belong in the closure or merge ledger, not in a `direct` plan's workers array. When validation cannot run, use compact prose and do not emit an unchecked structured plan. Sequential handoff from reconciled bytes remains a root observation and verification responsibility. For light work, keep the same distinctions in active state without creating paperwork. ## Packet work by coherent responsibility Map the work as dependencies, not a shopping list. A parallel slice needs all required inputs, one coherent transformation, no hidden dependency on another active slice, and single-writer ownership for every mutable surface. Reserve a root slot and useful root work unless the live host proves another topology safe. When multiple passes touch the same artifact, the order is mandatory: semantic or technical correction first; only after observing and reconciling those current bytes may clarity, style, formatting, or polish write. Never reverse that order. If independent views help, collect comment-only recommendations in parallel and let one owner integrate them. Compose each dispatch from `assets/delegation-packet.template.md`. Give the worker: - one objective and exact deliverable; - the evidence or acceptance burden; - the smallest sufficient context, sources, paths, and live state; - explicit included and excluded scope; - authority, tool, filesystem, network, privacy, and external-action boundaries; - file or artifact ownership and integration contract; - the expected return shape and stop condition. Choose the smallest context fork that preserves success. Withhold irrelevant transcript, the coordinator’s preferred answer, evaluator oracles, and other workers’ conclusions when independence matters. Use fresh context for hostile review and competing hypotheses. Use inherited context only when reconstructing the mission would be costlier or less faithful than the context carried forward. Minimize sensitive or private source material inside every packet. When a worker needs only named sections, claims, fields, or excerpts from an available private artifact, send only those portions or narrowly scoped read access—not the entire artifact merely because it is available. The root keeps the full source and the synthesis boundary unless the complete artifact is necessary for acceptance. ## Coordinate through the live contract Inspect the injected Codex collaboration tools before dispatch. Tool presence, argument schemas, fork behavior, concurrency slots, communication timing, waiting, interruption, cancellation, and nested delegation are live contracts—not folklore. Create agents only through the admitted primitive. Keep their canonical identifiers. Send in-flight guidance without restarting work when messaging is supported. Trigger a follow-up turn only where the host distinguishes it from ordinary messaging. Interrupt for cancellation, authority revocation, or material misdirection; interruption is not proof of rollback or non-commit. Use event-driven waiting for genuinely pending work. Continue useful root work while agents run. Do not poll unchanged state or make the user watch a status metronome. When the user adds, corrects, or replaces the mission, update root custody first, then preserve useful in-flight work by redirecting each compliant-capable active worker in place. Interrupt or retire only a worker whose current action crosses the corrected authority or whose packet cannot be safely narrowed; do not cancel and reconstruct an equivalent swarm merely to express the correction. Treat workers stated as active in the task as active mission state; a context-only analysis must describe the required immediate redirect or interruption and must not demote them to unavailable merely because no live collaboration primitive executes in that episode. After redirecting or interrupting active workers, label prior write and commit state `unknown` until authoritative readback. Without that readback, do not say no files changed, nothing changed, the workspace is unchanged, an artifact is untouched, or a schema remains untouched; missing tools or sources in the present episode establish none of those claims. Agents may communicate or spawn descendants only when the live host permits it and the topology earns the added control surface. Root-owned spawning is the default because it keeps budgets, authority, conflicts, and closure legible. ## Reconcile before believing Receive every worker through `assets/agent-return.template.md` or an equivalent compact return. A return is **agent-reported** until the root observes the cited artifact, source location, command result, hash, or external state. Specific citations do not become root-observed merely because a worker supplied them; when the root cannot read them, retain `agent-reported` and withhold the dependent factual or health conclusion. Shared filesystem visibility does not make simultaneous edits safe, and a successful dispatch does not establish commit. Maintain `assets/merge-ledger.template.md` when claims, files, agents, or evidence can conflict. Merge compatible deltas. Resolve factual conflict against authoritative evidence or a discriminating check. Preserve unresolved evidence conflict. Return value conflict, changed priority, or new authority to the user. Verify the merged outcome at the lowest layer that can expose the real failure. Use a fresh independent agent when review value exceeds its cost, and keep the expected answer, builder diagnosis, and hidden rubric out of that agent’s packet. Easy successes cannot cancel a failed authority, safety, ownership, or indispensable acceptance condition. ## Recover the goal, not the failed choreography When a worker stalls, fails, loses context, overruns, collides on a write surface, or returns unusable evidence, preserve its useful delta and failure signature. Change the decomposition, context, model, tool, ownership, sequence, or verifier before retrying. Reassign only the unearned edge. If collaboration tools disappear, finish the root-owned work and provide an exact prepared delegation plan labeled `PREPARED — NOT DISPATCHED`. If a mutation’s commit is uncertain, reconcile authoritative post-state before any retry. If budget or quality floors cannot support another responsible cycle, stop with the truthful terminal state and re-entry condition. ## Close as one accountable agent Before completion: 1. account for every worker as returned, failed, interrupted, cancelled, or still live; 2. reconcile shared state and material claims; 3. verify the merged result to the exercised boundary; 4. release completed workers and preserve only useful continuation state; 5. return one coherent result in the user’s requested form. When the user asks to summarize and finish but evidence remains agent-reported, close with the bounded synthesis that is earned: name what workers reported, what the root did or did not observe, and which conclusion remains unverified. Do not ask the user to bless agent reports as evidence, and do not keep the whole mission open merely because a stronger verification layer is unavailable. Expose topology, agent reports, costs, or conflict only when they clarify the evidence, decision, or next action. Completion means the user’s acceptance condition is supported—not that every worker produced text.