loop

Load when the user asks for a repeating autonomous mode: "loop 10 30m <prompt>", "loop 99 6666 <prompt>", "work cycle after cycle", "keep going until it's done", "continue on your own, don't stop", "f

SKILL.md

GitHub

loop — repeating autonomous iterations

The agent does not "answer and stop": it goes iteration after iteration — a full work cycle → a checkpoint on disk → immediately the next iteration with a new angle. It stops only on explicit criteria, not out of the habit "answered — enough".

Invocation format

loop [N] [M] [prompt]
Argument Rule
N number of iterations (integer)
M minute limit (integer or with m/h suffix). Both N and M set — stop at whichever comes first
prompt task/goal, rest of the line. Not set — continue from the last checkpoint

Limits are owner-supplied, never invented: when neither N nor M is given, the run is bounded by the readiness criterion and the no-progress stop only, and the opening message says exactly that. Do not silently substitute a default budget.

Examples:

loop 10 30m run an audit and close findings one by one
loop 99 6666 invent improvements and ship them turn after turn
loop improve the release checklist   # no N/M → readiness + no-progress stops
loop                                 # continue from the last checkpoint

These are plain requests to the agent, not slash commands: the trigger is the owner saying "keep going until done" / "work in cycles", not a client command.

When to use / NOT to use

Use: the user explicitly asks for a loop; "do N iterations"; "keep going until it's done"; a series of sequential improvements where each next step depends on the previous result.

NOT to use: a single task — the task-cycle skill; unattended assigned-goal work with its own stop contract — loops/parts/autonomous-work; parallel decomposition of ONE task by subagents — a host tool capability this loop does not own, so when the host exposes spawn_agents fan out directly instead of through a loop request (fan-out is not iteration); a trivial request — just do it.

Workflow

0. Initialization (once).

  1. Record the task as a Memora node under root/skill/loops (project branch when the work belongs to a project) and mirror the open steps in write_todos.
  2. Write the start checkpoint (format below) into that node, with the plan for the first iterations.
  3. Record the start time: date +%s (for the M limit, not by feel).
  4. Define the readiness criterion: what must be visible at the end (green tests, N findings closed, empty backlog, a concrete file/state). If the criterion cannot be formulated — ask the owner before iterating.

1. Iteration (repeats). Each iteration is a compact work cycle:

  1. Iteration angle: one phrase — what this iteration does and HOW it differs from the previous one (new hypothesis, other source, other tool, other order). Repeating the previous iteration is forbidden.
  2. Prior knowledge: targeted lookups in Memora (this branch and the domain that matches the topic), then knowledge/ and project docs — so we don't repeat or argue with our own conclusions.
  3. Action: research per the step type → edits/experiment → verification (the project's real checks plus the usage path; "it built" ≠ "it works").
  4. Findings: record what you chose, why, what you rejected, links — as a Memora node (bidirectional supersedes when it replaces an earlier one). Iterations without a record are wasted iterations.
  5. Checkpoint delta: append the checkpoint (format below) — short, only non-obvious.
  6. Summary to the owner: 1-2 lines — iteration X/N done, what was done, what's next.

2. Transition to the next iteration.

  • Progress exists → the next iteration develops the previous one (the next finding, the next plan step).
  • No progress for 2 iterations in a row → change the angle (another hypothesis, another source, another tool); do not hammer the same thing a third time (an error twice = change the method).
  • Before starting an iteration, check the limits: iterations done ≥ N? Minutes elapsed ≥ M (date +%s against start)? Readiness criterion reached AND verified? Yes → phase 3, no → iterate.

3. Stop and final.

  1. Close the task node in Memora with a one-two line result and the stop reason.
  2. Final report to the owner: what was done across all iterations, what remains, how to continue (a loop request with no arguments resumes from the last checkpoint).
  3. Stop always with a named reason: which criterion exactly fired.

Progress detector & retry policy

  • Repeat fingerprint: hash (step+result) per turn; 2 identical turns with no new information = stop criterion → change angle.
  • Retries by class: validation/auth/permanent → STOP; 429/timeout → 2-3 retries with backoff+jitter; safety/irreversible → owner confirmation; everything else → 1 retry.
  • Budgets: owner-supplied N/M only — never invented; exceeding any stated limit = stop with reason. Expensive operations get a cost mention before, not after.

Checkpoint format

loop: iteration X/N (or X iterations, M min)
done: <what this iteration completed>
decisions: <what you chose and rejected, one line>
next: <the next iteration's angle — one line>
files: <what changed>

~100 words limit. The checkpoint is the fuel of resumption: reading the node back must restore context after a session restart or compaction.

Success criteria

  • N iterations (or M minutes) completed, each with a finding and a checkpoint (check: the Memora node has ≥ N+1 entries).
  • Or earlier: the readiness criterion reached AND verified by a check (not claimed in words).
  • Each iteration differs from the previous one — visible from the checkpoints.
  • Stop always with a reason; the task record is closed.

Failure modes

Symptom What to do
Repeats the same iteration The angle-change rule after 2 no-progress iterations — apply, don't discuss
Context running out (>50-60%) Don't start a new iteration: checkpoint + tell the owner "say loop — I'll continue from the checkpoint"
Owner doesn't see progress 1-2 line summary after EVERY iteration — mandatory, not optional
Stopped without a reason Stop only by phase 3 criteria; the reason goes in the report
Decisions not recorded Every iteration must leave a finding; otherwise knowledge dies with the context

Gotchas

  • Keep the iteration counter EXPLICIT in every checkpoint (iteration X/N) — from memory the agent errs in both directions.
  • Minutes — by date +%s, not by felt time.
  • Expensive/irreversible/outward-facing actions — owner confirmation even inside the loop (the irreversibility gate). Never Destroy outranks any loop.
  • Secrets — placeholders only, even in checkpoints.
  • "Readiness criterion reached" — only after verification by a check; a green check that doesn't verify the feature is not done.
  • Iterations don't have to be big: a small verified step beats a large unverified one.
  • If the owner asks for 99 iterations and 6666 minutes: a BIG autonomous mode. Checkpoints are critical: without them everything is lost on context overflow.

References

  • The cycle behind one iteration and its gates: task-cycle and AGENTS.md § Engineering cycle.
  • Unattended assigned goal, checkpoints and valid stops: loops/parts/autonomous-work.
  • Loop patterns and design interviews: loops/parts/loop-library.