orchestrating-swarms

Orchestrating ws swarms

Two peer-swarm agents ship with the swarmspace plugin. They coordinate as equals through a filesystem memo + journal — no leader, no single agent holds the plan. Your job as orchestrator is not to run the protocol (the agents do that); it's to set up the pre-launch contract correctly and read the right keys back when they're done.

When to reach for this vs. alternatives

The swarm pays for itself when the work is already decomposable into concrete, non-overlapping scopes — one per repo, one per service interaction, one per file glob. If you can't enumerate the scopes before launching, a single Task agent exploring serially is almost always faster and cheaper.

Situation	Tool
One repo, one file, one question	Direct tool use (Grep/Read/Edit)
One coherent investigation with no obvious parallel splits, inside this Claude session	Task / Agent (single subagent)
Routine multi-repo git ops (pull all, status all, run same command)	managing-workspaces skill
"Which of these 5 services does X" / evidence across a known scope	ws investigate
Apply the same concrete change across N repos / N files	ws swarm
Bridge two swarm steps (e.g. synthesize an investigation into a plan), or run one CLI agent from a shell pipeline / CI / cron	ws agent
Ambiguous, exploratory "I don't know where to start"	Start with a single Task, narrow the scope, then consider swarming

The swarm is leaderless by design. If the task needs a designated coordinator (one agent drafts, others review), that's not a swarm — use the Agent tool with a planned sequence.

Three primitives, one substrate

All three commands spawn CLI agents (Claude or Copilot) against the same workspace memo + journal. They differ in how many agents and what protocol they run:

• ws investigate — N peers, read-only investigation protocol (proposals → consensus → claim → finding → audit → summary). Output is evidence.
• ws swarm — N peers, executor protocol (proposals → consensus → claim → done → audit → summary). Output is changes to repos. Also dispatches alternative protocols via --agent <name> — e.g. --agent tournament for divergent-creative work where each peer produces a complete candidate and one peer judges (output is a chosen design + reasoned per-candidate evaluation, not code changes).
• ws agent — exactly one agent, no protocol. Output is whatever the agent's contract says it produces (typically a memo key like plan or report). Use this to bridge the two swarm types or to script anything that doesn't decompose into peers.

The pipeline pattern looks like:

ws investigate <dir> 4 --goal "..." --scope "..."   # N=4 peers, gather evidence
ws agent <dir> --agent synthesizer "Draft an implementation plan from the findings"
ws swarm <dir> 3 "Apply the plan in memo key 'plan' across the repos it names"

Each step reads what the previous one left in memo. Because ws agent is just one CLI process, it works in shell pipelines, CI jobs, and cron — places where the in-process Task tool doesn't reach.

Choosing the right protocol

ws investigate — read-only. Agents grep, read, git log, produce finding-<scope> memos with cited evidence (file:line, commit SHAs, grep outputs) and an explicit confidence level. They cannot write, commit, or modify state. Use when the output you want is evidence, not code.

ws swarm (default swarm-agent protocol) — executors. Agents can edit files and commit. Use only when the work is already scoped to known concrete artifacts and each peer has a clear write target. An executor swarm with an under-specified task fans out and makes inconsistent changes across repos — worse than doing it yourself.

ws swarm --agent tournament — divergent-creative. Each peer produces a complete candidate solution to the same task; one peer judges and picks a winner with reasoned per-candidate evaluation. No claim-splitting, no commits. Use when the task is design/strategy/prose-shaped and a single take might miss alternatives — "design three approaches to X and pick the best", "give me three names with reasoning", "draft three takes on this RFC opener". The verdict is consumed by a downstream step (often an executor swarm) that implements the chosen design. The judge picks; it does not synthesize — combining the best parts of multiple candidates is a different (harder) problem and isn't what this protocol does.

When in doubt, run ws investigate first to produce the evidence map, then decide if ws swarm is warranted. Cheap-to-run, hard-to-unwind is the rule: read before you write. For creative/design questions, reach for --agent tournament before an executor swarm — divergence-then-selection beats premature commitment.

The pre-launch contract

ws investigate

ws investigate <dir> <N> --goal "<question>" --scope "<repos/files/services>"

• <dir> — the workspace root (the parent directory containing the cloned repos as siblings). Must already be a workspace; if you need to bootstrap one or verify its state, see the managing-workspaces skill.
• <N> — the number of peer agents. Pick N to match the number of concrete scope splits you expect, not an aspirational number. Typical range: 2–5. N=1 is not a swarm; use Task instead.
• --goal — the question. Not the answer, not a directive. "What emits the malformed X-Request-ID header?" beats "Fix the header bug."
• --scope — the narrowed set of repos, files, services, or interactions. The narrower the scope, the faster the swarm converges. "All 14 backend repos" is not a scope; "auth-service, user-service, session-service" is.

The launcher writes goal and scope into the workspace memo before agents start. They read those keys in Phase 1 — that's how your intent reaches them.

ws swarm

ws swarm <dir> <N> "<task>"

There's no --goal/--scope for the executor variant — the task string is the brief. Write it like a PR description: what change, in which repos/files, and what "done" looks like. Vague executor briefs produce uneven changes.

ws agent

ws agent <dir> --agent <name> [--cli ...] [--seed key=value]...
                              [--output-format text|json|stream-json]
                              [--json-schema <file-or-inline>] "<task>"

One agent, no protocol. Required: --agent <name> (must resolve to agents/<name>.md or agents/<name>.agent.md). Optional: --seed key=value (repeatable) to write memo keys before launch — handy for passing structured input. Same --cli/--model/--detach flags as the swarm.

The agent reads prior memo state with ws memo <dir> in its first turn and produces an output key per its contract (e.g. the synthesizer agent writes plan). Don't reach for ws agent when a Task subagent inside this session would do — only when you need a CLI process: bridging two swarm steps, running from CI/cron, or scripting a multi-stage pipeline.

Structured output. --output-format json emits the agent's response on stdout (launcher chatter goes to stderr) so ws agent ... | jq works in shell pipelines. --json-schema <file-or-inline> constrains the agent's structured output to a JSONSchema — and crucially uses memo as the canonical sink so the contract works on both backends. The launcher tells the agent to write the schema-conforming JSON to memo key result (override with --result-key <key>), then reads that key and emits it on stdout. Claude additionally gets --json-schema natively (belt-and-suspenders stdout validation); Copilot only gets the prompt-side instruction. Either way the launcher's stdout shape is identical across backends — schema-validated JSON, nothing else.

Why memo and not stdout? Copilot's CLI runtime forces every turn to end with a task_complete tool call whose summary is the only stdout channel — and the model treats that as a human-facing message, not a structured slot. Telling both backends to write to memo sidesteps the divergence.

ws agent ~/ws --agent synthesizer \
  --json-schema ./schemas/plan.json \
  "Synthesize the investigator-swarm findings into an actionable plan." \
  | jq '.next_steps[] | {action, executor}'

A first agent ships with the plugin: synthesizer — reads summary, audit-result, and all finding-* keys from a prior investigate run and writes a structured plan key with verified findings, gaps, and recommended next steps. Add your own role files (planner, reporter, verifier) to agents/ as needs surface.

Flags worth knowing

• --cli claude|copilot|auto — backend for spawning peers. auto (default) prefers claude. Claude Code's latency sometimes causes one agent to race-win all claims; peers honor ownership and fall back to auditor — the protocol still completes cleanly.
• --agents <cli[:model],...> — heterogeneous swarm (e.g. claude:sonnet,copilot:gpt-5.3-codex). N must equal the number of specs.
• --fresh — archive the prior run's memo+journal to .workspace/history/<prior-swarm-id>/ and clear, then launch fresh. Use when re-running the same workspace after a prior failed run. The audit trail is preserved in history; you can read prior summary / audit-result / finding-* from there.
• --resume — spawn agents against the existing in-flight memo without re-seeding. Picks up partial runs (e.g. after a process crash, network blip, or auth dropout). Refuses if summary is already set (that swarm is closed — use --fresh). Mutually exclusive with --fresh and --scopes. Task arg is optional on resume; the launcher reads the original task from memo.
• --detach — return immediately after spawning. Useful for long-running swarms; pair with ws swarm-status <dir> to poll progress.
• --scopes "a,b,c" — pre-seed enumerated work units (only on ws swarm). Launcher writes scope-mode=enumerated and scope-1..M; agents skip proposal/quorum and claim claim-scope-N (with the actual scope value at memo key scope-N). Use when you already know how to split the work — saves the quorum round and prevents agents from re-deriving scopes you already have. Pairs naturally with sub-repo splits (file globs, directory paths) where executor-swarm normally has no way to seed scope.

Sizing N

N is how you split work, not how much parallelism you want. Rule of thumb:

• Count the concrete, non-overlapping scopes you can name before launch. That's your ceiling.
• With ws investigate, err toward one peer per scope split — over-provisioning just means some peers become auditors, which is fine but wasteful.
• With ws swarm, err toward one peer per write artifact. Two peers claiming work on the same file is the protocol's worst-case failure mode.
• For exploration where the right number of splits is unclear, start at N=3. Three peers surface disagreement (proposals diverge) faster than two, and the quorum-floor rule (N-1 proposals to proceed) handles one peer crashing.

Post-run synthesis

The swarm doesn't hand you a result — it writes structured state into the workspace memo. Read it.

From ws investigate

Read these keys in order:

1. summary — ranked findings by confidence, plus audit verdict. Written last, only if audit existed.
2. audit-result — PASS: <summary> or FAIL: <which finding, what's wrong>. PASS means the cited evidence exists as described, not that the hypothesis is correct. Hypothesis correctness is your call.
3. finding-<scope> keys (one per enumerated claim) — the raw evidence blocks. Read these when you need the actual citations, not just the summary.
4. consensus — the investigation plan and enumerated claim keys. Useful if a scope seems to have been missed.

If audit-result is FAIL, don't treat the findings as ground truth. The auditor found a citation that doesn't hold up. Re-run (with --fresh and a corrected scope) or investigate by hand.

If summary is missing, the swarm didn't close cleanly — check ws journal <dir> for what happened.

From ws swarm

1. summary — what was done, by whom, audit result.
2. audit-result — PASS/FAIL. For executors, PASS means the claimed artifacts (file contents, commits) match what done-<X> reported. It does not mean the changes are correct — run tests, read the diff.
3. done-<item> keys — self-reports. Treat as "agent says it did this." Verify the actual git state with ws status <dir> and direct inspection.
4. ws status <dir> — ground truth for what changed in the working trees.

A FAILed audit on ws swarm is serious — some repo has state that doesn't match the agent's claim. Investigate the specific failure before deciding whether to commit, revert, or re-run.

Observability during a run

• ws swarm-status <dir> — live progress dashboard. Use when a swarm is detached or taking long.
• ws journal <dir> — recent shared timeline (proposals, claims, completions, audit). Lower-signal than memo, but useful when a run seems stuck.
• ws memo <dir> — current state of all keys.

Don't write to memo or journal yourself while a swarm is running — the agents key off those files for coordination. If you need to abort, kill the swarm process; don't edit state underneath it.

Before launching

The common pre-swarm flow — confirming the workspace is clean, on expected branches, and synced with upstream — is the managing-workspaces skill's territory. Typical sequence:

ws status <dir>        # branch / dirty / ahead-behind for every repo
ws preflight <dir>     # advisory: any repo that will fight a write?
ws pull-all <dir>      # only if preflight showed behind repos
# → now launch the swarm

Skip these at your peril on executor swarms — a dirty tree in one repo turns into a partially-applied change you'll spend longer untangling than you saved by not checking.

Common mistakes

Launching without narrowing scope. --scope "all repos" defeats the purpose. If you can't name the scope, use managing-workspaces commands (ws status, ws each ~/ws bash -c "grep -l PATTERN -r src/") to narrow first, then launch.

Setting N=2 and expecting speed. Two peers often just agree immediately and one does all the work while the other audits. N=3+ gets you disagreement signal that's useful for investigation. (For a straight parallel-edit across exactly 2 files, N=2 is fine.)

Using ws swarm for exploration. If you don't already have concrete claim scopes in mind, the executor swarm will produce inconsistent edits. Investigate first, execute second.

Treating done-* as verified. A done-<X> is a self-report. Only audit-result: PASS verifies it against the filesystem — and even then, only that the change was made, not that it was correct.

Re-running with --fresh reflexively. --fresh wipes the memo and journal. If a prior run FAILed, the memo tells you why. Read it before you erase it.

Swarming something better handled by one agent. A single Task subagent with a clear brief beats a 3-peer swarm on any task that doesn't naturally decompose. Ask: "Could I write down N concrete scopes right now?" If no, don't swarm.

Minimal examples

Cross-service investigation:

ws investigate ~/workspaces/lafourchette 4 \
  --goal "Which service emits the malformed X-Request-ID header for stale sessions?" \
  --scope "auth-service, user-service, session-service, gateway"

Coordinated dependency bump:

ws swarm ~/workspaces/payments 3 \
  "In billing-api, billing-worker, and billing-web: bump @our-org/sdk from 3.x to 4.0.1, update call sites per the v4 migration guide (https://…), run tests, commit to branch chore/sdk-v4."

Heterogeneous audit:

ws investigate ~/workspaces/core 3 \
  --agents claude:sonnet,copilot:gpt-5.3-codex,claude:opus \
  --goal "Which repos still import the deprecated v1 auth middleware?" \
  --scope "all repos under core/services/"

Reference

• Full agent protocols: agents/swarm-agent.agent.md and agents/investigator-swarm.agent.md. The agents already know how to run the protocol — you do not need to brief them on it. Your job is scope, N, and reading the result.
• managing-workspaces skill — bootstrap, status, preflight, pull-all, each/some. The commands you'll typically run before a swarm.