# 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`:

```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.