Agent Docs Readiness

Every line in AGENTS.md gets loaded on every task. Bloat steals the budget you need for project-specific rules. Contradictions silently override each other. Default-behavior bullets dilute the rules that actually steer the model.

Core principle. Every line in AGENTS.md must be project-specific. If a competent model would do the right thing without it, delete it.

The root file is a map. Depth lives in README.md, docs/, and references/.

Normative language

Use plain imperatives for routine workflow instructions. Reserve MUST / MUST NOT for hard constraints with clear failure modes, and use SHOULD for strong defaults where a deviation can be explained. Do not require every rule to begin with RFC 2119 keywords; keyword inflation hides the rules that actually matter.

Workflow

1. Find contradictions

List each pair. Propose the version to keep — one sentence of reasoning. Ask the user. Never autoresolve.

Contradictions encode a user choice the model cannot see. Autoresolving silently picks a side.