handover

name	handover
description	Use when wrapping up or capturing the current state of a coding session — writes a short, dated entry to the repo's RepoHandover.md so a future agent or you can resume without grepping archived sessions. Triggers on "handover", "hand off", "write handover", "capture state", "checkpoint this session".

Handover

Append a short, dated entry to RepoHandover.md at the repo root (newest-first) capturing where things stand, so you or a future agent can resume. Keep it lean — a handful of lines, no git audit. The user already opted in by running /handover, so draft and write it directly — do NOT ask for approval or show a draft to confirm. Just write, report one line, and stop. Never commit.

Procedure

1. Draft from the conversation — do NOT run a git audit. You already know what happened this session. At most, run a single git branch --show-current if you want the branch in the header. Do not run git status/log/diff sweeps — that's the verbosity we removed.

2. Compose a short entry in this format. Omit any line/section that would be empty. Aim for ~8–15 lines total:

    ## <YYYY-MM-DD HH:MM> · <slug> · <title>
    status: in-progress            # in-progress | blocked | done
   
    **State:** <one sentence — where things stand right now>
   
    **Decided / don't redo:**      <only if there is something>
    - <a decision made, or a dead-end already tried>
   
    **Key files:**                 <only if it helps resume>
    - `path` — <why it matters>
   
    **Next:**
    1. <the next concrete step>
    2. <...>
   

   • slug = the branch or plan/spec name (keep it stable — supersede-matching uses it).
   • Timestamp: date +'%Y-%m-%d %H:%M'.

3. Write it immediately — no approval prompt.

   • New file → create RepoHandover.md with this entry as its only content.

   • Existing file → prepend the entry above the current top entry (blank line between). Don't touch older entries except the silent supersede below.

   • Ensure the repo's CLAUDE.md contains this pointer (add it once, creating a short CLAUDE.md if absent):

        > Before starting work, read the newest entry in `RepoHandover.md`.
     

   • Silent supersede: if an older entry has the same slug and its status isn't already done or superseded-by:, change that older entry's status line to status: superseded-by:<new-entry-date> (one-line edit; leave its prose alone). No prompt.

   • Never run git commit.

4. Report one line and stop. e.g. Wrote handover to RepoHandover.md (superseded the previous runway-auth entry). Not committed. Do not ask follow-up questions — the user is about to close/archive the session.

Notes

• Lean by default. State + key decisions + next steps. No git verification dump, no "Verified/Believed" ceremony, no risk matrix.
• If the drafted entry is wrong, the user edits the file directly — it's short and uncommitted, so a bad entry is cheap. That's why no approval gate is needed.
• Sanity-check (optional, cheap): handover-lint.sh RepoHandover.md — installed next to this skill — exits 0 when the newest entry's heading + status: line are well-formed.
• Rotation: if RepoHandover.md passes ~1000 lines, offer (never silently) to move all but the newest ~10 entries to RepoHandover-archive.md.