checkpointed-agent-loop

# Checkpointed Agent Loop Use this skill when a task can be interrupted, needs bounded retries, or must prove verification before it is called complete. It adds a small local checkpoint file around ordinary Claude Code work so a new context can resume from explicit state instead of reconstructing progress from chat. The included Node.js utility stores state and evidence. It does **not** execute commands, call a model, spawn agents, access secrets, or contact a network service. Claude Code remains responsible for each actual tool call and for deciding whether a human approval is required. ## When to Use This Skill - A migration, refactor, test repair, or investigation may span multiple sessions. - A bounded retry loop is safer than repeatedly improvising from conversation history. - A task needs a durable next action and a record of which verification actually ran. - You need to stop at an external dependency or a human decision without claiming success. Do not use it for a one-line edit or a workflow that already has its own durable runner. ## State Model The checkpoint uses these states and only these transitions: ```text planned -> running running -> verifying | failed | blocked verifying -> succeeded | running | failed | blocked ``` `succeeded`, `failed`, and `blocked` are terminal. Entering `running` consumes one attempt, and the finite `maxAttempts` value cannot be exceeded. A transition to `succeeded` is rejected until the checkpoint contains at least one passing evidence record from `verifying`. ## Setup Choose a project-local path that is not committed with application code, for example `.agent/checkpoints/data-migration.json`. Keep objectives, reasons, and evidence free of API keys, tokens, passwords, personal data, and raw secret-bearing logs. Set the helper path for the commands below: ```bash SKILL_DIR="<absolute path to the installed checkpointed-agent-loop skill>" CHECKPOINT=".agent/checkpoints/task.json" ``` Initialize with a finite budget: ```bash node "$SKILL_DIR/scripts/checkpoint-loop.mjs" init \ --file "$CHECKPOINT" \ --task "data-migration" \ --objective "Migrate the user table without losing records" \ --max-attempts 3 \ --next-action "Inspect the current migration and test fixture" ``` ## Operating Protocol ### 1. Start one bounded attempt Before making the change, persist the next action and enter `running`: ```bash node "$SKILL_DIR/scripts/checkpoint-loop.mjs" transition \ --file "$CHECKPOINT" \ --to running ``` Use Claude Code-native tools for exactly the bounded action described by `nextAction`. Do not turn one attempt into an unbounded plan. ### 2. Enter verification After the action, move to verification before deciding the outcome: ```bash node "$SKILL_DIR/scripts/checkpoint-loop.mjs" transition \ --file "$CHECKPOINT" \ --to verifying ``` Run the relevant check yourself. The helper records a check name and outcome; it never runs that check for you: ```bash node "$SKILL_DIR/scripts/checkpoint-loop.mjs" evidence \ --file "$CHECKPOINT" \ --check "npm test -- workspace migration" \ --outcome passed \ --artifact "artifacts/migration-test.txt" ``` Only cite an artifact that exists and is safe to share. A failed check can be recorded with `--outcome failed`; do not convert it to a passing record by rewriting the expected value. ### 3. Finish, retry, or escalate If verification is genuinely passing: ```bash node "$SKILL_DIR/scripts/checkpoint-loop.mjs" transition \ --file "$CHECKPOINT" \ --to succeeded ``` If the change needs another bounded attempt, provide a concrete next action and reason: ```bash node "$SKILL_DIR/scripts/checkpoint-loop.mjs" transition \ --file "$CHECKPOINT" \ --to running \ --next-action "Fix the null-row fixture and rerun the focused test" \ --reason "Verification found a reproducible null-row failure" ``` Use `failed` for a terminal technical failure. Use `blocked` only when progress needs an external dependency or human decision: ```bash node "$SKILL_DIR/scripts/checkpoint-loop.mjs" transition \ --file "$CHECKPOINT" \ --to blocked \ --reason "Waiting for the database owner to approve the production window" ``` ### 4. Resume after interruption Read the checkpoint before doing any work in a new session: ```bash node "$SKILL_DIR/scripts/checkpoint-loop.mjs" status \ --file "$CHECKPOINT" \ --format summary ``` For machine-readable recovery, omit `--format summary`. Continue from `nextAction`, inspect the history and evidence, and never repeat a completed attempt merely because the old conversation is unavailable. ## Safety Rules - Use a positive, finite attempt budget. A loop without a ceiling is not a recoverable loop. - Never mark `succeeded` without passing verification evidence in the checkpoint. - Do not place secrets or full sensitive logs in the checkpoint; store only a safe check name and sanitized artifact path. - The helper does not run evidence commands. Execute checks with normal approval and tool policy, then record their observed result. - Destructive actions, external writes, payments, deployments, and permission changes still require the normal human approval boundary. - Treat a malformed or manually edited checkpoint as invalid and stop for review; do not guess its missing state. ## Examples ### Interrupted migration An agent initializes `data-migration` with three attempts, enters `running`, updates the migration, and is interrupted before verification. The next session runs `status`, sees `running` and the saved `nextAction`, performs only that action, then records the actual test result before moving to `succeeded` or a bounded retry. ### Attempt ceiling reached An agent records a failed verification, transitions back to `running` with `maxAttempts: 2`, and fails the same focused check on the second attempt. A third transition into `running` is rejected with `attempt budget exhausted`; the agent must report the failure or escalate rather than silently looping forever. ## Verification The script has a local Node test suite covering legal transitions, terminal immutability, attempt limits, evidence rules, malformed input, atomic persistence, and rejected-operation preservation: ```bash node --test "$SKILL_DIR/scripts/checkpoint-loop.test.mjs" ``` The repository validator checks the frontmatter and directory/name contract: ```bash node scripts/validate-skills.js ```