handoff
GitHub用于在长会话或上下文耗尽前保存工作检查点，确保下一代理能无缝接续。通过数据库存储状态而非临时文件，提升跨会话协作效率。
Trigger Scenarios
Install
npx skills add open-gsd/gsd-pi --skill handoff -g -y
SKILL.md
Frontmatter
{
"name": "handoff",
"description": "Prepare a clean cross-session handoff so the next agent can pick up where you left off. Saves a focused Work Checkpoint with `gsd_checkpoint_save` and ensures summary artifacts are current. Use when asked to \"hand off\", \"prepare handoff\", \"pause work\", \"bookmark this\", \"I'll come back to this later\", before running out of context budget, or ending a long session with unfinished work."
}
The Work Checkpoint exists for exactly this. It is a database row. The next session of the task gets it as the "Resume State" section of its prompt, and /gsd offers "Resume" instead of "Execute" for a task that has one. CONTINUE.md in the slice directory is rendered from the row for people to read; it is never read back. Do not write continue.md, CONTINUE.md or HANDOFF.md yourself.
Invocation points:
- User says "pause", "hand off", "I'll come back later", "this is a good stopping point"
- Context usage nearing budget — better to hand off cleanly than truncate mid-thought
- Before a risky operation (dependency upgrade, major refactor) where you want a known-good checkpoint
- End of a long session, multi-day work
<core_principle>
WRITE FOR A STRANGER. The next reader is not you. They do not have this conversation. They have the project snapshot (gsd_project_snapshot), the checkpoint, the last summary, and the code. That has to be enough.
CURRENT STATE ONLY. The checkpoint says "pick up HERE." It is not a log of what you did; that goes in summaries. It is not a plan for future work; that lives in the plan files.
NO SECRETS, NO STALE PATHS. Do not inline env values, tokens, or paths that only exist in your working directory. Cite artifacts by relative path from the project root. </core_principle>
Step 1: Identify what's in flight
Answer briefly:
- What task (
T##) am I on? What's its current plan file? - What have I completed since the last summary?
- What's the next concrete action? (Not a goal — an action: "Run X. If Y, do Z.")
- What, if anything, is blocking or uncertain?
Step 2: Update the summaries, not the handoff
Before saving the checkpoint:
- Any task that's actually done? Use
gsd_task_complete(or the equivalent tool) to toggle state. Do NOT edit checkboxes by hand. This triggersSTATE.mdrebuild andT##-SUMMARY.mdgeneration. - Any slice-level decisions worth preserving? Save them with
gsd_decision_save. - Any patterns or traps future agents should know about? Record each one with
capture_thought.
This shrinks what the checkpoint has to carry.
Step 3: Save the checkpoint
Call gsd_checkpoint_save with the fields below. Keep it tight — one screenful max.
milestoneId,sliceId,taskId— the unit in flight. PasstaskIdwhen a task is in progress; without it the next session of the task does not get the checkpoint.kind—handoff.confirmedContext— the last action, with evidence, and why the next step follows. Example: "Rannpm testafter editingsrc/auth/session.ts; 2 failures insession.test.ts— both complain about a missingexpiresAtfield in the mock fixture. The session refactor movedexpiresAtfrom optional to required inSession; fixtures were never updated."nextAction— one concrete action the next agent should take. Example: "Updatefixtures/sessions.tsto includeexpiresAt: Date.now() + 3600_000on every fixture, then re-runnpm test."unresolved— open threads you noticed but deliberately didn't act on, and traps the next agent might stumble into. Example: "Validator insrc/auth/validator.tsstill accepts unbounded session lengths — file as a separate issue after T03 lands. Do NOT revert theSessioninterface change — it's required for T04. Do NOT runnpm run db:resetin this branch; dev data is still needed for manual UAT."evidence— optional: commands, files and results that support the confirmed context. List modified, uncommitted files here.
Step 4: Sanity check
Call gsd_project_snapshot, then read the checkpoint you saved + the most recent summary as if you were a fresh agent. Ask:
- Do I know what to do next?
- Do I know why?
- Do I know what not to do?
If any answer is no, the handoff is incomplete. Save a new checkpoint; the newest one is the resume state.
Step 5: Stop cleanly
- Do not leave in-flight
async_bashorbg_shelljobs. Cancel or wait for them. - Do not leave uncommitted changes without flagging them in the checkpoint — note which files are modified and why.
- Do not push mid-task commits to remote unless that was the plan — they create noise for reviewers.
<anti_patterns>
- Chat-log handoffs. "First I did X, then Y, then Z…" The next agent doesn't need the journey.
- A checkpoint that summarizes the whole slice. That's what
S##-SUMMARY.mdis for, at slice completion. - No
nextAction. A handoff without a concrete next action is a journal entry. - Implicit assumptions. "Obviously the next thing is…" — write it down.
- Leaving background processes running. They'll be orphaned when the session ends.
- Handoff without updating summaries. The checkpoint should be thin because the summaries carry the weight.
- Writing
continue.mdorHANDOFF.mdby hand. Nothing reads those files; only the checkpoint row selects the resume path.
</anti_patterns>
<success_criteria>
-
gsd_checkpoint_savesucceeded for the unit in flight. - The
nextActionis concrete and executable without this session's context. - Completed tasks were marked done via
gsd_*tools, not by hand-edited checkboxes. - Anything notable that was learned is saved with
capture_thoughtorgsd_decision_save. - Background processes are not orphaned.
- A cold-read of the project snapshot + the checkpoint + latest summary would produce the right next action.
</success_criteria>
Version History
-
5fd73d3
Current 2026-10-18 17:18
将交接机制从文件系统(CONTINUE.md)迁移至数据库行(gsd_checkpoint_save)，/gsd resume-work直接读取数据库头记录，移除旧的文件读写逻辑。
- 1131ba3 2026-08-27 09:07
