Checkpoint Protocol for Superpowers

Checkpoint Protocol for Superpowers

Purpose: Define how superpowers update metadata.json checkpoints during execution for state tracking and resumption.

Version: 1.0 Created: 2026-02-13

Overview

Superpowers must update metadata.json at key points during execution to enable:

1. Progress Tracking - Orchestrator knows what's happening
2. Resumption - Can resume from exact checkpoint after interruption
3. Failure Recovery - Clear record of what succeeded/failed
4. Audit Trail - Complete history of execution

Checkpoint Update Points

When to Update

Superpowers MUST update checkpoints at these points:

Checkpoint Data Structure

Full Checkpoint Format

{
  "loop_state": {
    "current_step": "PLAN",
    "step_status": "IN_PROGRESS",
    "step_started_at": "2026-02-13T12:00:00Z",
    "fix_cycle_count": 0,
    "max_fix_cycles": 3,

    "checkpoints": {
      "PLAN": {
        "status": "IN_PROGRESS",
        "started_at": "2026-02-13T12:00:00Z",
        "completed_at": null,
        "agent": "superpowers:writing-plans",
        "progress": {
          "current_phase": 2,
          "total_phases": 5,
          "current_task": "Designing parameter schema",
          "tasks_completed": 5,
          "tasks_total": 35
        },
        "output_files": [],
        "notes": "",
        "last_updated": "2026-02-13T12:05:00Z"
      }
    }
  }
}

Required Fields

Update Protocol for Each Superpower

superpowers:writing-plans

Checkpoint Key: PLAN

1. On Start: Set status IN_PROGRESS, record agent and timestamp
2. During Execution (every 5 minutes): Update progress with current phase/task
3. On Completion: Set status PASSED, record output_files and notes

superpowers:executing-plans

Checkpoint Key: EXECUTE

1. On Start: Set status IN_PROGRESS, record tasks_total
2. After Each Task: Update tasks_completed, last_task, last_commit
3. On Completion: Set status PASSED, record total tasks and commits

superpowers:systematic-debugging

Checkpoint Key: FIX

1. On Start: Set status IN_PROGRESS, record issues_total
2. During Fixing: Update issues_fixed, current_issue
3. On Completion: Set status PASSED, record fix summary

superpowers:brainstorming

Checkpoint Key: BRAINSTORM

1. On Start: Set status IN_PROGRESS
2. On Completion: Set status PASSED, record output_files

Error Handling

On Failure

Update checkpoint with failure details in the notes field:

{
  "status": "FAILED",
  "notes": "ERROR: Missing required spec.md file at conductor/tracks/{track-id}/spec.md"
}

On Interruption

Checkpoint preserves exact state for resumption. The orchestrator can resume with --resume-from parameter using the last_task value from the checkpoint.

File Locking

To prevent race conditions with concurrent metadata updates:

# Acquire lock
lockfile="${track_dir}/.metadata.lock"
while ! mkdir "$lockfile" 2>/dev/null; do
  sleep 0.1
done

# Update metadata
# ... (update code here)

# Release lock
rmdir "$lockfile"