---

name: session-handoff model: standard description: | WHAT: Create comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves long-running agent context exhaustion problem.

WHEN: (1) User requests handoff/memory/context save, (2) Context window approaches capacity, (3) Major task milestone completed, (4) Work session ending, (5) Resuming work with existing handoff.

KEYWORDS: "save state", "create handoff", "context is full", "I need to pause", "resume from", "continue where we left off", "load handoff", "save progress", "session transfer", "hand off"

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