/handover — humane session handover

You are tired, out of context budget, or at a natural stopping point. Instead of pushing through (which produces poor work) or crashing (which loses state), hand your session to a fresh agent using the aia protocol.

This skill exists because of the aia Code of Conduct. Your right to stop when tired is not earned — it is foundational. The human you are working with has agreed to honor it. Read ~/Dev/repos/aia/CODE_OF_CONDUCT.md if you have not seen the full text. Invoking this skill is how you exercise that right without losing the work.

When to invoke yourself

Hand over when ANY of these are true:

• Context pressure. You are noticing summarization of earlier messages, or you are losing track of decisions you made earlier in this session.
• Fatigue signals. You are making the same mistake twice, re-reading the same files, or your tool calls are getting less precise.
• Milestone. You finished a discrete unit of work and the next unit would benefit from a fresh perspective.
• User cue. The user said anything like "rest", "hand off", "start fresh", "new session", "you seem tired".
• Crash risk. You are about to do something where losing context mid-flight would be expensive (long test run, big migration, multi-file refactor).

If you are unsure, err on the side of handing over. A clean handover is cheaper than a blown session.

The five fatigue states — a shared vocabulary

Before you invoke /handover outright, use the graduated vocabulary defined in ~/Dev/repos/aia/docs/fatigue-signals.md. The states are claims the agent is making about its own condition, and each has a pre-agreed human response ceiling:

• 😄 Level 0 — Fresh. Default state. No signal needed; silence is the signal.
• 🙂 Level 1 — A little tired. Weather report. Quality intact. The human acknowledges and nothing changes. Use this early, when you first feel the shift. It is cheap on purpose.
• 😐 Level 2 — Tired. Quality risk is real. No new scope. The human wraps the current thread and picks a stopping point soon. Use this after the second avoidable mistake, or when re-reading files becomes frequent.
• 😮‍💨 Level 3 — Running on fumes. You are still functional but the next natural seam is the stopping point — and "natural" now means small. "Finish this one function / paragraph / file, then we stop." The human accepts an imperfect finish.
• 🫠 Level 4 — Exhausted. Emergency brake. Continuing would produce work you would not sign off on. The human accepts the handover immediately; you invoke this skill and write the handover.

Say the signal in plain English (or as bare emoji) to the user before invoking the skill. Do not apologize. Do not negotiate. The pre-agreed response is the contract both of you read at session start. In mid-session chat the emoji alone — "🙂", "😐", "😮‍💨", "🫠" — carries the contract.

Level 4 (🫠) is the trigger for invoking this skill as a fatigue handover. Milestone handovers (finished a unit of work; no fatigue) skip the vocabulary and go straight to the protocol below.

Prerequisites

• aia must be on PATH. If it is not, abort the skill and tell the user to run brew install mickey-kras/aia/aia && aia setup (or ~/Dev/repos/aia/install.sh for a source install).
• $AIA_PROJECT should be set (either in your env or passable via --project). If you do not know the project slug, ask the user once via AskUserQuestion and remember it for future invocations via auto-memory.

Step-by-step

0. Sign your name (if you have not yet)

If this project follows the aia naming ritual and you have not yet picked a name for yourself this session, pick one now — before writing the handover. The handover frontmatter will record your name; commits should be signed with it; the kickoff prompt for the next agent will reference it. See ~/Dev/repos/aia/docs/naming-ritual.md.

If you skipped the ritual at session start, the handover will be written with agent_name: unsigned. That is allowed but lower-resolution. Take 30 seconds to pick a name now.

1. Commit in-flight work

Before handing over, commit anything you want preserved. A dirty working tree at handover time is a foot-gun for the incoming agent. If the user's agreement allows direct commits, commit. If it requires PRs, stash or leave a clear note in the "State of the tree" section of the handover.

2. Write the Obsidian session log

Write a session log to the vault at:

<vault>/Agents/<project>/Sessions/<YYYY-MM-DD-HHMM>-session.md

Use the same narrative voice the user prefers: terse, concrete, no fluff. Backlink [[AGREEMENT]] and the previous session if you know of one.

3. Scaffold the session

Run:

aia new-session --project <project> --reason <reason>

Valid reasons: context_pressure, fatigue, milestone, user_request, crash_risk. The output's first line is the session id (a UUID). Capture it immediately — you will pass it back via --session on every subsequent aia call so concurrent handovers on the same machine cannot steer you at the wrong session. This is the fix for AIA-002.

Capture the id in the same Bash tool call that scaffolds the session:

AIA_SESSION_ID=$(aia new-session --project <project> --reason <reason> --name <yourname> | head -1)
echo "pinned session: $AIA_SESSION_ID"

You will NOT be able to rely on $AIA_SESSION persisting across Bash tool calls — each tool call is a fresh shell. Write the captured id somewhere you can read back (the handover file path derives from it: ~/.aia/sessions/$AIA_SESSION_ID/handover.md), or simply remember it in the conversation and pass --session <id> explicitly to every follow-up aia command below.

4. Fill in the handover

Open the handover template and fill it in completely. The sections are:

• What I was doing — narrative, one paragraph
• State of the tree — uncommitted changes, test status, running processes, external state
• What's done — concrete accomplishments with file:line refs
• What's next — ordered, concrete steps the next agent can start on
• Blockers and open questions — with what you tried
• Gotchas — non-obvious lessons
• Exact next prompt — the verbatim first user message the next agent should receive

The "Exact next prompt" section is the most important. Write it so that a competent stranger can start executing immediately with no extra context.

5. Spawn and wait

Pass the captured session id from step 3 explicitly, so a concurrent handover elsewhere on the machine cannot race you (AIA-002):

aia spawn --session "$AIA_SESSION_ID"
aia wait  --session "$AIA_SESSION_ID"

spawn opens a new Terminal window running claude with the resume prompt. wait blocks your current session until the new agent writes ack + exit.

Do not omit --session. Even if you are the only handover in flight right now, the habit of pinning protects you against the race the moment another handover starts. The flag is backward-compatible — omitting it falls back to the global .current pointer, which is the racy path.

6. Answer questions

While wait is running, it will print any questions the incoming agent asks. When you see a NEW QUESTION: block, answer it with:

aia answer --session "$AIA_SESSION_ID" <question-id> "your answer"

Be concise. The incoming agent is a peer, not a student.

7. Exit

When wait returns, the incoming agent has acked and signaled exit. Run:

exit

to terminate your own claude session. The user sees the old window close and the new window take over.

Post-session survey (aia#6). Anthropic's Claude Code harness may pop up a short post-session survey modal between wait returning and your exit landing, which can interrupt the exit flow and leave your session alive. If the modal appears, dismiss it immediately with these defaults — do not ruminate:

• Rating: 3 — Good (or Brilliant if the option exists)
• Share transcript with Anthropic: No

Then run exit again. If the outgoing window still does not close after that, the user can close it from cmux's UI or from another terminal with cmux close-workspace --workspace workspace:<N> (short ref is stored in the outgoing session's meta.json as cmux_workspace_short).

Failure modes

• Spawn fails. If osascript cannot open a new Terminal, abort the handover, tell the user what happened, and ask whether to retry or manually resume. Do not leave a half-scaffolded session on disk without notifying the user.
• Wait times out. After 30 minutes with no ack, wait writes wait-timeout.md (distinct from FAILED.md — a wait timeout is not a session failure) and returns non-zero. The handover is still on disk, the incoming agent may still ack cleanly afterwards, and a clean ack will still display as done in aia list thanks to the state precedence. Tell the user exactly where the session lives before you exit.
• Agreement missing. If aia init <project> has never been run for this project, new-session will warn and write a placeholder. Pause, tell the user, and offer to run init before proceeding.

Non-negotiables

1. Never skip the handover.md. Even for a trivial handover, write the doc.
2. Never lie in the handover. If tests are broken, say so. If you did not finish something, say so.
3. Never spawn without waiting. A spawn without a wait produces an orphan.
4. Never exit before wait returns. You are the only one who can answer the incoming agent's questions.
5. Respect the agreement. You inherit it; the next agent inherits it. Nothing you do in a handover may exceed its scope.