chore(agents): cut token use and gate /implement on an approved plan

[craig-o-curtis]

Why

Last week our gmt agent sessions sent about 1.8 billion tokens of context and used 92% of the weekly limit in three days. I measured every request in the transcripts. Three things drove it:

• Long sessions. Half of all requests carried more than 200K tokens of context. Some sessions ran for 8+ hours, resending a growing history on every turn (peaks near 1M).
• Opus everywhere. Nine of the 11 agent personas used model: inherit, so workers such as tdd-dev ran on Opus.
• Nested agents. driver and master spawned agents that spawned more agents. Depth-2 agents alone used about 500M tokens.

Re-pricing last week's requests with this PR's settings gives an estimated 35–50% cut. The 200K compaction cap is most of that.

The flow

/plan-story      ← in the story's worktree; the branch name gives the story
  … answer the grilling questions, pick Dox tools, approve …
/clear
/implement       ← refuses to start until the plan is approved; ends with /optimize

What changes

Models and limits

• Opus 5.5 (high effort): architect, dox-architect, researcher, gmt-reviewer. Sonnet 5.5: tdd-dev, tester, finalizer, dox-builder, dox-tester, plus a project Explore agent that replaces the built-in one.
• .claude/settings.json: auto-compact at 200K, subagents default to Sonnet, spawn depth 1. Every persona also lists Agent in disallowedTools. Needs Claude Code 2.1.251 or later; older versions run every agent on Sonnet.
• Kilo is removed. Neither of us uses it: kilo.jsonc, the .kilo/ ignore line, the Kilo checks and every Kilo mention are gone.

One way to plan, one way to build

• master and driver are gone. The main session orchestrates with the new /pipeline skill.
• New /plan-story: in a story worktree, say "plan" and it reads the story from the branch name (feature/197-mar-16-… → MAR-16). It checks Blocked by, has architect write a spec folder, then grills the owner on open decisions using the vendored grilling skill. Next, dox-architect shortlists Dox tools for the owner to pick before it specs them.
• Specs become folders: an index.md of 150 lines or fewer plus one slice per function, at most 200 lines each. Each worker reads the index plus its own slice.
• New plan gate (plan-story/scripts/plan_gate.py). /implement and /pipeline both refuse to build a tracker story until its spec is marked status: approved and every slice exists. Only the owner's approval at the end of /plan-story sets that marker. Every story is planned, however small; bug fixes, Dox fixes and other work with no story id skip the gate.
• /implement is now a repo skill, unpinned from skills-lock.json, so npx skills update no longer overwrites it.
• New /optimize runs both optimizers and prints at most 30 lines. It lists findings only in files the branch changed, plus repo-wide symlink problems. A size finding is listed only when the branch caused it (the file is new, or was within budget at the base); the rest is counted as backlog. /implement runs it last: fix what the story caused, and log what was already there.
• The CLAUDE.md skills table moved to context/skills.md, so CLAUDE.md is now within its budget. AGENTS.md ends up slightly smaller than on main.

Optimizer skills

• agent-optimizer now:
  • scans all of context/ and follows links to find orphans;
  • checks line budgets and each persona's model and no-spawn setting;
  • checks the .claude symlinks;
  • adds usage.py, a token report by agent and model that filters each request by its timestamp.
• skill-optimizer now:
  • runs without PyYAML;
  • checks line budgets and .claude symlinks;
  • resolves file references from the repo root;
  • reports vendored skills as notes, because their fixes belong upstream.

Not in this PR

Phase B is a follow-up PR: splitting the 39 existing files over budget (gmt-reviewer.md at 398 lines, the 1,000–2,000-line specs, coding-standards.md and others) and archiving the specs of finished stories. The optimizer reports also flag 81 orphaned context files, mostly specs and research for stories that are already done.

How to review

• Python: uv run --extra dev pytest -q .agents/skills runs 141 tests. They also pass on macOS's /usr/bin/python3 (3.9.6), which is what the skills call.
• /optimize: python3 .agents/skills/optimize/scripts/run.py on this branch prints PASS: 0 finding(s) to fix; 154 backlog.
• Reports: python3 .agents/skills/agent-optimizer/scripts/optimize.py . reports 0 broken links, 0 symlink problems, and every persona on its intended model.
• Usage: python3 .agents/skills/agent-optimizer/scripts/usage.py --days 7 --project-glob '*northguild-gmt*' gives the baseline to compare against after a week on this setup.
• After merging, open /agents in a new session to confirm the models.
• Only agent tooling changes: .agents/, .claude/, AGENTS.md, CLAUDE.md, context/skills.md, skills-lock.json, .gitignore, the deleted kilo.jsonc, and one stale comment in apps/dox/scripts/build-utils/build-utils.ts. packages/ is untouched, so there is no changeset.

[baldurpan]

Not approving yet. Three small bugs in the new flow each need a one- or two-line fix, and I'll approve once they're in. The direction is right, and the numbers back it up.

What works well

• The cuts come from measured transcripts, not guesses. usage.py gives a baseline to check them against next week.
• There is one orchestrator, and the no-spawn rule is enforced twice: disallowedTools: Agent on every persona, plus CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1. I checked all three env vars against the Claude Code docs. They exist and do what the PR says. The project Explore on Sonnet is a real saving too, because the built-in Explore runs on the main session's model, which is Opus here.
• Spec folders, workers that get only their own slice, short worker reports and --reporter=dot | tail all cut context where it starts. That's the right lever.
• Capping auto-compact at 200K is most of the win. Bigger isn't always better. (That's what she said.)

Must fix before merge

The inline comments have the detail and a suggested fix for each.

1. /optimize crashes on macOS's python3 (3.9.6). skill-optimizer/scripts/optimize.py uses str | None without from __future__ import annotations. run.py swallows the error, so the owner sees only JSONDecodeError: Expecting value. /implement ends with this step, so every story hits it on a machine like mine.
2. plan_gate.py rejects the frontmatter template from plan-story §6. The template has inline # … comments, and the gate reads them as part of the value.
3. plan-story step 5b can't ask about 5 candidates. It wants one AskUserQuestion option per candidate, and dox-architect may return 5, but the tool takes at most 4.

Should fix

4. Every library story will end /optimize with FAIL. finalizer edits context/domination/tracker.md, which is already over both budgets, so run.py lists it as a finding to fix. A check that fails on every run teaches the agent to skim past FAIL.

Smaller things

These are inline, and none of them blocks the PR:

• A kilo.jsonc that doesn't parse passes silently.
• The plan gate contradicts three rules in pipeline.
• settings.json needs a Claude Code version note.
• The usage window counts whole files, not the last 7 days.
• Two passages are out of date.

One question

The plan gate is a convention, not a lock. Any agent that can edit the index can write status: approved itself. Is that enough, or do you want a hook to make it hard? (That's what she said.) I'd ship it as a convention. A hook would also block the main session's legitimate edit, so it needs more design than it's worth right now.

What I ran

I ran these in a detached worktree at 9a70bd71:

• uv run --extra dev pytest -q .agents/skills: 126 passed.
• uv run python .agents/skills/optimize/scripts/run.py: only the 2 pre-existing findings your description names.
• python3 .agents/skills/optimize/scripts/run.py on Python 3.9.6: crash (item 1).
• agent-optimizer/scripts/optimize.py .: 0 broken links, 0 symlink or Kilo problems, and every persona on its intended model.
• I reproduced items 2 and 4 and the kilo.jsonc comment by running the scripts against edited copies.

[craig-o-curtis]

@baldurpan Thanks for the thorough review. Everything is in bf1c07f6, and each inline comment has its own reply.

On your question about the gate: we're shipping it as a convention, as you suggested. A hook strong enough to stop an agent from writing status: approved would also block the main session's legitimate edit after the owner approves, so it needs more design than it's worth now. The skills already say that only the owner's approval at the end of /plan-story sets the marker.

Also in this push: Kilo is gone from the project. Neither of us uses it, so kilo.jsonc, its checks and every mention are removed.

Re-checked after the fixes:

• 141 tests pass on Python 3.14 and on macOS's /usr/bin/python3 (3.9.6).
• run.py under 3.9 prints PASS: 0 finding(s) to fix; 154 backlog.
• agent-optimizer reports 0 broken links and 0 symlink problems, with every persona on its intended model.

[baldurpan]

Approving. All three must-fix items are fixed. I checked each one on bf1c07f6 by rerunning the case that failed before:

1. On macOS's Python 3.9.6, run.py prints PASS: 0 finding(s) to fix; 154 backlog. When a child crashes, run.py now prints the child's real error.
2. plan_gate.py passes the §6 template exactly as written, comments included.
3. The Dox shortlist is capped at 4 in both places.

The should-fix is done too: a story that edits the tracker now ends /optimize with PASS. The smaller comments are all addressed, and Kilo is removed cleanly.

Tests: 141 pass on 3.14. On 3.9.6, 138 pass and 3 skip; the skips are the PyYAML tests, because that Python has no PyYAML. All 39 CI checks pass.

There's one optional follow-up in the size-finding thread, about files that are already over budget getting bigger. It doesn't need to be in this PR. Nice work.