Token economy reference — spend fewer tokens, never less rigor
the-loop iterates, is verbose by design, and keeps each work item's harness TUI resident across the item's whole event stream — so it is inherently token-hungry (issue-37). This reference is the loop's opinion on token economy: a set of levers plus the guidance that makes them real. Nothing here is configured — the tokenEconomy block left .the-loop/harness-config.yaml in issue-352 because these are practices the skill follows, always advisory. The harness runs whatever model the operator chose.
The one guardrail (absolute)
Every lever here is advisory — it informs how the loop works, it never gates a merge, and it may never trade away:
input validation · error handling · security · accessibility · test-first discipline · the paper trail · review depth.
Cheaper never means sloppier. When a lever and correctness/safety conflict, correctness/safety wins, every time. This is the same stance as minimalism.md.
The levers
1. Progressive disclosure
SKILL.md is a thin index; the heavy detail lives in reference/*.md and is pulled in just-in-time. Deepen it: a step loads only the reference file(s) its phase needs — do not read the whole corpus up front. The phase → reference loading map:
| Phase / step | Load only |
|---|---|
| brainstorm | (SKILL.md index) + token-economy.md if optimizing |
| requirements-definition | workflow.md |
| design | workflow.md, design-artifacts.md (user-facing only), minimalism.md |
| tasks-breakdown | workflow.md |
| implementation | tooling.md, testing.md, minimalism.md, observability.md |
| self/critic review | reviewing.md |
| reviewer briefing / evidence | collaboration.md |
| any autonomous/webhook run | automation.md, token-economy.md |
2. Tighten what we control (corpus density)
The SKILL.md + reference/*.md + templates are context rent paid every turn that pulls them in. Keep them dense: no filler, no duplication between SKILL.md and a reference file, detail pushed down the disclosure tree. This is caveman applied to our own prompts — unambiguously safe because we own the text and the structural rules stay intact.
3. Tool-output & MCP hygiene
- Prefer the dedicated file/search tools over shell dumps; return summaries, not raw logs. Verbose tool results are resent every turn.
- Keep the MCP/tool surface scoped to the task — every connected server loads its full tool schemas into context whether used or not.
4. Generation minimalism (see minimalism.md)
The YAGNI → stdlib → native → existing-dep → inline → new-abstraction ladder is also a token lever: code never generated is tokens never spent (and never reviewed). This is ponytail's "lazy senior developer" ladder implemented natively (decision-005).
5. Output-verbosity compression
Narration is concise: drop conversational filler, prefer fragments, in the agent's narration only. NEVER compress the preserved set: code, commands, diffs, errors, paper-trail comments, the reviewer briefing, specs, decisions, capability docs. Because the reviewer briefing and ticket/PR comments are exempt, the educate-the-reviewer mandate is fully preserved. This is caveman's preservation rule implemented natively (decision-005).
6. Model choice
Different stages need different horsepower — mechanical stages (evidence, capability-doc fold-in, reviewer briefing, status reads, checkmark/lint updates, learnings) do not need a frontier model. The loop runs on whatever model the operator chose; there is no per-stage routing table and no stage → model-id binding. When the operator asks which model a stage warrants, this is the guidance:
| Horsepower | Stages |
|---|---|
| frontier | brainstorm, requirements, design, critic-review |
| standard | tasks, implementation, self-review |
| economy | evidence, capability-docs, reviewer-briefing, status, learnings |
High-risk work (tier 4/5) never warrants the economy end regardless of stage — an auth/schema change is not where to save. Advisory throughout: the row is the model a human would select, never one the loop switches to.
7. Thinking effort
Extended thinking bills as output tokens. Effort by stage: high for design and critic-review; medium for test-planning and implementation; low for verification, capability-docs and the reviewer briefing; none for evidence and status reads. Advisory where a harness can't set effort.
8. Sub-agent delegation
Run verbose work — the test suite, doc fetches, scanning large files/logs — in a fresh- context sub-agent so the raw output stays in its window and only a short summary returns to the controller. This keeps the controller's window lean across a long autonomous run (the classic 6k-tokens-read → 400-token-summary trade). Guidance where a harness lacks sub-agents.
9. Compaction & filesystem-as-memory
the-loop already persists durable state to disk (the spec chain, work-item-state.json, the capability docs) — that is why resumability works, and it is a token strategy: offload state to disk, keep the window lean. For long runs: tick the checkmarks, commit, then compact/reset the window with a "preserve the spec + open threads" instruction rather than letting the window grow unbounded ("context rot").
Persisting is not free, and the loop learned that the hard way. the-loop kept an append-only execution log as the third leg of this until issue-365: a 130-line template in every work item, a hook appending a checkpoint at every node boundary, and a prose entry demanded before every reset — all of it re-deriving what the harness transcript, the commits and the state file already held. State worth offloading is state something reads; anything else is generation billed twice. The boundaries at which the loop resets are fixed in reference/context.md.
10. Manage the resident session's window
Every daemon-spawned session is a resident tmux-hosted TUI (issue-32; the only runner since issue-156): each event is forwarded into the existing session — no re-spawn, no cold re-prime — so context amortizes across a work item's whole event stream. The flip side is a window that only grows: manage context inside the session — compaction and clears at phase boundaries per reference/context.md — rather than letting one giant mega-session re-send the whole growing conversation every turn.
11. Measure it — the prerequisite
You cannot reduce what you do not measure. Usage (input/output/cache tokens + cost) is parsed best-effort from each harness's JSON output (DispatchResult.usage) and surfaced per work item in the session registry and the event log. Every other lever is judged against this real baseline, not vendor claims — so the loop sets no headline reduction target until it has measured one.
Best-practices checklist (adoption status)
| # | Practice | Lever |
|---|---|---|
| 1 | Progressive disclosure (thin index, JIT bodies) | §1 |
| 2 | Dense, de-duplicated prompt corpus | §2 |
| 3 | Tool-output trimming / MCP hygiene | §3 |
| 4 | Generation minimalism (YAGNI ladder ≈ ponytail) | §4 |
| 5 | Output-verbosity compression (≈ caveman) | §5 |
| 6 | Model choice by stage + risk tier (guidance) | §6 |
| 7 | Thinking-effort control | §7 |
| 8 | Sub-agents w/ fresh context for verbose work | §8 |
| 9 | Compaction + structured note-taking | §9 |
| 10 | Resident sessions / in-session context management | §10 |
| 11 | Per-work-item token/cost telemetry | §11 |
References
- Root artifact & research digest:
docs/specs/issue-37/brainstorm.md. - Anthropic — Effective context engineering for AI agents; Agent Skills.
- Claude Code docs — Manage costs effectively.
- Prior art implemented natively, not vendored (decision-005, decision-062): caveman (output compression), ponytail (generation minimalism).