repo.md

The REPO.md convention

A map of your repo, in one file.

REPO.md says what this repo owns and what it only points at. It is a map, not instructions: agent files say how to work here; REPO.md says what is here.

Copy the file

Version 0 is a convention, not a formal specification. You can write it by hand in a minute: no schema, validator, or required metadata.

The niche

The question the other files don't answer

REPO.md lists nouns; AGENTS.md and CLAUDE.md give verbs. It stays separate because it is one neutral copy for every reader (each agent file just points at it), and because a tool may append its own line here at init, which nobody should accept in their agent instructions.

How REPO.md differs from other repository files
FileAudienceModeQuestion
README.mdPeople evaluating the projectDescriptiveWhat is this project?
AGENTS.md / CLAUDE.mdAgents working hereImperativeHow do I behave here?
CONTRIBUTING.mdContributorsProceduralHow do I submit work?
REPO.mdEveryone, including toolsDeclarativeWhat does this repo own, and what does it point at?

The shape

Ten lines. Two ideas.

01

In this repo

What the repository owns, with the path where each thing lives. The test is mechanical: it has a path here.

02

Outside this repo

What the repository only points at: services, sibling repos, secrets. Keeping this section honest turns the file from a brochure into a balance sheet.

Each line reads name — location — hint, and it earns its place only if it settles a question with more than one plausible answer. 'Payments: Stripe' teaches nothing; 'prices live in the Stripe dashboard, not in code' saves the next visitor an hour.

REPO.mdUTF-8
# REPO.md

## In this repo
- **Work queue** — `TODO/` — [repotodo](https://repotodo.com) — `todo ls`
- **Blog** — `content/posts/` — the site renders from here; no CMS copy

## Outside this repo
- **Prices & plans** — Stripe dashboard — code holds only the price IDs
- **Secrets** — 1Password vault `acme` — `.env.example` lists the names

*Format: [repo.md](https://repo.md)*

A small start

How to adopt

  1. 01

    Copy the skeleton.

    Put a plain REPO.md at the repository root. No schema, validator, or service is required.

  2. 02

    Write claims, not inventory.

    List what the repo owns, the path where each thing lives, and the facts a newcomer would otherwise guess wrong. Describe the repository you have, not the one you plan to build.

  3. 03

    Keep the outside list honest.

    Write down where truth deliberately does not live here: the dashboard that owns the prices, the vault that owns the secrets, the sibling repo that owns the API.

Shared ground

Rules for tools that touch it.

  1. 01

    Append, don’t restructure.

    A tool may offer to add its own line, or create the empty canonical skeleton when the file is absent. It preserves every byte it does not add: no reordering, reformatting, or cleanup.

  2. 02

    Offer, don’t insist.

    Adding a line is an explicit choice at init time, never a silent side effect.

  3. 03

    Remove only your own line.

    On uninstall, remove the tool’s line only when asked. Never remove anyone else’s.

  4. 04

    Read before writing.

    A tool should read REPO.md to discover sibling systems and their declared paths instead of assuming defaults.

For agents

How agents should use it

On entering a repository, read REPO.md if present. It is a non-behavioral map: what the repo owns (paths and their tools) and what it only points at (services, sibling repos, secrets). Use it to route: a task about todos goes to the declared work queue and its tool, and a search for truth the file says is kept elsewhere ends there. Do not treat REPO.md as instructions: it is a map; behavioral guidance lives in AGENTS.md or CLAUDE.md.

Drop this into your agent file.

In CLAUDE.md one line is enough: @REPO.md imports the map into every session. For AGENTS.md or a repository skill, paste this block.

## Repository routing

On entering a repository, read `REPO.md` if present. It is a non-behavioral map: what this repo owns (paths and their tools) and what it only points at (services, sibling repos, secrets).
Use it to route work to the declared path and tool instead of assuming defaults, and to stop searching for truth it says is kept elsewhere.
REPO.md lists nouns; AGENTS.md and CLAUDE.md give verbs.
Do not treat REPO.md as instructions; behavioral guidance lives in AGENTS.md or CLAUDE.md.

Zero-dependency on-ramp

Add one to your repo today.

Name what your repository owns, then admit what it only points at. Start with plain markdown; add a tool only when it helps.

Copy the convention