---

name: stop-hook-goal-loops description: Use when you want a coding agent to keep making progress against a standing backlog (a never-ending TODO, a QA tracker) by re-prompting itself on completion via a Stop hook, and you need the loop to stay bounded, committed, and reviewable rather than running away.

Stop-Hook Goal Loops for Standing Work

When to trigger

A repo has a durable backlog (for example a NEVERENDING-TODO.md or a QA.md) and you want the agent to pick the next highest-value items, ship them, and continue, instead of stopping after one batch.

How the loop works

A Stop hook fires when the agent finishes a turn. It can block the stop and feed a follow-up instruction, which restarts the agent on the next batch. That turns "do a batch" into "keep doing batches against the backlog file".

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "path/to/next-batch.sh"
      }]
    }]
  }
}

The hook script decides whether to continue: if the backlog still has unchecked high-value items and a per-run budget is not exhausted, it emits the next instruction and blocks the stop; otherwise it lets the agent stop.

Honest framing: this is a governor, not a promise of autonomy

A Stop-hook loop keeps momentum, but it does not make the agent correct. Bound it so a bad run cannot spin:

• Commit after every meaningful change so each iteration is independently reviewable and revertible. A loop that batches all work into one commit is unreviewable.
• Cap the loop: a max iteration count, a wall-clock budget, or "stop when the backlog's P0 items are clear". An unbounded loop burns tokens on diminishing work.
• Keep a floor on quality per iteration (the type gate, the lint gate, the commit-tree check) so speed never ships breakage.
• Log what each iteration did and learned so the next run reprioritizes instead of repeating.

Agent floors, not just ceilings

If the loop fans work out to subagents, set a floor on how much each must accomplish (one shipped item, one committed change) so a batch cannot "complete" with nothing done. Pair that with the per-run ceiling above.

Pitfalls

• An unbounded Stop hook re-prompts forever and burns budget on low-value or already-done work. Always give it an exit condition.
• Batching an entire loop into one commit makes it impossible to review or bisect. Commit per meaningful change inside the loop.
• Skipping the type/lint gate to "keep the loop fast" ships breakage that compounds. Keep the floor on every iteration.
• A loop with no learning log repeats the same low-impact picks. Have each iteration record what worked so the next reprioritizes.