Loop Builder
criscatalyst/loop-builder
Engenharia de loops: design uma vez, aprove o plano, verifique o resultado.
Ver no GitHubSkill Claude para construir loops de agentes autônomos baseados em arquivos, onde você desenha o sistema uma vez e verifica o resultado final, sem babysitting de cada passo. Usa bash em máquina única, sem infraestrutura especial, com gates de aprovação explícitos e backpressure automática.
Instalação
npx convez-ai criscatalyst/loop-builder1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de tarefas longas com verificação autônoma
- Pipelines de agentes que se auto-corrigem via testes/linting
- Projetos que requerem múltiplas iterações com rastreabilidade
Veredito

Ferramenta sofisticada para quem quer sair do ciclo de prompts manuais repetitivos. A abordagem de file-based harness com maker/verifier split é pragmática e escalável, mas exige disciplina no design inicial da VISION e specs. Recomendado para projetos complexos que rodam desatendidos.
README
A tradução para o português deste README ainda está na fila.
🔁 loop-builder
A Claude Code skill that builds the harness for a long task before running it — so you design the loop once and only verify the output, instead of babysitting every step.
Stop prompting your agent one step at a time. Define a goal and a verifiable done-condition; loop-builder scaffolds a file-based loop on disk (vision, specs, plan, prompts, engine), runs a planning pass, asks for one approval, then loops autonomously until the work clears your requirements — and hands you back a diff plus the proof it passed.
This is loop engineering: the leverage moves from the quality of a single prompt to the design of the system that prompts, runs, and verifies the agent.
Works on a single machine. No special infrastructure, no second computer. The only dependency for unattended runs is the
claudeCLI and a git repo.
Why
For the last couple of years we prompted agents one task at a time, driving every step by hand. The shift: you build a loop that handles discovery → planning → work → checking → iterating until the goal is met. One human role remains — stay the engineer: you design the boundaries and verify the result. You don't sit in the loop, you sit on it.
The hard-won lesson from people running these at scale: an unbounded "open" loop with a loose standard becomes a slop machine. So loop-builder builds a closed loop by default — a bounded path with an eval-gate at each step that runs on a normal budget and gets better every pass.
How it works
INTERVIEW (4-5 questions)
│
SCAFFOLD loops/<slug>/ + PLANNING → IMPLEMENTATION_PLAN.md
│
┌──┴── GATE 1: you approve VISION + PLAN ← the "design"
│
BUILDING loop (autonomous: maker → verifier → commit, one task per pass)
│
┌──┴── GATE 2: you verify the output (diff + eval results) ← the "verify"
Only two moments need you: approve the plan, then verify the output. Everything in between is autonomous.
The harness (files on disk)
A powerful loop doesn't live in the context window — it lives in files that every iteration reloads into a fresh context. That's what keeps the model in its "smart zone" and lets the loop run for hours without context rot.
| File | Role | Changes mid-run? |
|---|---|---|
| VISION.md | The compass: why the task exists, direction, and non-goals. Every agent re-reads it each pass. | No |
| specs/*.md | The what: requirements per topic, as behavioral outcomes — no implementation detail. | Rarely |
| IMPLEMENTATION_PLAN.md | The prioritized task list. Generated in planning. Live status. | Yes (each pass) |
| AGENTS.md | The operational how: build/test/lint commands + learnings. <60 lines. | Yes (append learnings) |
| PROMPT_plan.md / PROMPT_build.md | The loop instructions for each mode. | No |
| loop.sh | The bash engine that drives it all. | No |
The four principles that make it work
- Fresh context every pass — one task per iteration keeps the model sharp; no context rot.
- Backpressure beats direction — wrong output is rejected automatically by tests/lint/build, so the agent self-corrects before committing.
- Maker/verifier split — a separate verifier checks the work, because models skew positive grading themselves.
- Ratchet — every mistake becomes one line in
AGENTS.md, traceable to a real failure. The harness hardens over time.
VISION.md — the part that keeps agents aligned
VISION.md is the constitution every agent reloads on every iteration so the whole loop steers toward the same north. It does not change during a run (the plan changes, the vision doesn't). Its most important section is Non-goals — explicit boundaries are what stop a loop from drifting into slop. Division of labor: the vision sets the boundaries, the specs set the requirements, the plan sets the order, AGENTS.md sets the commands, and the backpressure (tests) is the judge.
Install
loop-builder is a standard Claude Code skill — a folder with a SKILL.md.
Option A — clone into your skills folder:
git clone https://github.com/<you>/loop-builder.git ~/.claude/skills/loop-builder
Option B — project-local skill:
git clone https://github.com/<you>/loop-builder.git .claude/skills/loop-builder
Then in Claude Code just say "build a loop for X" or /loop-builder. Confirm it's registered with /skills.
Requirements: the claude CLI on your PATH (for unattended loop.sh runs) and a git repository in your project (each iteration commits a checkpoint).
Quickstart
In Claude Code, in your project:
build a loop to add a /healthz endpoint to my API.
done = `pytest -q` passes and `curl localhost:8000/healthz` returns 200.
The skill will:
- Ask a couple of clarifying questions (non-goals, run mode).
- Scaffold
loops/healthz-endpoint/with the harness files. - Run planning → show you the plan.
- On your "go", loop the build until the tests pass.
- Hand you the diff + the passing test output to verify.
To run the build loop unattended yourself:
cd loops/healthz-endpoint
./loop.sh build 15
Engines
loop-builder picks the right engine for the task; all of them work on one machine.
| Task shape | Engine |
|---|---|
| Anything, unattended, single machine (default) | loop.sh — a bash while loop feeding PROMPT_build.md to claude -p until the plan is DONE. Zero extra deps. |
| Long overnight closed loop | The official ralph-wiggum plugin: /ralph-loop "<task>… output DONE when finished" --max-iterations N --completion-promise DONE. Install with /plugin install ralph-wiggum@claude-plugins-official. |
| Interactive, watch it live | The skill runs the loop steps directly via subagents (a maker + a separate verifier) so you can watch the first runs while you build trust. |
| Recurring heartbeat (triage, digests, nightly builds) | Your OS scheduler runs loop.sh on a timer: cron/launchd on macOS/Linux, Task Scheduler on Windows, or a tmux session. No second machine needed. |
Running a recurring loop on one machine (cron example)
# every night at 02:00, run the build loop and log it
0 2 * * * cd ~/myproject/loops/nightly-cleanup && ./loop.sh build 10 >> loop.log 2>&1
Guardrails
The loop is autonomous, not reckless. Even unattended:
- Irreversible/external actions (deploy, push to prod, send email/DM, delete) → the agent stops and asks. Never auto.
- Backpressure, not faith — nothing is "done" until the verify commands pass. Green-but-broken is rejected.
- Escape hatch — stuck twice on the same task → it marks
BLOCKED, moves on, and reports at handback. - Checkpoints — every iteration commits to git, so any pass is revertible.
- Stay the engineer — read the diffs. The comfortable posture (rubber-stamping loop output) is the dangerous one. Watch for comprehension debt: code shipping faster than you understand it.
Repository layout
loop-builder/
├── SKILL.md # the skill Claude Code loads
├── README.md # this file
├── LICENSE
└── templates/ # copied into loops/<slug>/ at scaffold time
├── VISION.md
├── spec.md
├── IMPLEMENTATION_PLAN.md
├── AGENTS.md
├── PROMPT_plan.md
├── PROMPT_build.md
└── loop.sh
See examples/ for a filled-in loop.
Credits & further reading
The patterns here stand on the shoulders of the people who named and proved them:
- Shann Holmberg — "what is agent looping" (open vs closed looping, fleet looping)
- Peter Steinberger — "design loops that prompt your agents" / OpenClaw
- Addy Osmani — Loop Engineering & Agent Harness Engineering
- Boris Cherny (Claude Code, Anthropic) — "I have loops running that prompt Claude"
- Geoffrey Huntley — the Ralph Wiggum technique; the Ralph Playbook by Clayton Farr
- Anthropic — the official
ralph-wiggumplugin
License
MIT — see LICENSE.