Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
Refactor / change path
There is no “refactor the whole project” pattern. That is deliberate. A multi-file rewrite sits in the high-risk zone in safety.md (denylist + max-files). Loop engineering’s job is to decompose that work and run each slice through a maker → verifier → human loop — not to L3 the tree overnight.
If you arrived from “I have a refactor, how do I break it into todos and automate it?” — this is the tutorial. Companion for run-until-done on a scoped objective: goal-engineering.
The boundary
| This repo (loop-engineering) | Goal-engineering |
|---|---|
| Discovers work (triage), babysits PRs, sweeps CI | Finishes a named objective (/goal) |
STATE.md is a queue |
A goal has a done-definition and a verifier |
| Cadence loops (1d, 15m) | Run until the goal is met or the budget trips |
Use both: triage to list the slices, /goal (or a human) to implement one slice, PR babysitter to land it.
Path (L1 → L2 → maybe later L3)
0. Scaffold, do not code
npx @cobusgreyling/loop init . --pattern daily-triage --tool claude
npx @cobusgreyling/loop doctor .
Default --tool is claude. Use opencode for a CLI agent on cron; grok / codex work the same. This writes STATE.md, LOOP.md, loop-budget.md, loop-run-log.md, and constraints. Week one: report only.
1. Inventory (L1)
Run daily triage against the repo. The output belongs in STATE.md High Priority / Watch — dead code, missing tests, modules to split — not in a 40-file PR.
- Pattern: daily-triage
- OpenCode: examples/opencode/daily-triage.md
A single High Priority line should be small enough for one PR (one module, one test gap, one rename). If it is not, split it before anyone codes.
2. One todo = one worktree = one PR (L2)
For each High Priority item:
npx @cobusgreyling/loop-worktree create --run-id <id> --pattern pr-babysitter(or a manual git worktree).- Implementer changes only that slice.
- Independent verifier runs the project tests — not the same session, not “looks good”.
- Human reviews the PR. The loop does not merge.
- Pattern: pr-babysitter
- OpenCode: examples/opencode/pr-babysitter.md · starter: starters/pr-babysitter-opencode
- Isolation: loop-worktree · loop-sandbox
Optional: name the slice as a /goal in goal-engineering so the agent has an explicit done-definition instead of “keep refactoring.”
3. Automate only what you already trust
After several L2 slices have landed with a real verifier:
- Formatting, tests-only, docs: may go on an auto-merge allowlist (
gate.yaml). - Core logic, public API, auth, payments: denylist, forever, human merge.
- Check loop-design-checklist.md before anything unattended.
- Do not jump to L3 on the refactor as a whole.
4. After each merge
Post-merge cleanup for leftover TODOs and changelog noise. Then the next STATE.md line.
Why not one L3 loop?
- Attempt caps exist because infinite fix loops are a known failure mode.
maxFilesingate.yamlwill escalate a “rewrite src/” diff.- A verifier in the same run as the implementer is theater.
- Token budget on a whole-repo rewrite will burn before the tests go green.
The valuable move is boring: many small PRs, each with a verifier, each with a human on the merge button until the allowlist has earned the right to grow.
Related
- jobs.md — if you wanted a different job
- QUICKSTART.md — 5-minute scaffold
- safety.md — denylist / max-files
- loop-design-checklist.md — L3 gates