Learn from a mistake

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:

1. A type the compiler rejects.
2. A lint rule in .oxlintrc.json.
3. 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.
4. A script check in .agents/scripts/ (verify, a hook).
5. A review check in .agents/checks/, for judgment a script can't make.
6. A line in AGENTS.md or 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.