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 QUICKSTART guide and token estimates in showcase picker
Cobus Greyling0a668de7416f
diff --git a/README.md b/README.mdindex 4cf1d52..0cb9cf5 100644--- a/README.md+++ b/README.md@@ -28,6 +28,8 @@**Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead.**+**New here?** [Quickstart (5 min)](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.A loop is a recursive goal: you define a purpose and the AI iterates (often with sub-agents, verification, and external state) until the goal is complete or the loop decides to hand off to you.@@ -48,6 +50,7 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with## Contents+- [Quickstart (5 min)](docs/QUICKSTART.md)- [Quick Links](#quick-links)- [Why This Matters](#why-this-matters)- [The Five Building Blocks + Memory](#the-five-building-blocks--memory)@@ -64,7 +67,8 @@ A loop is a recursive goal: you define a purpose and the AI iterates (often with| Start here | Description ||------------|-------------|-| [Loop Engineering essay](https://cobusgreyling.substack.com/p/loop-engineering) | The concept, primitives, and Grok mapping — **read this first** |+| [Quickstart (5 min)](docs/QUICKSTART.md) | Scaffold → cost check → audit → first loop — **start here if you just landed** |+| [Loop Engineering essay](https://cobusgreyling.substack.com/p/loop-engineering) | The concept, primitives, and Grok mapping — read for the why || [Pattern Picker](docs/pattern-picker.md) | Which loop to run first — **start here if unsure** || [Primitives Matrix](docs/primitives-matrix.md) | Grok vs Claude Code vs Codex — bookmark this || [Loop Design Checklist](docs/loop-design-checklist.md) | Ship readiness rubric |diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdnew file mode 100644index 0000000..d117073--- /dev/null+++ b/docs/QUICKSTART.md@@ -0,0 +1,111 @@+# Quickstart — 5 minutes to your first loop++Landed from [X](https://x.com), the [showcase](https://cobusgreyling.github.io/loop-engineering/), or a friend's README? This is the shortest path from zero to a running loop.++**Week one rule:** report only. No auto-fix, no auto-merge. Read what the loop writes before you let it act.++## 1. Pick your pain (30 seconds)++Not sure which loop? Use the [interactive pattern picker](https://cobusgreyling.github.io/loop-engineering/#interactive) on the showcase — it recommends a pattern, scaffold command, first `/loop` line, and a token estimate.++Or start with **Daily Triage** if you just want to learn loop discipline with low risk.++## 2. Scaffold in your repo (60 seconds)++Run this in the root of any git project (no clone required):++```bash+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok+```++Swap `--tool grok` for `claude` or `codex` if needed. Swap `--pattern` for any pattern from [patterns/registry.yaml](../patterns/registry.yaml).++`loop-init` copies the starter kit, creates `STATE.md`, `LOOP.md`, `loop-budget.md`, and `loop-run-log.md`, then prints your first command.++## 3. Check cost before you schedule (30 seconds)++```bash+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d+```++Adjust `--pattern`, `--level` (L1 → L2 → L3), and `--cadence` to match what you plan to run. High-frequency loops (CI Sweeper at 5m) can burn tokens fast — slow the cadence or require early-exit triage first.++## 4. Audit readiness (30 seconds)++```bash+npx @cobusgreyling/loop-audit . --suggest+```++Scores 0–100 with concrete next steps. Re-run after each improvement. Paste a badge when you're proud of the score:++```bash+npx @cobusgreyling/loop-audit . --badge+```++## 5. Run your first loop — report only (2 minutes)++### Grok++```bash+/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.+```++### Claude Code++```bash+/loop 1d Run $loop-triage. Read STATE.md. Merge findings into High Priority and Watch List. Update Last run. Do not edit code.+```++### Codex++Use the first-run command printed by `loop-init` (pattern-specific). Week one: triage and state updates only.++### Cursor or Windsurf++No `loop-init --tool cursor` yet — copy skills and state from any starter, then map scheduling to editor Automations or Workflows. See the [Cursor & Windsurf appendix](./primitives-matrix.md#appendix-editor-transfer-recipes-cursor--windsurf) in the primitives matrix.++### GitHub Actions only++Workflow examples under [examples/github-actions/](../examples/github-actions/) are schema-complete; you wire the agent invocation (Codex API, `repository_dispatch`, etc.). Start with report-only outputs to a state file or issue comment.++## 6. Read the output, commit state (1 minute)++Open `STATE.md`. Did the loop capture real priorities? Edit anything wrong — you're still the engineer.++Commit the scaffold + first run update so `loop-audit` sees activity on the next audit.++## What next?++| When | Do this |+|------|---------|+| End of week one | Re-run `loop-audit . --suggest` — aim for L1 (score ~40+) |+| Week two | Add a verifier skill; try one assisted fix in a worktree (L2) |+| Before unattended (L3) | `loop-budget.md` + `loop-run-log.md` filled, human gates in `LOOP.md`, proven runs |+| Unsure which pattern | [pattern-picker.md](./pattern-picker.md) · [loop-design-checklist.md](./loop-design-checklist.md) |+| Something broke | [failure-modes.md](./failure-modes.md) · [stories/](../stories/) |++## Copy-paste cheat sheet++```bash+# Scaffold+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok++# Cost check+npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1d++# Audit + suggestions+npx @cobusgreyling/loop-audit . --suggest++# Optional badge for your README+npx @cobusgreyling/loop-audit . --badge+```++## Learn the why (optional, 10 minutes)++- [Loop Engineering essay](https://cobusgreyling.substack.com/p/loop-engineering) — concept and primitives+- [Primitives matrix](./primitives-matrix.md) — Grok vs Claude vs Codex vs Cursor+- [Operating loops](./operating-loops.md) — when to kill a loop++---++*Questions? [GitHub Discussions](https://github.com/cobusgreyling/loop-engineering/discussions) · Share your setup via [Add Adopter](https://github.com/cobusgreyling/loop-engineering/issues/new?template=add-adopter.yml)*\ No newline at end of filediff --git a/docs/assets/css/showcase.css b/docs/assets/css/showcase.cssindex d122118..3cbbce9 100644--- a/docs/assets/css/showcase.css+++ b/docs/assets/css/showcase.css@@ -648,6 +648,21 @@ section {font-weight: 600;}+.reco-cost {+ margin: 8px 0 10px;+ padding: 8px 10px;+ font-size: 0.8rem;+ line-height: 1.45;+ color: var(--text-muted);+ background: rgba(62, 232, 197, 0.06);+ border: 1px solid rgba(62, 232, 197, 0.18);+ border-radius: 6px;+}++.reco-cost strong {+ color: var(--accent);+}+.reco-card {margin-top: 16px;padding: 16px 18px;diff --git a/docs/index.html b/docs/index.htmlindex 52eb1af..8c09449 100644--- a/docs/index.html+++ b/docs/index.html@@ -37,6 +37,7 @@ title: Loop Engineering — Showcase<li><a href="#primitives">Primitives</a></li><li><a href="#interactive">Picker</a></li><li><a href="#start">Get Started</a></li>+ <li><a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/QUICKSTART.md">Quickstart</a></li><li><a href="#adopters">Adopters</a></li><li><a href="https://cobusgreyling.substack.com/p/loop-engineering">Essay</a></li><li><a href="https://github.com/cobusgreyling/loop-engineering">GitHub</a></li>@@ -272,7 +273,7 @@ title: Loop Engineering — Showcase<section id="start" class="wrap"><p class="section-label">5 minutes</p><h2 class="section-title">Get started</h2>- <p class="section-desc">Clone a starter, audit your project, run report-only for one week.</p>+ <p class="section-desc">Scaffold in your repo, audit readiness, run report-only for one week. <a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/QUICKSTART.md">Full quickstart guide →</a></p><div class="code-block"><div class="code-header"><div class="code-dots"><span></span><span></span><span></span></div>@@ -291,6 +292,8 @@ npx @cobusgreyling/loop-audit . --suggest<span class="cmd">/loop</span> <span class="flag">1d</span> Run changelog-scan + draft-release-notes. Write RELEASE_NOTES_DRAFT.md. Human review only.</pre></div><p style="margin-top: 24px; text-align: center;">+ <a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/QUICKSTART.md">Quickstart guide</a>+ ·<a href="https://github.com/cobusgreyling/loop-engineering/tree/main/starters">All starters</a>·<a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/loop-design-checklist.md">Design checklist</a>@@ -319,6 +322,7 @@ npx @cobusgreyling/loop-audit . --suggest<div id="reco-output" class="reco-card" style="display:none;"><strong>Recommended:</strong> <span id="reco-name"></span> <span id="reco-meta" style="color:var(--text-muted);"></span><br>+ <div id="reco-cost" class="reco-cost" style="display:none;"></div><span style="font-size:0.8rem;">Scaffold:</span> <code id="reco-npx" class="cmd"></code> <button onclick="copyRecoNpx()" class="copy-btn">Copy</button><br><span style="font-size:0.8rem;">First run (report-only):</span> <code id="reco-loop" style="font-family:var(--font-mono);"></code><div style="margin-top:8px;">@@ -478,6 +482,8 @@ npx @cobusgreyling/loop-audit . --suggest<p><a href="https://github.com/cobusgreyling/loop-engineering">GitHub</a>·+ <a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/QUICKSTART.md">Quickstart</a>+ ·<a href="https://cobusgreyling.substack.com/p/loop-engineering">Essay</a>·<a href="https://addyosmani.com/blog/loop-engineering/">Addy Osmani</a>@@ -509,11 +515,101 @@ function copyNpxAudit() {setTimeout(() => t.textContent = orig || 'Copy', 1400);}+// === loop-cost estimator (client port of tools/loop-cost/src/estimator.ts) ===+const INTERVAL_MS = { m: 60_000, h: 3_600_000, d: 86_400_000 };++const REGISTRY_COSTS = {+ 'ci-sweeper': { cadence: '5m-15m', token_cost: 'very-high', cost: { tokens_noop: 5000, tokens_report: 50000, tokens_action: 200000, suggested_daily_cap: 1000000, early_exit_required: true } },+ 'pr-babysitter': { cadence: '5m-15m', token_cost: 'high', cost: { tokens_noop: 3000, tokens_report: 80000, tokens_action: 250000, suggested_daily_cap: 2000000, early_exit_required: true } },+ 'daily-triage': { cadence: '1d-2h', token_cost: 'low', cost: { tokens_noop: 5000, tokens_report: 50000, tokens_action: 200000, suggested_daily_cap: 100000, early_exit_required: false } },+ 'dependency-sweeper': { cadence: '6h-1d', token_cost: 'medium', cost: { tokens_noop: 5000, tokens_report: 60000, tokens_action: 300000, suggested_daily_cap: 500000, early_exit_required: true } },+ 'post-merge-cleanup': { cadence: '1d-6h', token_cost: 'low', cost: { tokens_noop: 5000, tokens_report: 40000, tokens_action: 150000, suggested_daily_cap: 200000, early_exit_required: false } },+ 'changelog-drafter': { cadence: '1d', token_cost: 'low', cost: { tokens_noop: 5000, tokens_report: 35000, tokens_action: 80000, suggested_daily_cap: 100000, early_exit_required: false } },+ 'issue-triage': { cadence: '2h-1d', token_cost: 'low', cost: { tokens_noop: 3000, tokens_report: 30000, tokens_action: 60000, suggested_daily_cap: 80000, early_exit_required: false } }+};++function parseInterval(token) {+ const m = token.match(/^(\d+)([mhd])$/);+ if (!m) return null;+ return Number(m[1]) * INTERVAL_MS[m[2]];+}++function runsPerDayForInterval(interval) {+ const ms = parseInterval(interval);+ return ms ? Math.floor(86_400_000 / ms) : 1;+}++function cadenceToRunsPerDay(cadence, conservative = false) {+ const parts = cadence.split('-').map(p => p.trim());+ if (parts.length === 1) return runsPerDayForInterval(parts[0]);+ const runs = parts.map(runsPerDayForInterval);+ return conservative ? Math.min(...runs) : Math.max(...runs);+}++function formatTokens(n) {+ if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;+ if (n >= 1_000) return `${Math.round(n / 1_000)}k`;+ return String(n);+}++function realisticMix(level, earlyExitRequired) {+ if (level === 'L1') {+ return earlyExitRequired+ ? { noop: 0.9, report: 0.1, action: 0 }+ : { noop: 0.6, report: 0.4, action: 0 };+ }+ if (level === 'L2') {+ return earlyExitRequired+ ? { noop: 0.85, report: 0.1, action: 0.05 }+ : { noop: 0.5, report: 0.3, action: 0.2 };+ }+ return { noop: 0.4, report: 0.35, action: 0.25 };+}++function estimatePatternCost(patternId, level, cadence) {+ const entry = REGISTRY_COSTS[patternId];+ if (!entry) return null;+ const runsPerDay = cadenceToRunsPerDay(cadence);+ const { cost } = entry;+ const mix = realisticMix(level, cost.early_exit_required);+ const realisticPerRun =+ cost.tokens_noop * mix.noop ++ cost.tokens_report * mix.report ++ cost.tokens_action * mix.action;+ const realisticDay = Math.round(realisticPerRun * runsPerDay);+ const overCap = realisticDay > cost.suggested_daily_cap;+ return {+ patternId,+ level,+ cadence,+ runsPerDay,+ tokenCostTier: entry.token_cost,+ realisticDay,+ suggestedDailyCap: cost.suggested_daily_cap,+ overCap,+ earlyExitRequired: cost.early_exit_required+ };+}++function formatCostSummary(estimate) {+ if (!estimate) return '';+ const capNote = estimate.overCap+ ? ` · <span style="color:#ffb347;">above suggested cap</span>`+ : '';+ const earlyExit = estimate.earlyExitRequired+ ? ' · early-exit required when watchlist empty'+ : '';+ return `<strong>~${formatTokens(estimate.realisticDay)} tokens/day</strong> at ${estimate.level} (${estimate.cadence}, ${estimate.runsPerDay} run${estimate.runsPerDay === 1 ? '' : 's'}/day) · cap ${formatTokens(estimate.suggestedDailyCap)}/day · tier ${estimate.tokenCostTier}${capNote}${earlyExit}<br><span style="font-size:0.75rem;">Refine: <code>npx @cobusgreyling/loop-cost --pattern ${estimate.patternId} --level ${estimate.level} --cadence ${estimate.cadence}</code></span>`;+}+// === Interactive Pattern Picker ===const PATTERNS = {ci: {name: 'CI Sweeper',meta: '5–15m • Medium risk • L2 cautious',+ patternId: 'ci-sweeper',+ costLevel: 'L2',+ costCadence: '15m',npx: 'npx @cobusgreyling/loop-init . --pattern ci-sweeper --tool grok',loop: '/loop 15m Run ci-triage on failing CI. Update ci-sweeper-state.md. Fix only regressions in worktree. Max 3 attempts.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/ci-sweeper.md',@@ -522,6 +618,9 @@ const PATTERNS = {prs: {name: 'PR Babysitter',meta: '5–15m • Medium risk • L1 watch → L2',+ patternId: 'pr-babysitter',+ costLevel: 'L1',+ costCadence: '10m',npx: 'npx @cobusgreyling/loop-init . --pattern pr-babysitter --tool grok',loop: '/loop 10m Run pr-review-triage. Update pr-babysitter-state.md. Worktree + verifier. No auto-merge by default.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/pr-babysitter.md',@@ -530,6 +629,9 @@ const PATTERNS = {morning: {name: 'Daily Triage',meta: '1d–2h • Low risk • Start here (L1)',+ patternId: 'daily-triage',+ costLevel: 'L1',+ costCadence: '1d',npx: 'npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok',loop: '/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/daily-triage.md',@@ -538,6 +640,9 @@ const PATTERNS = {deps: {name: 'Dependency Sweeper',meta: '6h–1d • Medium risk • Patch-only first',+ patternId: 'dependency-sweeper',+ costLevel: 'L2',+ costCadence: '6h',npx: 'npx @cobusgreyling/loop-init . --pattern dependency-sweeper --tool grok',loop: '/loop 6h Run dependency-triage. Patch-only auto-fix in worktree + verifier. Escalate majors.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/dependency-sweeper.md',@@ -546,6 +651,9 @@ const PATTERNS = {debt: {name: 'Post-Merge Cleanup',meta: '1d–6h • Low risk • Off-peak L1',+ patternId: 'post-merge-cleanup',+ costLevel: 'L1',+ costCadence: '1d',npx: 'npx @cobusgreyling/loop-init . --pattern post-merge-cleanup --tool grok',loop: '/loop 1d Run post-merge-scan on recent merges. Update post-merge-state.md. Small fixes only.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/post-merge-cleanup.md',@@ -554,6 +662,9 @@ const PATTERNS = {releases: {name: 'Changelog Drafter',meta: '1d or tag • Low risk • New favorite',+ patternId: 'changelog-drafter',+ costLevel: 'L1',+ costCadence: '1d',npx: 'npx @cobusgreyling/loop-init . --pattern changelog-drafter --tool grok',loop: '/loop 1d Run changelog-scan + draft-release-notes. Write RELEASE_NOTES_DRAFT.md. Human review only.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/changelog-drafter.md',@@ -562,6 +673,9 @@ const PATTERNS = {issues: {name: 'Issue Triage',meta: '2h–1d • Low risk • Pairs with Daily Triage',+ patternId: 'issue-triage',+ costLevel: 'L1',+ costCadence: '1d',npx: 'npx @cobusgreyling/loop-init . --pattern issue-triage --tool grok',loop: '/loop 1d Run issue-triage. Update issue-triage-state.md. Propose labels and priorities only — no auto-close.',patternHref: 'https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/issue-triage.md',@@ -594,6 +708,13 @@ function setupPatternPicker() {document.getElementById('reco-link').href = p.patternHref;document.getElementById('reco-starter').href = p.starterHref;+ const costEl = document.getElementById('reco-cost');+ if (costEl && p.patternId) {+ const estimate = estimatePatternCost(p.patternId, p.costLevel, p.costCadence);+ costEl.innerHTML = formatCostSummary(estimate);+ costEl.style.display = estimate ? 'block' : 'none';+ }+output.style.display = 'block';current = p;});