handoff
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.
- License 许可
- MIT
- 所属仓库
- open-gsd/gsd-pi
- 最近更新
- 2026-11-15
- Stars
- ★ 1.4k
- Forks
- 118
01 前言 Front Matter
- 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.
03 SKILL.md 正文
<objective>
Leave the project in a state where a fresh agent with no memory of this session can be productive within one minute. The deliverable is a Work Checkpoint saved with gsd_checkpoint_save plus up-to-date summary artifacts — not a chat recap.
</objective>
<context>
GSD already renders STATE.md (from the database, after every lifecycle tool call) and summary files (M###-SUMMARY.md, S##-SUMMARY.md, T##-SUMMARY.md). The gap is the mid-task handoff: you're partway through a task, context is getting long, and the next session shouldn't start by re-deriving your mental state.
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 </context>
<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>
<process>
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.
</process>
<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>
04 同仓库更多 Skills
write-milestone-brief
Synthesize the current conversation into a milestone brief (PRD). Saves it as the milestone CONTEXT (`gsd_summary_save`) by default, or files a GitHub issue only with explicit user confirmation. Use when asked to "turn this into a PRD", "draft a milestone brief", "capture this context", "write it up", or when enough has been discussed to commit the plan to paper. Does not interview — it synthesizes what is already known.
write-docs
Collaborative authoring workflow for proposals, technical specs, decision docs, READMEs, ADRs, and long-form prose that must work for fresh readers. Three stages: gather context, iterate on structure, reader-test for a stranger. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a doc must be understandable without this session's context.
web-quality-audit
Comprehensive web quality audit covering performance, accessibility, SEO, and best practices. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website".
web-design-guidelines
Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
verify-before-complete
Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.
userinterface-wiki
UI/UX best practices for web interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings.