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:
HANDOFF.md: where the work stands right now.DECISIONS.md: choices that future work must respect.
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.
- Reads.
sprint startreadsDECISIONS.mdand thenHANDOFF.mdbefore it plans. When a sprint is resumed, the agent readsDECISIONS.md,HANDOFF.mdand the ticket's folder, finds the first unchecked item and carries on from there. - Writes.
wrapup's refresh step updates Current Focus, In Progress and Next Steps when a sprint closes. Discoveries belong to thecaptureskill, which records a surprise the moment it is found, mid-sprint. - Save & End. When you end a session with Save & End, the Cockpit asks the agent to append a short status to
HANDOFF.mdif anything changed; see Agents and sessions. - Scratch sessions. What a Scratch session leaves behind is noted in
HANDOFF.mdunder## Scratch, after canon's managed block. Nothing else in the file changes.
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.

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
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.