A new agent takes over your repo in ten minutes: the seven-piece agent handover pack for vibe projects

Every vibe developer knows this scene: an agent spends three days building your project, you start a new session — or switch models — and it asks everything all over again, as if it had amnesia. What is this project for, how does the database connect, which path does payment take, which files must never be touched? You spend a morning re-explaining context, and it still steps into the same trap on the third change. That is not a model problem. It is a handover problem: your repository has no "handover pack" that a new agent can read in ten minutes and then start working from.

The handover pack is not a document pile: start with the ten-minute test

There is one test for whether a handover pack is good enough: a new agent that has never seen this project, reading only the pack and asking you nothing, should be able to state three things within ten minutes — who this project serves and what problem it solves, where to start a change, and how to prove the change did not break anything. If it cannot, the pack is decoration, however many pages it has.

That test rules out two common approaches. The first is turning the README into a chronicle: from the founding idea through every refactor. Everything in it may be true, but a new agent remembers half of it and looks the rest up while working. The second is stuffing all context into chat: agreements from one session do not survive into the next, and switching models wipes them entirely. Chat is volatile storage; the repository is durable storage. The handover pack must live in the repository, versioned, reviewed, and allowed to expire alongside the code.

The seven pieces: each with exactly one job

First, a one-pager. Half a page to a page: who it serves, what problem it solves, the three core steps, the tech stack (only what the project actually confirms — leave uncertain items blank), and the deployment address and running status. No vision statements, no roadmap essays. The reader is an agent that just walked in; it needs orientation, not persuasion.

Second, an architecture map. Not a full UML family portrait, but a "change map": the module list, one sentence of responsibility per module, data flow between modules, and where each external service (database, payments, mail, object storage) is used. The format does not matter; a text list works. What matters is that before changing A, the agent can see whether B is affected. The map must mark "legacy zones": code that is known to be unreasonable but cannot move yet, with why it cannot move and what must happen first.

Third, decision records. One line per important decision: date, decision, alternatives considered, why this one won, and under what conditions it may be overturned. Decision records fix the most common agent mistake: re-proposing, as an innovation, a solution the previous builder deliberately rejected. Without a record saying "why we do not use this ORM's auto-migration," a new agent has roughly even odds of proposing it as an improvement.

Fourth, a no-go list. This is the most valuable page in the pack: files that must never be touched, table structures that must not change, secret locations that must not rotate casually, commands that must never run in production, and legal and compliance red lines (for example, user data must not enter logs). The no-go list must be specific down to file paths and exact command text; a vague "be careful with the database" is the same as nothing.

Fifth, a verification command list. Build, test, lint, type check, and migration dry-run — each command written out verbatim, with what normal output looks like and what common failures look like. After changing code, the agent's first move is to run this list, not to ask you "does this look right?" The list must also include one golden path: the shortest manual steps from startup to completing one core business operation, for smoke verification.

Sixth, a task queue and known pitfalls. What is in progress, what is queued, known unfixed bugs, flaky tests and how to rerun them, and workarounds with expiry dates. Without this piece, a new agent treats known pitfalls as new discoveries and temporary workarounds as permanent design.

Seventh, the handover ritual itself. The rule: a new agent's first task is always "small fix + verification + write-back" — fix something small, run the verification list, then write back whatever outdated or wrong information it found in the pack. The ritual does two things: it tests, at low risk, whether the pack is actually usable; and it lets the pack correct itself at every handover instead of going stale.

A skeleton you can copy directly

docs/agent-handover/
  01-one-pager.md        # who, what problem, three core steps, stack, deploy address
  02-architecture-map.md # modules, data flow, external services, legacy zones
  03-decisions.md        # date, decision, alternatives, overturn conditions
  04-no-go-list.md       # forbidden files, forbidden commands, compliance lines (exact paths)
  05-verify.md           # build/test/lint/migration commands verbatim + normal and failure output
  06-queue-and-pitfalls.md # in progress/queued/known pitfalls/workarounds with expiry dates
AGENTS.md                 # entry: read the pack first, then act; first task follows the ritual

AGENTS.md is the entrance, not the body. It does three things only: point the way (read docs/agent-handover first), set the rule (the no-go list outranks every suggestion), and set the ritual (the first task must be small fix + verification + write-back). Stuffing long content into AGENTS.md is the most common anti-pattern: the longer the entrance, the more likely a new agent skips it.

Maintenance rules: an expired pack is more dangerous than none

An expired handover pack is more dangerous than no pack at all, because it makes an agent confidently wrong. So maintenance must be a process, not a resolution. First, any pull request touching architecture, data flow, external services, or no-go items must update the pack in the same change — put that line in the PR template checklist, and do not merge without it. Second, run a monthly "pack health check": give the pack alone to an agent (or colleague) who has never worked on the project, and ask it to restate the project positioning and verification steps; whatever it cannot restate gets fixed the same day. Third, stamp every item with a "last verified" date; anything unverified for more than 30 days gets marked "to be verified," so a reading agent knows not to trust it fully.

One iron rule: the pack contains no secrets, no real user data, and no screenshots of internal chats. Where a reference is needed, write where to fetch it (for example, the secret manager name or the environment variable name), not the value itself. The pack will be read in full into every session's context; anything sensitive written into it is effectively handed to every future session.

Boundaries with existing guides

This piece has a distinct job from five nearby guides, and the distinction matters before reading. The prompt version-control guide is about versioning prompts as code assets; its object is the prompt itself. This piece is about packaging project knowledge as a handover artifact; its object is repository knowledge, of which prompts are only a small part. The parallel-agents workflow guide is about multiple agents working at once — division of labor and conflict handling. This piece is about one new agent taking over — knowledge transfer, one step earlier, not overlapping. The dev-environment standardization guide is about making any machine run the project with one command; this piece assumes the project already runs and answers where to change it. The incident runbook guide is about stopping the bleeding by steps after an incident; this piece is about knowing where the shutoff valves are before anything happens. The AI evals guide is about measuring output quality with tests; this piece is about measuring, through the handover ritual, whether the pack itself is usable. Merging all five into one "agent best practices mega-guide" would thin every one of them; kept separate, each can be followed directly.

Three steps you can take this week

• Step one (30 minutes): create the skeleton directory from the seven pieces, and write first the three most life-saving pieces — the one-pager, the no-go list, and the verification command list. Leave the other four marked "to be filled" rather than delaying launch for completeness.
• Step two (at the next merge): add one line to the PR template — "has the handover pack been updated in sync?" — and enforce it from the next architecture change onward, turning maintenance into process rather than willpower.
• Step three (at the next agent switch): enforce the ritual — small fix + verification + write-back — and count how many places in the pack got changed afterward. The more it changed, the more alive it is.

Bottom line: a vibe project's real asset is not the output of any single agent session. It is the ability of any new agent to take over within ten minutes. Write that ability into the repository, not into a chat transcript, and the project truly belongs to you — not to one lucky session.