mathews-tom/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>