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 plus a per-invocation uniqueness suffix (timestamp + PID) so two concurrent handoffs — including two default-argument invocations from different chats — can never overwrite each other:

SLUG=$(echo "${ARGUMENTS:-session}" | tr '[:upper:] ' '[:lower:]-' | tr -cd 'a-z0-9-' | cut -c1-40)
OUT="${TMPDIR:-/tmp}/groundwork-handoff-${SLUG}-$(date +%Y%m%d%H%M%S)-$$.md"

The document has exactly these sections:

3. Redact before writing

Strip secrets, API keys, tokens, credentials, and PII from every section. Replace with [REDACTED]. Never echo a .env value or auth header into the file.

4. Report the path

Print the absolute temp path so the user can hand it off. Do not move it into the workspace.

Rationalizations

Red Flags

• The document file lives anywhere under the repository or worktree
• A PRD, plan, ADR, or diff is pasted in full instead of linked
• An API key, token, password, or PII appears in the text
• No "Suggested skills" section / no [[using-groundwork]] pointer

Verification

• Document exists at a ${TMPDIR:-/tmp}/... path, not inside the repo or any worktree
• Summary is tailored to the next objective (and to [focus] when given)
• State, Next objective, Artifacts, and Suggested skills sections all present
• Artifacts are links/paths/URLs — no copied source, plan, or diff bodies
• Secrets, tokens, and PII redacted
• Suggested skills names concrete skills and points at [[using-groundwork]]
• Absolute path reported to the user