rotate

Rotate: hand this session over to a fresh one

A long session gets worse before it compacts. A handover is a short file that tells a fresh session everything it needs to continue. Then /clear starts that fresh session: inside tmux the plugin types it into this session's own pane once the session is idle, elsewhere the user types it. The plugin gives the handover to the new session.

The first word of the arguments picks the action: write (also with no arguments), release or resume. For any other first word the plugin puts its usage line in your context: show that line to the user and do nothing else.

write

1. Find the path. It is in your context: the guard names it in every message about the context size, and when the user typed this command a note gives it. It looks like <project>/.claude/rotation/handover-<session id>.md. Never write another session's handover.

2. Bring the work to a resting point first: finish the edit you are in, or stop cleanly. The handover describes the state at the moment you write it.

3. Write the file with the Write tool. Not with a shell command: the check runs on Write and Edit. Use these sections, in this order:

   # Handover
   
   ## Goal
   What the user wants, in their terms, and how they will judge it done.
   
   ## Current state
   What is done and verified, the decisions taken and why, what was tried and failed.
   
   ## Running
   Background shells, subagents, servers or watchers that still run, with how to find
   them. Write "none" when nothing runs.
   
   ## Next steps
   1. The first thing the fresh session does: a command, a file, a question to the user.
   2. ...
   
   ## Files touched
   Each path with one line on what changed.
   
   ## Open risks
   What is unverified, what can break, what the user still has to decide.
   

   Rules for the text:

   • Write for a reader who has seen none of this conversation: full paths, exact names, the exact command and its last result. No "as discussed".
   • The first line under ## Next steps must be a step numbered 1..
   • At most 8,000 characters, or the limit named in your context.

4. Read the answer of the check. Right after the write the plugin either says the handover is valid and marked ready, or names exactly what is missing. Fix it with another Write or Edit until it is valid.

5. Make the valid write your last action. Do not call any other tool afterwards, not even a todo update: any call other than Read, Glob or Grep, and any new prompt, marks the handover outdated, and an outdated handover is never given to a fresh session. End your turn with one short line saying the handover is saved.