git:20260925.f6554ff to git:20260928.7d7cde1

14 added, 1 removed. Audit A to A.

---

name: vibe-handover-doc

description: Writes a handover document so another person, another agent, or a different tool can pick up multi-session work cold. Use when handing work to someone else, switching tools, or pausing work that will not resume in the same session.

user-invocable: true

---

# vibe-handover-doc

Within one session, the harness handles continuity: context compaction, session resume, and memory files. A handover doc is for the moment that breaks: a different person, a different agent tool, or a fresh session days later. Write it for a reader who has none of your context.

## When to Use This Skill

- Handing work to a teammate or another agent

- Switching tools mid-project (for example, Claude Code to Codex or Gemini CLI)

- Pausing multi-session work that won't resume via session resume

- User says "save progress", "let's continue tomorrow", or "write this up for X"

## When NOT to Use This Skill

- To free up context in the current session (the harness compacts automatically; if you want to compact early, use its own command)

- Short sessions with trivial tasks

- Work that is fully committed, tested, and described in the PR (the PR is the handover)

- A current handover doc already exists (update it instead)

## Steps

1. **Capture state from the repo, not from memory**:

- Branch, last commit, `git status` (uncommitted changes?)

- Test status: run the suite and record pass/fail, don't guess

- Open PR, CI state, unresolved review threads

2. **Document completed work** — What was done, key decisions (link `vibe-decision-journal` entries), problems solved and how.

3. **Document remaining work** — What's left, what's blocked and on what, known issues introduced, and approaches already tried and rejected (so the next person doesn't retry them).

4. **Write a resume prompt** — A self-contained prompt the next session can be started with: branch, files to read first, the next concrete task, and how to verify it.

- 5. **Save** to `docs/handover/YYYY-MM-DD-<topic>.md` (or `docs/HANDOVER.md` for a single rolling doc), and commit it if the next reader will work from a fresh clone.

+ 5. **Order it current-state-first.** The top of the doc is what the next reader acts on. Move superseded plans and history to the bottom or to a separate file; a resume file that grows into a history slows every pickup.

+ 6. **Save** to `docs/handover/YYYY-MM-DD-<topic>.md` (or `docs/HANDOVER.md` for a single rolling doc), and commit it if the next reader will work from a fresh clone.

+ ## Wind-Down Mode (usage limit, restart, or "stop for now")

+ When a session must stop mid-work, especially with agents running:

+ 1. Stop or message running agents to reach a safe point

+ 2. Commit what passes its checks; stash or commit half-done edits to a clearly named WIP branch or stash, and record where

+ 3. Record CI state per pushed commit

+ 4. Write the handover with exact resume steps (a `CONTINUE.md` at the root works well)

+ 5. Put the resume convention in the project instructions file, for example "on 'continue', re-read CONTINUE.md and resume from the first unfinished step"

+ When the owner says pause ("just note it down"), write the note and plan, then stop. Don't keep building.

## Output Format

### Handover: [Feature/Project Name]

**Date**: [today] · **Branch**: [branch] · **Last commit**: [sha]

**Tests**: [pass/fail counts, command used]

### Completed

- [x] [task]

### Remaining

- [ ] [task] — [notes]

- [ ] [task] — blocked by [X]

### Decisions & Dead Ends

- [decision] — [rationale / DEC-ID]

- Tried [approach], rejected because [reason]

### Known Issues

- [issue] — [impact]

### Resume Prompt

> [Self-contained prompt: context, branch, files to read first, next step, how to verify.]