Skip to content

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.

Add dark-theme SVG visuals and polish README layout

Cobus Greyling4edcefcfde29
diff --git a/README.md b/README.md
index 0cb9cf5..c5a6a09 100644
--- a/README.md
+++ b/README.md
@@ -19,11 +19,13 @@
<p align="center">
- <img src="assets/visuals/loop-engineering-logo.jpg" alt="Loop Engineering" width="96" />
+ <a href="https://cobusgreyling.github.io/loop-engineering/">
+ <img src="assets/visuals/loop-engineering-logo.svg" alt="Loop Engineering logo" width="88" />
+ </a>
</p>
<p align="center">
- <img src="assets/visuals/LE5.jpeg" alt="Loop Engineering" width="100%" />
+ <img src="assets/visuals/LE5.jpeg" alt="Loop Engineering — design the system that prompts your agents" width="100%" />
</p>
**Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead.**
@@ -36,10 +38,6 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with
-<p align="center">
- <img src="assets/visuals/loop-engineering-social-banner.jpg" alt="Loop Engineering — Design the system that prompts your agents" width="100%" />
-</p>
-
<p align="center">
<strong><a href="https://cobusgreyling.github.io/loop-engineering/">→ Interactive showcase + pattern picker</a></strong>
<br>
@@ -80,6 +78,10 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with
| [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | Companion: Grok Build `/goal` — run-until-done objectives (`npx @cobusgreyling/goal-audit`) |
| [Stories](stories/) | Real wins and honest failures |
+<p align="center">
+ <img src="assets/visuals/section-divider.svg" alt="" width="100%" />
+</p>
+
## Why This Matters
Peter Steinberger:
@@ -109,7 +111,14 @@ Full detail: [docs/primitives.md](docs/primitives.md) · Cross-tool matrix: [doc
<img src="assets/visuals/primitives-infographic.jpg" alt="The Five Building Blocks + Memory — Loop Engineering" width="100%" />
</p>
-### Anatomy of a Loop (Mermaid)
+### Anatomy of a Loop
+
+<p align="center">
+ <img src="assets/visuals/loop-cycle-animated.svg" alt="Animated loop flow — schedule, triage, state, worktree, implement, verify, MCP, human gate" width="100%" />
+</p>
+
+<details>
+<summary>Mermaid diagram (copy-friendly)</summary>
```mermaid
flowchart LR
@@ -126,10 +135,16 @@ flowchart LR
J --> A
```
+</details>
+
**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
+<p align="center">
+ <img src="assets/visuals/patterns-overview.svg" alt="Seven production loop patterns with cadence and token cost" width="100%" />
+</p>
+
| Pattern | Cadence | Starter | Week 1 | Token cost |
|---------|---------|---------|--------|------------|
| [Daily Triage](patterns/daily-triage.md) | 1d–2h | [minimal-loop](starters/minimal-loop/) | **L1** report | Low |
diff --git a/assets/visuals/loop-cycle-animated.svg b/assets/visuals/loop-cycle-animated.svg
new file mode 100644
index 0000000..6950a06
--- /dev/null
+++ b/assets/visuals/loop-cycle-animated.svg
@@ -0,0 +1,113 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 320" role="img" aria-label="Anatomy of a loop — animated flow">
+ <defs>
+ <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+ <stop offset="0%" stop-color="#0d1420"/>
+ <stop offset="100%" stop-color="#070b12"/>
+ </linearGradient>
+ <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+ <stop offset="0%" stop-color="#3ee8c5"/>
+ <stop offset="100%" stop-color="#5b9dff"/>
+ </linearGradient>
+ <filter id="glow" x="-20%" y="-20%" width="140%" height="140%">
+ <feGaussianBlur stdDeviation="3" result="b"/>
+ <feMerge>
+ <feMergeNode in="b"/>
+ <feMergeNode in="SourceGraphic"/>
+ </feMerge>
+ </filter>
+ <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+ <path d="M 0 0 L 10 5 L 0 10 z" fill="#3ee8c5"/>
+ </marker>
+ <style>
+ .title { font: 700 22px system-ui, -apple-system, sans-serif; fill: #e8edf5; letter-spacing: -0.02em; }
+ .subtitle { font: 500 13px system-ui, -apple-system, sans-serif; fill: #8b9cb3; }
+ .node-label { font: 600 11px system-ui, -apple-system, sans-serif; fill: #e8edf5; }
+ .node-sub { font: 500 9px system-ui, -apple-system, sans-serif; fill: #8b9cb3; }
+ .flow {
+ fill: none;
+ stroke: url(#accent);
+ stroke-width: 2.5;
+ stroke-linecap: round;
+ stroke-dasharray: 10 8;
+ marker-end: url(#arrow);
+ animation: dash 2.4s linear infinite;
+ }
+ .pulse {
+ animation: pulse 2.4s ease-in-out infinite;
+ }
+ @keyframes dash {
+ to { stroke-dashoffset: -36; }
+ }
+ @keyframes pulse {
+ 0%, 100% { opacity: 0.55; }
+ 50% { opacity: 1; }
+ }
+ </style>
+ </defs>
+
+ <rect width="960" height="320" rx="18" fill="url(#bg)"/>
+ <rect x="1" y="1" width="958" height="318" rx="17" fill="none" stroke="rgba(62,232,197,0.18)" stroke-width="1"/>
+
+ <text x="32" y="42" class="title">Anatomy of a Loop</text>
+ <text x="32" y="62" class="subtitle">Design once — the system prompts, verifies, and iterates</text>
+
+ <!-- flow path -->
+ <path class="flow" d="M 108 170 C 148 170, 168 130, 208 130
+ C 248 130, 268 170, 308 170
+ C 348 170, 368 210, 408 210
+ C 448 210, 468 170, 508 170
+ C 548 170, 568 130, 608 130
+ C 648 130, 668 170, 708 170
+ C 748 170, 768 210, 808 210
+ C 848 210, 868 170, 908 170"/>
+
+ <!-- nodes -->
+ <g filter="url(#glow)">
+ <g class="pulse" style="animation-delay: 0s">
+ <rect x="56" y="148" width="104" height="44" rx="12" fill="#111a28" stroke="#3ee8c5" stroke-width="1.5"/>
+ <text x="108" y="168" text-anchor="middle" class="node-label">⏱ Schedule</text>
+ <text x="108" y="182" text-anchor="middle" class="node-sub">cadence</text>
+ </g>
+ <g class="pulse" style="animation-delay: 0.3s">
+ <rect x="156" y="108" width="104" height="44" rx="12" fill="#111a28" stroke="#3ee8c5" stroke-width="1.5"/>
+ <text x="208" y="128" text-anchor="middle" class="node-label">👁 Triage</text>
+ <text x="208" y="142" text-anchor="middle" class="node-sub">skill</text>
+ </g>
+ <g class="pulse" style="animation-delay: 0.6s">
+ <rect x="256" y="148" width="104" height="44" rx="12" fill="#111a28" stroke="#3ee8c5" stroke-width="1.5"/>
+ <text x="308" y="168" text-anchor="middle" class="node-label">📋 STATE</text>
+ <text x="308" y="182" text-anchor="middle" class="node-sub">memory</text>
+ </g>
+ <g class="pulse" style="animation-delay: 0.9s">
+ <rect x="356" y="188" width="104" height="44" rx="12" fill="#111a28" stroke="#5b9dff" stroke-width="1.5"/>
+ <text x="408" y="208" text-anchor="middle" class="node-label">🌲 Worktree</text>
+ <text x="408" y="222" text-anchor="middle" class="node-sub">isolated</text>
+ </g>
+ <g class="pulse" style="animation-delay: 1.2s">
+ <rect x="456" y="148" width="104" height="44" rx="12" fill="#111a28" stroke="#5b9dff" stroke-width="1.5"/>
+ <text x="508" y="168" text-anchor="middle" class="node-label">⚙️ Implement</text>
+ <text x="508" y="182" text-anchor="middle" class="node-sub">sub-agent</text>
+ </g>
+ <g class="pulse" style="animation-delay: 1.5s">
+ <rect x="556" y="108" width="104" height="44" rx="12" fill="#111a28" stroke="#5b9dff" stroke-width="1.5"/>
+ <text x="608" y="128" text-anchor="middle" class="node-label">✓ Verify</text>
+ <text x="608" y="142" text-anchor="middle" class="node-sub">gates</text>
+ </g>
+ <g class="pulse" style="animation-delay: 1.8s">
+ <rect x="656" y="148" width="104" height="44" rx="12" fill="#111a28" stroke="#ffb347" stroke-width="1.5"/>
+ <text x="708" y="168" text-anchor="middle" class="node-label">🔗 MCP / PR</text>
+ <text x="708" y="182" text-anchor="middle" class="node-sub">tools</text>
+ </g>
+ <g class="pulse" style="animation-delay: 2.1s">
+ <rect x="756" y="188" width="104" height="44" rx="12" fill="#111a28" stroke="#ffb347" stroke-width="1.5"/>
+ <text x="808" y="208" text-anchor="middle" class="node-label">🧑 Human gate</text>
+ <text x="808" y="222" text-anchor="middle" class="node-sub">approve / escalate</text>
+ </g>
+ <g>
+ <rect x="856" y="148" width="72" height="44" rx="22" fill="rgba(62,232,197,0.12)" stroke="#3ee8c5" stroke-width="1.5"/>
+ <text x="892" y="176" text-anchor="middle" class="node-label">⟳</text>
+ </g>
+ </g>
+
+ <text x="892" y="248" text-anchor="middle" class="node-sub">loop back</text>
+</svg>
\ No newline at end of file
diff --git a/assets/visuals/loop-engineering-logo.svg b/assets/visuals/loop-engineering-logo.svg
new file mode 100644
index 0000000..8e890b8
--- /dev/null
+++ b/assets/visuals/loop-engineering-logo.svg
@@ -0,0 +1,34 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" role="img" aria-label="Loop Engineering">
+ <defs>
+ <linearGradient id="le-glow" x1="0%" y1="0%" x2="100%" y2="100%">
+ <stop offset="0%" stop-color="#6ff5d8"/>
+ <stop offset="100%" stop-color="#3ee8c5"/>
+ </linearGradient>
+ <filter id="le-soft-glow" x="-40%" y="-40%" width="180%" height="180%">
+ <feGaussianBlur stdDeviation="1.5" result="blur"/>
+ <feMerge>
+ <feMergeNode in="blur"/>
+ <feMergeNode in="SourceGraphic"/>
+ </feMerge>
+ </filter>
+ </defs>
+ <rect width="120" height="120" rx="24" fill="#070b12"/>
+ <g fill="none" stroke="url(#le-glow)" stroke-width="3" stroke-linecap="round" filter="url(#le-soft-glow)">
+ <path d="M24 60 L42 42 L60 60 L78 42 L96 60"/>
+ <path d="M24 60 L42 78 L60 60 L78 78 L96 60"/>
+ <path d="M42 42 L42 78"/>
+ <path d="M78 42 L78 78"/>
+ <path d="M24 60 L96 60"/>
+ </g>
+ <g fill="#3ee8c5">
+ <circle cx="42" cy="42" r="5"/>
+ <circle cx="78" cy="78" r="5"/>
+ <circle cx="96" cy="60" r="5"/>
+ </g>
+ <g fill="none" stroke="#3ee8c5" stroke-width="2.5">
+ <circle cx="24" cy="60" r="5"/>
+ <circle cx="60" cy="60" r="5"/>
+ <circle cx="42" cy="78" r="5"/>
+ <circle cx="78" cy="42" r="5"/>
+ </g>
+</svg>
\ No newline at end of file
diff --git a/assets/visuals/patterns-overview.svg b/assets/visuals/patterns-overview.svg
new file mode 100644
index 0000000..ca115eb
--- /dev/null
+++ b/assets/visuals/patterns-overview.svg
@@ -0,0 +1,94 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 420" role="img" aria-label="Seven production loop patterns">
+ <defs>
+ <linearGradient id="pbg" x1="0" y1="0" x2="1" y2="1">
+ <stop offset="0%" stop-color="#0d1420"/>
+ <stop offset="100%" stop-color="#070b12"/>
+ </linearGradient>
+ <style>
+ .title { font: 700 22px system-ui, -apple-system, sans-serif; fill: #e8edf5; }
+ .subtitle { font: 500 13px system-ui, -apple-system, sans-serif; fill: #8b9cb3; }
+ .card-title { font: 600 12px system-ui, -apple-system, sans-serif; fill: #e8edf5; }
+ .card-meta { font: 500 10px system-ui, -apple-system, sans-serif; fill: #8b9cb3; }
+ .badge { font: 700 9px system-ui, -apple-system, sans-serif; fill: #070b12; }
+ .icon { font-size: 22px; }
+ </style>
+ </defs>
+
+ <rect width="960" height="420" rx="18" fill="url(#pbg)"/>
+ <rect x="1" y="1" width="958" height="418" rx="17" fill="none" stroke="rgba(62,232,197,0.15)" stroke-width="1"/>
+
+ <text x="32" y="42" class="title">7 Production Patterns</text>
+ <text x="32" y="62" class="subtitle">Pick a cadence, clone a starter, start at L1 report-only</text>
+
+ <!-- row 1 -->
+ <g transform="translate(24,84)">
+ <rect width="210" height="128" rx="14" fill="#111a28" stroke="rgba(62,232,197,0.25)" stroke-width="1"/>
+ <text x="20" y="36" class="icon">📅</text>
+ <text x="52" y="34" class="card-title">Daily Triage</text>
+ <text x="52" y="50" class="card-meta">1d–2h · L1 report</text>
+ <rect x="20" y="92" width="52" height="20" rx="10" fill="#3ee8c5"/>
+ <text x="46" y="106" text-anchor="middle" class="badge">LOW</text>
+ </g>
+
+ <g transform="translate(252,84)">
+ <rect width="210" height="128" rx="14" fill="#111a28" stroke="rgba(62,232,197,0.25)" stroke-width="1"/>
+ <text x="20" y="36" class="icon">👶</text>
+ <text x="52" y="34" class="card-title">PR Babysitter</text>
+ <text x="52" y="50" class="card-meta">5–15m · L1 watch</text>
+ <rect x="20" y="92" width="58" height="20" rx="10" fill="#ffb347"/>
+ <text x="49" y="106" text-anchor="middle" class="badge">HIGH</text>
+ </g>
+
+ <g transform="translate(480,84)">
+ <rect width="210" height="128" rx="14" fill="#111a28" stroke="rgba(62,232,197,0.25)" stroke-width="1"/>
+ <text x="20" y="36" class="icon">🧹</text>
+ <text x="52" y="34" class="card-title">CI Sweeper</text>
+ <text x="52" y="50" class="card-meta">5–15m · L2 cautious</text>
+ <rect x="20" y="92" width="72" height="20" rx="10" fill="#ff6b6b"/>
+ <text x="56" y="106" text-anchor="middle" class="badge">V.HIGH</text>
+ </g>
+
+ <g transform="translate(708,84)">
+ <rect width="228" height="128" rx="14" fill="#111a28" stroke="rgba(62,232,197,0.25)" stroke-width="1"/>
+ <text x="20" y="36" class="icon">📦</text>
+ <text x="52" y="34" class="card-title">Dependency Sweeper</text>
+ <text x="52" y="50" class="card-meta">6h–1d · L2 patch-only</text>
+ <rect x="20" y="92" width="68" height="20" rx="10" fill="#5b9dff"/>
+ <text x="54" y="106" text-anchor="middle" class="badge">MEDIUM</text>
+ </g>
+
+ <!-- row 2 -->
+ <g transform="translate(24,232)">
+ <rect width="210" height="128" rx="14" fill="#111a28" stroke="rgba(91,157,255,0.22)" stroke-width="1"/>
+ <text x="20" y="36" class="icon">📝</text>
+ <text x="52" y="34" class="card-title">Changelog Drafter</text>
+ <text x="52" y="50" class="card-meta">1d or tag · L1 draft</text>
+ <rect x="20" y="92" width="52" height="20" rx="10" fill="#3ee8c5"/>
+ <text x="46" y="106" text-anchor="middle" class="badge">LOW</text>
+ </g>
+
+ <g transform="translate(252,232)">
+ <rect width="210" height="128" rx="14" fill="#111a28" stroke="rgba(91,157,255,0.22)" stroke-width="1"/>
+ <text x="20" y="36" class="icon">🧼</text>
+ <text x="52" y="34" class="card-title">Post-Merge Cleanup</text>
+ <text x="52" y="50" class="card-meta">1d–6h · L1 off-peak</text>
+ <rect x="20" y="92" width="52" height="20" rx="10" fill="#3ee8c5"/>
+ <text x="46" y="106" text-anchor="middle" class="badge">LOW</text>
+ </g>
+
+ <g transform="translate(480,232)">
+ <rect width="210" height="128" rx="14" fill="#111a28" stroke="rgba(91,157,255,0.22)" stroke-width="1"/>
+ <text x="20" y="36" class="icon">🏷️</text>
+ <text x="52" y="34" class="card-title">Issue Triage</text>
+ <text x="52" y="50" class="card-meta">2h–1d · L1 propose</text>
+ <rect x="20" y="92" width="52" height="20" rx="10" fill="#3ee8c5"/>
+ <text x="46" y="106" text-anchor="middle" class="badge">LOW</text>
+ </g>
+
+ <g transform="translate(708,232)">
+ <rect width="228" height="128" rx="14" fill="rgba(62,232,197,0.08)" stroke="#3ee8c5" stroke-width="1.5" stroke-dasharray="6 4"/>
+ <text x="114" y="58" text-anchor="middle" class="card-title">Not sure?</text>
+ <text x="114" y="78" text-anchor="middle" class="card-meta">Try the interactive picker →</text>
+ <text x="114" y="108" text-anchor="middle" class="icon">✨</text>
+ </g>
+</svg>
\ No newline at end of file
diff --git a/assets/visuals/section-divider.svg b/assets/visuals/section-divider.svg
new file mode 100644
index 0000000..edbdd28
--- /dev/null
+++ b/assets/visuals/section-divider.svg
@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 48" role="img" aria-hidden="true" preserveAspectRatio="none">
+ <defs>
+ <linearGradient id="line" x1="0" y1="0" x2="1" y2="0">
+ <stop offset="0%" stop-color="rgba(62,232,197,0)"/>
+ <stop offset="20%" stop-color="rgba(62,232,197,0.45)"/>
+ <stop offset="50%" stop-color="rgba(91,157,255,0.65)"/>
+ <stop offset="80%" stop-color="rgba(62,232,197,0.45)"/>
+ <stop offset="100%" stop-color="rgba(62,232,197,0)"/>
+ </linearGradient>
+ <radialGradient id="orb" cx="50%" cy="50%" r="50%">
+ <stop offset="0%" stop-color="#3ee8c5" stop-opacity="0.9"/>
+ <stop offset="100%" stop-color="#3ee8c5" stop-opacity="0"/>
+ </radialGradient>
+ </defs>
+ <rect width="960" height="48" fill="transparent"/>
+ <line x1="0" y1="24" x2="960" y2="24" stroke="url(#line)" stroke-width="2"/>
+ <circle cx="480" cy="24" r="18" fill="url(#orb)" opacity="0.35"/>
+ <circle cx="480" cy="24" r="5" fill="#3ee8c5"/>
+</svg>
\ No newline at end of file
diff --git a/docs/index.html b/docs/index.html
index 8c09449..59fb2c4 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -13,13 +13,16 @@ title: Loop Engineering — Showcase
<meta property="og:description" content="Stop prompting. Start designing loops.">
<meta property="og:image" content="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-engineering-social-banner.jpg">
<link rel="stylesheet" href="{{ site.baseurl }}/assets/css/showcase.css">
- <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>⟳</text></svg>">
+ <link rel="icon" href="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-engineering-logo.svg">
</head>
<body>
<nav class="nav">
<div class="wrap nav-inner">
- <a href="#" class="logo">Loop <span>Engineering</span></a>
+ <a href="#" class="logo">
+ <img src="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-engineering-logo.svg" alt="" width="28" height="28" style="vertical-align:-6px;margin-right:8px;border-radius:6px;" />
+ Loop <span>Engineering</span>
+ </a>
<button
type="button"
class="nav-toggle"
@@ -95,7 +98,7 @@ title: Loop Engineering — Showcase
<p class="section-desc">You design it once. You're not prompting every micro-step.</p>
<img
class="hero-img"
- src="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-anatomy.jpg"
+ src="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-cycle-animated.svg"
alt="Anatomy of a loop — schedule, triage, state, worktree, implementer, verifier, MCP, human gate"
loading="lazy"
style="margin-bottom: 24px;"
@@ -170,6 +173,13 @@ title: Loop Engineering — Showcase
<p class="section-label">Copy & run</p>
<h2 class="section-title">Production patterns</h2>
<p class="section-desc">Documented loops with scheduling, skills, state schemas, verification, and honest failure modes.</p>
+ <img
+ class="hero-img"
+ src="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/patterns-overview.svg"
+ alt="Seven production loop patterns — cadence and token cost overview"
+ loading="lazy"
+ style="margin-bottom: 28px;"
+ />
<div class="patterns">
<article class="pattern-card">
<span class="tag">Most popular</span>