convez.ai
SkillAutomaçãoAvançado
criscatalyst

Loop Builder

criscatalyst/loop-builder

Engenharia de loops: design uma vez, aprove o plano, verifique o resultado.

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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-builder

1 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

Estrelas
4
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 claude CLI 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.

FileRoleChanges mid-run?
VISION.mdThe compass: why the task exists, direction, and non-goals. Every agent re-reads it each pass.No
specs/*.mdThe what: requirements per topic, as behavioral outcomes — no implementation detail.Rarely
IMPLEMENTATION_PLAN.mdThe prioritized task list. Generated in planning. Live status.Yes (each pass)
AGENTS.mdThe operational how: build/test/lint commands + learnings. <60 lines.Yes (append learnings)
PROMPT_plan.md / PROMPT_build.mdThe loop instructions for each mode.No
loop.shThe bash engine that drives it all.No

The four principles that make it work

  1. Fresh context every pass — one task per iteration keeps the model sharp; no context rot.
  2. Backpressure beats direction — wrong output is rejected automatically by tests/lint/build, so the agent self-corrects before committing.
  3. Maker/verifier split — a separate verifier checks the work, because models skew positive grading themselves.
  4. 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:

  1. Ask a couple of clarifying questions (non-goals, run mode).
  2. Scaffold loops/healthz-endpoint/ with the harness files.
  3. Run planning → show you the plan.
  4. On your "go", loop the build until the tests pass.
  5. 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 shapeEngine
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 loopThe 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 liveThe 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:

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados