Session Handoff

Create handoff documents that enable fresh agents to continue work seamlessly.

Mode Selection

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

→ Follow CREATE Workflow

Resuming from a handoff? User wants to continue previous work or load context.

→ Follow RESUME Workflow

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

> "Consider creating a handoff document to preserve this context. Say 'create handoff' when ready."

CREATE Workflow

Step 1: Generate Scaffold

Run the smart scaffold script:

python scripts/create_handoff.py [task-slug]

For continuation handoffs (linking to previous work):

python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

The script creates .claude/handoffs/ directory and generates a timestamped file with pre-filled metadata (timestamp, project path, git branch, recent commits, modified files).

Step 2: Complete the Document

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

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)

See references/handoff-template.md for full structure.

Step 3: Validate

python scripts/validate_handoff.py <handoff-file>

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 handoffs with secrets detected or score below 70.

Step 4: Confirm

Report to user:

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

RESUME Workflow

Step 1: Find Handoffs

python scripts/list_handoffs.py

Step 2: Check Staleness

python scripts/check_staleness.py <handoff-file>

Staleness levels:

• FRESH: Safe to resume
• SLIGHTLY_STALE: Review changes first
• STALE: Verify context carefully
• VERY_STALE: Consider creating fresh handoff

Step 3: Load and Verify

Read the handoff document completely. If part of a chain, also read the previous handoff.

Follow references/resume-checklist.md:

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

Step 4: Begin Work

Start with "Immediate Next Steps" item #1.

Reference as you work:

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

Handoff Chaining

For long-running projects, chain handoffs 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

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

Storage

Location: .claude/handoffs/

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

Quality Criteria

Good handoffs have:

• Zero ambiguity about current state
• Clear, numbered next steps
• Rationale for decisions (not just outcomes)
• File paths with line numbers where relevant
• No secrets or credentials

NEVER

• Include API keys, passwords, tokens, or credentials
• Leave TODO placeholders in finalized handoffs
• Skip the validation step
• Create handoffs without the Important Context section
• Finalize handoffs with quality score below 70