Checkpoint
Migrated from the checkpoint command under ADR-064, which makes skills the single user-invocable surface. The command file is gone, so its path is named here in plain text rather than as a citation to something a reader could open.
The checkpoint and session directories
Resolve them the way paths.artifact_dir does, then take its checkpoints/ and
sessions/ subdirectories. Do not hard-code an agent-artifacts path: the tree
this skill writes into lives in the CONSUMER's workspace, and its root differs
between an upstream checkout and a plugin install. Every {checkpoints-dir} and
{sessions-dir} below means those resolved directories.
Capture the current state of work as a durable, timestamped snapshot. Use this mid-session when you want a recoverable save point before a risky change, at the end of a working block, or whenever the user asks to "checkpoint" progress. The file is the human-readable record; the session log keeps a reference to it.
Triggers
| Trigger | Effect |
|---|---|
/checkpoint |
Write a timestamped checkpoint and link it from the active session log. |
/checkpoint label |
Write a labeled checkpoint and link it from the active session log. |
Arguments
Optional label for this checkpoint: $ARGUMENTS
Process
Phase 1: Build checkpoint path
Resolve the timestamp, active session log, label, slug, and collision-safe checkpoint path.
Phase 2: Build and redact checkpoint
Render the checkpoint body and run it through the secret redactor before any Write call.
Phase 3: Persist and link
Write the redacted checkpoint to a path that does not already exist. Append checkpoint metadata to the active JSON session log when one exists, then validate the JSON.
When a checkpoint file is later committed, the commit message still follows the repository convention.
Commit messages MUST follow <type>(<scope>): <desc> and include a Co-Authored-By: trailer when authored with an AI agent.
Steps
The three phases expand into eight steps: resolve the timestamp and branch, find
the active session log, build the path, render the body, redact it, write it to a
path that does not exist, link and validate the session log, then report. Each
step, with its exact commands and failure handling, is in
references/steps.md. Read it before writing anything; the redaction and
validate-before-edit ordering is the part that matters.
Verification
A gate is any check whose failure would falsify your conclusion. Only a current result on the exact state and scope clears it. Failure, timeout, stale run, skip, or subset leaves the claim unproved. Say what ran and what returned. If blocked, name who can clear it.
- Checkpoint file path did not already exist before Write.
- Checkpoint body was redacted with
scripts/redact_secrets.pybefore Write. - Active session log was updated, or the "no active session log" reason was reported.
- Updated session log JSON was validated before editing the original file.
- Updated session log passed
python3 -m json.toolwhen a log was modified.
Anti-Patterns
- Do not overwrite an existing checkpoint path.
- Do not write unredacted durable text when the redactor fails.
- Do not create or guess a session log when no active branch-matching log exists.
- Do not edit a session log before validating the complete updated JSON string.
- Do not commit, push, or merge from this command.
Extension Points
- Add a restore command separately. Checkpoint only writes and links snapshots.
- Add automatic checkpointing separately. This command stays human-triggered.
This command writes a snapshot file and records a reference in the active session log when one exists. It does not push or commit. Keep it to the steps above.