session-handoff

Handoff

Creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves the long-running agent context exhaustion problem.

Mode Selection

Determine which mode applies:

Creating a handoff? User wants to save current state, pause work, or context is getting full.

• Follow: CREATE Workflow below

Resuming from a handoff? User wants to continue previous work, load context, or mentions an existing handoff.

• Follow: RESUME Workflow below

Proactive suggestion? After substantial work (5+ file edits, complex debugging, major decisions), suggest:

"We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."

CREATE Workflow

Step 1: Generate Scaffold

Run the smart scaffold script to create a pre-filled handoff document:

python3 ~/.agents/skills/session-handoff/scripts/create_handoff.py [task-slug] --model <your model ID>

Example: python3 ~/.agents/skills/session-handoff/scripts/create_handoff.py implementing-user-auth --model claude-opus-5-5

Pass --model with the model ID you run as: no CLI puts it in the environment. Without it, the Model line stays a [TODO] and the validator blocks.

Run it from the target project directory: the scaffold reads the project path, git branch, and recent commits from the current working directory.

For continuation handoffs (linking to previous work):

python3 ~/.agents/skills/session-handoff/scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

The script will:

• Create .claude/handoffs/ directory if needed
• Generate timestamped filename
• Pre-fill: timestamp, writer (CLI and session id), model, host name, project path, git branch, recent commits, modified files
• Add handoff chain links if continuing from previous
• Output file path for editing

Step 2: Complete the Handoff Document

Open the generated file and fill in all [TODO: ...] sections. Prioritize these sections:

1. Current State Summary - What's happening right now
2. Important Context - Critical info the next agent MUST know
3. Immediate Next Steps - Clear, actionable first steps. Each item names its Source: a user quote or a user-reviewed work record. A user quote is the user's verbatim words with a date; a filled Q-n ans: counts. A user-reviewed work record is an artifact page or spec the user reviewed. A handoff or an agent note is not one. Put your own ideas under "Agent Proposals (not requested)".
4. Decisions Made - Choices with rationale (not just outcomes)
5. Mistakes and Corrections - Wrong turns and user corrections, with evidence; a rule proposal goes to ~/.agents/retro-inbox/pending/ and only its file name goes here

Use the template structure in references/handoff-template.md for guidance.

Step 3: Validate the Handoff

Run the validation script to check completeness and security:

python3 ~/.agents/skills/session-handoff/scripts/validate_handoff.py <handoff-file>

The validator checks:

• No [TODO: ...] placeholders remaining
• Required sections present and populated
• No potential secrets detected (API keys, passwords, tokens)
• Referenced files exist

Do not finalize a handoff while the validator reports BLOCKED. It blocks on secrets, remaining [TODO: ...] placeholders, or missing required sections, and exits nonzero. Everything else is a warning.

Step 4: Confirm Handoff

Report to user:

• Handoff file location
• Validation verdict (READY / BLOCKED) and any warnings
• Summary of captured context
• First action item for next session

RESUME Workflow

Step 1: Find Recent Handoffs

Several sessions can work in one repo at the same time, so the newest file may belong to another session. List the recent ones, not only the newest:

ls -lt .claude/handoffs/*.md | head -10              # newest first
grep -H -E '^- (Written by|Session|CLI|Model|Host):' .claude/handoffs/*.md   # writer: manual and compact handoffs

Read every handoff from the last two days whose task or files overlap yours. Also read the handoff named by the user or linked by the task's handoff chain, even if it is older. Select the handoff for your task by its task, files, and chain links. Written by: and compact-<session id>.md identify the writer, which may be a previous session. Do not treat a different writer as proof of concurrent work. A missing or UNCONFIRMED writer means the writer is unknown.

Step 2: Check Staleness

Compare the handoff's own header (timestamp, branch, commit) against the repo now:

git log --oneline -- .            # commits since the handoff was written
git status --short                # uncommitted drift
git branch --show-current         # still the branch the handoff names?

A handoff written on another branch, or behind many commits, is a lead rather than a fact: re-verify anything it asserts before acting on it.

Step 3: Load the Handoff

Read the relevant handoff document completely before taking any action.

If handoff is part of a chain (has "Continues from" link), also read the linked previous handoff for full context.

Read in full every user-reviewed work record the handoff names, in any section. Do not check it by keyword search alone.

Step 4: Verify Context

Before you state scope or act on the handoff:

1. Project directory and git branch match what the handoff names.
2. Listed blockers are still blockers (they may have been resolved since). Read every Q-n and its ans: first: a filled ans: not yet acted on is an instruction to carry into this session verbatim; an empty ans: or the Suggested value is not approval.
3. Stated assumptions still hold — check the ones the next step depends on.
4. Modified files have no conflicting work on top of them.
5. Check every Immediate Next Step against its Source. Read the Source and confirm it supports the listed action. An item with no Source is a proposal. An item whose Source you cannot check is UNCONFIRMED. Never present a proposal, an UNCONFIRMED item, or your own new idea as the user's scope. A user quote beats a user-reviewed work record. Between user quotes, the later one wins. An agent-written item never overrides a Source. Report the conflict and correct the handoff before you state scope or act.

Step 5: Begin Work

Before "Immediate Next Steps" item #1, check the run's latest human corrections and authorization.

Reference these sections as you work:

• "Critical Files" for important locations
• "Key Patterns Discovered" for conventions to follow
• "Potential Gotchas" to avoid known issues

Step 6: Update or Chain Handoffs

As you work:

• Mark completed items in "Pending Work"
• Add new discoveries to relevant sections
• For long sessions: create a new handoff with --continues-from to chain them

Handoff Chaining

For long-running projects, chain handoffs together to maintain context lineage:

handoff-1.md (initial work)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

Each handoff in the chain:

• Links to its predecessor
• Can mark older handoffs as superseded
• Provides context breadcrumbs for new agents

When resuming from a chain, read the most recent handoff first, then reference predecessors as needed.

Storage Location

Handoffs are stored in: .claude/handoffs/

Naming convention: YYYY-MM-DD-HHMMSS-[slug].md

Example: 2024-01-15-143022-implementing-auth.md

Resources

scripts/

Script	Purpose
create_handoff.py [slug] [--continues-from <file>]	Generate new handoff with smart scaffolding
validate_handoff.py <file>	Check completeness, quality, and security

Listing and staleness need no script — see the RESUME workflow above.

references/

• handoff-template.md - Complete template structure with guidance