t1k-handoff

name	t1k:handoff
description	Save and resume session context for handoffs between sessions or developers. Use for 'save session', 'hand off to', 'resume context', 'where did I leave off', 'context transfer'.
version	1.0.0
argument-hint	save|resume|list [date-slug]
effort	medium
origin	theonekit-core
repository	The1Studio/theonekit-core
module	null
protected	true

TheOneKit Handoff — Session Context Transfer

Capture structured session context for handoff between sessions or developers. Extends the session state system with a human-readable markdown export.

Usage

/t1k:handoff save                    # Save current session state as handoff doc
/t1k:handoff resume                  # Load latest handoff into context
/t1k:handoff list                    # Show available handoffs with timestamps
/t1k:handoff resume 260325-auth      # Load specific handoff by date-slug

Subcommands

Subcommand	Action
save	Capture current state to .claude/handoffs/{date}-{slug}.md
resume	Load latest handoff file, inject content as context
list	Show all handoffs with timestamps, sorted newest first
resume {date-slug}	Load a specific handoff by its date-slug identifier

Handoff Document Structure

Saved to .claude/handoffs/{date}-{slug}.md:

# Handoff — {date} {time}
Generated by: t1k:handoff save

## Active Plan
- Path: plans/{timestamp}-{slug}/
- Current phase: Phase N — {phase name}
- Phase status: {in_progress|blocked|pending}

## Progress
### Completed Tasks
- [x] Task description
- [x] Task description

### In Progress
- [ ] Task description (owner: {agent})

### Blocked
- [ ] Task description
  - Blocker: {reason}

## Key Decisions Made
- {architectural or design decision with context}
- {why X was chosen over Y}

## Blockers
- {blocker description} — context: {why it's blocked, what's needed to unblock}

## Next Steps
1. {highest priority action}
2. {second priority}
3. {third priority}

## Git State
- Branch: {branch name}
- Last commit: {hash} {message}
- Dirty files: {list or "none"}
- Uncommitted changes: {summary or "none"}

## Session Notes
{any freeform notes from the session worth preserving}

save Workflow

1. Read .claude/hooks/session-state-manager.cjs for current session state (if available)
2. Call TaskList to get current task statuses
3. Run git status --short and git log --oneline -3 for git state
4. Read active plan directory (most recent in plans/) and find in-progress phase
5. Synthesize key decisions from recent conversation (last N exchanges mentioning architecture, choice, decided, rejected)
6. Write to .claude/handoffs/{YYMMDD}-{slug}.md
7. Report: saved to {path}, summary of what was captured

Slug is auto-generated from the active plan name or current task, lowercased, max 30 chars.

resume Workflow

1. If no date-slug given: read .claude/handoffs/ directory, pick newest file by filename
2. Read the handoff markdown file
3. Output the full content as a context block prefixed with:

   [Handoff loaded: {filename}]
   Resuming session from {date}. Context:
   

4. Suggest the next step from "Next Steps" section
5. Check if the listed active plan still exists — warn if not found

list Workflow

Output newest-first table:

Available handoffs:

  260325-auth-implementation.md      (2 days ago)  Phase 3 — Auth API
  260323-database-schema.md          (4 days ago)  Phase 2 — DB Models
  260320-project-kickoff.md          (7 days ago)  Phase 1 — Setup

Use: /t1k:handoff resume 260325-auth-implementation

Auto-Cleanup

On each save, check for handoffs older than 30 days:

• Move them to .claude/handoffs/archive/
• Log: Archived N handoffs older than 30 days → .claude/handoffs/archive/

Do NOT delete — archive only.

.gitignore Note

.claude/handoffs/ is local state and should NOT be committed. Ensure .gitignore contains:

.claude/handoffs/

If not present, add it when save is first called.

Gotchas

• Session state dependency: save works best with the session-state-manager hook active (Phase 2 #8). Without it, git state and task list are still captured but session history context is shallower.
• Slug collisions: If two saves happen on the same day with the same plan, the second appends -2 suffix
• Large conversation history: Only synthesize decisions from last 20 AI turns — don't dump full history
• resume doesn't restore tool state: It provides context text only — the AI must re-read relevant files

Auto-Activation Keywords

Triggers on: handoff, hand off, transition, context transfer, session save, session resume, save progress, resume session, where did I leave off, switch sessions