session-handoff — Session State Persistence

This skill is mechanical: save state to .claude/memory/SESSION.md or load it back. Do not deliberate — no thinking needed on any step here.

Saves and loads session state between Claude Code sessions, useful when approaching usage limits and needing to continue work later.

When This Triggers

Save session:

• User says: "save session", "/save-session", "nearing limit", "running out of tokens"
• Or explicitly: "pause here", "save my work", "handoff"

Load session:

• Automatically at session start if SESSION.md exists with status: in-progress
• User says: "load session", "resume session", "continue where we left off"

Complete session:

• User says: "complete session", "session done"
• Or after all tasks are completed and working tree is clean

Session File Location

.claude/memory/SESSION.md

Save Session Action

When user triggers save:

1. Gather current state:
   • Run git status to check uncommitted changes
   • Run git diff --stat for summary
   • Call TaskList to get all tasks with status
   • Note current branch, recent commits

2. Write .claude/memory/SESSION.md:

   ---
   session-id: <uuid>
   created: <ISO-timestamp>
   last-updated: <ISO-timestamp>
   status: in-progress
   ---
   
   # Session Handoff
   
   **Session saved:** <date-time>
   **Branch:** <branch-name>
   **Recent commits:** <latest commit hash: message>
   
   ## What We Were Working On
   
   <High-level summary of current task>
   
   ## Current State
   
   ### Tasks
   
   <Capture from TaskList with checkboxes and status>
   - [ ] Task 1 (in_progress)
   - [x] Task 2 (completed)
   - [ ] Task 3 (pending)
   
   ### Decisions Made
   
   <List key decisions with rationale>
   - **Decision 1:** <what and why>
   - **Decision 2:** <what and why>
   
   ### Uncommitted Changes
   ```
   
   <git diff --stat output>
   
   ```
   
   ### Next Steps
   1. <First next step>
   2. <Second next step>
   
   ## Context Notes
   <Any additional context for resumption>

3. Return summary:

   Session saved to .claude/memory/SESSION.md
   Tasks: X total, Y in progress
   Uncommitted changes: <files modified>
   Resume: Next session will prompt to restore this session

Load Session Action

Triggered: At session start (if SESSION.md exists with status: in-progress)

1. Check for SESSION.md:
   • Read .claude/memory/SESSION.md
   • If missing or status: complete, skip load
2. Ask with one AskUserQuestion call — question: "Found a previous session from <date>: <one-line summary from SESSION.md>. What now?" — three options:
   • Resume session — restore tasks and context
   • Start fresh — archive the session and begin new
   • View full details — show the complete SESSION.md, then ask again
3. If user resumes:
   • Display "What We Were Working On" section
   • Display "Current State" (tasks, decisions, uncommitted changes)
   • Display "Next Steps"
   • Offer to restore task list via TaskCreate for each pending task
4. If user starts fresh:
   • Archive .claude/memory/SESSION.md to .claude/memory/SESSION.archive.<timestamp>.md
   • Remove active .claude/memory/SESSION.md
   • Confirm: "Previous session archived. Starting fresh."

Complete Session Action

When user triggers complete:

1. Verify completion:
   • Check git status — should be clean (no uncommitted changes)
   • Check TaskList — should have no in_progress tasks

2. Archive session:

   mv .claude/memory/SESSION.md .claude/memory/SESSION.archive.<timestamp>.md

3. Confirm:

   Session completed and archived
   Archived to: .claude/memory/SESSION.archive.<timestamp>.md
   Ready for new session

If not complete:

• Warn user: "Session has uncommitted changes or in-progress tasks. Complete those first, or say 'save session' to pause."

SESSION.md Structure

The session file uses YAML frontmatter for metadata and markdown for content:

---
session-id: uuid
created: ISO-8601 timestamp
last-updated: ISO-8601 timestamp
status: in-progress | complete
---

Content sections:

• What We Were Working On — high-level summary
• Current State — tasks, decisions, uncommitted changes
• Next Steps — what to do when resuming
• Context Notes — any additional context

Mid-workflow saves

When session-handoff is triggered partway through another multi-step skill (bigin-harness-setup, task-workflow, sprint-distill), no per-skill schema is needed — record the in-progress step in plain language under "Current State" (e.g. "bigin-harness-setup: Phase 4 of 8, CLAUDE.md and .claude/rules/ written, enforcement gates not yet generated"). On resume, the target skill re-derives its actual progress from what's already on disk (which files exist, PLAN.md's task table, etc.) rather than trusting a saved phase number — SESSION.md's job is pointing the user/agent back at where they left off, not being the source of truth for it.

Trigger Phrases

These are phrases, not slash commands — the plugin ships no commands/, so /load-session typed as a command is unknown. Typing /session-handoff invokes this skill directly.

Best Practices

1. Save before hitting limit — Don't wait until tokens are exhausted
2. Include decisions in Context Notes — Rationale is as important as outcome
3. Keep Next Steps actionable — Specific tasks, not vague goals
4. Complete sessions cleanly — Archive when done, don't leave stale sessions
5. Verify on resume — Check git branch and uncommitted changes match expectation