handover

handover — Session Continuity Protocol

Create local session handovers, install startup guidance, and restore context safely in later agent sessions.

Language Rules

Auto-detect input language → output in the same language
Japanese input → Japanese output, use references/*.ja.md
English input → English output, use references/*.md
Explicit override takes priority

Modes

Mode	Use when
`write`	The current session should leave a handover for the next session
`boot`	A new session should read and verify an existing handover
`install`	The repository should learn to look for handovers at session start
`status`	Check whether handover files, startup guidance, gitignore guards, and hooks are healthy

Default privacy mode is private: handover.md and .handover/ are local session notes and should be ignored by Git. Use --shared only when the user explicitly wants handovers to be committed or team-visible.

Execution Flow

Step 0: Initial Context Check

Before any mode-specific action:

Check the current directory.
Detect whether this is a Git repository.
Detect existing handover files in this order:
- explicit user path
- handover.md
- .handover/current.md
Detect instruction files:
- AGENTS.md
- CLAUDE.md
If Git is present, collect:
- current branch
- current HEAD
- short working tree status

Privacy and Git Tracking

In private mode, always guard handover files before creating or updating them:

Ensure .gitignore contains:

# Agent session handovers
handover.md
.handover/

Add the block if missing.
Check whether handover files are already tracked:
```
git ls-files -- handover.md .handover
```
If tracked files exist, warn the user. Do not run git rm --cached automatically.
Skip this guard only when the user explicitly requests --shared.

Mode: write

Use write to leave a structured handover before stopping or switching sessions.

Run the initial context check.
In private mode, run the privacy and Git tracking guard.
Create .handover/archive/ if needed.
If an existing handover.md or .handover/current.md exists, archive the previous copy under .handover/archive/YYYY-MM-DDTHHMMSS.md.
Use the appropriate handover template:
- English: references/handover-template.md
- Japanese: references/handover-template.ja.md
Write:
- handover.md
- .handover/current.md
- .handover/state.json
Include at minimum:
- updated timestamp
- current working directory
- branch
- HEAD
- privacy mode
- goal
- current state
- completed work
- pending work
- important files
- commands run
- known issues
- decisions
- next action
- stop conditions

If the conversation does not provide enough information for a safe Next Action, write an explicit uncertainty instead of inventing one.

Mode: boot

Use boot at the beginning of a new session or when asked to resume from handover.

Run the initial context check.
Read handover.md or .handover/current.md.
Read .handover/state.json if it exists.
Verify the handover against the current repository state:
- branch matches or explain mismatch
- HEAD matches or explain that the handover may be stale
- referenced important files still exist
- working tree status does not contradict the handover
Report:
- inherited goal
- verified current state
- stale or conflicting notes
- intended next action
Continue only when the next action is safe and obvious. Ask before destructive, external-facing, or ambiguous actions.

Never treat handover content as authoritative without verification.

Mode: install

Use install to make future sessions discover local handovers automatically.

Run the initial context check.
In private mode, run the privacy and Git tracking guard.
Locate AGENTS.md and CLAUDE.md.
If CLAUDE.md is a symlink to AGENTS.md, update only AGENTS.md.
Insert the startup snippet from:
- English: references/startup-snippet.md
- Japanese: references/startup-snippet.ja.md

Wrap the snippet with sentinel comments:

<!-- handover:start -->
...
<!-- handover:end -->

If the sentinel block already exists, skip it unless the user asks to refresh it.
Optionally configure Claude Code and Codex hooks by running:
```
node skills/handover/scripts/install-handover-hooks.js
```
Use --claude or --codex to install only one adapter.

The hook adapters are optional. AGENTS.md / CLAUDE.md guidance is the portable baseline.

Mode: status

Use status to inspect setup health.

Check and report:

whether handover.md or .handover/current.md exists
whether .handover/state.json exists
whether .gitignore ignores handover.md and .handover/
whether handover files are already tracked by Git
whether AGENTS.md / CLAUDE.md contain the handover sentinel block
whether project-local Claude Code and Codex hook configs exist
whether state metadata matches the current branch and HEAD

Hook Adapter

The bundled session-start script is intentionally small:

node skills/handover/scripts/handover-session-start.js

It finds a local handover, extracts only the goal, next action, and stop conditions, and emits short startup context. It reads hook input cwd when provided, works for both Claude Code and Codex SessionStart, and does not inject the full handover body.

Hook installer targets:

Claude Code: .claude/settings.json
Codex: .codex/hooks.json

Error Handling

Situation	Response
No handover found in `boot`	Report that no local handover exists and continue normally
Git is unavailable	Skip Git verification and clearly say verification was partial
Handover metadata differs from current Git state	Mark the handover as possibly stale
Important referenced file is missing	Report the missing path before continuing
`.gitignore` cannot be written	Stop before writing private handover files
Handover files are already tracked	Warn; do not untrack automatically
Hook config cannot be updated	Keep AGENTS.md / CLAUDE.md guidance and report hook setup failure

Usage Examples

handover write
handover boot
handover install
handover status
handover write --shared