| name | session-handoff |
| description | A human-invoked utility that writes a grounded session-handoff document (plus a continuation pointer memory) so a fresh agent can resume in-progress work. Not auto-invoked; a human runs it deliberately. |
| disable-model-invocation | true |
Session Handoff
Write a grounded handoff document — and a one-line continuation memory — so a fresh
session can resume exactly where this one left off.
Announce at start: "I'm using the session-handoff skill to write a session handoff."
Human-invoked only. A human fires this skill directly (slash command or explicit
ask) — before /clear, /compact, a context limit, or a teammate handoff. It stays
off every agent-trigger surface by design.
When a human uses this
- Before
/clear or /compact, mid-task, when context is about to be lost.
- End of a working session, to seed the next one.
- Handing work to a teammate or another agent.
Optional argument: a short description of what the next session will focus on — used to
tailor Work In Progress / Loose Threads / Suggested Skills.
Pipeline
- Gather (read-only, run the commands — do not recall):
git status -sb, git log --oneline -15, git diff --stat, branch + ahead/behind;
bd ready, bd blocked, bd count --by-status, in-progress beads; list the
spec, plan, and architecture-decision-record files touched this session.
Done when: every listed command has run and its output is captured.
- Synthesize into the bundled template (
handoff-template.md). Reference
artifacts by path — never paste their bodies (commits, ADRs, specs, plans, diffs).
Duplicating bloats the doc and goes stale.
Done when: every section maps to a captured fact, referenced by path.
- Write the doc — Default:
.internal/handoff/YYYY-MM-DD[-HHMMSS]-<topic>-handoff.md
(-HHMMSS only if a same-day handoff exists).
(The same-day check globs the inbox .internal/handoff/*.md only; archived docs under archive/ are out of scope and do not affect same-day naming.)
If the human names another location,
write there. mkdir -p the target first.
Done when: the doc exists at the target path.
- Write the continuation memory —
bd remember "continuation-<date>-<topic>: <one-line pointer to doc path + headline state>"
(episodic continuation record; one-line pointer only).
Done when: bd remember has run for the continuation key.
- Verification (externally anchored — output the result block):
- Cross-check each state line against the captured Phase-1 command output.
- Gitignore safety:
git check-ignore <output-path>; if NOT ignored, warn the
human ("⚠️ is not gitignored; a handoff can contain sensitive session
state") and offer to add it to .gitignore before writing.
ls <path> confirms the doc exists; bd memories <key> confirms the memory.- Secret-scan grep over the doc (
sk-, ghp_, AKIA, -----BEGIN,
password=) — a backstop, not a guarantee.
- The narrative synthesis is the author's recollection — not externally verified;
that is why it references artifacts by path.
Done when: the confirmation block is output — doc path · memory key ·
gitignore-safety result · secret-scan result.
Doctrine
- Redact secrets (keys, tokens, passwords, PII) — the doc lands on disk and may be
shared. This is a hard rule; never weaken it.
- Reference, don't duplicate — point at commits/ADRs/specs by path.
- Ground every fact — run the gather commands; never invent state. If a command
fails (not a git repo,
bd absent), degrade gracefully and note the gap.
Red Flags (low-independence backstop — not the primary guard)
| Rationalization | Reality |
|---|
| "I'll write it from memory" | Run the gather commands — recollection drifts. |
| "I'll add it to the skill index so the agent finds it" | Forbidden — human-invoked only. |
| "The output dir is probably gitignored" | Run git check-ignore — secrets to a tracked path is a leak. |
Integration
Standalone. Human-invoked only, with no skill, hook, or agent-routing surface
pointing to it. Read-side counterpart: getting-up-to-speed reads the latest
.internal/handoff/ doc (no skill-to-skill call) and archives it to
.internal/handoff/archive/ on close — .internal/handoff/ is an unread inbox, so a
stale doc is never re-read as the last session.
