| name | session-handoff |
| description | Update docs/STATE.md with current session state. Use whenever the user says "wrap up", "handoff", "end session", "save state", "update state", or signals they are stopping work — even mid-task. |
session-handoff
Maintains docs/STATE.md, the 40-line rolling dashboard a fresh session reads before anything else. It is a dashboard, not a journal — history lives in git, not here.
Process
- Read
docs/STATE.md. If missing, create it from the template below.
- Update ONLY the sections that changed this session. Newest entries first.
- Enforce every cap by deleting the oldest or stale entries: Now ≤5, Blocked ≤3, Recent decisions ≤8, Don't touch ≤4, whole file ≤40 lines. Never exceed a cap to "keep something important" — if it's durable, it belongs in an ADR or the code, not here.
- One-line bullets only. No paragraphs, no code blocks, no transcripts.
- Every "Now" bullet MUST name a file path or issue ID plus the next step, so the next session can act without searching.
- Finish by printing the diff (
git diff docs/STATE.md, or full content if new) and ask the user to confirm before treating the handoff as done.
Template (for a missing STATE.md)
# Project State
> Rolling state file. Hard cap 40 lines. Newest first. Prune on every update.
## Now (max 5 bullets — in-flight work, one line each: what + where + next step)
## Blocked (max 3 bullets — what's stuck and on what)
## Recent decisions (max 8 bullets — decision + one-clause rationale, newest first, delete oldest when full)
## Don't touch (max 4 bullets — fragile areas and why)
Hard rules
- Never let STATE.md exceed 40 lines — it is read at the start of every session and must stay cheap
- Never write history or explanations into it — prune, don't accumulate
