fabric-swarm
Fabric mode for many similar workers claiming items from one shared pool. Arrives in 5.4.1. Until then this skill routes to fabric-multigraph. Use when the user asks for a swarm or for many parallel w
SKILL.mdskills/basic/fabric-swarm/SKILL.md
GitHub/fabric-swarm — many similar workers, one shared pool
When: one list of many near-identical items (files, tickets, pages) that each fit one worker. If items depend on each other, use fabric-graph instead.
Agents never invoke each other. The dispatcher (the main session) decides every next step. Workers only return a result.
Pool file
production_artifacts/swarm.json, written ONLY by the dispatcher:
{ "goal": "", "worker_brief": "", "max_workers": 4, "review_done": false,
"items": [ { "id": "", "input": "", "status": "open|claimed|done|failed", "worker": "", "attempts": 0, "result": "" } ] }
- The dispatcher clamps
max_workersto 1..6 on write. --skill=<name>is passed through into theworker_briefof every worker.- Workers never write it; they return their result to the dispatcher.
- The claim: the dispatcher marks an item
claimedfor a worker before starting it, so no item runs twice. - Attempt counter:
attemptsis incremented exactly once per attempt, when the dispatcher claims an item (open->claimed). Nowhere else. Max 2 attempts per item. review_doneisfalseuntil the one review pass has run (see Loop step 4).- Resume: the file is the source of truth. On resume, every
claimeditem goes back toopen; the interrupted attempt already counted at claim, so nothing is incremented. If that item already hasattempts= 2, it becomesfailedwith resultinterruptedinstead.
Width
Default 4 workers at a time, hard cap 6 (same as workstreams). Harness or user limits may lower it. Each worker is a subagent with the same worker_brief plus exactly one item.
Loop
- Fill free slots with the next
openitem: mark itclaimed, setworker, and incrementattemptsby 1. This is the only placeattemptsis incremented. - On a result: mark
donewith a one-lineresult. - On a worker failure, without touching
attempts: ifattempts< 2, set the item back toopen; ifattempts= 2, mark itfailedwith the error asresult. - When no item is
openorclaimedandreview_doneisfalse, run the review pass once over thedoneresults (a reviewer subagent reads them against theworker_brief), then setreview_donetotrue. Rejected items go back toopenwithattemptsset to 1 (a reset, not an increment), so each gets exactly one more attempt: its next claim makesattempts2. Then return to step 1. The dispatcher writes the review verdict (rejected items back toopen) andreview_done: truein one write of swarm.json, so a crash cannot repeat the review. - When no item is
openorclaimedandreview_doneistrue, the run ends: report done/failed counts. No second review round.
Stop
All items done or failed, or the user stops it, or usage reaches 95 % via stay-within-limits (pause and keep the file).
Safety
Workers get no push, merge or publish. A swarm run never counts as a GO. Destructive or external writes stay behind the go-gate. Models per role come from the router or .aos/pipeline.json, never from this skill.