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:
- Current State Summary - What's happening right now
- Important Context - Critical info the next agent MUST know
- Immediate Next Steps - Clear, actionable first steps
- 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:
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:
- Verify project directory and git branch match
- Check if blockers have been resolved
- Validate assumptions still hold
- Review modified files for conflicts
- 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
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
