Loop Engineering

<p align="center"> <a href="https://cobusgreyling.github.io/loop-engineering/"> <img src="https://img.shields.io/badge/✨_Explore_the_Showcase-Design_systems_that_prompt_your_agents-0d1117?style=for-the-badge&labelColor=111a28&color=3ee8c5" alt="Explore the Showcase" /> </a> </p> <p align="center"> <a href="https://github.com/cobusgreyling/loop-engineering/stargazers"><img src="https://img.shields.io/github/stars/cobusgreyling/loop-engineering?style=social" alt="GitHub stars"></a> <a href="https://github.com/cobusgreyling/loop-engineering/actions/workflows/audit.yml"><img src="https://img.shields.io/github/actions/workflow/status/cobusgreyling/loop-engineering/audit.yml?label=loop-audit%20dogfood" alt="loop-audit dogfood"></a> <a href="https://www.npmjs.com/package/@cobusgreyling/loop"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop?label=loop" alt="loop npm"></a> <a href="https://www.npmjs.com/package/@cobusgreyling/loop-audit"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-audit?label=loop-audit" alt="loop-audit npm"></a> <a href="https://www.npmjs.com/package/@cobusgreyling/loop-init"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-init?label=loop-init" alt="loop-init npm"></a> <a href="https://www.npmjs.com/package/@cobusgreyling/loop-cost"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-cost?label=loop-cost" alt="loop-cost npm"></a> <a href="https://www.npmjs.com/package/@cobusgreyling/loop-sync"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-sync?label=loop-sync" alt="loop-sync npm"></a> <a href="https://www.npmjs.com/package/@cobusgreyling/loop-context"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-context?label=loop-context" alt="loop-context npm"></a> <a href="https://www.npmjs.com/package/@cobusgreyling/loop-mcp-server"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-mcp-server?label=loop-mcp-server" alt="loop-mcp-server npm"></a> <a href="https://www.npmjs.com/package/@cobusgreyling/loop-worktree"><img src="https://img.shields.io/npm/v/@cobusgreyling/loop-worktree?label=loop-worktree" alt="loop-worktree npm"></a> <a href="https://github.com/cobusgreyling/loop-engineering/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a> <a href="https://cobusgreyling.github.io/loop-engineering/"><img src="https://img.shields.io/badge/GitHub_Pages-live%20%7C%20interactive-3ee8c5" alt="Pages"></a> </p> <p align="center"> <a href="https://cobusgreyling.github.io/loop-engineering/"> <img src="assets/visuals/loop-engineering-logo.svg" alt="Loop Engineering logo" width="88" /> </a> </p>

Stop prompting. Design the loop. Get a score.

<p align="center"> <img src="assets/visuals/LE5.jpeg" alt="Loop Engineering — design the system that prompts your agents" width="100%" /> </p>

# 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.

<p align="center"> <a href="docs/QUICKSTART.md"> <img src="assets/visuals/loop-audit-demo.gif" alt="Loop Ready score climbs from 10 to 100 in 15 seconds" width="100%" /> </a> </p>

Loop engineering replaces you as the person who prompts the agent — you design the system that does it instead.

New here? Quickstart (5 min) · Interactive picker

For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agents.

<p align="center"> <strong><a href="https://cobusgreyling.github.io/loop-engineering/">→ Interactive showcase + pattern picker</a></strong> · <a href="https://cobusgreyling.substack.com/p/loop-engineering">Essay</a> · <a href="https://addyosmani.com/blog/loop-engineering/">Addy Osmani</a> </p>

Contents

• Quickstart (5 min)
• Quick Links
• Why This Matters
• The Five Building Blocks + Memory
• Patterns
• Getting Started (5 minutes)
• Examples by Tool
• Operating & Safety
• Caveats
• Help wanted
• Contributing
• Sources
• License

Quick Links

| Start here | Description | |------------|-------------| | Quickstart (5 min) | loop init → loop doctor → first loop — start here if you just landed | | CLI front door | Unified @cobusgreyling/loop — old packages stay open | | Loop Engineering essay | The concept, primitives, and Grok mapping — read for the why | | Pattern Picker | Which loop to run first — start here if unsure | | Primitives Matrix | Cross-tool loop primitive mapping — bookmark this | | Loop Design Checklist | Ship readiness rubric | | Patterns | 7 production patterns + interactive picker | | Starters | Clone-and-run kits (Grok, Claude Code, Codex, Opencode) | | Opencode examples | CLI-first loops: cron/systemd + opencode run, skills, worktrees | | loop (front door) | Unified CLI — npx @cobusgreyling/loop init \| doctor \| status \| audit \| cost · cli-front-door | | loop-audit | Loop Readiness Score CLI (v1.7 — constraints + governance + Harness Runtime) — npx @cobusgreyling/loop audit . --suggest · also loop-audit | | loop-init | Scaffold starters + budget/run-log + constraints (v1.5) — npx @cobusgreyling/loop init . --pattern daily-triage --tool grok · also loop-init | | harness-foundry | Companion runtime: versioned stacks, sessions, traces — npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage | | outerloop | Companion governance: evidence → verdict → answerability | | loop-cost | Token spend estimator — npx @cobusgreyling/loop-cost | | loop-sync | Drift detection between STATE.md and LOOP.md — npx @cobusgreyling/loop-sync . | | loop-context | Stateful memory manager + circuit breaker for long runs — npx @cobusgreyling/loop-context --check --ledger run.json | | loop-mcp-server | MCP runtime lookup for patterns, skills, state — npx @cobusgreyling/loop-mcp-server | | loop-worktree | Manage isolated git worktrees per fix attempt — npx @cobusgreyling/loop-worktree create --run-id <id> --pattern <p> | | loop-gate | Mechanical enforcement of the path denylist + auto-merge allowlist from gate.yaml — npx @cobusgreyling/loop-gate check --action auto-merge --paths <f1,f2,...> | | loop-sandbox | Ephemeral git worktree isolation + patch capture — npx @cobusgreyling/loop-sandbox run -- <cmd> | | loop-action | GitHub Composite Action for running loops in CI — uses: cobusgreyling/loop-engineering/tools/loop-action@main | | Goal Engineering | Companion: loops discover, goals finish — /goal + stack cookbook (npx @cobusgreyling/goal doctor .) | | Memory Engineering | Companion: stop re-explaining the repo — tiers, budget, Memory Ready score (node tools/memory-init/cli.js .) | | Fleet Engineering | Companion: govern populations of agents — registry, inbox, Fleet Ready score (npx @cobusgreyling/fleet-init .) | | 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 | | 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 | | Govern | Evidence, verdict, answerability | outerloop | | Fleet | Registry, inbox, budgets, kill switch | npx @cobusgreyling/fleet-init . · Fleet Ready |

Scale beyond one loop: when agents forget across sessions, add memory-engineering. When you have many agents/loops on a team, add 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 | Help wanted: open good first issues — comment I'll take this to get assigned · see Help wanted | | Community update | July 4: 5.5k stars, traffic sources, contributor merges | | Community week (Jul 8) | loop-worktree npm, MCP quickstart, tool appendices | | npm update (Jul 16) | loop-context 1.2.0 + loop-worktree 1.1.0 — daily budget, path locks | | Maintenance (Jul 10) | Doc sync, branch prune, loop-audit 1.6.0 follow-up | | Prior release notes | v1.5.0 — loop-sync, constraints, MCP server | | Add your project | Pinned: Loop Ready badge + adopters list |

<p align="center"> <img src="assets/visuals/section-divider.svg" alt="" width="100%" /> </p>

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 desi