handoff

Handoff

Overview

A handoff is a baton, not a backpack: it carries just enough for the next session to resume, and points at everything else. The receiving agent has none of this conversation's context, so the document is the entire transfer — but it must stay compact, or it competes for the very context budget it is meant to preserve.

Core principle: Reference artifacts by path or URL; never duplicate their content into the handoff.

When to Use

• Ending a session with work still in progress
• Handing a task to another agent or person
• Approaching context compaction and wanting a durable resume point

The optional [focus] argument shapes the summary toward the next objective (e.g. /groundwork:handoff finish the auth refactor). Without it, summarize toward the most recent active thread.

Process

1. Locate work products

Gather what already exists rather than restating it. Run as needed:

git rev-parse --abbrev-ref HEAD          # current branch
git log --oneline -5                     # recent commits
git status --short                       # uncommitted changes
git diff --stat                          # scope of working-tree changes

Note paths to PRDs, plans (.groundwork-plans/), ADRs, specs, and any issue/PR URLs. These become links, not content.

2. Compose the document

Write to a temp path outside the repo, slug derived from the focus:

SLUG=$(echo "${ARGUMENTS:-session}" | tr '[:upper:] ' '[:lower:]-' | tr -cd 'a-z0-9-' | cut -c1-40)
OUT="${TMPDIR:-/tmp}/groundwork-handoff-${SLUG}.md"

The document has exactly these sections:

Section	Contents
Summary	Focused recap of the conversation, tailored to the next objective. Decisions made and why; dead ends ruled out.
State	What is done, what is in progress, what is blocked. Branch and commit refs.
Next objective	The single thing the receiving session should accomplish next.
Artifacts	Bulleted links — paths, branch names, commit SHAs, diffs, issue/PR URLs. References only.
Suggested skills	Which Groundwork skills to invoke next, and a pointer to [[using-groundwork]] to map any remaining work.