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.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
Add dark-theme SVG visuals and polish README layout
Cobus Greyling4edcefcfde29
diff --git a/README.md b/README.mdindex 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 MattersPeter 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>```mermaidflowchart LR@@ -126,10 +135,16 @@ flowchart LRJ --> 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.svgnew file mode 100644index 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 filediff --git a/assets/visuals/loop-engineering-logo.svg b/assets/visuals/loop-engineering-logo.svgnew file mode 100644index 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 filediff --git a/assets/visuals/patterns-overview.svg b/assets/visuals/patterns-overview.svgnew file mode 100644index 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 filediff --git a/assets/visuals/section-divider.svg b/assets/visuals/section-divider.svgnew file mode 100644index 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 filediff --git a/docs/index.html b/docs/index.htmlindex 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><buttontype="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><imgclass="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>