Loop Builder

/loop-builder — design the harness, then run the loop

Stop prompting an agent step by step. Instead, define the goal + a verifiable done-condition; this skill generates the whole file-based harness on disk and then runs the loop. You only verify the output.

Promise: from "I babysit every step in case it errors" → "I approve a plan, then I verify the result."

This is loop engineering: the leverage is no longer the single prompt, it's the system that prompts, runs, and verifies the agent until the goal is met. See README.md for the full background and credits.

When to use

• A long, powerful task: a new feature, a big refactor, a new tool/script, a content batch, a migration.
• The user says: "build a loop", "create a loop for X", "set this up to run on its own", "/loop-builder".

Do NOT use for: 5-minute one-shots, tasks with no objective done-condition, pure-judgment decisions, or single irreversible actions (those stay direct-confirm).

Guiding principles (loop engineering)

1. State lives on disk, not in context. Each iteration starts from fresh context and reloads the files.
2. VISION.md does not change during the run (the compass). The PLAN changes (the task order).
3. Backpressure beats direction: wrong output is rejected by an automatic eval-gate (tests/lint/build), not by the human.
4. Maker/verifier split: the agent that builds ≠ the agent that verifies (models skew positive grading their own work).
5. Ratchet: every agent mistake → one line in AGENTS.md, traceable to a real failure.
6. The human "sits on the loop, not in it": design + review, not in the per-step seat.

Flow (3 phases, only 2 human touchpoints)

INTERVIEW (interactive, 4-5 questions)
      │
SCAFFOLD loops//  +  PLANNING mode  →  IMPLEMENTATION_PLAN.md
      │
   ┌──┴── GATE 1: human approves VISION + PLAN   (the "design")
   │
BUILDING loop (autonomous: maker/verifier, backpressure, commit per task)
      │
   ┌──┴── GATE 2: human verifies the output (diff + eval results)   (the "verify")

PHASE 1 — Interview (interactive, terse)

Ask only these (a single multi-question prompt is ideal). Nothing more.

1. Goal — what must be true at the end? (1-2 sentences)
2. Objective done-condition — how is "finished" verified automatically?

• Code/software → "tests pass + lint clean + build ok + runs locally"
• Content/docs → "passes the style guide + readability ≥ threshold + matches the brief"

1. Non-goals — what is explicitly out of scope? (prevents scope creep / slop)
2. Verify commands — the concrete gate commands (e.g. pytest -q, npm test, npm run lint, npm run build).
3. Run mode — run now in this session (you watch it), or run unattended in the background (see Engines).

If the user already gave goal + done-condition, skip the covered questions. Infer the rest and state your assumptions; don't ask for the sake of asking.

PHASE 2 — Scaffold + Planning (autonomous)

2a. Create the folder

./loops// at the project root (kebab-case slug from the goal). Keep it inside the git repo so each iteration is a checkpoint.

loops//
├── VISION.md                 # the compass (does not change mid-run)
├── specs/.md          # requirements per topic (outcomes, no implementation)
├── IMPLEMENTATION_PLAN.md    # generated in planning; live status
├── AGENTS.md                 # build/test/lint commands + learnings (/` files persist — the loop is re-runnable and improves each run (eventual consistency). For a recurring loop, wire `loop.sh` into your OS scheduler.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [criscatalyst](https://github.com/criscatalyst)
- **Source:** [criscatalyst/loop-builder](https://github.com/criscatalyst/loop-builder)
- **License:** MIT

Install and usage instructions live in the source repository linked above.