-
Inventory the real command surface before writing anything. Read, in this order: package.json (scripts), Makefile, pyproject.toml / setup.cfg, Cargo.toml, go.mod, composer.json, .github/workflows/*.yml, justfile, Taskfile.yml, and any CONTRIBUTING.md. CI workflows are the highest-value source: they contain the commands that actually have to pass.
For each command record its provenance — the file and key it came from. Provenance is what makes audit mode possible later.
-
Apply the evidence rule without exception. A command appears only if it traces to a file in the repo. Never infer from ecosystem convention: a Python repo does not necessarily run pytest, and a repo with jest in devDependencies may still have no test script.
When a section needs a command that doesn't exist, write the marker, not a guess: ✅ "Test: [missing: no test script in package.json or CI]" — ❌ "Test: npm test". The marker is useful; the guess is a trap.
-
Derive file placement from the actual tree, not from what the framework usually does. Name the directories that exist and what belongs in each. Two or three rows beat a full tree dump.
-
Extract only conventions an agent would otherwise get wrong. The test is counterfactual: would a competent agent, without this line, do the wrong thing? Naming rules that are enforced somewhere, invariants that look arbitrary but aren't, a generated file that must never be hand-edited. If the answer is no, cut the line.
Generic virtue instructions — "write clean code", "be thorough", "follow best practices", "use good naming" — are stripped, not softened. They consume context and change no behaviour.
-
Name forbidden actions explicitly. This is the section most files omit and the one that prevents the most damage: paths that must not be touched, commands that must never run unattended, files that are generated, secrets that must never be committed. Concrete and few.
-
Assemble under ~150 lines. In generate mode this is a hard cap — go over and cut, lowest value first (background prose, then examples, then convention lines that failed the counterfactual test). In audit mode it is a warning: report the overage and name the sections you would cut, because an existing file may be long for good reason.
-
Satellites only on request, and only as a delta. If asked to wire a specific tool, emit a satellite (CLAUDE.md, .github/copilot-instructions.md, GEMINI.md) that contains only what is specific to that tool, plus one line pointing at AGENTS.md for everything shared. Refuse to copy shared content into a satellite — four copies of a command list is four chances to be wrong, and the drift is invisible. See reference.md for the per-tool shapes.
-
Emit. Generate mode: the file, plus a provenance table showing where each command came from and what was marked [missing]. Audit mode: verdict, the unverifiable lines quoted, the virtue instructions to cut, the line-count position, and a concrete diff.
