A standard template for the REPO.md file — part of the Agent Rules Suite.
Every repo has unwritten rules. "We don't use Redux." "No runtime type checking." "This service owns its own schema." Right now that stuff lives in PR comments, Slack threads, and people's heads.
REPO.md puts it in writing.
It sits alongside your README (what this is), CONTRIBUTING (how to contribute), and ADRs (why we decided X). The gap it covers is the settled "we don't do Y" stuff — the architectural constraints and scope boundaries that aren't obvious from reading the code.
For AI agents it's even more valuable. A human can ask "wait, why not?" An agent will just try again with a different approach. A REPO.md that says "no class components, period" saves three rounds of back-and-forth.
Copy template/REPO.md into the root of your repo and fill it in. Keep it short. If you catch yourself writing "we prefer" or "we might," that doesn't belong — save it for an ADR or a discussion issue. REPO.md is only for things that are decided and non-negotiable.
REPO.md is one file in a suite of standard files designed to make repos legible to both humans and AI agents:
| File | Purpose |
|---|---|
| REPO.md | Scope, non-negotiables, conventions, what won't be accepted |
| SUMMARY.md | Agent orientation — quick overview so agents don't scan the whole repo |
| HANDOFF.md | Context transfer between sessions — what was done, what's next |
| HITL.md | Human-in-the-loop rules — when to stop and ask vs. when to proceed |
| PORTMASTER.md | Port registry for all running services |
| CONTRIBUTING.md | How to contribute — process, setup, PR workflow |
| README.md | What this is, how to use it |
| ADR/ | Why specific decisions were made (one file per decision) |
Each file has a single job. None of them overlap.
MIT — use it however you want.