auto-loop

Files (6)

• SKILL.md
• example-setups.md · references/
• iteration-protocol.md · references/
• progress-document.md · references/
• stop-conditions.md · references/
• subagent-brief.md · references/

SKILL.md (first lines)

# auto-loop

Work one goal round after round, unattended, until measurable criteria say it is done — or until a
defined brake stops the run and hands control back with a report.

## Contract

- **Input:** a goal, plus the parameters the setup interview turns it into something verifiable.
- **Output:** one Markdown document at `docs/auto-loop/YYYY-MM-DD-<slug>.md`, written *during* the
  run and closed with a report, plus commits on a dedicated branch.
- **Not in scope:** deciding *what* should be built. auto-loop supplies endurance, not requirements
  work, not architecture, not root-cause analysis. A goal that is not yet clear enough to check by
  command belongs in `create-dev-spec` / `create-dev-plan` first; a goal that asks *why* something
  happens belongs in `diagnose-bug`. See Phase 0.
- **Two interactions, and only two:** the setup interview, and the go. Between the go and a brake,
  the loop does not ask. That is the entire point — and the reason the setup has to be thorough.

**Commits — deliberately, unlike the rest of this family.** Every other cc-ai-dev skill leaves
history to the user. This one cannot. A run of twenty rounds without checkpoints has no "back to
the last good state", and it ends in one sprawling working-tree diff that nobody can review round by
round. So the loop works on its own branch and commits each green iteration. The user's branch is
never touched, nothing is pushed, and nothing is merged — the branch is offered at the end and the
user decides what enters history.

## The one rule everything else serves

**The progress document is the loop's only memory.**

In sub-agent mode this is literal: each round is a fresh agent whose entire knowledge of the run is
that file. In in-session mode it is true in practice — a long run gets compacted, and you do not get
to choose when. And in both modes it is the user's only window into an unattended process they were
promised they would not have to watch.

So anything learned that is not written down is lost, and a loop that forgets rediscovers the same
dead end every round. That is the single most common way a loop like this burns a budget without
moving. Write the plan for a step *before* taking it, and write the outcome the moment it is known —
not at the end of the round, when a crash or a compaction can still eat it.

## Principles

1. **Measurable or it does not count.** A success criterion has to be checkable by a command, or by
   an inspection whose result two people would agree on without discussion. "The code is cleaner"
   cannot end a loop, because nothing can ever decide it. `dotnet test` exits 0, `rg -c TODO src`
   reports 0, "the endpoint returns 201 for a valid payload" — those can.

2. **One step per iteration.** When a round changes five things and verification goes red, you
   cannot tell which one did it, and the rollback throws the four good ones away with the bad one.
   Small rounds also keep the commit log readable, which is what makes the run reviewable afterwards.

   A step is one *change*, not one file. Where something else encodes the behaviour you are
   changing — a caller comparing against the old form, a data file keyed by it — that belongs in the
   same step, because neither half leaves the repository in a verifiable state alone. Foreseeing the
   coupling and doing both at once is the good case; discovering it only when verification goes red
   is what `references/iteration-protocol.md` step 8 handles. Same judgement, two different moments.

3. **A red round is information, not failure.** Its value is the approach it rules out. Record what
   was tried, the actual error, and why you now believe it failed — that record is the most useful
   thing the next round will read. A run of six rounds where four were red and the document explains
   all four is healthy; a run where reds vanish silently is a run that will retry them.

4. **Never weaken the instrument.** Do not edit tests, assertions, verification commands, or success
   criteria to make a round green. A loop that can move its own goalposts always succeeds and never
   delivers. If the criteria turn out to be wrong or contradictory, that is a brake — stop and ask.
   Criteria are frozen at the go.

5. **Never widen the goal.** Something else worth fixing will show up; note it in the document's
   *Found, not fixed* section and leave it. An unattended loop that also does unrequested work is
   unreviewable, and the user agreed to the scope, not to your judgement about it.

6. **The brakes exist because the loop cannot see itself.** From inside round eleven, "I am making
   progress" and "I have been rewriting the same file for six rounds" feel identical. That is why
   progress is measured against a number recorded before the run, not against a feeling.

## Workflow

```
Phase 0: Preconditions           → clean tree, git, baseline run
    ↓
Phase 1: Setup interview         → parameters, each with a recorded origin
    ↓
Phase 2: Loop plan + document    → docs/auto-loop/<date>-<slug>.md, user gives the go
    ↓
Phase 3: The loop ─── read doc → check brakes → one step → verify ───┐
    ↓                   green: commit · red: keep or roll back, record │
    │                        └───────────────────────────────────────┘
Phase 4: Termination + closing report
```

### Phase 0 — Preconditions

Four things have to be true before a setup interview is worth anyone's time.

**A loop-shaped goal — check this first.** auto-loop grinds through a known kind of change until a
number reaches zero. It is the wrong instrument for finding something out: "why does this fail
sometimes", "where is the leak", "which commit broke it". A diagnosis has no metric a round can
move, so the loop would iterate without a hypothesis and neither progress nor stagnation would be
decidable. Route those to `diagnose-bug`; route a goal too vague to check to `create-dev-spec` or
`create-dev-plan`.

Saying so and stopping is a complete outcome, not a failure to start. Write nothing — no branch, no
document, no commit — name the skill that fits, and offer auto-loop for the step after it: once the
cause is known, "apply the fix and prove it across the suite" is exactly loop-shaped.
`references/example-setups.md` section 3 works this distinction through on a flaky test.

**Explicit invocation.** This skill starts only when the user named it. It is not the answer to
"just keep going" — that is a request to continue the current work, not to hand over control of the
working tree for the next hour.

**A clean working tree.** `git status --porcelain` must be empty. Rollback of a red round is a
`git reset --hard`, and uncommitted work of the user's would be destroyed by it. If the tree is
dirty, stop, list what is there, and let the user commit or stash first.

If the directory is not a Git repository, say so plainly: red rounds cannot be rolled back and
green rounds cannot be checkpointed, so the run degrades to "hope". Offer Git strategy `none`
(see Phase 1) only if the user insists after hearing that, and record it as a decision.

**A baseline run.** Run the verification commands once, before anything else, and record the result
in the document. This is not ceremony:

From CreativeCodersTeam/ai-store, Apache-2.0.

More from CreativeCodersTeam/ai-store