# 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).