skills/agent-swarm/references/token-economy.md

Token economy

Quality per token beats raw token spend. The expensive part of a swarm is usually input context and repeated reading, not the code a worker writes. Measure, budget, then cut redundancy — never cut the independent checks that catch real defects.

Measure before optimizing

Record usage per phase and per agent in .swarm/state.json:

{
  "budget": { "tokens": 600000, "soft_cap": 0.7, "reserved_for_verify": 0.2 },
  "usage": [
    { "phase": "recon", "agent": "R01", "tokens_in": 18000, "tokens_out": 4000 },
    { "phase": "build", "agent": "T03", "tokens_in": 24000, "tokens_out": 9000 }
  ]
}

If the runtime does not expose usage, estimate from context size and output length and mark the value as estimated. The point is a feedback loop, not accounting precision.

Useful ratios:

• tokens per accepted task;
• verifier tokens per confirmed defect;
• rework tokens caused by a missed contract;
• share of spend on recon / build / verify / integration.

Budgets and reserves

• Set a hard budget for the milestone and a soft cap at ~70%. At the soft cap, stop expanding scope; finish the current slice and verify.
• Reserve 20–30% for verification, integration and one round of fixes. Do not spend the whole budget on generation.
• Budget per phase, not only per wave: recon, build, verify, integrate.
• Stop at the cap and report partial results plus unverified areas. Silent overspend is worse than a partial result.
• Calibrate from the first measured milestone; do not copy invented numbers from a template.

Context discipline

The biggest savings without quality loss:

1. Small files. Split modules above ~800 lines (UI panels, viewport, inspector). A worker should read 300–800 relevant lines, not 3,000. Smaller modules also compile and verify faster.
2. Read ranges, not repositories. Use path:line, symbol search and grep first. Do not read a whole crate to change one function.
3. Point to artifacts, do not paste them. Task cards reference .swarm/brief.md, .swarm/contracts.md and exact ranges; they do not duplicate them in the prompt.
4. Cap reports and reviews. Worker report: summary, files/artifacts, evidence, issues, assumptions. Review: findings + commands + evidence; target 5–8k tokens, raw logs stay in files.
5. One page per task. If a card needs more, the task is too broad.
6. No full-suite runs per worker. Workers run targeted checks; the lead runs the full gate once per wave.
7. Fresh context only where independence matters. The final verifier needs a clean read. A fix re-check can be a delta review: diff + findings + acceptance commands, not the whole repo.

Verification ladders

Do not spend LLM review tokens on a red build:

1. compile / typecheck / lint;
2. targeted tests;
3. artifact/render/source check;
4. independent verifier on the diff and evidence;
5. final full review once, on a frozen integrated build.

Freeze before step 4. If code changes, re-check only the affected delta; mark the old review stale. This preserves quality while avoiding repeated full reviews.

Orchestration shape

• Fixed overhead dominates small tasks. Each child carries system prompt, tools, brief and task context. 30 small agents can cost more than 8 substantial ones.
• Right-size: 2–4 implementers + 1 verifier for a vertical slice; 6–10 agents for a broad milestone; 30 only for genuinely independent breadth.
• Model routing: strong model for architecture, difficult fixes and final review; cheaper/faster model for tests, docs, screenshots and mechanical edits.
• Vertical slices: ship one end-to-end feature at a time (selection → transform → undo → save), with a checkpoint and verification after each. Do not generate the whole product and verify at the end.
• Reuse: do not regenerate a working core, format or codegen. Extend it.

Anti-patterns

Pattern	Cost	Fix
3k-line file edited by several agents	repeated reads, merge conflicts	split before dispatch
Full repo read for a one-function change	huge input	path:line + grep
Full re-review after every fix	duplicate verifier spend	delta review
Verifier runs on a failing build	wasted review	automated gate first
20 tiny tasks	fixed overhead per child	merge into coherent units
Reports/reviews as essays	output + lead input	schema + evidence lines
Whole product in one wave	late integration, huge rework	vertical slices + checkpoints
Vague "max quality" with no budget	unbounded spend	hard/soft caps + reserve

Minimal operating rule

Measure per phase, reserve for verification, keep files and packets small, verify the diff after fixes, and spend the saved tokens on one strong independent review rather than many redundant agents.