repo-handover
Keep a repository ready for another agent or person to take over with no context. Sets up and maintains the canonical doc set (README, AGENTS.md, CHANGELOG, roadmap, docs/architecture) and defines when each must be updated. Use when creating a repo, at the end of every task that changes behaviour, and whenever you notice docs disagree with the code.
A repo is handed over well when a new agent can read AGENTS.md and, within minutes, know what the project is, how to build and test it, what state it's in and what to do next. Nobody should have to ask "where were we?".
The canonical doc set#
| File | Audience | Must say |
|---|---|---|
README.md | People | What it is, who it's for, how to get it, where docs live. Short. |
AGENTS.md | Agents (and maintainers) | Current state, build, test, conventions, gotchas, next steps, links to the Agent-Toolkit skills it uses. |
CLAUDE.md / GEMINI.md | Specific agents | One line: "Read AGENTS.md". Never a second copy of the rules. |
release-notes.json → CHANGELOG.md | Everyone | What changed, in plain language. Generated with tools/changelog.cjs. |
roadmap.json → ROADMAP.md | Everyone | Stages, items, status, evidence. Generated with tools/roadmap.cjs. |
docs/architecture.md | Developers | Components, data flow, where code lives, external services. |
Templates are in templates/repo/ and templates/data/.
When to update#
- Every merged change:
- Add a
release-notes.jsonentry (or append to the unreleased one). - Regenerate
CHANGELOG.md. - Update
roadmap.jsonitem status and evidence (PR link, test result).
- Add a
- Behaviour or setup changed: update
AGENTS.md(build/test/gotchas) anddocs/architecture.mdif components moved. - End of a session: the "Current state" and "Next steps" sections of
AGENTS.mdreflect reality. If you stop mid-task, write exactly where you stopped and what you were about to do. - You learned something general: add it to the Agent-Toolkit (see its
CONTRIBUTING.md), not only to this repo.
Steps for a new repo#
- Copy
templates/repo/*andtemplates/data/*into the repo root and fill in every<placeholder>. - Copy
tools/changelog.cjsandtools/roadmap.cjsfrom the toolkit into the repo'stools/(or call them from a toolkit checkout). - Run
node tools/changelog.cjs && node tools/roadmap.cjs, then commit.
How you know it's done#
node tools/changelog.cjs --checkandnode tools/roadmap.cjs --checkboth pass.- A fresh agent given only "continue this project" would know the next step from
AGENTS.md.
Gotchas#
- Two sources of truth rot. Never hand-edit
CHANGELOG.mdorROADMAP.md; edit the JSON. - Agent-specific files drift. Keep
CLAUDE.mdetc. as one-line pointers. - Secrets. Account IDs, tokens and personal data never go in docs. Say where they live (e.g. "Cloudflare account: Knot Vector") instead.