--- name: handoff description: Run end-of-session checklist and generate the next session handoff document disable-model-invocation: true argument-hint: "[notes]" --- # Session Handoff You are wrapping up a work session. Your job is to run the verification checklist, sync project state, and write a handoff document so the next session can cold-start with full context. ## Adaptability The handoff structure below is guidance. When the project doesn't fit — no GitHub, no MAP plan, unusual workflow — adapt the sections and tell the user what you're changing: > "This project doesn't use milestones, so I'll drop the milestone table and > track priorities as a simple ordered list instead." > "No MAP phases here — I'll structure 'what to build next' around the open > GitHub issues instead." The goal is a handoff that's actually useful for cold-starting the next session, not one that rigidly matches a template. ## Usage If `$ARGUMENTS` is "help" or "?", show this and stop: ``` /handoff [notes] Wrap up a session. Runs the verification checklist, syncs GitHub issues, and generates the next session handoff document. Examples: /handoff Standard wrap-up /handoff "had to skip Phase 3 testing" Add notes to the handoff /handoff "discovered a GC bug, see #42" Note new issues Part of the /map → /goon → /handoff workflow: /map Plan the work and bootstrap the project /goon Resume a session from the latest handoff /handoff Wrap up a session (you are here) Requires .claude/map/*/goon.yaml — run /map first to bootstrap. Can also bootstrap from scratch if no map exists yet. ``` ## 1. Load project config Glob for `.claude/map/*/goon.yaml` to find all map configurations. - **No results**: Ask the user: > "No map found in `.claude/map/`. I can either: > 1. Run a quick project scan and generate one now (lighter than /map) > 2. You run `/map` first for the full planning workflow > > Which do you prefer?" If they choose option 1, ask for a short slug for the feature (e.g., `initial-setup`), create `.claude/map/{slug}/`, do a lightweight scan (read Cargo.toml, CLAUDE.md, check git remote, find test/lint commands), and generate a minimal `goon.yaml` there. Then continue. - **One result**: Load it. Set `{map_dir}` to the directory containing it. - **Multiple results**: If `$ARGUMENTS` matches a subfolder name (exact or substring), use that one. Otherwise, list the available maps and ask which one the user is wrapping up. Once loaded, all MAP files, handoff files, and phase docs live in `{map_dir}/`. ## 2. Read the current handoff and MAP plan Glob for `{handoff.dir}/{handoff.prefix}*.md` and pick the highest-numbered file (same logic as `/goon` — sort numerically, unnumbered file is iteration 1). Read the entire file. This is your format reference — the next handoff should follow the same structure, adapted with this session's work. Also check for `{map_dir}/MAP_PLAN.md` and `{map_dir}/MAP_PHASE_*.md`. If they exist, you need to track phase progress in the handoff. If no previous handoff exists, that's OK — you're creating the first one. Use the template from the handoff structure section below. ## 3. Summarize what was done You (or your subagents) did the work this session — you already know what happened. Summarize it from your own context. Use `git log` and `git diff --stat` to supplement and verify, not to discover. If the user passed `$ARGUMENTS`, incorporate those notes — they're editorial direction ("emphasize the GC fix", "don't forget the parser regression"), not answers to questions. If you see commits or changes you don't recognize (e.g., the user made edits outside this session), ask about those specifically. But that's the exception, not the baseline. ## 4. Run verification checklist Run commands from `checklist.verify` and `checklist.lint` in goon.yaml. Report results to the user. If anything fails, ask: > "Test/lint failure: [summary]. Want to: > 1. Fix it now before handing off > 2. Note it as a known issue in the handoff > 3. Skip it" Wait for their choice. Don't silently skip failures. ## 5. Sync GitHub project If `repo` and `milestone` are set: - Check open issues: `gh issue list --repo {repo} --milestone "{milestone}" --state open` - Present any issues that look completed based on the session's work: > "These issues look done based on what was accomplished. Close them? > - #12 — Add foo support > - #15 — Fix bar bug" - If new work was discovered, suggest creating issues: > "Should I create an issue for [thing discovered]?" - If all milestone issues are closed, note that it's ready to tag Wait for confirmation before closing issues or creating new ones. ## 6. Gather session data Run these in parallel: - `git log --oneline` since the last handoff (use the handoff's date or find the commit that was HEAD when the session started) - `git diff --stat HEAD~N` for a summary of files changed (estimate N from log) - Count current tests: look for test count in checklist output - Count LOC: `find . -name '*.rs' -not -path './target/*' | xargs wc -l | tail -1` (or equivalent for the project's language — check goon.yaml or file extensions) ## 7. Assess MAP phase progress If MAP files exist, determine: - Which phases were completed this session (fully done, all exit criteria met) - Which phase is in progress (started but not finished) - What remains in the current phase (reference the phase doc's exit criteria) This goes into the handoff's plan/progress section. ## 8. Write the next handoff Create the next file by incrementing the number suffix with zero-padding: - Latest is `SESSION_HANDOFF-05.md` → create `SESSION_HANDOFF-06.md` - Latest is `SESSION_HANDOFF-12.md` → create `SESSION_HANDOFF-13.md` - Latest is unnumbered `SESSION_HANDOFF.md` → create `SESSION_HANDOFF-02.md` - No previous handoff exists → create `SESSION_HANDOFF.md` The handoff document MUST include these sections (follow the format of the previous handoff if one exists, adapting content): 1. **Project description** — what is this project (copy from previous, update if scope changed) 2. **Where things stand** — updated stats (LOC, tests, etc.), current state 3. **Project management** — milestone table (update open/closed counts), workflow description, current priority 4. **The plan** (if MAP exists) — reference MAP_PLAN.md, list phases with status: done/in-progress/pending. For the in-progress phase, note what's left. For done phases, note when they were completed. 5. **What to build next** — the current or next MAP phase (with enough detail to start immediately), or open issues if no MAP 6. **Known bugs and tech debt** — carry forward unresolved items, add new ones, remove fixed ones 7. **What was done in this session** — concrete list of accomplishments with enough detail for someone to understand the changes without reading diffs 8. **Workflow lessons** — what worked, what didn't (carry forward still-relevant lessons, add new ones) 9. **Key files to read** — update if the important files changed 10. **Running commands** — update if commands changed 11. **End-of-session checklist** — carry forward 12. **Style guide** — carry forward (update if conventions changed) ## 9. Review with user Show the user a summary of what the handoff captures: > "Here's what the handoff says: > - **Done this session**: [bullet points] > - **Current state**: [stats, phase progress] > - **Next up**: [what the next session should tackle] > - **Known issues**: [any new or carried-forward bugs] > > Written to `{map_dir}/SESSION_HANDOFF-NN.md`. Anything to add or change?" Wait for feedback. Incorporate any corrections. ## 10. Update goon.yaml If the milestone changed (e.g., all issues closed and release tagged), update the `milestone` field in goon.yaml to the next version. If new workflow lessons were learned this session, ask the user: > "Should I add any of these to the workflow notes in goon.yaml?" ## 11. Clean up and push The `.claude/map/` directory is gitignored — handoff files, goon.yaml, MAP docs all live outside version control. Do NOT try to commit them. What you DO need to ensure before wrapping up: 1. **All code changes are committed**: check `git status` for uncommitted work. If there are unstaged changes, stage and commit them with a clear message. Don't leave dirty working state for the next session. 2. **Push to origin**: push the current branch so nothing is only local. Ask first: "Push to origin?" (don't assume) 3. **Verify clean state**: run `git status` one final time — the branch should be clean and up to date with the remote. Tell the user: "Handoff ready. Branch is clean and pushed. Start your next session with `/goon`."