# Handoff > Produces and refreshes `.docs/handoff.md`, a 200-line session-continuity runbook for coding agents. Captures git state, working-tree changes, last validation commands, session decisions, blockers, resume checklist, references, and greenfield scaffolds. Triggers on: "update handoff", "session handoff", "refresh handoff", "/handoff", "/handoff init", "resume checklist", "cold-start primer". Use this skill when ending, pausing, resuming, or transferring in-flight project work across agent sessions. - Skill: `mathews-tom/handoff` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add mathews-tom/handoff` - Raw SKILL.md: https://api.skillmd.com/api/skills/mathews-tom/handoff/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: mathews-tom (https://skillmd.com/u/mathews-tom) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mathews-tom/handoff --- # Handoff Maintains `.docs/handoff.md` as the project-local cold-start primer for the next coding agent or human developer. The file captures transient session state only: what changed, what was decided, what is blocked, and exactly how to resume. ## Reference Files | File | Contents | Load When | | --- | --- | --- | | `references/schema.md` | Verbatim handoff schema and line-budget rules | Always before writing | | `references/authority-boundaries.md` | Boundary between handoff, memory, CLAUDE.md, plans, and git | Always before writing | ## When To Use | Use handoff | Use another surface | | --- | --- | | In-flight work, uncommitted edits, current branch, blockers, resume steps | `git log` for committed history | | Session-scoped decisions and failed approaches | Memory or ADRs for durable project facts | | Immediate validation state and exact next command | `CLAUDE.md` for stable setup instructions | | Current roadmap cursor | Plan files for strategic roadmap content | ## Triggers - Direct commands: `/handoff`, `/handoff init` - Refresh phrases: "update handoff", "session handoff", "refresh handoff", "save handoff" - Resume phrases: "cold-start primer", "resume checklist", "handoff to next session" - Stop hook: refresh silently when `.docs/handoff.md` already exists ## Prerequisites - `git` available in the project root. - Project write access for `.docs/handoff.md`. - Optional project-local marker files: - `.docs/handoff.last-validation` containing the last verification command and result. - `.docs/handoff.session` containing extra bullets for changes, decisions, blockers, or refs. ## Workflow 1. **Resolve mode.** - `/handoff init` or invocation from an initialization workflow writes a greenfield stub when `.docs/handoff.md` is absent. - `/handoff`, refresh phrases, and Stop-hook invocation rewrite the full file. 2. **Read source of truth.** - Load `references/schema.md` and preserve the schema headings exactly. - Load `references/authority-boundaries.md` and include the authority boundary line in every generated handoff. 3. **Detect repository state.** - Run `git rev-parse --show-toplevel`, `git branch --show-current`, `git rev-parse --short HEAD`, and `git status --porcelain`. - Count modified, untracked, and staged paths from porcelain status. - Include the top 3-5 changed paths in the Status section. 4. **Detect validation state.** - Prefer recent session context: commands actually run in the current agent session and their result. - If available, read `.docs/handoff.last-validation`. - If neither exists, write explicit unknowns: "not recorded this session" rather than inventing pass/fail. 5. **Gather session substance.** - Summarize logical changes from current conversation, uncommitted paths, and commits since the branch base when relevant. - Record decisions with rationale in two sentences or fewer. - Record blockers and open questions as actionable unchecked items. - Include failed approaches when they would prevent wasted work in the next session. 6. **Write by full rewrite.** - Replace `.docs/handoff.md` atomically; do not append. - Create `.docs/` if absent. - Keep the file lowercase at `.docs/handoff.md`. 7. **Enforce 200 lines.** - Count final lines after rendering. - If over 200, truncate `## What changed this session` oldest-first. - Insert ``. - If still over 200, compress decisions and blockers to the newest actionable items, preserving all required headings. ## Supported Operations | Operation | Command | Behavior | | --- | --- | --- | | Refresh | `/handoff` | Rewrites `.docs/handoff.md` from current repo and session state | | Scaffold | `/handoff init` | Creates an empty schema stub when no handoff exists | | Stop refresh | Stop hook | Refreshes only when `.docs/handoff.md` already exists | | Dry run | `uv run skills/handoff/scripts/handoff.py --dry-run` | Prints generated content without writing | ## Implementation Notes The bundled script is the deterministic baseline used by the command and hook: ```bash uv run skills/handoff/scripts/handoff.py --project-root "$PWD" uv run skills/handoff/scripts/handoff.py --project-root "$PWD" --init ``` Agents may improve populated bullets from live session context before writing, but must preserve: - Schema headings and order. - Authority boundary line. - Full-file rewrite semantics. - Hard 200-line cap. - Explicit unknowns instead of silent fallbacks. ## Greenfield Scaffold When invoked as `/handoff init` or under a project initialization flow and `.docs/handoff.md` does not exist, write the schema with empty placeholders and real git metadata. This documents the `/init` integration point without modifying any init script. ## Output Format Write exactly one file: `.docs/handoff.md`. Required first lines: ```markdown # Handoff — **Last touched:** · **branch:** `` · **HEAD:** `` · **session:** ``` ## Troubleshooting | Problem | Resolution | | --- | --- | | Not in a git repository | Fail clearly for refresh; scaffold may use branch `—` and HEAD `—` only during `/handoff init` | | `.docs/` missing | Create it before writing | | Validation state unavailable | Write "not recorded this session"; do not claim tests passed | | Generated file exceeds 200 lines | Truncate oldest `What changed` bullets and add the warning comment | | Existing handoff uses old casing or root path | Do not migrate automatically; future refreshes converge only when invoked in that project | ## Verification - `uv run python scripts/validate_evals.py` - `uv run scripts/evaluate_package.py skills/handoff` - `uv run skills/handoff/scripts/handoff.py --project-root --dry-run` - `uv run skills/handoff/scripts/handoff.py --project-root --init --output `