/handoff

name: handoff
description: '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.'
metadata:
  version: 0.1.0
  category: development
  tags: [session-continuity, runbook, context]
  difficulty: intermediate
  phase: ship

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 `<!-- 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 be