`docs/conventions.md`

The canonical conventions block: the day-to-day rules that are too small to be decisions and too real to leave unwritten. Commit format, branch and history, the working language, how comments earn their place, what a guard has to do.

It ships as a separate file that gets merged into AGENTS.md at adoption, and then AGENTS.md is the living home. This file is the delivery mechanism, not a second copy.

What it is for

The rules where reversing the decision costs a search-and-replace rather than a rewrite. Those are not decision records. Recording them as ADRs buries the real decisions under formatting preferences; leaving them unwritten means they are re-argued in every pull request by whoever cares most that day.

What goes in here

- Conventional Commits, ticket after the colon; no AI/tool attribution;
  ASCII hyphen only; small focused PRs.
- **Branch and history (R23):** branch off main and base every PR on main;
  update by rebase, never merge main into your branch.
- **Comments:** explain why, never what. Match the density of the file you
  are editing. If a comment restates the line below it, delete it.

Two that are worth calling out because they are easy to read past.

The working language is a configuration, not a constraint. An agent reads whatever you choose, so decide per artefact and write it down: code and commits in English, docs in the team's language, user-facing copy in the persona's. What breaks a repo is not the choice, it is leaving it unstated so that every file guesses.

A fact has one home (R4). A count, a version, a path, a command lives in one file and everywhere else links to it. Where a restatement genuinely must exist, declare it in docs/facts.json and a guard fails when the two stop agreeing. Undeclared restatements rot: "twenty rules" outlived the twenty-first by weeks.

What does not go in here

Anything contestable. If a future engineer could reasonably argue for the opposite and the argument would matter, it is a decision record, not a convention.

Anything the guards already enforce mechanically, unless a person needs to know it before the guard fires. A convention that only restates a check is one more thing to keep true.

Restatements in a third file. Once this is merged into AGENTS.md, that is where it lives. Do not copy it into CLAUDE.md or .cursor/rules; point at AGENTS.md from there.

Decisions behind it

ADR-012 - in-repo instructions are the source of truth. Personal memory, global agent configs and chat may point at repo rules; they must never hold them. A rule that exists only outside the repo is treated as missing, and finding one is a defect fixed by landing the rule at its home. "It is in my memory" is not a location.
Conventions ship as a file and end up merged. Shipping them only as a section of AGENTS.md was the alternative, and it makes updating the standard's conventions a three-way merge inside a file the adopter has heavily edited.

Reference

Status. Optional - part of the core profile.
How it arrives. merge - combine the standard's content with what the repo already has, keeping both (ignore files, CI that already has jobs)
Shipped form. read it in the standard's own tree

The rule that requires it

A repo MUST carry AGENTS.md at its root as the single entry point for

See it in the spec