Token Harness

Four mechanisms that reduce cost without reducing capability. Each is measured, not asserted.

When to reach for which

rcskills is on the shell PATH when installed as a plugin, and from any project once linked (npm link in the harness repo). Inside the harness repo, npm run <tool> -- does the same thing.

Core rules

1. Reduce the work before choosing a model. Walk the reuse ladder first — does this need to exist / already in the codebase / stdlib / platform / an installed dependency / one line / only then write it. The cheapest token is the one never generated. Never trade away security or data-loss handling to shorten code; this is reuse, not code golf.

2. Act on the router, and let evidence pick the model. A [router] delegate -> haiku line is an instruction: call the Agent tool with the named subagent (rc-haiku, or rcskills:rc-haiku in a plugin install; pinned to Haiku 4.5) and a self-contained brief — files, exact change, verifying command — then check what it did. escalate -> opus hands the reasoning-heavy core to rc-opus when the session runs a weaker model. The router delegates down only on clear cheap evidence (score -2 or lower): vague work orders like "make it better" read short but are not small. Moderate work is never delegated on wording alone, because wording cannot tell it from complex. Older Opus and Sonnet versions are never the cheapest adequate choice and are never routed to.

2b. The model is chosen per task, not per token. A model that is cheaper per token can take more steps and cost more per task. On the Artificial Analysis Coding Agent Index (Claude Code, max effort) Sonnet 5.5 scores 68 at $14.20 and 1.5h a task; Opus 5.5 scores 66 at $13.04 and 1h. Within 3 points counts as a tie, so Opus 5.5 is the model for every Opus or Sonnet session: cheaper per task, faster, as good. The benchmark lives in TASK_BENCH in tools/model-router/cost.cjs; update it with the index and the choice follows. It is one run at max effort, so your own costs take over: the Stop hook prices each finished turn on the model that ran it (observed.cjs), and once both models have 15 complex tasks on record, their medians decide instead. Everyday tasks are never the same task on two models; rcskills compare --task "..." is: it runs each task on both models in a throwaway clone, edit-only, capped by --max-budget-usd, and 5 such pairs per model outrank everything else. rcskills backtest backfills that record from your history, prints each model's cost per task as price per request x requests, and names what decides the choice right now. Only a model your sessions have really run is ever recommended, so the advice never names one your Claude Code cannot select; the first session on a new model makes it eligible. Every reason given is the true one: cheaper per task, or dearer but more than 3 points better (Opus 5 → Opus 5.5 at max effort: $10.79 vs $13.04 a task, 60 vs 66). Any other Opus or Sonnet is told to move: the first message that starts a task is held once, at no token cost, with the command and the message handed back; a question or small edit is told, never held (demand.cjs reads which is which); every later reply ends with the same [next] line. Nothing is said when the switch would not pay back over a working session. Switch as /compact first, then /model: the cache belongs to one model, so the re-cache is charged on the small compacted result. Reasoning is bound to the exact model that wrote it, so the switch hook saves it as text and the next prompt shows a [handoff] line: continue from it. Never switch the model for the user; Claude Code refuses a session re-pricing itself.

3. Never dump memory into context. Query it. Recall is BM25-ranked and hard- capped by a token budget, so cost cannot grow with store size. Unused notes decay and self-prune; retrieved notes strengthen. Pin only standing policy.

4. Score on evidence, not opinion. Four of seven scorecard parameters cap at 5/10 without real measurement. Report the total, name the weakest parameter and why, then fix it or declare it an open gap.

5. Never put bookkeeping on PostToolUse. It spawns one process per tool call (~166ms each; real turns average 12.6 tools). Derive from the transcript at Stop.

6. Audit what is always loaded. CLAUDE.md and MCP schemas are paid on every single request — an unused MCP server costs its whole schema forever. Skills are paid only when they load, so push detail into references/. npm run audit ranks offenders by that leverage.

6b. Continue from a [ledger] line. No hook can write into a /compact summary, so the PreCompact hook reads the full transcript first and keeps a ledger: decisions (the session's commits), open tasks (the last todo list), recent asks and files edited. It is shown right after the compaction and at the next session, and its decisions and open tasks go into memory, where recall brings them back when a prompt returns to the work. Your rule-like requests (always, never, only, from now on) and uncommitted work are kept too. When you settle something no commit will record, write it on its own line as Decision: … so the ledger keeps it; every session start says so in a [decisions] line. An instruction a later one restates is dropped; for any other conflict, the later wins. Treat the ledger as settled: do not redo decided work.

7. Copy every [next] line, word for word, as the last line of the reply. Only the user can run /compact or /model, so the hook writes the finished line — the command, what to keep, and what it costs — and it must reach them every time. One per reply at most. The compaction point is worked out per session: the lower of where re-reading costs $0.15 per request and 40% of the model's window, brought forward at a natural break or fast growth, pushed back mid-task. Tune it with rcskills config compact <on|off|dynamic|tokens> and compact-budget <usd>.

Details on demand

Load only what the current task needs:

• references/router.md — tier signals, repo blast radius, cache-aware cost model
• references/memory.md — decay math, budgeted recall, fixed core
• references/outcome-loop.md — transcript parsing, backtesting, how to retune
• references/scorecard.md — the seven parameters and their evidence gates
• references/install.md — harness install, profiles, doctor, uninstall

Verify before claiming

npm run verify (typecheck + tests) must pass before reporting any of this as working. npm run backtest must not regress after touching the router.