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:

python scripts/create_handoff.py [task-slug]

Example: python scripts/create_handoff.py implementing-user-auth

For continuation handoffs (linking to previous work):

python 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, 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
4. Decisions Made - Choices with rationale (not just outcomes)

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:

python 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
• Quality score (0-100)

Do not finalize a handoff with secrets detected or score below 70.

Step 4: Confirm Handoff

Report to user:

• Handoff file location
• Validation score and any warnings
• Summary of captured context
• First action item for next session

RESUME Workflow

Step 1: Find Available Handoffs

List handoffs in the current project:

python scripts/list_handoffs.py

This shows all handoffs with dates, titles, and completion status.

Step 2: Check Staleness

Before loading, check how current the handoff is:

python scripts/check_staleness.py <handoff-file>

Staleness levels:

• FRESH: Safe to resume - minimal changes since handoff
• SLIGHTLY_STALE: Review changes, then resume
• STALE: Verify context carefully before resuming
• VERY_STALE: Consider creating a fresh handoff

The script checks:

• Time since handoff was created
• Git commits since handoff
• Files changed since handoff
• Branch divergence
• Missing referenced files

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.

Step 4: Verify Context

Follow the checklist in references/resume-checklist.md:

1. Verify project directory and git branch match
2. Check if blockers have been resolved
3. Validate assumptions still hold
4. Review modified files for conflicts
5. Check environment state

Step 5: Begin Work

Start with "Immediate Next Steps" item #1 from the handoff document.

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

The scripts below require a Python 3.9+ interpreter. They exit with a clear error if invoked on an older version.

scripts/

Script	Purpose
create_handoff.py [slug] [--continues-from <file>]	Generate new handoff with smart scaffolding
list_handoffs.py [path]	List available handoffs in a project
validate_handoff.py <file>	Check completeness, quality, and security
check_staleness.py <file>	Assess if handoff context is still current

references/

• handoff-template.md - Complete template structure with guidance
• resume-checklist.md - Verification checklist for resuming agents
• setup.md - One-time host setup: recommended permissions and how to run the tests