Reference for agents working with the workflow checkpoint system.
Sign in to like and favorite skills
Reference for agents working with the workflow checkpoint system.
The checkpoint system enables workflow resume after context compaction. Each
/work-on-issueCheckpoint state is stored in
.claude/execution-state.dbAll commands use
pnpm checkpoint workflow <action>pnpm checkpoint workflow create <issue_number> "<branch_name>"
Output: JSON with
idissue_numberbranch_namestatuscurrent_phaseExample:
pnpm checkpoint workflow create 12 "feat/12-add-parser"
pnpm checkpoint workflow find <issue_number>
Output: JSON workflow or
nullUse case: Check if workflow exists before creating a new one.
pnpm checkpoint workflow get <workflow_id>
Output: JSON with
workflowactionscommitsUse case: Full context for resuming work.
pnpm checkpoint workflow list [--status=running|completed|failed] [--limit=N]
Output: JSON array of workflows
pnpm checkpoint workflow set-phase <workflow_id> <phase>
Phases:
setupresearchimplementreviewfinalizepnpm checkpoint workflow set-status <workflow_id> <status>
Statuses:
runningpausedcompletedfailedpnpm checkpoint workflow log-action <workflow_id> <action_type> <status> [details]
Status values:
successfailedskippedCommon action types:
workflow_starteddev_plan_createdimplementation_completepr_createdpnpm checkpoint workflow log-commit <workflow_id> <sha> "<message>"
CRITICAL: Commit logging pattern
Always log commits in two separate commands:
# 1. Get SHA (separate command) git rev-parse HEAD # 2. Log to checkpoint (use literal SHA, not variable) pnpm checkpoint workflow log-commit "abc123" "a1b2c3d" "feat: add feature"
NEVER combine with
or use shell variables. This prevents errors if the git command fails.&&
pnpm checkpoint workflow delete <workflow_id>
# Check for existing workflow pnpm checkpoint workflow find {issue_number} # If found with status=running, offer to resume # If not found, create new workflow pnpm checkpoint workflow create {issue_number} "{branch_name}"
pnpm checkpoint workflow set-phase "{workflow_id}" research pnpm checkpoint workflow log-action "{workflow_id}" "dev_plan_created" success
# Get SHA first git rev-parse HEAD # Then log (with actual SHA value) pnpm checkpoint workflow log-commit "{workflow_id}" "{sha}" "{message}"
pnpm checkpoint workflow log-action "{workflow_id}" "pr_created" success pnpm checkpoint workflow set-status "{workflow_id}" completed
When starting
/work-on-issuepnpm checkpoint workflow find {issue_number}status=runningIf a checkpoint command fails: