davepoon/buildwithclaude / plugins/all-skills/skills/checkpointed-agent-loop
checkpointed-agent-loop
UnverifiedRun long or failure-prone Claude Code tasks as bounded, resumable loops with a durable state machine, attempt budget, and verification evidence checkpoint.
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:
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:
SKILL_DIR="<absolute path to the installed checkpointed-agent-loop skill>"
CHECKPOINT=".agent/checkpoints/task.json"
Initialize with a finite budget:
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:
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:
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:
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:
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:
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:
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:
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
succeededwithout 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:
node --test "$SKILL_DIR/scripts/checkpoint-loop.test.mjs"
The repository validator checks the frontmatter and directory/name contract:
node scripts/validate-skills.js
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 463k | Updated | Claude CodeCodex | Verified | Install |
| discernment-nudgeanthropics/skillsAfter you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| internal-commsanthropics/skillsA set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.). | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |