--- slug: "loop-engineering" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/cobusgreyling/loop-engineering@main/README.md" repo: "https://github.com/cobusgreyling/loop-engineering" source_file: "README.md" branch: "main" --- # Loop Engineering

Explore the Showcase

GitHub stars loop-audit dogfood loop npm loop-audit npm loop-init npm loop-cost npm loop-sync npm loop-context npm loop-mcp-server npm loop-worktree npm MIT Pages

Loop Engineering logo

> **Stop prompting. Design the loop. Get a score.**

Loop Engineering — design the system that prompts your agents

```bash # Front door (recommended) — one binary for init + doctor + status npx @cobusgreyling/loop init . --pattern daily-triage --tool grok npx @cobusgreyling/loop doctor . # Same as before (still fully supported — forks need not change) npx @cobusgreyling/loop-init . # Optional: also scaffold a versioned harness (harness-foundry) npx @cobusgreyling/loop init . --with-foundry ``` `loop init` (or `loop-init`) scaffolds skills, state, and budget files, then prints your **Loop Ready** score and first loop command. `loop doctor` combines audit + sync + file checks into top-3 next actions. Swap `--tool` for `claude`, `codex`, or `opencode`. Use `--with-foundry` when you want the loop as a composable runtime stack. See [docs/cli-front-door.md](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/cli-front-door.md).

Loop Ready score climbs from 10 to 100 in 15 seconds

Loop engineering replaces you as the person who prompts the agent — you design the system that does it instead. **New here?** [Quickstart (5 min)](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/QUICKSTART.md) · [Interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agents.

→ Interactive showcase + pattern picker · Essay · Addy Osmani

## Contents - [Quickstart (5 min)](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/QUICKSTART.md) - [Quick Links](#quick-links) - [Why This Matters](#why-this-matters) - [The Five Building Blocks + Memory](#the-five-building-blocks--memory) - [Patterns](#patterns) - [Getting Started (5 minutes)](#getting-started-5-minutes) - [Examples by Tool](#examples-by-tool) - [Operating & Safety](#operating--safety) - [Caveats](#caveats) - [Help wanted](#help-wanted) - [Contributing](#contributing) - [Sources](#sources) - [License](#license) ## Quick Links | Start here | Description | |------------|-------------| | [Quickstart (5 min)](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/QUICKSTART.md) | `loop init` → `loop doctor` → first loop — **start here if you just landed** | | [CLI front door](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/cli-front-door.md) | Unified `@cobusgreyling/loop` — old packages stay open | | [Loop Engineering essay](https://cobusgreyling.substack.com/p/loop-engineering) | The concept, primitives, and Grok mapping — read for the why | | [Pattern Picker](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/pattern-picker.md) | Which loop to run first — **start here if unsure** | | [Primitives Matrix](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/primitives-matrix.md) | Cross-tool loop primitive mapping — bookmark this | | [Loop Design Checklist](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/loop-design-checklist.md) | Ship readiness rubric | | [Patterns](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/patterns/README.md) | 7 production patterns + [interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) | | [Starters](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/starters/) | Clone-and-run kits (Grok, Claude Code, Codex, Opencode) | | [Opencode examples](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/examples/opencode/) | CLI-first loops: cron/systemd + `opencode run`, skills, worktrees | | [**loop** (front door)](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/tools/loop/) | **Unified CLI** — `npx @cobusgreyling/loop init \| doctor \| status \| audit \| cost` · [cli-front-door](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/cli-front-door.md) | | [loop-audit](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/tools/loop-audit/) | Loop Readiness Score CLI (v1.7 — constraints + governance + **Harness Runtime**) — `npx @cobusgreyling/loop audit . --suggest` · also `loop-audit` | | [loop-init](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/tools/loop-init/) | Scaffold starters + budget/run-log + constraints (v1.5) — `npx @cobusgreyling/loop init . --pattern daily-triage --tool grok` · also `loop-init` | | [harness-foundry](https://github.com/cobusgreyling/harness-foundry) | **Companion runtime:** versioned stacks, sessions, traces — `npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage` | | [outerloop](https://github.com/cobusgreyling/outerloop) | **Companion governance:** evidence → verdict → answerability | | [loop-cost](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/tools/loop-cost/) | Token spend estimator — `npx @cobusgreyling/loop-cost` | | [loop-sync](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/tools/loop-sync/) | Drift detection between `STATE.md` and `LOOP.md` — `npx @cobusgreyling/loop-sync .` | | [loop-context](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/tools/loop-context/) | Stateful memory manager + circuit breaker for long runs — `npx @cobusgreyling/loop-context --check --ledger run.json` | | [loop-mcp-server](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/tools/mcp-server/) | MCP runtime lookup for patterns, skills, state — `npx @cobusgreyling/loop-mcp-server` | | [loop-worktree](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/tools/loop-worktree/) | Manage isolated git worktrees per fix attempt — `npx @cobusgreyling/loop-worktree create --run-id --pattern

` | | [loop-gate](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/tools/loop-gate/) | Mechanical enforcement of the path denylist + auto-merge allowlist from `gate.yaml` — `npx @cobusgreyling/loop-gate check --action auto-merge --paths ` | | [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | **Companion:** loops discover, goals finish — `/goal` + [stack cookbook](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/stack-cookbook.md) (`npx @cobusgreyling/goal doctor .`) | | [Memory Engineering](https://github.com/cobusgreyling/memory-engineering) | **Companion:** stop re-explaining the repo — tiers, budget, Memory Ready score (`node tools/memory-init/cli.js .`) | | [Fleet Engineering](https://github.com/cobusgreyling/fleet-engineering) | **Companion:** govern populations of agents — registry, inbox, Fleet Ready score (`npx @cobusgreyling/fleet-init .`) | | [Stories](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/stories/) | Real wins and honest failures | ### Ecosystem stack ``` memory-engineering → loop-engineering → harness-foundry → outerloop → fleet-engineering (persist) (patterns) (runtime) (verdict) (population) ``` | Layer | You get | Start | |-------|---------|--------| | **Memory** | Tiers, recall budget, Memory Ready score | [memory-engineering](https://github.com/cobusgreyling/memory-engineering) | | **Design** (this repo) | Patterns, starters, Loop Ready score | `npx @cobusgreyling/loop init .` then `loop doctor .` | | **Runtime** | Versioned harness, traces, evolve | `npx @cobusgreyling/loop init . --with-foundry` or [Foundry showcase](https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md) | | **Govern** | Evidence, verdict, answerability | [outerloop](https://github.com/cobusgreyling/outerloop) | | **Fleet** | Registry, inbox, budgets, kill switch | `npx @cobusgreyling/fleet-init .` · [Fleet Ready](https://github.com/cobusgreyling/fleet-engineering/blob/main/docs/fleet-ready-score.md) | **Scale beyond one loop:** when agents forget across sessions, add [memory-engineering](https://github.com/cobusgreyling/memory-engineering). When you have many agents/loops on a team, add [fleet-engineering](https://github.com/cobusgreyling/fleet-engineering). **Next after Loop Ready 80+:** version the loop as a harness — `loop-init` prints the CTA automatically; `loop-audit` recommends Foundry when the score is strong but `.foundry/stack.yaml` is missing. ### Community & announcements | Discussion | Summary | |------------|---------| | [Contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123) | **Help wanted:** open `good first issues` — comment *I'll take this* to get assigned · see [Help wanted](#help-wanted) | | [Community update](https://github.com/cobusgreyling/loop-engineering/discussions/145) | **July 4:** 5.5k stars, traffic sources, contributor merges | | [Community week (Jul 8)](https://github.com/cobusgreyling/loop-engineering/discussions/219) | loop-worktree npm, MCP quickstart, tool appendices | | [npm update (Jul 16)](https://github.com/cobusgreyling/loop-engineering/discussions/294) | `loop-context` 1.2.0 + `loop-worktree` 1.1.0 — daily budget, path locks | | [Maintenance (Jul 10)](https://github.com/cobusgreyling/loop-engineering/discussions/241) | Doc sync, branch prune, loop-audit 1.6.0 follow-up | | [Prior release notes](https://github.com/cobusgreyling/loop-engineering/discussions/89) | v1.5.0 — loop-sync, constraints, MCP server | | [Add your project](https://github.com/cobusgreyling/loop-engineering/discussions/92) | **Pinned:** Loop Ready badge + adopters list |

## Why This Matters Peter Steinberger: > “You shouldn’t be prompting coding agents anymore. You should be designing loops that prompt your agents.” Boris Cherny (Head of Claude Code at Anthropic): > “I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops.” The leverage point has moved from crafting individual prompts to designing the control systems that orchestrate agents over time. ## The Five Building Blocks + Memory | Primitive | Job in the Loop | |-----------|-----------------| | **Automations / Scheduling** | Discovery + triage on a cadence | | **Worktrees** | Safe parallel execution | | **Skills** | Persistent project knowledge | | **Plugins & Connectors** | Reach into your real tools (MCP) | | **Sub-agents** | Maker / checker split | | **+ Memory / State** | Durable spine outside any conversation | Full detail: [docs/primitives.md](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/primitives.md) · Cross-tool matrix: [docs/primitives-matrix.md](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/primitives-matrix.md) ### Visual Overview

The Five Building Blocks + Memory — Loop Engineering

### Anatomy of a Loop

Animated loop flow — schedule, triage, state, worktree, implement, verify, MCP, human gate

Mermaid diagram (copy-friendly) ```mermaid flowchart LR A[Schedule / Automation] --> B[Triage Skill] B --> C[Read + Write STATE / Memory] C --> D[Isolated Worktree] D --> E[Implementer Sub-agent] E --> F[Verifier Sub-agent
tests + gates] F --> G[MCP / Git / Tickets] G --> H{Human Gate?} H -->|safe / allowlisted| I[Commit / PR / Action] H -->|risky / ambiguous| J[Escalate to human
with full context] I --> A J --> A ```
Deeper diagrams — the actor-level sequence within one run, the run lifecycle's states, autonomy levels L1-L3, and how `tools/` maps onto the primitives — live in [docs/architecture-diagrams.md](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/architecture-diagrams.md). **This reference repo now runs its own `validate-patterns` + `audit` workflows on every push/PR** (see `.github/workflows/`). We also added `LOOP.md` describing the loops that will maintain it. ## Patterns

Seven production loop patterns with cadence and token cost

| Pattern | Cadence | Starter | Week 1 | Token cost | |---------|---------|---------|--------|------------| | [Daily Triage](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/patterns/daily-triage.md) | 1d–2h | [minimal-loop](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/starters/minimal-loop/) | **L1** report | Low | | [PR Babysitter](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/patterns/pr-babysitter.md) | 5–15m | [pr-babysitter](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/starters/pr-babysitter/) | L1 watch | High | | [CI Sweeper](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/patterns/ci-sweeper.md) | 5–15m | [ci-sweeper](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/starters/ci-sweeper/) | L2 cautious | Very high | | [Dependency Sweeper](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/patterns/dependency-sweeper.md) | 6h–1d | [dependency-sweeper](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/starters/dependency-sweeper/) | L2 patch-only | Medium | | [Changelog Drafter](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/patterns/changelog-drafter.md) | 1d or tag | [changelog-drafter](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/starters/changelog-drafter/) | **L1** draft | Low | | [Post-Merge Cleanup](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/patterns/post-merge-cleanup.md) | 1d–6h | [post-merge-cleanup](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/starters/post-merge-cleanup/) | **L1** off-peak | Low | | [Issue Triage](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/patterns/issue-triage.md) | 2h–1d | [issue-triage](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/starters/issue-triage/) | **L1** propose-only | Low | Not sure which to pick? Try the [interactive picker](https://cobusgreyling.github.io/loop-engineering/#interactive) or [pattern-picker](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/pattern-picker.md). Machine-readable index: [patterns/registry.yaml](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/patterns/registry.yaml) (7 patterns) ## Getting Started (5 minutes) ```bash # 1. Scaffold + Loop Ready score (printed automatically) npx @cobusgreyling/loop init . --pattern daily-triage --tool grok # 2. One health check (audit + sync + files → top 3 actions) npx @cobusgreyling/loop doctor . # 3. Optional: cost estimate / badge / day-2 dashboard npx @cobusgreyling/loop cost --pattern daily-triage --level L1 npx @cobusgreyling/loop badge . npx @cobusgreyling/loop status . # 4. See scores climb: empty → L1 → L2 bash scripts/before-after-demo.sh # 5. Start report-only (Grok example) /loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one. ``` **Same as before:** `npx @cobusgreyling/loop-init` and `loop-audit` still work — [CLI front door](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/cli-front-door.md). All npm CLIs publish from tagged releases — see [docs/RELEASE.md](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/RELEASE.md). No clone required. **Develop from source** (monorepo contributors): ```bash cd tools/loop && npm ci && npm test && node dist/cli.js doctor ../.. cd tools/loop-init && npm ci && npm test && node dist/cli.js /path/to/project --pattern daily-triage --tool grok cd tools/loop-audit && npm ci && npm test && node dist/cli.js /path/to/project --suggest cd tools/loop-cost && npm ci && npm test && node dist/cli.js --pattern ci-sweeper --cadence 15m ``` Phased rollout: **L1 report → L2 assisted fixes → L3 unattended** — see [loop-design-checklist](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/loop-design-checklist.md). ## Examples by Tool - [Grok](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/examples/grok/daily-triage.md) - [Claude Code](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/examples/claude-code/) - [Codex](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/examples/codex/) - [OpenClaw](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/examples/openclaw/daily-triage.md) - [Opencode](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/examples/opencode/) - [GitHub Actions](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/examples/github-actions/) ## Operating & Safety - [Failure Modes](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/failure-modes.md) — incident-style catalog - [Anti-Patterns](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/anti-patterns.md) — design mistakes before production - [Multi-Loop Coordination](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/multi-loop.md) — when loops collide - [Operating Loops](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/operating-loops.md) — cost, logging, when to kill - [Safety](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/safety.md) — denylist, auto-merge, MCP scopes - [Security](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/SECURITY.md) — reporting and unattended automation risks - [Concepts](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/concepts.md) — intent debt, comprehension debt, harness vs loop - [MCP Cookbook](https://github.com/cobusgreyling/loop-engineering/tree/HEAD/examples/mcp/) — connector examples by pattern ## Caveats Loop engineering amplifies judgment — both good and bad. - **Token costs** can explode with sub-agents and long-running loops. - **Verification is still on you.** Unattended loops make unattended mistakes. - **Comprehension debt** grows faster unless you read what the loop ships. - Two people can run the same loop and get opposite results. The loop doesn't know. You do. Addy Osmani: > “Build the loop. But build it like someone who intends to stay the engineer, not just the person who presses go.” ## Help wanted **First PR?** Pick one open issue below. Stories and adopters get **same-day review** when possible. See [CONTRIBUTORS.md](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/CONTRIBUTORS.md) and the [contributor quickstart](https://github.com/cobusgreyling/loop-engineering/discussions/123). **14 open** [`good first issue`](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)s (refreshed Jul 2026). Comment **"I'll take this"** for assignment. | Time | Issue | What you ship | |------|-------|---------------| | ~10 min | [#120 — Adopters list](https://github.com/cobusgreyling/loop-engineering/issues/120) | One row in `docs/adopters.md` (or [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) template) | | ~15–20 min | [#118 — Daily Triage story](https://github.com/cobusgreyling/loop-engineering/issues/118) · [#173 — Issue Triage story](https://github.com/cobusgreyling/loop-engineering/issues/173) · [#119 — PR Babysitter failure](https://github.com/cobusgreyling/loop-engineering/issues/119) · [#392 — CI Sweeper story](https://github.com/cobusgreyling/loop-engineering/issues/392) | Honest `stories/` write-up + index row | | ~25–30 min | [#389 — loop-action QUICKSTART](https://github.com/cobusgreyling/loop-engineering/issues/389) · [#390 — loop-sandbox QUICKSTART](https://github.com/cobusgreyling/loop-engineering/issues/390) · [#391 — loop-gate QUICKSTART](https://github.com/cobusgreyling/loop-engineering/issues/391) | Doc subsection + links to tool READMEs | | ~40 min | [#384 — Windsurf CI Sweeper](https://github.com/cobusgreyling/loop-engineering/issues/384) · [#385 — Windsurf Issue Triage](https://github.com/cobusgreyling/loop-engineering/issues/385) · [#386 — Windsurf Dependency Sweeper](https://github.com/cobusgreyling/loop-engineering/issues/386) | Fill pattern-coverage gaps in `examples/windsurf/` | | ~40–45 min | [#387 — Hermes CI Sweeper](https://github.com/cobusgreyling/loop-engineering/issues/387) · [#388 — Hermes Issue Triage](https://github.com/cobusgreyling/loop-engineering/issues/388) | Fill pattern-coverage gaps in `examples/hermes/` | | ~45–60 min | [#393 — Harden loop-action quoting](https://github.com/cobusgreyling/loop-engineering/issues/393) | Safer `inputs.command` handling in `tools/loop-action` | | Anytime | Templates | [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml) · [Share a story](https://github.com/cobusgreyling/loop-engineering/issues/new?template=share-story.yml) | | Hubs | Discussions | [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326) · [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327) | Maintainers re-seed the backlog with `bash scripts/create-good-first-issues.sh` (idempotent; skips existing titles). Prefer [live open GFI filter](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) over this table if a row looks stale. ## Contributing Share production patterns, tool mappings, and failure stories. See [CONTRIBUTING.md](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/CONTRIBUTING.md) (contribution ladder + [`good first issue` backlog](https://github.com/cobusgreyling/loop-engineering/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)), [Code of Conduct](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/CODE_OF_CONDUCT.md), [adopters](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/docs/adopters.md), and hubs: [Show your loop](https://github.com/cobusgreyling/loop-engineering/discussions/326) · [Ask anything](https://github.com/cobusgreyling/loop-engineering/discussions/327). ## Sources - [Cobus Greyling – Loop Engineering (Substack)](https://cobusgreyling.substack.com/p/loop-engineering) - [Addy Osmani – Loop Engineering](https://addyosmani.com/blog/loop-engineering/) - [Attribution & further reading](https://github.com/cobusgreyling/loop-engineering/blob/HEAD/resources/sources.md) ## License MIT --- *Practical, tool-aware reference for loop engineering, patterns you can clone, checklists you can ship against, and stories that include what broke.*

Essay · Showcase · Cobus Greyling

Star History Chart

Static chart (CI-updated daily). Live chart needs a GitHub token — stored in your browser only.