AGENTS.md Setup and Audit

• IS: wiring a repo so every agent tool in use reads the same rules, then auditing, scoring, refactoring, and writing the AGENTS.md / CLAUDE.md / CLAUDE.local.md files agents load at session start.
• IS NOT: authoring SKILL.md files (use agent-skills-creator), project docs or READMEs (use docs-writing or readme-creator), or mining session history (use the external cadence-advise skill where installed; this skill audits the file as-is).

AGENTS.md files are execution contracts, not knowledge bases. Two tests catch the two ways a line fails.

• Dead weight: "Would removing this cause the agent to make a mistake?" If no, cut it; bloat makes agents ignore the rules that matter.
• Harmful precision: "Is this wrong on any plausible task in this repo?" A prohibition that is wrong one task in ten is still obeyed on that task, and the agent cannot tell that this is the exception. State the outcome you want and let the surrounding code pick the path. NEVER write comments becomes match the comment density of the file you are editing: shorter, no exception list to maintain, and correct in a densely commented file without being told.

Absolutes still earn their place for safety, data loss, format contracts, and rules this repo's agents have actually been observed to break.

AGENTS.md is the tool-agnostic source of truth. Claude Code loads AGENTS.md, CLAUDE.md, and CLAUDE.local.md natively at any directory level, so Claude Code alone needs no symlink. A CLAUDE.md -> AGENTS.md symlink is still correct when the repo also targets tools that read only CLAUDE.md; it keeps one source of truth instead of two files to drift. If only a CLAUDE.md exists, recommend mv CLAUDE.md AGENTS.md.

Choose a Mode

• Repo has no agent instructions, or targets a tool it is not wired for -> Setup: references/project-setup.md decides which files exist and which tool reads each one, then Writing From Scratch below fills the root file, then Audit scores it.
• A file exists and the question is quality -> Audit, below.
• A file exists and is bloated, stale, or scored badly -> Refactor, references/refactor-workflow.md.