handoff

name	handoff
version	1.1.0
description	Use when completing work in a worktree or ending a session - writes a structured memory transfer record so the next agent can continue without context loss; prevents duplicate work and cold-start ramp-up
triggers	["handoff","done working","finishing branch","leaving worktree","session ending","context transfer","shift change"]

Handoff — Agent Memory Transfer

Write a structured memory transfer record when finishing work. Inspired by Smith's iterative handoff protocol — append-only, sequenced, per-agent records stored in the project's shared coordination space.

Handoffs are NOT logs. They are memory transfers — the minimum context the next execution unit needs to reconstruct state without the model memory that created it.

When to Use This Skill

• Completing work on a feature branch or worktree
• Session is ending or context is about to compress
• Merging a branch and want to preserve context for follow-up work
• Handing off mid-task to another agent or future session
• Before running /pickup in a new session (someone must have handed off first)

When NOT to Use This Skill

• Mid-work coordination with parallel agents — use /signal instead
• Quick status checks — just read git log
• Work that is fully captured in commit messages — handoff adds nothing
• Trivial changes (typo fixes, formatting) — no context worth transferring

Shared Coordination Space

All handoff data lives in a shared location accessible to all worktrees:

{main-worktree}/.claude/handoff/
├── active/                    # Who's currently working (presence)
│   └── {agent-name}.json     # One file per active agent
├── journal/                   # Execution events (append-only)
│   └── {agent-name}/
│       └── 0001.md           # Sequenced, left-padded
├── handoffs/                  # Memory transfer records
│   └── {agent-name}/
│       └── 0001.md           # One per handoff, sequenced
└── HANDOFFS.md               # Global index of all handoffs

Finding the Shared Location

Agents may be in worktrees (isolated copies). The coordination space is ALWAYS in the main worktree:

# Get main worktree path (first line of output)
MAIN_WORKTREE=$(git worktree list --porcelain | head -1 | sed 's/worktree //')
HANDOFF_DIR="${MAIN_WORKTREE}/.claude/handoff"

Agent Identity

Your agent name is derived from your context:

• In a worktree: the worktree directory name (e.g., feat-auth-refactor)
• On main/branch directly: the branch name (e.g., main, fix-logging)
• Fallback: agent-$(date +%s) (timestamp-based unique ID)

# Detect agent name
if git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
  WORKTREE_PATH=$(git rev-parse --show-toplevel)
  MAIN_WORKTREE=$(git worktree list --porcelain | head -1 | sed 's/worktree //')
  if [ "$WORKTREE_PATH" != "$MAIN_WORKTREE" ]; then
    AGENT_NAME=$(basename "$WORKTREE_PATH")
  else
    AGENT_NAME=$(git branch --show-current)
  fi
fi

The 5 Steps (MANDATORY)

Step 1: Resolve Shared Location and Identity (REQUIRED)

Determine the main worktree path and your agent name using the commands above. Verify the handoff directory exists, create it if not:

mkdir -p "${HANDOFF_DIR}/active" "${HANDOFF_DIR}/journal/${AGENT_NAME}" "${HANDOFF_DIR}/handoffs/${AGENT_NAME}"

Gate: You know your agent name AND the absolute path to the shared handoff directory.

Step 2: Gather Context (REQUIRED)

Collect what you need for the handoff record:

1. Current SHA: git rev-parse HEAD
2. Branch name: git branch --show-current
3. Changed files since last handoff (or branch creation):
   • Read your last handoff file if one exists to get the previous SHA
   • Run git diff --name-only {previous-sha}..HEAD (or git diff --name-only $(git merge-base HEAD main)..HEAD if no prior handoff)
4. What you completed: Summarize from your session context — decisions made, code written, problems solved
5. What remains: Unfinished work, known issues, next steps
6. What you decided: Architectural or design choices that affect future work

Gate: You have a clear, factual list of done/remaining/decisions. No prose — structured data.

Step 3: Determine Sequence Number (REQUIRED)

Check existing handoffs for your agent to get the next sequence number:

# Find the highest existing sequence number
LAST=$(ls "${HANDOFF_DIR}/handoffs/${AGENT_NAME}/" 2>/dev/null | sort -n | tail -1 | sed 's/\.md//')
NEXT=$(printf "%04d" $(( ${LAST:-0} + 1 )))

Gate: You have a unique, sequential filename like 0001.md, 0002.md, etc.

Step 4: Write the Handoff Record (REQUIRED)

Write the handoff file to ${HANDOFF_DIR}/handoffs/${AGENT_NAME}/${NEXT}.md:

---
sequence: {N}
agent: {agent-name}
branch: {branch-name}
sha: {current-sha}
previous_sha: {sha-from-last-handoff-or-merge-base}
timestamp: {ISO-8601}
---

## Done
- {Completed item 1}
- {Completed item 2}

## Remaining
- {Unfinished item 1}
- {Unfinished item 2}

## Decisions
- {Decision 1}: {rationale}
- {Decision 2}: {rationale}

## Key Files
- {path/to/file1} — {what changed and why}
- {path/to/file2} — {what changed and why}

Keep it tight. Each item should be one line. No paragraphs. The next agent needs to parse this in under 100 tokens.

Gate: Handoff file is written and contains all four sections.

Step 5: Update Index and Cleanup (REQUIRED)

1. Append to HANDOFFS.md — add one line to the global index:

   - [{NEXT}] {agent-name} ({timestamp}) — {one-line summary of what was done}
   

   Create HANDOFFS.md if it doesn't exist, with a header: # Handoff Index

2. Write a journal entry — record this handoff event: Write to ${HANDOFF_DIR}/journal/${AGENT_NAME}/{NEXT}.md:

   ---
   type: handoff
   agent: {agent-name}
   timestamp: {ISO-8601}
   ---
   Handed off at {sha}. Done: {count} items. Remaining: {count} items.
   

3. Remove presence file (if one exists in active/):

   rm -f "${HANDOFF_DIR}/active/${AGENT_NAME}.json"
   

Gate: HANDOFFS.md is updated, journal entry written, presence cleaned up.

Red Flags - STOP

If you catch yourself:

• ❌ Writing paragraphs instead of bullet points — handoffs are structured data, not narratives
• ❌ Including implementation details that are in the code — the code IS the documentation, handoff covers what's NOT in the code
• ❌ Skipping the "Remaining" section — this is the most valuable part for the next agent
• ❌ Skipping the "Decisions" section — undocumented decisions get reversed
• ❌ Writing to a worktree-local .claude/handoff/ instead of the main worktree — other agents won't see it
• ❌ Using the SHA as the filename — SHAs are metadata, sequence numbers are the key

STOP. Go back to Step 2 and gather structured data.

Verification Checklist

Before considering the handoff complete:

• Handoff file exists at {main-worktree}/.claude/handoff/handoffs/{agent}/{NNNN}.md
• File has valid frontmatter with sequence, agent, branch, sha, timestamp
• Done section has at least one item
• Remaining section exists (even if empty — write "None" explicitly)
• Decisions section exists (even if empty — write "None" explicitly)
• Key Files section lists files that were modified
• HANDOFFS.md index has been updated
• Journal entry written
• Presence file removed (if it existed)

Handoff Record Format Reference

Frontmatter Fields

Field	Required	Description
sequence	Yes	Left-padded sequence number (0001, 0002, ...)
agent	Yes	Worktree name or branch name
branch	Yes	Git branch name
sha	Yes	Current HEAD SHA
previous_sha	Yes	SHA from last handoff or merge-base with main
timestamp	Yes	ISO-8601 timestamp

Body Sections

Section	Required	Purpose
Done	Yes	What was completed — the next agent doesn't need to do this
Remaining	Yes	What's unfinished — the next agent starts here
Decisions	Yes	Choices made that constrain future work
Key Files	Yes	Files touched with brief rationale

Best Practices

1. Write handoffs at natural boundaries — end of a feature, end of a session, before a merge. Not after every commit.
2. Decisions are the most durable section — code changes, remaining items get done, but decisions explain WHY the code looks the way it does.
3. Reference the previous handoff — previous_sha creates a chain. The pickup skill uses this to walk the history.
4. One handoff per agent per work session — don't write five handoffs in one sitting. Consolidate.
5. Keep Key Files to files YOU changed — not every file in the diff. The important ones with non-obvious changes.

Related Skills

• /pickup — The consumer of handoff records. Reads and synthesizes handoffs into a briefing.
• /signal — Mid-work coordination. Use for live signals; handoff is for completed work.
• /coordinate — Distributed coordination via the switchboard repo. Handoffs are the permanent record; coordinate is the live state.
• /repo-ingest — Updates the coordination protocol by learning from external repos like Smith.

After Using This Skill

MANDATORY NEXT STEPS:

• If merging: proceed with merge, the handoff record persists in the main worktree
• If ending session: the handoff IS your exit — no other cleanup needed

OPTIONAL NEXT STEPS:

• Run /pickup in a new session to verify your handoff reads cleanly
• Review HANDOFFS.md to see the full history of agent work
• If using distributed coordination: write a leave message in the switchboard before handoff

Changelog

v1.1.0 (2026-04-11)

• Added switchboard/coordinate integration references
• Clarified relationship: handoffs are permanent (project repo), coordination is ephemeral (switchboard repo)

v1.0.0 (2026-04-11)

• Initial skill creation
• Smith-inspired append-only sequenced handoff protocol
• Shared coordination space via main worktree
• Agent identity from worktree/branch name
• Four required sections: Done, Remaining, Decisions, Key Files
• Journal integration for audit trail
• HANDOFFS.md global index