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

When To Use

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.

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

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

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

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

1. Write by full rewrite.

- Replace .docs/handoff.md atomically; do not append. - Create .docs/ if absent. - Keep the file lowercase at .docs/handoff.md.

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

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

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>