Context Handoff

Writes a structured session handoff to docs/superpowers/handoff.md in the project repo. Use this before /clear or /compact to capture where you left off in a way that's both human-readable and machine-parseable.

Not the same as /context-save: /context-save (gstack) stores machine-local session state in ~/.gstack/projects/ and is restored by /context-restore. This skill writes a Markdown file directly into the repo — readable by anyone, on any machine, without gstack installed. The YAML frontmatter lets the SessionStart hook pick up structured fields (active task, next step, env) without prose-parsing.

When this skill activates

• User says "context getting long", "about to clear", "save before clear"
• CLAUDE.md sensor triggers after /compact (user opts in to continuous handoff)
• User explicitly invokes /context-handoff

Save state

1. Create docs/superpowers/ directory if it doesn't exist.

2. Write handoff file at docs/superpowers/handoff.md (overwrite if exists). Use this YAML+prose hybrid:

   ---
   type: handoff
   session_end: {ISO-8601 with timezone, e.g. 2026-05-14T16:30:00+02:00}
   branch: {current git branch, or "n/a" if not a repo}
   commit_at_handoff: {short SHA of HEAD, or "n/a"}
   mode: {manual | continuous}
   
   active_task: {feature-slug-N, e.g. auth-rewrite-3}
   status: {in_progress | blocked | ready_to_review | done}
   completed: [task-id-1, task-id-2]
   remaining: [task-id-4, task-id-5]
   
   files_in_flight:
     - {path/to/file.ts}
   
   env:
     venv: {.venv | n/a}
     dev_server: {"npm run dev (port 3000)" | n/a}
     test_cmd: {"npm test -- auth" | n/a}
   
   next_step: {one concrete sentence — file:line + verb. E.g. "Read session.ts:45-78, decide if refresh-flow goes in middleware or hook"}
   ---
   
   # Session Handoff — {YYYY-MM-DD HH:MM}
   
   ## What I was doing
   {1-2 sentence summary of current task}
   
   ## Key decisions made this session
   - {decision 1}
   - {decision 2}
   
   ## Files modified this session
   - {path} — {1-line description of change}
   
   ## Plan progress
   {If a Superpowers plan exists in docs/superpowers/plans/: list completed vs remaining tasks. Otherwise: "No active plan."}
   
   ## Open questions / blockers
   - {anything unresolved, or "None"}
   

3. Tell the user: "State saved. You can /clear now — I'll pick up automatically."

STOP HERE. Do not continue or suggest next steps.

Task ID convention

Use <feature-slug>-<n> where <feature-slug> is a stable kebab-case identifier for the feature/initiative and <n> is a sequence number. Examples: auth-rewrite-3, pdf-export-1, bug-double-charge-2.

• IDs are stable — once assigned, never renumber. Even if task 2 is deleted, do not shift task 3 down to 2.
• IDs are grep-able — including the feature-slug means grep auth-rewrite- finds all related tasks across handoff history, plan files, and commit messages.
• One feature-slug per coherent unit of work. New unrelated work gets a new slug.

YAML field rules

• type: handoff MUST be the first field — it is the type discriminator the session-start reader keys on.
• mode: takes manual or continuous. Older spellings of continuous are no longer read; a file carrying one is treated as manual and rewritten correctly on the next write.
• Never blank a continuous handoff. The read-and-clear step in CLAUDE.md's Session Continuity section clears handoff.md after presenting the summary. Clearing a continuous handoff to an empty string destroys the mode value the post-compact check reads one step later, so the project re-asks the opt-in question forever. When mode is continuous, "clear" means rewrite the file with type: handoff + mode: continuous and nothing else.
• continuous is not Claude Code's auto permission mode. This field has nothing to do with permissions — never change a permission mode because a handoff file says continuous.
• next_step MUST be one sentence with a concrete verb and (where possible) a file:line anchor. "Continue work on auth" is not acceptable; "Read src/auth/session.ts:45-78, decide middleware vs hook for refresh flow" is.
• completed and remaining arrays may be empty ([]) but must be present.
• env keys may be n/a for languages/projects that don't need them, but the env: block must be present.

Continuous handoff mode (activated after compact)

When the user opts in to continuous handoff after a compact trigger:

1. Set mode: continuous in YAML immediately. The YAML value is what tells the CLAUDE.md sensor not to re-ask after subsequent compacts.

2. Update handoff.md after each significant milestone — completing a task, making a key decision, finishing a file. Don't update on every small change. Always preserve mode: continuous when updating.

3. Suggest /clear proactively when you're about to start a new major task that would benefit from fresh context, or when the session has been through multiple large operations since last compact/clear.

   Say: "Context is getting heavy. handoff.md is up to date — safe to /clear."

4. Do NOT ask repeatedly. Suggest /clear once. If the user continues, respect that and keep working. You may suggest again only if another compact happens.

Files that are not handoffs

A handoff.md is a handoff only when its frontmatter carries type: handoff. A file at that path without that field is NOT assumed to be a handoff: at least one project used the path for permanent notes, and an automatic reader that consumed and cleared it destroyed them. So:

• On the automatic read path (the Session Continuity rule in CLAUDE.md): do not present it, do not clear it. Say in one line that the file holds unrecognized content.
• When the user explicitly invokes this skill to save state: writing is what they asked for, so write — but if the existing file has unrecognized content, say what you are replacing in one line first. Overwriting on request is fine; overwriting silently is not.

Resume is automatic

Resume is NOT part of this skill. It's handled by a CLAUDE.md instruction that runs on every session start and after compact. See the "Session continuity" section in CLAUDE.md.