Splitting work across agents — and when not to

A "swarm" in Tvijo is not a magic mode. It is several bounded tasks running in parallel, each in its own working copy, each with its own budget and receipt. The model does not coordinate itself; a human (or a coordinating task) hands out disjoint pieces and checks the results.

That definition is boring on purpose. It is also the only one that survives contact with a shared codebase.

🔹 The three hard rules

1. One task = one capped call chain. Every question or dsh run is a separate task with its own limit. There is no shared "team budget" that a runaway agent can drain.
2. Parallel agents need separate working copies. Two agents editing the same checkout will overwrite each other, and git will not tell you who won. Copy the repository per lane, or use a worktree per lane.
3. Disjoint write paths. Lane A writes docs/, lane B writes api/. If two lanes must touch the same file, they are not parallel work — they are sequential work disguised as a swarm.

🔹 A shape that works

lane-1 (work copy A) → drafts section 1..3      → receipt-1
lane-2 (work copy B) → drafts section 4..6      → receipt-2
lane-3 (read-only)   → checks both against the source of truth → findings.md

The third lane is the one people skip. It is also the cheapest: a read-only check costs a fraction of a drafting task and catches the failures that make the whole batch unusable.

🔹 Running it from the command line

dsh login
dsh status
dsh run "Summarise docs/architecture.md into five bullet points" --json
dsh tasks
dsh task TASK_ID
dsh stop TASK_ID

--json makes the client print a machine-readable result, which is what you want when a shell script (not a person) dispatches the work. Sessions are stored locally with owner-only permissions; dsh resume SESSION_ID continues a conversation, and dsh sessions lists them.

📊 Measure the swarm, or you are guessing

For any task you plan to split, record four numbers per lane and one for the whole run:

The comparison you want is: one agent vs swarm vs swarm + judge, on the same task, with the same acceptance check. Without that baseline, "the swarm is faster" is a feeling.

🚧 When this does NOT work

• The task fits in one context. Splitting it adds handoff loss and cost, not speed.
• The pieces share a file. Serialise them instead.
• You cannot state an acceptance check. Then you cannot tell a good lane from a fluent one, and the swarm just produces more text.
• You are near a daily budget cap. Parallel lanes fail together; a sequential run degrades gracefully.
• You expect the agents to negotiate. They do not see each other. Every shared decision must be written down before dispatch.

➡️ Next

• AI judging — the check that makes a swarm worth running.
• Costs, budgets and limits — how the sum is counted.
• Recovery after a failed run — stopping a lane without losing the others.