# Loop Builder

> Build a file-based agent loop (harness) for a long, powerful task BEFORE running it — so you design the loop and only verify the output, instead of supervising every step. Runs a short interview (goal, done-condition, non-goals, verify commands), scaffolds loops/<slug>/ with VISION.md + specs + IMPLEMENTATION_PLAN.md + AGENTS.md + PROMPT files + loop.sh, runs PLANNING, gets ONE plan approval, the…

- **Type:** Skill
- **Install:** `agentstack add skill-criscatalyst-loop-builder-loop-builder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [criscatalyst](https://agentstack.voostack.com/s/criscatalyst)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [criscatalyst](https://github.com/criscatalyst)
- **Source:** https://github.com/criscatalyst/loop-builder

## Install

```sh
agentstack add skill-criscatalyst-loop-builder-loop-builder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /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"
3. **Non-goals** — what is explicitly out of scope? (prevents scope creep / slop)
4. **Verify commands** — the concrete gate commands (e.g. `pytest -q`, `npm test`, `npm run lint`, `npm run build`).
5. **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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-criscatalyst-loop-builder-loop-builder
- Seller: https://agentstack.voostack.com/s/criscatalyst
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.