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 <!-- 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.