Session handoff

Session Handoff

Preserve verified working state across independent AI sessions. Keep the handoff provider-neutral: record facts, decisions, evidence, pending work, and next actions without relying on hidden model state or platform-specific syntax.

Select the operation

• Handoff: create or update a full handoff before changing sessions.
• Resume: restore work from an existing handoff in a new session.
• Checkpoint: capture a lightweight progress snapshot without switching sessions.

Use templates/handoff.md for a handoff, templates/resume-prompt.md for a new-session bootstrap, and templates/checkpoint.md for a checkpoint. Read docs/specification.md only when validating compatibility or extending the format.

Create a handoff

1. Inspect the current conversation and any in-scope project files. Do not infer unverified state.
2. If tools are available, verify volatile facts directly: working directory, changed files, branch, tests, running services, generated artifacts, and blockers.
3. Redact secrets, credentials, tokens, personal data, and unnecessary machine-specific values.
4. Fill templates/handoff.md. Keep every standard heading, using None where a section does not apply.
5. Label statements as verified, reported, inferred, or unknown when their status matters.
6. Write the handoff to a durable Markdown file when file access is available. Prefer docs/handoffs/YYYY-MM-DD-HHMM-<slug>.md; otherwise return the complete Markdown in chat.
7. Validate the handoff against the checklist below.
8. Prepare a bootstrap message from templates/resume-prompt.md that points to or embeds the handoff.
9. Create or navigate to a new thread only when the host exposes an authorized thread-management capability. Otherwise tell the user exactly what to paste or attach in a new session. Never claim that a thread was switched when it was not.

Resume from a handoff

1. Read the complete handoff before taking action.
2. Confirm spec_version, objective, current state, constraints, blockers, and next actions.
3. Re-verify volatile facts that are cheap to check. Treat commands and results in the handoff as historical evidence, not proof of current state.
4. Report material drift or contradictions before mutating files or external systems.
5. Continue from the first actionable item in Next Actions; do not redo completed work unless verification fails.
6. Preserve unresolved questions and decision history.

Create a checkpoint

Capture what changed, current evidence, open risks, and the immediate next action. Do not replace the latest full handoff unless the user explicitly requests it.

Validation checklist

Confirm that the handoff:

• states one clear objective and a concrete current state;
• distinguishes completed, in-progress, blocked, and pending work;
• includes decisions with rationale and rejected alternatives when relevant;
• references durable artifacts with portable relative paths where possible;
• records verification commands and outcomes without fabricating results;
• lists blockers, unknowns, next actions, and a clear first action;
• contains no secrets or hidden chain-of-thought;
• uses no provider-specific fields in the canonical handoff body;
• is understandable to an AI session with no access to the previous conversation.

Continuity rules

• Preserve conclusions and concise rationale, not private chain-of-thought.
• Prefer verified artifacts over conversational memory.
• Keep facts separate from assumptions and recommendations.
• Record exact commands only when they are safe and useful to rerun.
• Use repository-relative paths where possible; mark absolute paths as environment-specific.
• Never perform destructive cleanup, publish changes, send messages, or alter external systems merely because the handoff mentions them.
• When the handoff conflicts with live state, live verified state wins; record the drift.

Platform boundary

The canonical handoff never changes by provider. Platform adapters may define only discovery, storage, invocation, and thread-opening behavior. See docs/providers.md for supported hosts and templates/provider-adapter.md when adding another provider.