Layered repository conventions
Compose repository-wide, language, and area instructions without turning one entry document into a monolith.
Start with one reading order
A short entry document should explain where authoritative instructions live and in what order they apply. It is a map to the contract, not a duplicate of every rule.
Add narrower layers near their owners
Repository-wide rules form the base. Language and code-area conventions add narrower constraints beside the code they govern, so a shell rule does not burden unrelated Make or application code.
A narrower layer adds to or deliberately overrides a broader layer. Naming that relationship makes conflicts reviewable.
Write down the review boundary
A review request also needs a written boundary. Distinguishing staged work from unstaged work prevents a reviewer from silently folding unrelated edits into the requested change.
1AGENTS.md2docs/conventions/3shell/docs/conventions/4toolchain/docs/conventions/AGENTS.md is this repository's chosen instruction entry point. The useful general pattern is the explicit reading order, not an assumption that every repository uses the same filename.