swarm

boshu2/agentops

Dispatch explicit disjoint packets exactly once through a caller-selected executor.

What is swarm?

Swarm enables parallel execution of independent work packets by dispatching each exactly once through a chosen executor, with guaranteed disjointness and independent failure isolation. Use it when you need to run multiple non-interfering tasks in parallel while preserving per-packet results and context.

Dispatches each packet exactly once to a caller-selected executor
Validates write-scope disjointness lexically before any dispatch to prevent packet interference
Preserves packet and context identities throughout execution
Collects per-packet results, evidence, or errors independently
Stops after all packets complete without retry or semantic verdict logic

How to install swarm

npx skills add https://github.com/boshu2/agentops --skill swarm

Claude Code

Cursor

Windsurf

Cline

How to use swarm

1.Prepare explicit disjoint packets with workspace-relative, canonical (symlink-resolved) write scopes
2.Verify all write scopes are disjoint before calling dispatch_once
3.Call dispatch_once(explicit_disjoint_packets, executor) with your packet batch and chosen executor
4.Collect and handle per-packet results, evidence, or errors independently
5.Treat executor errors as factual packet results; retry decisions remain with the caller

Use cases

Good for

Running N independent experiments in parallel where each has its own workspace scope
Batch processing of non-overlapping file operations across multiple directories
Parallel task execution where failures in one packet must not affect others
Distributed work where the caller controls both packet composition and executor selection

Who it's for

Developers building parallel execution systems
Teams using team-topologies and design-by-contract practices
Agents needing to dispatch independent work with guaranteed isolation

swarm FAQ

What does 'disjoint' mean for write scopes?

Write scopes must not overlap; Swarm checks this lexically with case-folding for safety on case-insensitive filesystems. Scopes must be workspace-relative and canonical (symlink-resolved). Non-canonical or symlinked scopes forfeit the disjointness guarantee.

What happens if one packet fails?

Executor failures remain independent per-packet evidence and do not affect other packets. The error is returned as that packet's factual result; retry is the caller's decision, not Swarm's.

Can Swarm retry failed packets?

No. Swarm dispatches each packet exactly once. Retrying is an anti-pattern; instead, return the error as the packet's result and let the caller decide whether to retry.

What does Swarm not do?

Swarm does not select work, create packets, schedule from a backlog, persist queues, validate packet content, integrate results, use Git, or issue binding verdicts. Those are the caller's responsibilities.

What is the 'partial-batch launch' failure mode?

Dispatching valid packets before discovering an invalid one leaves the batch half-run. Validate the entire batch before the first call to avoid this.

Full instructions (SKILL.md)

Source of truth, from boshu2/agentops.

name: swarm description: 'Dispatch explicit disjoint packets exactly once through a caller-selected executor. Triggers: "swarm", "dispatch disjoint packets", "parallel explicit tasks".' practices: [team-topologies, design-by-contract] hexagonal_role: driving-adapter consumes: [explicit-disjoint-packets] produces: [per-packet-results] context_rel: [] skill_api_version: 1 user-invocable: true metadata: tier: execution dependencies: [] capabilities: [dispatch_once] effects: [invoke_selected_executor] canonical_status: canonical disposition: keep_optional_adapter output_contract: per-packet candidate, evidence, or error

Swarm

Swarm exposes one optional factory port:

dispatch_once(explicit_disjoint_packets, executor)
  -> per-packet candidate | evidence | error

The caller supplies every complete packet, proves their write scopes disjoint, and chooses the executor. Swarm dispatches each packet once, preserves packet and context identities, collects results, and stops.

Write scopes must be workspace-relative and canonical — symlink-resolved and already normalized. The disjointness check is lexical: it case-folds prefixes so scopes differing only by case are treated as a collision (safe on case-insensitive filesystems), but it cannot see a symlink that aliases two scopes onto one target. Supplying non-canonical or symlinked scopes forfeits the disjointness guarantee; a non-empty write_scope.exclude is rejected, not silently ignored, because the proof cannot honor it.

Exactly-once dispatch over proven-disjoint scopes is why parallel failures stay independent: no packet can observe, block, or corrupt another, so N packets yield N factual results about N experiments rather than one tangle. Those results are not semantic verdicts.

Named failure mode — partial-batch launch: dispatching valid packets before discovering an invalid one, leaving the batch half-run; validate the entire batch before the first call.

Anti-pattern: re-dispatching a packet whose executor returned an error. Corrective: return the error as that packet's factual result; retry is the caller's decision, not the dispatcher's.

The developer-only reference implementation is scripts/dispatch_once.py. Repository tests exercise this module; the supported native installed path follows this skill through the caller-selected executor and does not invoke Python. It validates the entire explicit batch before the first call, invokes the supplied executor exactly once for each packet, and returns executor exceptions as factual per-packet errors.

Swarm's own effect is invoking the selected executor once per packet; the real blast radius rides on the packets. Each packet's transitive effects — whatever its executor writes, runs, or reaches — are the caller's to declare on the packet, not Swarm's to bound.

Swarm does not select work, create packets, schedule from a backlog, persist a queue, claim ownership, retry, validate, integrate, close, use Git, or deliver. Executor failures remain executor evidence and cannot become core phase or verdict state. The adapter cannot select AgentOps semantics, issue a binding verdict, or turn factory completion into delivery or validation proof.