Advanced Session Handoff

A practical skill for creating AI agent handoff documents — enabling seamless context transfer between sessions when an AI agent runs out of context window, needs to pause work, or when a fresh agent must continue a complex task with zero ambiguity.

When to Use This Skill

Choose Advanced Session Handoff when you need to:

• Save the current state of a long-running AI session before it hits context limits
• Create a handoff document for a fresh agent to continue your work
• Pause a complex multi-step task and resume it later
• Transfer context between different AI tools or platforms
• Document work progress for another person or agent to continue

Consider alternatives when:

• You need project documentation (use a documentation skill)
• You need meeting handoff notes (use a meeting notes skill)
• You need git commit messages (use a commit message skill)

Quick Start

Copy
# Create a session handoff document
claude "Create a handoff document for the current session. We've been refactoring the auth module from JWT to session-based auth. Files modified: auth.ts, middleware.ts, session-store.ts. Remaining: update tests, update API docs."

Copy
# Session Handoff Document
**Created**: 2024-12-15T14:30:00Z
**Task**: Auth Module Refactoring (JWT → Session-Based)
**Status**: In Progress (60% complete)

## Context
Migrating authentication from JWT tokens to server-side
sessions with Redis backing. Motivation: token revocation
requirements and reduced payload size.

## Completed Work
### Files Modified
1. `src/auth/auth.ts` (lines 15-89)
   - Removed JWT signing/verification
   - Added session creation with `express-session`
   - Session config: 24hr TTL, httpOnly, secure cookies

2. `src/middleware/auth-middleware.ts` (lines 1-45)
   - Changed from `verifyJWT()` to `req.session.userId`
   - Added session refresh on activity (sliding window)

3. `src/auth/session-store.ts` (NEW FILE)
   - Redis-backed session store using `connect-redis`
   - Config: redis://localhost:6379, prefix: "sess:"

## Remaining Work
### Must Complete
- [ ] Update `tests/auth.test.ts` — replace JWT mocks
      with session fixtures
- [ ] Update `tests/middleware.test.ts` — mock session
      store instead of JWT verification
- [ ] Update `docs/api/authentication.md` — document
      new cookie-based auth flow

### Nice to Have
- [ ] Add session listing endpoint for users
- [ ] Add "sign out all devices" functionality

## Key Decisions Made
1. Using Redis (not in-memory) for session store
   → Reason: multi-instance deployment requirement
2. 24-hour session TTL with sliding window
   → Reason: matches previous JWT expiry behavior
3. Cookie name: `app_session` (httpOnly, secure, sameSite=lax)

## Gotchas for Next Agent
- Redis must be running locally: `docker run -p 6379:6379 redis`
- The test suite expects `SESSION_SECRET` env var to be set
- Don't change the cookie name — frontend is already updated

Core Concepts

Handoff Document Sections

Section	Purpose	Priority
Context	Why this work exists	Required
Completed Work	What's been done with file references	Required
Remaining Work	What still needs to be done	Required
Key Decisions	Decisions made with rationale	Required
Gotchas	Non-obvious issues the next agent must know	Required
Architecture	System design context if relevant	If applicable
Dependencies	External requirements	If applicable

Handoff Quality Checklist

Copy
## Before Creating the Handoff, Verify:

### Completeness
- [ ] All modified files listed with line numbers
- [ ] Every remaining task is actionable (not vague)
- [ ] Key decisions include rationale (not just "we chose X")
- [ ] Known issues and workarounds documented

### Clarity
- [ ] A fresh agent can start working without questions
- [ ] File paths are absolute or relative to project root
- [ ] Code snippets include enough context to locate them
- [ ] Technical terms are used consistently

### Accuracy
- [ ] File changes match the actual current state
- [ ] Remaining tasks reflect what's actually left
- [ ] No completed items listed as remaining
- [ ] Environment setup instructions are verified

Mode Selection

Copy
## Handoff Mode Decision

### Creating a Handoff (Saving State)
Trigger: "Save session", "Create handoff", "Pause work"
Action: Analyze current session state and generate
a comprehensive handoff document covering all context
needed by the next agent.

### Resuming from Handoff (Loading State)
Trigger: "Continue from handoff", "Resume work",
followed by handoff document content.
Action: Read the handoff document, verify file states
match the documented state, then continue from the
remaining work list.

### Mid-Session Checkpoint
Trigger: Context window is getting large, or complex
task will span multiple sessions.
Action: Create a checkpoint document that captures
progress without ending the current session. Useful
for insurance against context window limits.

Configuration

Parameter	Description	Example
mode	Create handoff or resume from one	"create" / "resume"
detail_level	How much context to include	"full" / "summary"
include_code	Include code snippets in handoff	true
include_env	Include environment setup steps	true
format	Handoff document format	"markdown"

Best Practices

1. Include file paths with line numbers, not just file names — "Modified auth.ts" is vague when the file has 500 lines. "Modified src/auth/auth.ts lines 15-89: replaced JWT signing with session creation" tells the next agent exactly where to look.

2. Document decisions with rationale, not just outcomes — "Using Redis for sessions" doesn't explain why. "Using Redis because we need session persistence across multiple server instances" prevents the next agent from questioning or reversing the decision.

3. Mark remaining tasks with priority and dependencies — A flat to-do list doesn't indicate what to do first. Use priority markers (must/should/nice-to-have) and note dependencies: "Update tests before updating API docs, since docs should reference the test examples."

4. Include a gotchas section for non-obvious issues — Every project has landmines that aren't obvious from the code. "The test suite requires Redis running locally" or "Don't rename the cookie — the mobile app hardcodes it" saves the next agent from hours of debugging.

5. Verify the handoff document against actual file state — Before finalizing, spot-check that the files mentioned in the handoff actually exist and contain the changes described. A handoff that describes files that don't exist is worse than no handoff at all.

Common Issues

Handoff documents are too vague to be actionable — "Continue working on the auth refactor" gives the next agent nothing. Every remaining task should be specific enough that the agent can start coding without asking questions: "Update tests/auth.test.ts to replace the mockJWT() helper with createTestSession() from tests/helpers.ts."

Modified file state doesn't match the handoff description — The handoff says "auth.ts uses session-based auth" but the file still has JWT code because the changes weren't saved. Always verify that the actual file state matches what you document before creating the handoff.

Key context is assumed rather than stated — The creating agent assumes the receiving agent knows about the project structure, tech stack, or business requirements. Every handoff should include enough context that a completely fresh agent can understand the project without prior exposure.