From kc-hyperfocus
Use when user says 'handoff', 'prepare handoff', '準備交接', or when context pressure is high and work state needs preservation before session ends.
How this skill is triggered — by the user, by Claude, or both
Slash command
/kc-hyperfocus:kc-session-handoffThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Write a journal entry and produce a minimal resume prompt for the next session.
Write a journal entry and produce a minimal resume prompt for the next session.
Companion skill: kc-session-resume handles context restoration on the other side.
/gsd:pause-work insteadContext pressure (WARNING/CRITICAL) is the most common trigger. The skill is designed to work under tight context budgets. Steps 2.5 and 2.7 are conditional — skip them freely. Steps 1–3 and the confirmation block are never optional, regardless of remaining context.
pwd # current working directory
git branch --show-current 2>/dev/null || echo "(no git branch)"
git status --short 2>/dev/null || echo "(no git repo)"
git log --oneline -5 2>/dev/null
git rev-parse --show-toplevel 2>/dev/null
Non-git fallback: If git commands fail (workspace root, temp dir, non-repo), proceed with branch = "(no branch)". The journal and resume prompt still work — use the working directory and description as the primary identifiers instead.
Working directory: Record pwd output. This is critical for multi-directory workspaces where GSD, bun test, or other tools must run from a specific subdirectory (not the git root or workspace root). The resume skill restores this context so the next session starts in the right place.
Worktree detection — compare --show-toplevel against main worktree:
git worktree list
If --show-toplevel differs from the first line of worktree list → you are in a linked worktree. Record the path. If they match → main worktree, omit worktree field. If git worktree list fails → omit worktree field (assume main).
From conversation: completed work, decisions, remaining work, blockers, Linear issue (if any).
Load journal tools:
ToolSearch → "select:mcp__plugin_kc-hyperfocus_context-lake__process_thoughts,mcp__plugin_kc-hyperfocus_context-lake__list_recent_entries"
Call process_thoughts with these fields:
| Field | Content |
|---|---|
feelings | 1-2 honest sentences about your current state (mandatory) |
project_notes | Structured handoff using template below |
project_notes template — the Session Handoff: header is critical for searchability:
Session Handoff: {branch} — {short description}
Issue: {SC-xxx} (if any)
Working dir: {pwd output} (always include — critical for multi-dir workspaces)
Worktree: {path} (only if linked worktree, omit for main)
## Completed
- ...
## Remaining
- ...
## Decisions
- ...
## Key Files
- ...
Optionally add technical_insights if you discovered reusable patterns worth preserving.
project_notes minimum content — the entry MUST contain at least:
Session Handoff: header lineWorking dir: line## Completed or ## RemainingA journal entry with only the header and empty sections is vacuous — it tells the next session nothing. If you genuinely have nothing to report under Completed or Remaining, you are in a trivial session and should not be running this skill.
Immediately after writing, call list_recent_entries(limit: 1, type: "project") to capture the entry path. The tool returns entries with a Path: field like:
Path: /path/to/project/.private-journal/2026-03-06/02-35-35-040018.md
Extract the handoff ID — strip everything before .private-journal/ and the trailing .md to get 2026-03-06/02-35-35-040018. This ID is used in step 3.
If list_recent_entries returns no results (MCP failure, timing issue): retry once. If still empty, report the failure to the user — do NOT fabricate an ID or skip the resume prompt. The user needs to know the handoff is incomplete.
If the journal entry you just wrote includes technical_insights:
Read → ~/.claude/projects/{project}/memory/MEMORY.md
## Topic Name (YYYY-MM-DD)
One-sentence summary of the reusable pattern.
Rules:
If the context lake MCP server is available (check by attempting to call store_insight):
/tmp/claude-lake-touched-{session_id}.json — list of files Read during this session/tmp/claude-lake-explores-{session_id}.json — list of completed Explore dispatchesstore_insight calls in this session (the post-explore-nudge hook prompted you to cache during the session). If insights were already stored → skip those files.store_insight for each with source: "handoff"/tmp/claude-lake-touched-{session_id}.json, /tmp/claude-lake-explores-{session_id}.json)Skip conditions: Neither temp file exists, no files with meaningful analysis in this session, or MCP server not available.
Output a one-line prompt the user copies into the next session. Include the handoff ID from step 2 so the resume skill can do a direct O(1) lookup instead of searching:
resume {handoff-id} 繼續 {branch} 的 {description}
If in a linked worktree, append the worktree path:
resume {handoff-id} 繼續 {branch} 的 {description} (worktree: {path})
Example: resume 2026-03-06/02-35-35-040018 繼續 feature/sc-571 的租戶切換問題
Example (worktree): resume 2026-03-06/02-35-35-040018 繼續 feature/sc-571 的租戶切換問題 (worktree: /path/to/project-wt-sc-571)
Handoff complete:
- Handoff ID: {handoff-id}
- Journal: project_notes with "Session Handoff: {branch}"
- MEMORY.md: {+N insights captured / no new insights}
- Branch: {branch}
- Working dir: {pwd}
- Worktree: {path} (or "main" if not in a linked worktree)
Resume prompt:
───────────────────
resume {handoff-id} 繼續 {branch} 的 {description}
───────────────────
Estimate the journal entry size: count the characters in project_notes you wrote in step 2, divide by 4 to get approximate tokens.
Call get_metrics with:
event: "handoff"event_details: { entryTokens: <estimated_tokens> }Silent — no output needed.
| Evidence | Required |
|---|---|
Journal written with Session Handoff: header | ✅ |
list_recent_entries called, handoff ID extracted | ✅ |
| Resume prompt with handoff ID output to user | ✅ |
| Confirmation block output | ✅ |
get_metrics(event: "handoff") called | ✅ |
Any missing row = incomplete handoff. The user cannot resume without the handoff ID. Writing journal alone is NOT a handoff — it's just a journal entry.
process_thoughts directly without invoking this skilllist_recent_entries because "context is low"/kc-session-resume to find it" instead of providing the IDlist_recent_entries — the ID MUST come from the journal tool's returned Path: fieldSession Handoff: header but empty Completed/Remaining sectionsAll of these produce a handoff without resume ID → the user must manually search before resuming.
npx claudepluginhub iamcxa/kc-claude-plugins --plugin kc-hyperfocusCreates structured handoff documents that capture session state, active goals, and artifact context for seamless continuation. Useful before clearing context or at end of session.
Captures full session context into a handoff document so a fresh agent can resume work with zero prior context. Write a single actionable sentence for the next agent.
Generates a passoff package (session summary, PROGRESS/CLAUDE/memory updates, commit, next-session prompt) for clean handoffs to future-you or a coworker brief mode.