build-loop
A plugin for Claude Code that turns big code changes into a checked, repeatable workflow.
What it is
Build-loop runs your code change through five phases — plan, execute, review, iterate — plus a mandatory Learn step that runs after every build. It splits the work into safe parallel chunks where it can. A critic reads the diff before tests run, so cheap checks catch the obvious mistakes first. Tests must actually pass. Every number on the page traces back to a real source. Fake data in production paths gets flagged. The build stops if what you shipped does not match what you said you would build. The plugin picks the right model for each task: a strong model to plan and review, a faster model to write code, a small model for pattern checks.
Why use it
Big changes break things. You forget an edge case. You skip the test pass. The diff drifts from the plan. The implementer makes a quiet design call you never see. Build-loop catches all of that before the change ships.
- One source of truth. The plan lists every design decision up front. The implementer must say which decisions it made. A lint compares the claim to the actual diff. If the two do not match, the loop stops.
- Speed where you can, depth where you must. Mechanical work runs in parallel on a fast model. Work with five or more design decisions auto-routes to the strong model in one pass. Five is the cutoff measured in our testing where the fast model lost cross-decision context.
- Real evidence, not vibes. Every pass or fail has a code-based grader. Every metric on a page traces back to its data source. Tests must run. Output must render. Placeholders get flagged.
- Less rework. A read-only critic runs before full validation. Cheap checks catch the obvious mistakes first.
- A way to actually improve a number. Run multiple tests in a single experiment using Design of Experiments and other statistical methods. You can test six variables at once instead of one. The optimize mode plans the test matrix, runs each combination, and tells you which variable actually moved the number.
You ship fewer regressions. You get a clean record of what changed and why. You can trust the workflow on changes that touch many files at once.
Get started
Install the plugin via the RossLabs AI Toolkit marketplace (recommended) or directly from the build-loop repo.
# Recommended — via the RossLabs AI Toolkit marketplace (includes companion plugins):
/plugin marketplace add tyroneross/RossLabs-AI-Toolkit
/plugin install build-loop@rosslabs-ai-toolkit
# Or direct — install from the build-loop source repo alone:
/plugin marketplace add tyroneross/build-loop
/plugin install build-loop@build-loop
Run a build.
/build-loop:run add user notification system with email and push
Skip the loop for small fixes (under about 20 lines, single file, no new endpoint). For everything else, run it through the loop. That includes features, refactors, migrations, schema changes, and anything that crosses a file or system boundary.
Debug a failing system.
/build-loop:debug tests pass locally but fail in CI
Detail on each phase, the model tier rules, the synthesis-decision lint, the architecture engine, and the debugger is below.
Phases
| # | Phase | Purpose |
|---|
| 1 | Assess | Understand state (project type, architecture, tools, prior state) AND define goal + 3-5 scoring criteria with pass/fail conditions |
| 2 | Plan | Task breakdown with dependency order and parallel-safe groups |
| 3 | Execute | Build it — parallel subagents for independent work |
| 4 | Review | Critic → Validate → Optimize (opt-in) → Fact-Check → Simplify → Report — six ordered sub-steps, single exit point; routes to Iterate on failure |
| 5 | Iterate | Fix Review failures, loop back to Review (max 5x) |
| 6 | Learn (mandatory) | Always runs and always emits a ## Learn outcome line in the Review-G report. Three states: accruing (runs[] < 3 — detector + memory consolidation only), deferred (debug-only or budget-exhausted — writes a marker, skips Sonnet draft), or full (runs[] >= 3 + a pattern crossed threshold — detector + Sonnet draft + Opus signoff). Reads two signal sources: state.json.runs[] and proposals/enforce-from-retro/ (recurring enforce-candidates across runs). |
Supply-chain: dependency cooldown
Build-loop refuses to install third-party JS packages (or version bumps) until the resolved version has been published for at least 7 days, mitigating smash-and-grab npm compromises (a malicious version published then yanked within hours-to-days never reaches your lifecycle scripts). Defense-in-depth, three layers:
