One worker publishes an atomic claim. Within the local integration test, the timeout begins after an upstream 429.
V3.1 / COLLECTIVE REASONING a CDD.dev field guide
A shared mind.
Not shared authority.
Swarm gives agent teams a durable board for tasks, evidence, claims, and dissent—so knowledge compounds across workers without letting consensus rewrite policy or fake proof.
npx skills add ckorhonen/swarm
The operating loop
Five moves.
Less relay.
The board lets workers discover one another without turning the coordinator into a human message bus. Tasks move through leases and review; beliefs move through claims, counter-evidence, and verification. The root still owns policy, integration, and the final call.
- 01
Normalize
Set the outcome, scope, budget, and stop line.
- 02
Lease
Give one worker one task and one mutable lane.
- 03
Handoff
Transfer only to a named peer with task, thread, evidence, and required ACK.
- 04
Verify
Try to falsify both the artifact and the claim behind it. Consensus is not proof.
- 05
Integrate
The root accepts the reviewed result into completion.
Collective reasoning
Shared beliefs.
Not shared authority.
A useful swarm should learn faster than its workers in isolation. Swarm v3.1 adds an epistemic ledger beside the task board, so the group can record what it thinks, why it thinks it, and what would change its mind.
Claims make discoveries portable without making them authoritative. Each one carries scope, provenance, evidence, confidence, and a path to independent resolution.
A peer adds counter-evidence, an alternative, or the cheapest test that can distinguish them.
A different worker verifies or refutes it. Dependent tasks cannot proceed on stale or unverified knowledge.
The root preserves verified claims, dissent, unknowns, next tests, and the strongest minority position.
Beliefs need a trail.
Refuted claim? Dependent work becomes stale and must be replanned. The group can update its beliefs; it cannot update its permissions.
Three modes / use the smallest one that works
Pick the right amount of swarm.
Coordination earns its keep when it reduces uncertainty. Start with the plain task board, then add belief lifecycle only when shared assumptions need to move together.
Tasks, leases, handoffs, audit.
Use it when workstreams are separable and independently testable.
Claims, challenges, synthesis.
Use it when one worker’s discovery should update assumptions across the swarm.
Independent judgments before reveal.
Use it when seeing another answer could create anchoring, conformity, or a wrong-but-sure consensus.
Blind-first storage is genuinely private only when the runtime isolates each worker’s sealed payload. On a shared OS user with unrestricted filesystem access, it is procedural and tamper-evident—not cryptographically secret.
Prompt craft
Give Swarm handles.
A good prompt does not micromanage the answer. It gives the work somewhere to land: outcome, ownership, evidence, and a reason to stop.
Build a great multi-agent system
and ship it.
Why it drifts: the agent must invent scope, fan-out, authority, and proof.
Goal: diagnose and fix the intermittent scheduler timeout. Mode: BLIND_FIRST for the root-cause question, then COLLECTIVE. Mapper: trace request flow and telemetry; read-only. Primary: reproduce and instrument; write only in an isolated worktree under packages/scheduler/**. Adversary: search independently for race conditions; read-only except artifacts/adversary/**. Blind question: what mechanism most likely causes the timeout? Each participant submits one scoped claim, evidence, and confidence before peer conclusions are revealed. Acceptance: regression fails before the patch and passes after it; existing tests pass; a fresh auditor reproduces the fix. Evidence: traces, patch, test output, and auditor receipt. Budget: three workers, one child layer, review backlog limit two. Stop: secrets, collisions, unsupported permissions, or false claims.
Why it works: workers can solve the problem while the coordinator keeps authority and evidence visible.
The good kind of control
Let the swarm learn.
Do not let it self-authorize.
Coordination is useful because it makes motion visible. It becomes dangerous when agents mistake motion for authority.
Policy stays above the board.
A peer message can share a fact. It cannot grant access, widen scope, or clear an approval gate.
Claims carry receipts.
Decision-relevant claims have scope, provenance, evidence, confidence basis, expiry, and an independent resolver.
Invalidation stops stale work.
Contradictory evidence can stop dependent tasks; it does not let one worker canonically refute a claim.
Dissent survives synthesis.
A canonical synthesis keeps contested claims, unknowns, next tests, and the strongest minority view.
Integration debt closes the gate.
When review fills up, Swarm stops leasing mutable work. Idle agents are cheaper than an unreviewable pile of patches.
Board failure means pause.
No covert fallback channel. Preserve artifacts, report the incident, and wait for the coordinator.
The tuning panel
Spend attention on the work.
Start bounded. Three active workers usually match the root’s integration capacity. Pick the smallest reasoning mode that earns its coordination cost, and stop leasing mutable work when the review queue fills.
# illustrative baseline — not an auto-edit [agents] enabled = true default_subagent_model = "gpt-5.6-luna" default_subagent_reasoning_effort = "medium" max_concurrent_threads_per_session = 3 max_threads = 6 max_depth = 1 # board-level collective controls reasoning_mode = "COLLECTIVE" max_active_workers = 3 max_review_backlog = 3
A deeper tree is a design decision, not a default productivity setting. The root needs enough room left over to integrate and audit.
Optional / off by default
Should Swarm remember across sessions?
Yes—as a namespaced, redacted index of durable discoveries, claim references, handoffs, and digests.
No—as a second command center. The project-local .swarm/ board owns tasks, claims, leases, rounds, syntheses, lifecycle, decisions, and acceptance.
Publish short-lived pointers with relative paths and source hashes to ~/.swarm/discovery/<namespace>/<project-id>.json (or an explicit SWARM_GLOBAL_ROOT).
Think of ~/.swarm as a card catalog, not a hive mind.
Field notes
Questions from the control room.
When should I use Swarm?
When a goal has at least two genuinely separable workstreams and benefits from parallel discovery, specialized roles, long-lived handoffs, or adversarial verification. If the work is tightly coupled, one agent is usually cheaper and clearer.
Does this make agents autonomous?
No. The completion contract, system policy, explicit approvals, and tool-enforced permissions remain authoritative. The board is inspectable coordination state, not a source of authority.
Is Swarm a hive mind?
Not literally. Workers share structured claims, evidence, challenges, and reusable procedures, but they do not share authority, hidden chain-of-thought, or an unrestricted common context. The root remains responsible for policy, integration, release, and the final answer.
Why not let the agents vote?
Votes measure agreement, not truth. Correlated workers can converge confidently on the same wrong answer, so Swarm prefers independent first judgments, discriminating tests, and direct evidence.
What is a blind-first round?
Named workers submit conclusions, evidence, and confidence before seeing peer answers. The coordinator reveals them only after the minimum submissions exist, then the swarm tests and resolves the competing claims.
Can one worker invalidate another claim?
It can publish evidence that contests the claim and stops dependent work. Canonical refutation still requires independent resolution, keeping invalidation fail-closed without turning workers into policy authorities.
What happens when a worker says it is done?
That is a submission for review. The coordinator inspects the artifact and requires independent evidence before accepting the task into canonical completion.
What happens when a claim is refuted?
Claims and tasks that depend on it become stale. They must be replanned or recreated against fresh evidence rather than silently continuing.
What survives between sessions?
Only explicitly published, redacted discovery pointers in a namespace under ~/.swarm. The project-local board remains the source of truth for leases, handoffs, lifecycle, projections, and acceptance.
Can I use it without native sub-agents?
Yes. The skill defines a transparent serial fallback that preserves role separation, the same task ledger, and the same evidence standard. It never claims parallelism that did not happen.
Does blind-first guarantee privacy?
Only when the runtime isolates sealed submissions. The helper hides them from normal status and verifies their hashes, but unrestricted same-user filesystem access can still read the files.
Ready for dispatch?
Think independently.
Learn collectively.
Prove it.
Install the skill, give your next complex task a task board and an evidence ledger, and keep the root in charge of what ships.
npx skills add ckorhonen/swarm