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.

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.py
• uv run scripts/evaluate_package.py skills/handoff
• uv run skills/handoff/scripts/handoff.py --project-root <repo> --dry-run
• uv run skills/handoff/scripts/handoff.py --project-root <repo> --init --output <tmp-file>