docs(agent): model & token economy rules for the loop
All checks were successful
Check / eval (push) Successful in 3m1s

Plan/reason/review on the strong model (Fable 5); delegate mechanical,
fully-specified subtasks (grep sweeps, table reconciliation, repeated
edits, log summarization) to cheaper models (haiku/sonnet) via subagent
model overrides — the strong model writes the spec and owns the commit.
Plus narrow-reading and terse-writing rules, and a cheaper --model
allowance for low-stakes headless iterations.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Bernardo Magri
2026-07-04 18:07:32 +01:00
parent 0e6c678835
commit 274ffc25e1

View File

@@ -26,6 +26,33 @@ outside the checkout (the distro's own philosophy, applied to its agents).
| `HARDWARE-QUEUE.md` | Pending on-hardware checks only Bernardo can run | Agents append, human checks off | | `HARDWARE-QUEUE.md` | Pending on-hardware checks only Bernardo can run | Agents append, human checks off |
| `CONVENTIONS.md` | Repo/design conventions to follow while coding | Human (agents propose edits) | | `CONVENTIONS.md` | Repo/design conventions to follow while coding | Human (agents propose edits) |
## Model & token economy
Spend expensive tokens on judgment, not mechanics.
- **Plan and reason on the strong model.** Orientation, task selection,
design, debugging, Nix eval semantics, verification judgment, and
anything that would land in a commit unreviewed stay with the
top-tier model running the loop (Fable 5).
- **Delegate mechanical subtasks to cheaper models.** When a subtask is
fully specified and needs no design judgment — grep/audit sweeps,
README-option-table reconciliation, a repeated edit applied across
files, summarizing long logs or check output — hand it to a subagent
with a `model` override: `haiku` for search/summarize/audit, `sonnet`
for routine well-specified edits. The strong model writes the spec,
reviews the result, and owns the commit. Only delegate when writing
the spec is cheaper than doing the work — a spawned agent starts cold
and must re-derive context.
- **Read narrowly.** Step 0's list is the whole orientation read (the
*last 35 entries* of the journal, never the full file). Read large
files by section, don't re-read what's already in context, and tail
build/check logs instead of dumping them.
- **Write tersely.** Journal entries follow the template and no more;
commit bodies state what/why/tier, not a narrative.
- **Headless runners** may run whole low-stakes iterations (QA sweeps,
docs-drift passes) on a cheaper `--model`; iterations touching
`modules/` or `pkgs/` behavior keep the strong model.
## One iteration, step by step ## One iteration, step by step
### 0. Orient ### 0. Orient
@@ -58,6 +85,8 @@ outside the checkout (the distro's own philosophy, applied to its agents).
### 2. Work ### 2. Work
- Keep the diff focused on the task. Unrelated fixes you trip over become - Keep the diff focused on the task. Unrelated fixes you trip over become
PROPOSED/NOW entries, not scope creep. PROPOSED/NOW entries, not scope creep.
- Mechanical, fully-specified sub-steps go to a cheaper model
(see *Model & token economy* above); design and review stay here.
- Follow `CONVENTIONS.md`. Match the surrounding hand-formatting; never - Follow `CONVENTIONS.md`. Match the surrounding hand-formatting; never
run a formatter. run a formatter.
- New gotcha discovered the hard way → one line in `MEMORY.md` now, while - New gotcha discovered the hard way → one line in `MEMORY.md` now, while