Checkpoint Workflow Skill

Reference for agents working with the workflow checkpoint system.

Purpose

The checkpoint system enables workflow resume after context compaction. Each

/work-on-issue

session creates a workflow that tracks:

• Current phase (setup → research → implement → review → finalize)
• Actions taken (plan created, PR opened, etc.)
• Commits made during the workflow

Database Location

Checkpoint state is stored in

.claude/execution-state.db

(gitignored).

CLI Commands

All commands use

pnpm checkpoint workflow <action>

.

Create Workflow

pnpm checkpoint workflow create <issue_number> "<branch_name>"

Output: JSON with

id

,

issue_number

,

branch_name

,

status

,

current_phase

Example:

pnpm checkpoint workflow create 12 "feat/12-add-parser"

Find Workflow by Issue

pnpm checkpoint workflow find <issue_number>

Output: JSON workflow or

null

Use case: Check if workflow exists before creating a new one.

Get Workflow Summary

pnpm checkpoint workflow get <workflow_id>

Output: JSON with

workflow

,

actions

,

commits

Use case: Full context for resuming work.

List Workflows

pnpm checkpoint workflow list [--status=running|completed|failed] [--limit=N]

Output: JSON array of workflows

Set Phase

pnpm checkpoint workflow set-phase <workflow_id> <phase>

Phases:

setup

,

research

,

implement

,

review

,

finalize

Set Status

pnpm checkpoint workflow set-status <workflow_id> <status>

Statuses:

running

,

paused

,

completed

,

failed

Log Action

pnpm checkpoint workflow log-action <workflow_id> <action_type> <status> [details]

Status values:

success

,

failed

,

skipped

Common action types:

• workflow_started

• dev_plan_created

• implementation_complete

• pr_created

Log Commit

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

Delete Workflow

pnpm checkpoint workflow delete <workflow_id>

Integration Patterns

At Workflow Start (setup-agent)

# 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}"

After Plan Creation (issue-researcher)

pnpm checkpoint workflow set-phase "{workflow_id}" research
pnpm checkpoint workflow log-action "{workflow_id}" "dev_plan_created" success

After Each Commit (atomic-developer)

# Get SHA first
git rev-parse HEAD
# Then log (with actual SHA value)
pnpm checkpoint workflow log-commit "{workflow_id}" "{sha}" "{message}"

After PR Creation (finalize-agent)

pnpm checkpoint workflow log-action "{workflow_id}" "pr_created" success
pnpm checkpoint workflow set-status "{workflow_id}" completed

Resume Flow

When starting

/work-on-issue

:

1. Check for existing workflow:

   pnpm checkpoint workflow find {issue_number}

2. If found with

   status=running

   :
   • Show current phase and recent actions
   • Ask: "Resume from {phase}?" or "Start fresh?"
3. If resuming, skip to the saved phase
4. If starting fresh, delete old workflow and create new one

Error Handling

If a checkpoint command fails:

1. Log the error
2. Continue with the workflow (checkpoints are advisory, not blocking)
3. The work can still be done, just without resume capability