write-agentsmd

AGENTS.md is loaded into every agent session in the repo — its cost compounds across every future conversation. Optimize for token budget and signal density, not completeness.

Workflow

1. Measure the current file: wc -l and a char/4 token estimate (see Bloat Scan below). Flag anything past ~150 lines / ~2500 tokens.
2. Classify every section: operating rule (keep inline), reference material (extract to a linked doc or the tool's own --help/docstring), or filler (cut outright).
3. Check ordering: the highest-blast-radius prohibitions must be readable in the first ~30 lines, not past the midpoint.
4. Run every remaining section against the Rules below.
5. For each extraction candidate, verify the reference target actually contains the detail before cutting — grep/cat it, don't assume from memory.
6. Re-measure. Confirm nothing load-bearing was lost, not just that the file got shorter.

Rules