1. Name the mistake
Write the mistake as a check: "a list command prints the id before the name", not "be careful with list output". Done when a script could, in principle, detect it.
2. Pick the strongest structure that holds it
In this order, take the first that works:
- A type the compiler rejects.
- A lint rule in
.oxlintrc.json. - A test that scans the code or the command tree, like
src/lib/root-options.test.ts, which checks cli-core's argv scan agrees with commander. - A script check in
.agents/scripts/(verify, a hook). - A review check in
.agents/checks/, for judgment a script can't make. - A line in
AGENTS.mdor a skill, only if nothing above can hold it.
A rule already written down that still got broken skips straight to 1–4. Done when you can say why the stronger options don't fit.
3. Prove it catches the mistake
Make the mistake on purpose. The new structure must fail on it. Remove it: it passes. Run npm run verify. Done when you have seen both.
4. Delete what it replaces
Remove instruction lines the new check makes redundant, in AGENTS.md or the skills. Update the rules table in docs/agents.md: the rule, what holds it, and how certain it is.
5. Ship it on its own
One small pull request for the new structure, titled chore: or test: so it does not release. Done when its diff contains only this rule.