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