# Handover & Resume — Session Continuity Skills
A pair of skills for Claude Code and Craft Agents that keep long coding sessions from degrading.
They treat a session boundary as **state transfer, not conversation summary** — you write the truth
into durable files inside your project, then start a fresh session that reconstructs state from those
files instead of from a giant, noisy transcript.
Two skills, one contract:
| Skill | Command | What it does |
|---|---|---|
| **Handover** | `/handover` | At a milestone or phase change, captures the session's real state into in-repo artifacts and writes a self-contained startup brief. |
| **Resume** | `/resume` | In a fresh session, reads the brief, verifies it against the live files and git, reconciles any drift, then restates the plan before changing anything. |
## Why bother
Long sessions fail in two ways: the context window fills with noise, and the model starts trusting
its own stale summary over the actual code. Compaction helps you stay in **one** thread, but when you
cross a boundary — finishing a milestone, switching phases, or noticing drift — a clean restart from
explicit files is more reliable. These skills make that restart disciplined and repeatable.
## The loop
```
session 1 (build) ──/handover──▶ writes artifacts ──▶ START A NEW SESSION ──/resume──▶ session 2 (build)
```
The fresh session is the whole point. `/handover` ends by telling you to open a **new** session and
run `/resume` there — it will not resume in the same polluted context.
## Artifacts (all live inside your project repo)
```
{project-root}/
├── PROGRESS.md # living log — appended every milestone, never wiped
├── HANDOVER.md # the latest self-contained brief — overwritten each handover
├── handover/ # visible archive of timestamped snapshots, one per handover
│ └── HANDOVER-YYYY-MM-DD-HHMM.md
└── init.sh # optional deterministic startup (install / build / serve)
```
Because the artifacts live in the repo, a handover travels with your code — clone the project, get the
state.
### HANDOVER.md structure
The brief uses XML-tagged sections so the next session can parse fields unambiguously while staying
human-readable:
- `<mission>` — what the project is and what "done" means for the current phase
- `<current_state>` — what works (verified), what's half-built, what's broken
- `<artifacts>` — repo/branch, key files, how the app runs, where tests live
- `<decisions>` — settled choices that must not be reopened, with the why
- `<constraints>` — hard limits and forbidden moves, read from the project itself
- `<verification>` — what was actually run vs assumed
- `<next_steps>` — exact next actions, in order
- `<unknowns_and_do_not_assume>` — explicit gaps to verify before acting
- `<source_of_truth_rank>` — precedence when the brief disagrees with reality
- `<startup_protocol>` — what to read and run before answering or editing
Two of these do the heavy lifting against hallucination: the **verified-vs-assumed split** (unverified
claims go to `<unknowns>`, never to `<current_state>`) and **`<source_of_truth_rank>`** (a fixed
precedence — `running code > tests > docs > PROGRESS.md > this HANDOVER > older handovers` — so a
stale brief can never override live code).
## Install
Drop both folders into your agent's `skills/` directory:
- **Claude Code:** `~/.claude/skills/` (global) or `.agents/skills/` (per-project)
- **Craft Agents:** your workspace's `skills/` folder
```
skills/
├── handover/
│ ├── SKILL.md
│ └── icon.svg
└── resume/
├── SKILL.md
└── icon.svg
```
Then invoke `/handover` and `/resume`. No external services, sources, or memory systems required —
the only dependencies are `git` and a shell.
## When to use which
- Use **`/handover`** at a boundary: a milestone is stable, you're switching phases, the conversation
has drifted, or you're stopping for the day. Not for trivial mid-thread saves.
- Use **`/resume`** at the start of a fresh session on a project that already has a `HANDOVER.md`.
It verifies before it trusts, and it won't edit until it has restated the plan.
## License
© 2026 Steff VanHaverbeke (CoachSteff). Licensed under
[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) — a copyleft
license. You may share and adapt this material, including commercially, as long as
you **credit Steff VanHaverbeke (CoachSteff)**, link to the license, indicate any
changes, and license your derivatives under the same terms. See [LICENSE](./LICENSE).