Session continuity

An agent session ends and the next one starts knowing nothing. canon bridges that gap with two plain Markdown files in your project, which you can read and edit like any other file:

sprint start reads both at the start of a sprint, so a new session, a different agent, or a session after a context reset picks up from them and not from your memory.

What goes in HANDOFF.md

canon manages the part between two marker comments:

# Handoff <!-- canon:handoff:BEGIN --> ## Current Focus One sentence. ## In Progress - Ticket or file path — current state ## Discoveries - 🔴 **YYYY-MM-DD** Discovery — how to apply it - 🟢 **YYYY-MM-DD** Lower-priority note ## Next Steps 1. Concrete next action <!-- canon:handoff:END -->

Tag a discovery with a glyph if it helps the next session triage: 🔴 is "load-bearing — the next session must know this to act correctly", 🟡 is "maybe — relevant depending on what gets picked up next", and 🟢 is "info-only — context or FYI, often derivable; first to prune".

The rule for the whole file: "Keep it short. Prefer bullets that help the next agent act. Do not duplicate the git diff, ticket body, or obvious code facts. Decisions belong in DECISIONS.md — do not restate them here."

Who reads it and who writes it

No background process keeps HANDOFF.md current. The workflow tells the agent when to read and write it, and the Cockpit adds the two prompts and the note described below.

What the board shows

The ticket tab's Status panel reads HANDOFF.md from the folder the session runs in, so a session in a worktree shows that worktree's copy. It shows the ticket's own entry under In Progress if there is one. If not, it shows the Current Focus, labelled "Current focus (no per-ticket state yet):". If neither exists it says "No saved state yet for this ticket in HANDOFF.md." Below that it lists "Next steps:" from the Next Steps section.

The Status panel of a ticket running in a worktree: Running in sprint/restyle-ui, the label Current focus with no per-ticket state yet, a one-line state for the ticket, and a Next steps list with two items.
The Status panel reads HANDOFF.md: current focus first, then the next steps.

A worktree has its own copy of HANDOFF.md on its branch. When a branch is merged, its notes come with it; see Working in worktrees.

Keep it within 80 lines

Keep the content between the canon:handoff:BEGIN and canon:handoff:END markers within 80 lines; wrapup prunes it when it goes over. wrapup's size check counts only the lines between those markers: anything you add outside them is never read, counted or edited by wrapup's refresh. Both markers must be present. wrapup confirms the pair before it counts and restores it if one is missing, because with a marker missing the count would silently read as zero.

This is a step in wrapup's protocol; the sprint command does not enforce it. If you use Pi, skills.sh init also installs a Pi extension that prepends HANDOFF.md to your first message of a session and warns when the file is over 80 lines. It counts every line in the file, not only the marked block. Prune freely. Git history keeps everything.

What canon hooks into

No hooks in your project

canon writes no Claude Code hooks into your project. For each Claude Code session the Cockpit passes a temporary settings file to claude --settings, kept in the Cockpit's own state folder and not in your project, which merges with your project's own settings. It holds Notification hooks that tell the Cockpit when the agent needs you (a permission or approval prompt) or has finished its turn. The file is removed when the session ends. See Agents and sessions for the states it drives. The How it works page makes a related point: canon adds no Claude Code hooks to your project. The hook above lives in the Cockpit's own state folder and goes away with the session.

canon also installs a git pre-commit hook in a git project. That is a git hook, not a Claude Code hook; Registering skills lists everything that registering a skill adds.