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
- 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.
- 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.
- 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.
- 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.
- 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.
- Write by full rewrite.
- Replace
.docs/handoff.md atomically; do not append.
- Create
.docs/ if absent.
- Keep the file lowercase at
.docs/handoff.md.
- Enforce 200 lines.
- Count final lines after rendering.
- If over 200, truncate
## What changed this session oldest-first.
- Insert
<!-- WARNING: handoff exceeded 200 lines; oldest session changes were truncated. -->.
- 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:
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:
# Handoff — <project name>
**Last touched:** <ISO 8601 timestamp with timezone> · **branch:** `<branch>` · **HEAD:** `<short-sha>` · **session:** <model id>
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.pyuv run scripts/evaluate_package.py skills/handoffuv run skills/handoff/scripts/handoff.py --project-root <repo> --dry-runuv run skills/handoff/scripts/handoff.py --project-root <repo> --init --output <tmp-file>
1---2name: handoff3description: 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.4---56# Handoff78Maintains `.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.910## Reference Files1112| File | Contents | Load When |13| --- | --- | --- |14| `references/schema.md` | Verbatim handoff schema and line-budget rules | Always before writing |15| `references/authority-boundaries.md` | Boundary between handoff, memory, CLAUDE.md, plans, and git | Always before writing |1617## When To Use1819| Use handoff | Use another surface |20| --- | --- |21| In-flight work, uncommitted edits, current branch, blockers, resume steps | `git log` for committed history |22| Session-scoped decisions and failed approaches | Memory or ADRs for durable project facts |23| Immediate validation state and exact next command | `CLAUDE.md` for stable setup instructions |24| Current roadmap cursor | Plan files for strategic roadmap content |2526## Triggers2728- Direct commands: `/handoff`, `/handoff init`29- Refresh phrases: "update handoff", "session handoff", "refresh handoff", "save handoff"30- Resume phrases: "cold-start primer", "resume checklist", "handoff to next session"31- Stop hook: refresh silently when `.docs/handoff.md` already exists3233## Prerequisites3435- `git` available in the project root.36- Project write access for `.docs/handoff.md`.37- Optional project-local marker files:38 - `.docs/handoff.last-validation` containing the last verification command and result.39 - `.docs/handoff.session` containing extra bullets for changes, decisions, blockers, or refs.4041## Workflow42431. **Resolve mode.**44 - `/handoff init` or invocation from an initialization workflow writes a greenfield stub when `.docs/handoff.md` is absent.45 - `/handoff`, refresh phrases, and Stop-hook invocation rewrite the full file.462. **Read source of truth.**47 - Load `references/schema.md` and preserve the schema headings exactly.48 - Load `references/authority-boundaries.md` and include the authority boundary line in every generated handoff.493. **Detect repository state.**50 - Run `git rev-parse --show-toplevel`, `git branch --show-current`, `git rev-parse --short HEAD`, and `git status --porcelain`.51 - Count modified, untracked, and staged paths from porcelain status.52 - Include the top 3-5 changed paths in the Status section.534. **Detect validation state.**54 - Prefer recent session context: commands actually run in the current agent session and their result.55 - If available, read `.docs/handoff.last-validation`.56 - If neither exists, write explicit unknowns: "not recorded this session" rather than inventing pass/fail.575. **Gather session substance.**58 - Summarize logical changes from current conversation, uncommitted paths, and commits since the branch base when relevant.59 - Record decisions with rationale in two sentences or fewer.60 - Record blockers and open questions as actionable unchecked items.61 - Include failed approaches when they would prevent wasted work in the next session.626. **Write by full rewrite.**63 - Replace `.docs/handoff.md` atomically; do not append.64 - Create `.docs/` if absent.65 - Keep the file lowercase at `.docs/handoff.md`.667. **Enforce 200 lines.**67 - Count final lines after rendering.68 - If over 200, truncate `## What changed this session` oldest-first.69 - Insert `<!-- WARNING: handoff exceeded 200 lines; oldest session changes were truncated. -->`.70 - If still over 200, compress decisions and blockers to the newest actionable items, preserving all required headings.7172## Supported Operations7374| Operation | Command | Behavior |75| --- | --- | --- |76| Refresh | `/handoff` | Rewrites `.docs/handoff.md` from current repo and session state |77| Scaffold | `/handoff init` | Creates an empty schema stub when no handoff exists |78| Stop refresh | Stop hook | Refreshes only when `.docs/handoff.md` already exists |79| Dry run | `uv run skills/handoff/scripts/handoff.py --dry-run` | Prints generated content without writing |8081## Implementation Notes8283The bundled script is the deterministic baseline used by the command and hook:8485```bash86uv run skills/handoff/scripts/handoff.py --project-root "$PWD"87uv run skills/handoff/scripts/handoff.py --project-root "$PWD" --init88```8990Agents may improve populated bullets from live session context before writing, but must preserve:9192- Schema headings and order.93- Authority boundary line.94- Full-file rewrite semantics.95- Hard 200-line cap.96- Explicit unknowns instead of silent fallbacks.9798## Greenfield Scaffold99100When 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.101102## Output Format103104Write exactly one file: `.docs/handoff.md`.105106Required first lines:107108```markdown109# Handoff — <project name>110111**Last touched:** <ISO 8601 timestamp with timezone> · **branch:** `<branch>` · **HEAD:** `<short-sha>` · **session:** <model id>112```113114## Troubleshooting115116| Problem | Resolution |117| --- | --- |118| Not in a git repository | Fail clearly for refresh; scaffold may use branch `—` and HEAD `—` only during `/handoff init` |119| `.docs/` missing | Create it before writing |120| Validation state unavailable | Write "not recorded this session"; do not claim tests passed |121| Generated file exceeds 200 lines | Truncate oldest `What changed` bullets and add the warning comment |122| Existing handoff uses old casing or root path | Do not migrate automatically; future refreshes converge only when invoked in that project |123124## Verification125126- `uv run python scripts/validate_evals.py`127- `uv run scripts/evaluate_package.py skills/handoff`128- `uv run skills/handoff/scripts/handoff.py --project-root <repo> --dry-run`129- `uv run skills/handoff/scripts/handoff.py --project-root <repo> --init --output <tmp-file>`130
mathews-tom