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#

FileAudienceMust say
README.mdPeopleWhat it is, who it's for, how to get it, where docs live. Short.
AGENTS.mdAgents (and maintainers)Current state, build, test, conventions, gotchas, next steps, links to the Agent-Toolkit skills it uses.
CLAUDE.md / GEMINI.mdSpecific agentsOne line: "Read AGENTS.md". Never a second copy of the rules.
release-notes.json → CHANGELOG.mdEveryoneWhat changed, in plain language. Generated with tools/changelog.cjs.
roadmap.json → ROADMAP.mdEveryoneStages, items, status, evidence. Generated with tools/roadmap.cjs.
docs/architecture.mdDevelopersComponents, 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.json entry (or append to the unreleased one).
    • Regenerate CHANGELOG.md.
    • Update roadmap.json item status and evidence (PR link, test result).
  • Behaviour or setup changed: update AGENTS.md (build/test/gotchas) and docs/architecture.md if components moved.
  • End of a session: the "Current state" and "Next steps" sections of AGENTS.md reflect 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#

  1. Copy templates/repo/* and templates/data/* into the repo root and fill in every <placeholder>.
  2. Copy tools/changelog.cjs and tools/roadmap.cjs from the toolkit into the repo's tools/ (or call them from a toolkit checkout).
  3. Run node tools/changelog.cjs && node tools/roadmap.cjs, then commit.

How you know it's done#

  • node tools/changelog.cjs --check and node tools/roadmap.cjs --check both 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.md or ROADMAP.md; edit the JSON.
  • Agent-specific files drift. Keep CLAUDE.md etc. 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.