cobusgreyling/loop-engineering

Loop Engineering – Design, run and score autonomous AI‑agent loops

What it is – A CLI‑driven framework that helps you replace manual prompting with a repeatable “loop” that discovers work, hands it to LLM‑based agents (Claude, Grok, Codex, Opencode, etc.), verifies the output and records state. It ships with a library of ready‑made patterns (daily triage, PR babysitter, CI sweeper, etc.) that you can plug into any code repository and run locally or in GitHub Actions.

Why it matters – Building reliable AI‑agent pipelines is hard: you need to decide when the loop runs, how it scores its own work, and how to keep costs under control. Loop Engineering gives you a structured checklist, a STATE.md file that tracks the loop’s knowledge, and a scoring system (L1‑L3) that tells you when you can move from “report‑only” to fully unattended automation.

---

Core concepts

Concept	Explanation
Pattern	A pre‑defined workflow (e.g., daily-triage) that specifies cadence, initial safety level (L1‑L3) and expected cost.
Tool	The underlying LLM used for the agents (claude by default, also grok, codex, opencode).
STATE.md	A markdown file that persists the loop’s learned state; the CLI walks you through creating it the first time.
Loop Ready score	A numeric rating that reflects how well the loop is designed (recent runs weighted more heavily).
Levels	L1 = report‑only, L2 = assisted, L3 = unattended. You only promote after a week of correct verification.

---

Getting started (5‑minute quickstart)

# Initialise a loop in the current repo
npx @cobusgreyling/loop init . --pattern daily-triage --tool claude

# Run a health check
npx @cobusgreyling/loop doctor .

# See the cost estimate for your chosen pattern
npx @cobusgreyling/loop cost --pattern daily-triage --level L1

If you omit --tool the CLI defaults to Claude.

The command creates a STATE.md file and a small set of configuration files that describe what the loop will monitor (issues, CI, dependencies, etc.). After the first week you’ll get an L1 report showing what the loop would have done. When the verifier is consistently correct you can bump the level to let the loop act automatically.

---

Main patterns (pick one to start)

Pattern	Cadence	Week‑1 output	Typical cost
Daily Triage	1 day – 2 h	L1 report of repo health	Low
PR Babysitter	5–15 min	L1 watch of incoming PRs	High
CI Sweeper	5–15 min	L2 cautious fixes to flaky CI	Very high
Dependency Sweeper	6 h–1 d	L2 patch‑only updates	Medium
Changelog Drafter	1 d or on tag	L1 draft changelog	Low
Post‑Merge Cleanup	1 d–6 h	L1 off‑peak housekeeping	Low
Issue Triage	2 h–1 d	L1 propose‑only issue handling	Low

Each pattern lives in patterns/ with a markdown description and a YAML entry in patterns/registry.yaml. An interactive picker is available on the showcase site.

---

Example workflows

• Claude Code – uses Claude to generate code changes and includes a VS Code plugin.
• Grok daily‑triage – runs a Grok‑powered triage loop on a fresh repo.
• GitHub Actions thin loop – a minimal loop that can be added to a repo via a single workflow file, no extra STATE.md needed.

All examples are in the examples/ directory and can be run with the same CLI commands.

---

Safety & operating guidance

• Failure modes – documented in docs/failure-modes.md (e.g., runaway token usage, hallucinated fixes).
• Anti‑patterns – see docs/anti-patterns.md for common pitfalls like over‑automating without verification.
• Safety checklist – docs/loop-design-checklist.md walks you through verifying the loop before promoting to a higher level.
• Stories – real‑world successes and failures are collected in stories/ to help you learn from the community.

The project stresses that loops amplify human judgment; unattended loops can make costly mistakes, so the L1→L2→L3 progression is mandatory.

---

Community & contribution

• Adopters list – add your project via the “add‑adopter” issue template.
• Good first issues – labelled for newcomers; maintainers aim to respond within 48 h.
• Companion repos – optional extensions like memory-engineering, outerloop, etc., meant for later stages after a loop has proven reliable.

---

License

MIT – free to use, modify, and distribute.

---

Bottom line – Loop Engineering is a practical, pattern‑based toolkit for turning LLM agents into repeatable, auditable automation loops around a codebase. It gives you a clear onboarding path, safety scaffolding, and a scoring system to know when you can trust the loop to act on its own.