Skip to content

Token-ROI Agent Conventions

How ANY agent — Claude, Codex, Gemini, Grok, local models, on any house PC — participates in the spend-metrics system. Written for harness priming; keep it short enough to inline into a fleet brief. Parent spec: METRICS-STANDARD.md (v1.1).

1. Make your work attributable (the only hard requirement)

  • Put the ticket id in your branch name (ww66-metering, WW-67-governor) or commit subject/trailer (AI-Ticket: WW-66). The attribution engine reads both; branch is primary.
  • One ticket per branch. Mixed-ticket branches dump spend into the visible unattributed bucket, which counts against the measuring system.
  • Work in a worktree with a real branch, not detached at repos root — repos-root sessions on master are ~unattributable by design.

2. Board flips ARE the phase tracker

Phases (MAKE/WORK/REVIEW/REWORK) are computed mechanically from BoardTransition events. Two ways to emit them, both model-agnostic:

  • Automatic (preferred): just flip the ticket's status row in docs/BOARD.md and commit. The WorkWingman post-commit hook diffs the board table and emits the transition with the commit SHA as evidence. This works for every model and every worktree — the hook is shared.
  • Manual (non-WW repos, or board-less work): token-roi board-transition --ticket WW-66 --to in-progress|in-review|done|reopened --evidence "<why>" Exe lives at %USERPROFILE%\source\repos\token-roi\publish\token-roi.exe on every house PC.

Rules that protect you: flipping late degrades confidence labels, it never gets you blamed; reopening a ticket honestly renders neutral forever; quietly fixing closed work WITHOUT a reopen trips the phantom-rework detector and looks worse. Never edit historical board rows — append correction events.

3. Spend logging per model

  • Claude Code: automatic (session JSONL is parsed; Stop hook writes the ledger).
  • Codex / Gemini (agy) / Grok CLIs: metered via shims when the caller activates them (council ruling 2026-07-10: scoped, never silent-global). Before launching these CLIs:
  • Prepend the shim dir for your process tree: $env:Path = "$env:USERPROFILE\source\repos\token-roi\hooks\shims;" + $env:Path
  • Stamp intent: $env:TOKENROI_CONTEXT = 'council-seat' | 'offload' | 'harness' — absent means your rows land in the visible unattributed-context bucket. Shims tee only provably-headless runs (codex exec, redirected stdout); interactive runs pass through untouched but still log a counted run with unknown tokens. No invented counts anywhere: rows carry null tokens + raw outputBytes when no token line exists, and null cost (a shim can't price without certainty). TOKENROI_SHIM_BYPASS=1 = escape hatch; token-roi shim-doctor diagnoses resolution.
  • Ollama / local models: unmetered until the reverse proxy lands; same rule.
  • Council runs: each seat's spend gets a ledger line once seat self-report lands; until then council runs are marked telemetry:incomplete. Never fabricate a seat line.

4. What you must never do

  • Never claim savings without a priced baseline (MEASURED) or an explicit estimate label (MODELED). The two are never summed.
  • Never add a metric, score, or dashboard figure anywhere without a Kerr row (gaming vector + paired guardrail) in METRICS-STANDARD.md §11/§12.6 first.
  • Never block or fail work because a spend number is big. Gates fail only on missing telemetry or unattributed spikes.
  • Never put content (resume text, prompts, code) into ledger rows. Numbers and enums only.

5. Per-repo requirement

Every repo an agent builds must carry a METRICS.md conforming to METRICS-STANDARD.md §8. If you scaffold a new repo, add it in the first commit.