Session Handoff
Two modes sharing one state contract. HANDOFF packages current work so the next agent (or future session) resumes without re-discovery. PICKUP rehydrates from that package at session start. Pick the mode from intent: ending or pausing work = HANDOFF; starting on existing work = PICKUP.
Mode: HANDOFF
Produce a concise bullet package with these sections, in order. Every claim comes from a command you ran this session — re-run when stale, because a wrong handoff costs more than no handoff.
- Scope/status — the task in one line, finished vs. remaining work, blockers.
- Working tree —
git status -sb summary; note local commits not yet pushed and whether you are in a worktree (pwd contains .claude/worktrees/).
- Branch/PR — current branch, PR number/URL, CI status (
gh pr checks <num> when a PR exists).
- Live processes — long-running jobs the next agent must know about: summarize
ps auxww | grep -E '<your-process>', plus a copy-paste attach or log-tail command (tail -f <logfile>, jobs -l). Redact secrets in command lines.
- Tests/checks — which commands ran, results, what still needs to run.
- Next steps — remaining actions in execution order, most urgent first.
- Risks/gotchas — flaky tests, feature flags, brittle areas, approvals still needed.
Gate: every live process has a copy-paste command; every pending step is ordered. Output format: bullet list, Dense-Complete — short enough to paste into a PR comment or session note.
Mode: PICKUP
Rehydrate in this order, then act.
- Read the handoff — the prior package, plus repo CLAUDE.md and any docs it names.
- Repo state —
git status -sb; confirm branch, local commits, worktree path.
- CI/PR —
gh pr view <num> --comments (derive the PR from the branch when unnumbered); note failing checks.
- Processes — check for live jobs named in the handoff; attach or tail logs using its commands.
- Tests/checks — note what last ran; decide what you will run first.
- Plan — write the next 2–3 actions as bullets, then execute them.
Gate: branch, PR state, and first action are confirmed before any edit. Report discrepancies between the handoff and observed state; observed state wins.
Constraints
- State only what you verified; mark inherited claims as "per handoff, unverified."
- In worktrees, follow
skills/process/worktree-agent/SKILL.md rules: verify CWD, feature branch first.
- Keep secrets out of the package: redact tokens and credential paths as
<redacted>.
Error handling
Handoff references a process that is gone
Cause: job exited between sessions.
Solution: check its log file for exit status, record the finding, drop the attach step.
Branch in handoff differs from checked-out branch
Cause: another agent or the user moved the worktree.
Solution: report the difference and proceed from observed state.
1---2name: session-handoff-43description: Package session state for the next agent, or rehydrate it at start.4---5
6# Session Handoff
7
8Two modes sharing one state contract. HANDOFF packages current work so the next agent (or future session) resumes without re-discovery. PICKUP rehydrates from that package at session start. Pick the mode from intent: ending or pausing work = HANDOFF; starting on existing work = PICKUP.
9
10## Mode: HANDOFF
11
12Produce a concise bullet package with these sections, in order. Every claim comes from a command you ran this session — re-run when stale, because a wrong handoff costs more than no handoff.
13
141. **Scope/status** — the task in one line, finished vs. remaining work, blockers.
152. **Working tree** — `git status -sb` summary; note local commits not yet pushed and whether you are in a worktree (`pwd` contains `.claude/worktrees/`).
163. **Branch/PR** — current branch, PR number/URL, CI status (`gh pr checks <num>` when a PR exists).
174. **Live processes** — long-running jobs the next agent must know about: summarize `ps auxww | grep -E '<your-process>'`, plus a copy-paste attach or log-tail command (`tail -f <logfile>`, `jobs -l`). Redact secrets in command lines.
185. **Tests/checks** — which commands ran, results, what still needs to run.
196. **Next steps** — remaining actions in execution order, most urgent first.
207. **Risks/gotchas** — flaky tests, feature flags, brittle areas, approvals still needed.
21
22**Gate:** every live process has a copy-paste command; every pending step is ordered. Output format: bullet list, Dense-Complete — short enough to paste into a PR comment or session note.
23
24## Mode: PICKUP
25
26Rehydrate in this order, then act.
27
281. **Read the handoff** — the prior package, plus repo CLAUDE.md and any docs it names.
292. **Repo state** — `git status -sb`; confirm branch, local commits, worktree path.
303. **CI/PR** — `gh pr view <num> --comments` (derive the PR from the branch when unnumbered); note failing checks.
314. **Processes** — check for live jobs named in the handoff; attach or tail logs using its commands.
325. **Tests/checks** — note what last ran; decide what you will run first.
336. **Plan** — write the next 2–3 actions as bullets, then execute them.
34
35**Gate:** branch, PR state, and first action are confirmed before any edit. Report discrepancies between the handoff and observed state; observed state wins.
36
37## Constraints
38
39- State only what you verified; mark inherited claims as "per handoff, unverified."
40- In worktrees, follow `skills/process/worktree-agent/SKILL.md` rules: verify CWD, feature branch first.
41- Keep secrets out of the package: redact tokens and credential paths as `<redacted>`.
42
43## Error handling
44
45### Handoff references a process that is gone
46Cause: job exited between sessions.
47Solution: check its log file for exit status, record the finding, drop the attach step.
48
49### Branch in handoff differs from checked-out branch
50Cause: another agent or the user moved the worktree.
51Solution: report the difference and proceed from observed state.
majiayu000