handoff-session

Create a .ytstack/HANDOFF.md that lets the next session (yours or someone else's) pick up exactly where this one left off. This is the user-triggered equivalent of the automatic pre-compact hook -- but richer, because the user decides what matters.

Anti-Pattern: "I'll remember what I was doing"

You won't. Tomorrow-you, monday-you, and teammate-you all read handoffs cold. The test: write the handoff, read it yourself 30 seconds later, can you pick up without scrolling conversation history? If yes, ship. If no, add detail.

Checklist

1. Run preamble -- detect state
2. HARD-GATE -- ytstack initialized
3. Ask: what's open right now? -- one sentence on in-flight work
4. Ask: what's the next action? -- concrete next step
5. Ask: any open decisions blocking? -- things you need the next session to decide
6. Ask: any warnings / gotchas? -- things easy to miss
7. Write HANDOFF.md (overwrites the hook-generated one)
8. Report + suggest clean exit

Preamble

# ytstack resolver (M016): checkout = where this shell runs, via the shared lib.
_LIB="${CLAUDE_SKILL_DIR}/../../hooks/lib/git-ctx.sh"
if [ -f "$_LIB" ]; then
  . "$_LIB"; yt_git_ctx "$PWD"; yt_resolve_yt_dir >/dev/null
  _PROJECT_DIR="$YT_TOPLEVEL"; _YT_DIR="$YT_DIR"; _YT_SCOPE="$YT_SCOPE"; _IS_GIT="$YT_IS_GIT"; _PROJECT_KEY="$YT_REPO_KEY"
else
  # Host did not substitute CLAUDE_SKILL_DIR (e.g. Codex adapter): project scope only.
  _IS_GIT=$([ "$(git rev-parse --is-inside-work-tree 2>/dev/null)" = true ] && echo yes || echo no)
  _PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd -P)
  _YT_DIR=""; _YT_SCOPE=none; _PROJECT_KEY=""
  [ -d "$_PROJECT_DIR/.ytstack" ] && { _YT_DIR="$_PROJECT_DIR/.ytstack"; _YT_SCOPE=project; }
fi
cd "$_PROJECT_DIR" 2>/dev/null || true
_PROJECT_SLUG=$(basename "$_PROJECT_DIR")
_HAS_YTSTACK=$([ -n "$_YT_DIR" ] && echo yes || echo no)

_CURRENT_MILESTONE=none; _ACTIVE_SLICE=none; _ACTIVE_TASK=none; _PROJECT_NAME=unknown
if [ -f "$_YT_DIR/STATE.md" ]; then
  _CURRENT_MILESTONE=$(sed -n 's/^current_milestone: *//p' "$_YT_DIR/STATE.md" | head -1)
  _ACTIVE_SLICE=$(sed -n 's/^active_slice: *//p' "$_YT_DIR/STATE.md" | head -1)
  _ACTIVE_TASK=$(sed -n 's/^active_task: *//p' "$_YT_DIR/STATE.md" | head -1)
fi
[ -f "$_YT_DIR/PROJECT.md" ] && _PROJECT_NAME=$(sed -n 's/^name: *//p' "$_YT_DIR/PROJECT.md" | head -1)
_BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)

echo "HAS_YTSTACK: $_HAS_YTSTACK"
echo "PROJECT_NAME: $_PROJECT_NAME"
echo "CURRENT_MILESTONE: $_CURRENT_MILESTONE / $_ACTIVE_SLICE / $_ACTIVE_TASK"
echo "BRANCH: $_BRANCH"

Procedure

Step 2 HARD-GATE. If HAS_YTSTACK=no: abort.

Step 3 -- Open work. AskUserQuestion:

Writing a handoff for {PROJECT_NAME} on branch {BRANCH}. Position: {CURRENT_MILESTONE} / {ACTIVE_SLICE} / {ACTIVE_TASK}.

What's currently in-flight? One sentence. What were you in the middle of when you hit pause?

Remember as _OPEN_WORK.

Step 4 -- Next action. AskUserQuestion:

What's the exact next step when you pick this up? Be concrete. Not "continue the task" but "finish the argon2 integration in src/auth/signup.ts, starting at line 47."

Remember as _NEXT_ACTION.

Step 5 -- Open decisions. AskUserQuestion:

Any decisions that need to be made before the next session can proceed? These become blockers if forgotten.

Enter "none" if there are no blocking decisions.

Remember as _OPEN_DECISIONS.

Step 6 -- Warnings. AskUserQuestion:

Any warnings, gotchas, or easy-to-miss details the next session should know? Examples: "the test suite skips a flaky test on main -- don't be surprised", "env var X must be set before running", "the staging DB is seeded, don't reset it".

Enter "none" if nothing.

Remember as _WARNINGS.

Step 7 -- Write HANDOFF.md. Use Write tool. Path: {YT_DIR}/HANDOFF.md. This file is user-owned: since M016 no hook writes it (automatic pre-compaction breadcrumbs live out of tree and resume-session reads both), so whatever is there was written by a person or by this skill -- read it before overwriting and carry forward anything still open.

---
kind: handoff
event: user-triggered
# user-owned: hooks never write this file; automatic handoffs live out of tree (see resume-session)
timestamp: {ISO_TIMESTAMP}
project: {PROJECT_NAME}
branch: {BRANCH}
current_milestone: {CURRENT_MILESTONE}
active_slice: {ACTIVE_SLICE}
active_task: {ACTIVE_TASK}
---

# Session Handoff

Written by the user via `/ytstack:handoff-session` at {ISO_TIMESTAMP}.

## Position

- Project: **{PROJECT_NAME}**
- Branch: `{BRANCH}`
- Milestone / Slice / Task: `{CURRENT_MILESTONE}` / `{ACTIVE_SLICE}` / `{ACTIVE_TASK}`

## In-flight work

{OPEN_WORK}

## Next action

{NEXT_ACTION}

## Open decisions blocking progress

{OPEN_DECISIONS}

## Warnings / gotchas

{WARNINGS}

## How to resume

1. Start a new Claude Code session in this project directory.
2. SessionStart hook will auto-inject state from `STATE.md` -- read that first.
3. Read this file (`HANDOFF.md`) for the in-flight context.
4. Check latest `{CURRENT_MILESTONE}-{ACTIVE_SLICE}-{ACTIVE_TASK}-PLAN.md` and corresponding `-SUMMARY.md` if it exists.
5. Run `/ytstack:resume-session` to get a synthesized briefing.
6. Execute the "Next action" above.

## Related artifacts

- Full dashboard: `{YT_DIR}/STATE.md`
- Milestone roadmap: `{YT_DIR}/{CURRENT_MILESTONE}-ROADMAP.md`
- Deferred items: `{YT_DIR}/REVIEW-NOTES.md`
- Decision log: `{YT_DIR}/DECISIONS.md`

Step 8 -- Report + suggest exit.

Handoff written to {YT_DIR}/HANDOFF.md. Safe to exit Claude Code now.

To resume later: start a new session in this project, run /ytstack:resume-session, then execute the next action.

If you're handing off to another person / machine: make sure .ytstack/ is committed to git so they have access.

Terminal State

Return after writing HANDOFF.md. Do NOT invoke any other skill. Do NOT attempt to end the Claude Code session -- that's the user's choice.