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.

feat(conversion): hero single-line install and auto Loop Ready score (#95)

Cobus Greyling209b4fcb5050
diff --git a/README.md b/README.md
index c3bce4f..0b9d546 100644
--- a/README.md
+++ b/README.md
@@ -25,26 +25,36 @@
</a>
</p>
+> **Stop prompting. Design the loop. Get a score.**
+
+```bash
+npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
+```
+
+`loop-init` scaffolds your loop and prints your **Loop Ready** score. Paste the badge when you're proud of it:
+
+```bash
+npx @cobusgreyling/loop-audit . --badge
+```
+
<p align="center">
- <img src="assets/visuals/LE5.jpeg" alt="Loop Engineering — design the system that prompts your agents" width="100%" />
+ <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 is replacing yourself as the person who prompts the agent. You design the system that does it instead.**
+Loop engineering replaces you 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.
-
-
-
<p align="center">
<strong><a href="https://cobusgreyling.github.io/loop-engineering/">→ Interactive showcase + pattern picker</a></strong>
- <br>
- <strong><a href="https://cobusgreyling.substack.com/p/loop-engineering">→ Loop Engineering essay (Substack)</a></strong>
- <br>
- <a href="https://addyosmani.com/blog/loop-engineering/">Canonical essay by Addy Osmani</a>
+ ·
+ <a href="https://cobusgreyling.substack.com/p/loop-engineering">Essay</a>
+ ·
+ <a href="https://addyosmani.com/blog/loop-engineering/">Addy Osmani</a>
</p>
## Contents
@@ -167,13 +177,13 @@ Machine-readable index: [patterns/registry.yaml](patterns/registry.yaml) (7 patt
## Getting Started (5 minutes)
```bash
-# 1. Scaffold a starter (or copy manually — see starters/)
+# 1. Scaffold + get your Loop Ready score (printed automatically)
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
# 2. Estimate token spend for your cadence
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1
-# 3. Audit readiness (budget + run-log now scored)
+# 3. Re-audit after improvements
npx @cobusgreyling/loop-audit . --suggest
# Optional: paste Loop Ready badge into your README
diff --git a/assets/visuals/loop-audit-demo.gif b/assets/visuals/loop-audit-demo.gif
new file mode 100644
index 0000000..127d8db
Binary files /dev/null and b/assets/visuals/loop-audit-demo.gif differ
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 30395b2..5b4a8da 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -1,5 +1,9 @@
# Quickstart — 5 minutes to your first loop
+> **Stop prompting. Design the loop. Get a score.**
+
+Watch the score climb: [loop-audit-demo.gif](../assets/visuals/loop-audit-demo.gif) (10 → 70 → 100 in ~15s).
+
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.
@@ -20,7 +24,7 @@ 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.
+`loop-init` copies the starter kit, creates `STATE.md`, `LOOP.md`, `loop-budget.md`, and `loop-run-log.md`, then **prints your Loop Ready score** and first command.
## 3. Check cost before you schedule (30 seconds)
diff --git a/docs/index.html b/docs/index.html
index c0bc187..bc4e466 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -10,7 +10,7 @@ title: Loop Engineering — Showcase
<title>Loop Engineering — Design systems that prompt your agents</title>
<meta name="description" content="The practical reference for loop engineering. Patterns, starters, checklists, and tooling for Grok, Claude Code, and Codex.">
<meta property="og:title" content="Loop Engineering">
- <meta property="og:description" content="Stop prompting. Start designing loops.">
+ <meta property="og:description" content="Stop prompting. Design the loop. Get a score. Two npx commands.">
<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="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-engineering-logo.svg">
@@ -52,28 +52,30 @@ title: Loop Engineering — Showcase
<header class="hero wrap">
<div class="badge">Open source · Tool-agnostic · Production-ready · L3 dogfood · 7 patterns · Interactive tools</div>
- <h1>Design the system<br>that prompts your agents</h1>
+ <h1>Stop prompting.<br>Design the loop.<br>Get a score.</h1>
<p class="lead">
- Loop engineering moves you from "I prompt → agent responds → I prompt again"
- to "I design the autonomous system that discovers work, verifies results, and drives progress."
+ Run one command in any repo. <code>loop-init</code> scaffolds your loop and prints a <strong>Loop Ready</strong> score you can paste into your README.
</p>
+ <div class="code-block" style="max-width:720px;margin:0 auto 24px;">
+ <div class="code-header">
+ <div class="code-dots"><span></span><span></span><span></span></div>
+ <span>terminal — try now</span>
+ <button onclick="copyNpxInit()" class="copy-btn">Copy</button>
+ </div>
+ <pre>npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok</pre>
+ </div>
<div class="hero-cta">
- <a href="https://github.com/cobusgreyling/loop-engineering/tree/main/starters/minimal-loop" class="btn btn-primary">Clone a Starter →</a>
+ <a href="#start" class="btn btn-primary">Try in 60 seconds →</a>
+ <a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/QUICKSTART.md" class="btn btn-ghost">Quickstart</a>
<a href="https://cobusgreyling.substack.com/p/loop-engineering" class="btn btn-ghost">Read the Essay</a>
- <a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/primitives-matrix.md" class="btn btn-ghost">Primitives Matrix</a>
<a href="https://cobusgreyling.github.io/goal-engineering/" class="btn btn-ghost">Goal Engineering</a>
</div>
- <p style="text-align:center; margin-top:-12px; margin-bottom:32px; font-size:0.9rem; color:var(--text-muted);">
- Or try instantly: <code style="background:#050810;padding:2px 6px;border-radius:4px;">npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok</code>
- &nbsp; <button onclick="copyNpxInit()" class="copy-btn" style="vertical-align:middle;">Copy</button>
- &nbsp;&nbsp; <code style="background:#050810;padding:2px 6px;border-radius:4px;">npx @cobusgreyling/loop-audit . --suggest</code>
- <button onclick="copyNpxAudit()" class="copy-btn" style="vertical-align:middle;">Copy</button>
- </p>
<img
class="hero-img"
- src="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-engineering-social-banner.jpg"
- alt="Loop Engineering — Design the system that prompts your agents"
+ src="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-audit-demo.gif"
+ alt="Loop Ready score climbs from 10 to 100"
loading="lazy"
+ style="margin-top:24px;"
/>
</header>
diff --git a/scripts/before-after-demo.sh b/scripts/before-after-demo.sh
index 27193e5..23671dc 100755
--- a/scripts/before-after-demo.sh
+++ b/scripts/before-after-demo.sh
@@ -12,6 +12,17 @@ if [[ ! -f "$AUDIT" ]]; then
(cd "$ROOT/tools/loop-audit" && npm ci --silent && npm run build --silent)
fi
+score_bar() {
+ local score="$1"
+ local width=20
+ local filled=$(( (score * width + 50) / 100 ))
+ local bar=""
+ local i
+ for ((i=0; i<filled; i++)); do bar+="█"; done
+ for ((i=filled; i<width; i++)); do bar+="░"; done
+ echo "$bar ${score}/100"
+}
+
run_audit() {
local label="$1"
local path="$2"
@@ -20,6 +31,16 @@ run_audit() {
echo "$label"
echo "══════════════════════════════════════════════════"
node "$AUDIT" "$path" || true
+ local json
+ json="$(node "$AUDIT" "$path" --json 2>/dev/null || true)"
+ if [[ -n "$json" ]]; then
+ local score level
+ score="$(python3 -c "import json,sys; print(json.load(sys.stdin)['score'])" <<<"$json")"
+ level="$(python3 -c "import json,sys; print(json.load(sys.stdin)['level'])" <<<"$json")"
+ echo ""
+ echo "▸ Loop Ready: ${score}/100 (${level})"
+ score_bar "$score"
+ fi
}
echo "Loop Readiness — before/after demo"
diff --git a/scripts/generate-audit-demo-gif.py b/scripts/generate-audit-demo-gif.py
new file mode 100644
index 0000000..0117fdc
--- /dev/null
+++ b/scripts/generate-audit-demo-gif.py
@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Render loop-audit-demo.gif — score climbing 10 → 70 → 100."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+ROOT = Path(__file__).resolve().parents[1]
+OUT = ROOT / "assets" / "visuals" / "loop-audit-demo.gif"
+AUDIT = ROOT / "tools" / "loop-audit" / "dist" / "cli.js"
+FONT_CANDIDATES = [
+ "/System/Library/Fonts/Menlo.ttc",
+ "/System/Library/Fonts/Supplemental/Courier New.ttf",
+ "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
+]
+
+BG = (5, 8, 16)
+FG = (220, 228, 240)
+MUTED = (130, 145, 170)
+ACCENT = (62, 232, 197)
+WARN = (210, 153, 34)
+BAR_FILL = (62, 232, 197)
+BAR_EMPTY = (30, 40, 58)
+TITLE = "#0d1117"
+BORDER = (30, 45, 68)
+
+STAGES = [
+ ("Stage 0 — empty project", 10, "L0", "Not loop-ready — start with a starter."),
+ ("Stage 1 — after loop-init", 70, "L2", "Good foundation — triage + state in place."),
+ ("Stage 2 — verifier + AGENTS.md", 100, "L2", "Strong loop — paste your badge."),
+]
+
+WIDTH, HEIGHT = 900, 520
+FPS = 2
+
+
+def load_font(size: int) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
+ for path in FONT_CANDIDATES:
+ if Path(path).exists():
+ try:
+ return ImageFont.truetype(path, size)
+ except OSError:
+ continue
+ return ImageFont.load_default()
+
+
+def score_bar(score: int, width: int = 24) -> str:
+ filled = max(0, min(width, round(score / 100 * width)))
+ return "█" * filled + "░" * (width - filled)
+
+
+def render_frame(stage_title: str, score: int, level: str, assessment: str) -> Image.Image:
+ img = Image.new("RGB", (WIDTH, HEIGHT), BG)
+ draw = ImageDraw.Draw(img)
+
+ font_sm = load_font(16)
+ font_md = load_font(20)
+ font_lg = load_font(28)
+ font_xl = load_font(40)
+
+ draw.rounded_rectangle((24, 24, WIDTH - 24, HEIGHT - 24), radius=12, fill=TITLE, outline=BORDER, width=2)
+
+ # window chrome
+ for i, color in enumerate([(255, 95, 86), (255, 189, 46), (39, 201, 63)]):
+ draw.ellipse((44 + i * 22, 44, 56 + i * 22, 56), fill=color)
+ draw.text((120, 42), "terminal — loop-audit", fill=MUTED, font=font_sm)
+
+ y = 100
+ draw.text((48, y), "Loop Readiness — before/after demo", fill=MUTED, font=font_sm)
+ y += 36
+ draw.text((48, y), stage_title, fill=FG, font=font_md)
+ y += 48
+
+ draw.text((48, y), f"Score: {score}/100 Level: {level}", fill=FG, font=font_lg)
+ y += 44
+ bar = score_bar(score)
+ bar_color = ACCENT if score >= 40 else WARN
+ draw.text((48, y), bar, fill=bar_color, font=font_md)
+ draw.text((48 + len(bar) * 12 + 16, y), f"{score}/100", fill=bar_color, font=font_md)
+ y += 52
+
+ draw.text((48, y), assessment, fill=MUTED, font=font_sm)
+ y += 56
+
+ if score >= 70:
+ draw.text((48, y), "✓ Triage skill present", fill=ACCENT, font=font_sm)
+ y += 28
+ draw.text((48, y), "✓ State file(s): STATE.md", fill=ACCENT, font=font_sm)
+ y += 28
+ if score >= 100:
+ draw.text((48, y), "✓ Verifier skill present", fill=ACCENT, font=font_sm)
+ y += 28
+
+ draw.text((48, HEIGHT - 88), "npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok", fill=FG, font=font_sm)
+ draw.text((48, HEIGHT - 56), "npx @cobusgreyling/loop-audit . --badge", fill=ACCENT, font=font_sm)
+
+ # big score watermark
+ draw.text((WIDTH - 200, 130), str(score), fill=(20, 32, 48), font=font_xl)
+
+ return img
+
+
+def build_gif() -> None:
+ frames: list[Image.Image] = []
+
+ intro = Image.new("RGB", (WIDTH, HEIGHT), BG)
+ draw = ImageDraw.Draw(intro)
+ font_lg = load_font(32)
+ font_md = load_font(22)
+ font_sm = load_font(18)
+ draw.text((48, 180), "Stop prompting.", fill=FG, font=font_lg)
+ draw.text((48, 230), "Design the loop.", fill=FG, font=font_lg)
+ draw.text((48, 280), "Get a score.", fill=ACCENT, font=font_lg)
+ draw.text((48, 360), "loop-init → loop-audit", fill=MUTED, font=font_md)
+ draw.text((48, 400), "10 → 70 → 100", fill=ACCENT, font=font_sm)
+ for _ in range(3):
+ frames.append(intro)
+
+ for title, score, level, assessment in STAGES:
+ frame = render_frame(title, score, level, assessment)
+ hold = 5 if score == 100 else 4
+ frames.extend([frame] * hold)
+
+ cta = render_frame("Done — paste your badge", 100, "L2", "Share your Loop Ready score in README.")
+ frames.extend([cta] * 4)
+
+ OUT.parent.mkdir(parents=True, exist_ok=True)
+ duration_ms = int(1000 / FPS)
+ frames[0].save(
+ OUT,
+ save_all=True,
+ append_images=frames[1:],
+ duration=duration_ms,
+ loop=0,
+ optimize=True,
+ )
+ print(f"Wrote {OUT} ({len(frames)} frames, {OUT.stat().st_size // 1024} KB)")
+
+
+def ensure_audit_built() -> None:
+ if AUDIT.exists():
+ return
+ subprocess.run(["npm", "ci"], cwd=ROOT / "tools" / "loop-audit", check=True)
+ subprocess.run(["npm", "run", "build"], cwd=ROOT / "tools" / "loop-audit", check=True)
+
+
+if __name__ == "__main__":
+ ensure_audit_built()
+ build_gif()
\ No newline at end of file
diff --git a/tools/loop-audit/dist/reporter.d.ts b/tools/loop-audit/dist/reporter.d.ts
index 9381720..8a3a189 100644
--- a/tools/loop-audit/dist/reporter.d.ts
+++ b/tools/loop-audit/dist/reporter.d.ts
@@ -1,4 +1,6 @@
import type { AuditResult } from './auditor.js';
+/** ASCII progress bar for terminal + demo GIFs. */
+export declare function formatScoreBar(score: number, width?: number): string;
/** Markdown badge for README — paste output from `loop-audit . --badge`. */
export declare function formatBadge(r: AuditResult): string;
export declare function formatHuman(r: AuditResult): string;
diff --git a/tools/loop-audit/dist/reporter.js b/tools/loop-audit/dist/reporter.js
index 5b5290f..a25b71d 100644
--- a/tools/loop-audit/dist/reporter.js
+++ b/tools/loop-audit/dist/reporter.js
@@ -5,6 +5,14 @@ const LEVEL_BADGE_COLORS = {
L3: '3ee8c5',
};
const SHOWCASE_URL = 'https://cobusgreyling.github.io/loop-engineering/';
+/** ASCII progress bar for terminal + demo GIFs. */
+export function formatScoreBar(score, width = 20) {
+ const filled = Math.max(0, Math.min(width, Math.round((score / 100) * width)));
+ return `${'█'.repeat(filled)}${'░'.repeat(width - filled)} ${score}/100`;
+}
+function auditTargetArg(target) {
+ return target.includes(' ') ? `"${target}"` : target;
+}
/** Markdown badge for README — paste output from `loop-audit . --badge`. */
export function formatBadge(r) {
const color = LEVEL_BADGE_COLORS[r.level];
@@ -18,6 +26,7 @@ export function formatHuman(r) {
lines.push(`Loop Readiness Audit — ${r.target}`);
lines.push('═'.repeat(50));
lines.push(`Score: ${r.score}/100 Level: ${r.level}`);
+ lines.push(formatScoreBar(r.score));
lines.push(r.assessment);
lines.push('');
lines.push('Findings:');
@@ -33,6 +42,7 @@ export function formatHuman(r) {
}
}
lines.push('');
+ lines.push(`Share: npx @cobusgreyling/loop-audit ${auditTargetArg(r.target)} --badge`);
lines.push('Docs: docs/loop-design-checklist.md');
lines.push('Tip: rerun with --suggest for ready-to-paste copy commands from templates/starters.');
lines.push('');
diff --git a/tools/loop-audit/package.json b/tools/loop-audit/package.json
index e406a56..7041f7d 100644
--- a/tools/loop-audit/package.json
+++ b/tools/loop-audit/package.json
@@ -1,6 +1,6 @@
{
"name": "@cobusgreyling/loop-audit",
- "version": "1.5.0",
+ "version": "1.5.1",
"description": "Loop engineering readiness auditor. Compute Loop Readiness Score (L0-L3), detect activity, and get actionable suggestions. npx @cobusgreyling/loop-audit . --suggest",
"type": "module",
"bin": {
diff --git a/tools/loop-audit/src/reporter.ts b/tools/loop-audit/src/reporter.ts
index 314c260..348578b 100644
--- a/tools/loop-audit/src/reporter.ts
+++ b/tools/loop-audit/src/reporter.ts
@@ -9,6 +9,16 @@ const LEVEL_BADGE_COLORS: Record<AuditResult['level'], string> = {
const SHOWCASE_URL = 'https://cobusgreyling.github.io/loop-engineering/';
+/** ASCII progress bar for terminal + demo GIFs. */
+export function formatScoreBar(score: number, width = 20): string {
+ const filled = Math.max(0, Math.min(width, Math.round((score / 100) * width)));
+ return `${'█'.repeat(filled)}${'░'.repeat(width - filled)} ${score}/100`;
+}
+
+function auditTargetArg(target: string): string {
+ return target.includes(' ') ? `"${target}"` : target;
+}
+
/** Markdown badge for README — paste output from `loop-audit . --badge`. */
export function formatBadge(r: AuditResult): string {
const color = LEVEL_BADGE_COLORS[r.level];
@@ -23,6 +33,7 @@ export function formatHuman(r: AuditResult): string {
lines.push(`Loop Readiness Audit — ${r.target}`);
lines.push('═'.repeat(50));
lines.push(`Score: ${r.score}/100 Level: ${r.level}`);
+ lines.push(formatScoreBar(r.score));
lines.push(r.assessment);
lines.push('');
lines.push('Findings:');
@@ -38,6 +49,7 @@ export function formatHuman(r: AuditResult): string {
}
}
lines.push('');
+ lines.push(`Share: npx @cobusgreyling/loop-audit ${auditTargetArg(r.target)} --badge`);
lines.push('Docs: docs/loop-design-checklist.md');
lines.push('Tip: rerun with --suggest for ready-to-paste copy commands from templates/starters.');
lines.push('');
diff --git a/tools/loop-init/dist/cli.js b/tools/loop-init/dist/cli.js
index 08abe35..92c475b 100644
--- a/tools/loop-init/dist/cli.js
+++ b/tools/loop-init/dist/cli.js
@@ -1,4 +1,5 @@
#!/usr/bin/env node
+import { spawn } from 'node:child_process';
import { cp, mkdir, readFile, writeFile, access } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -254,6 +255,57 @@ function firstLoopCommand(pattern, tool) {
};
return cmds[pattern][tool];
}
+async function resolveAuditCli() {
+ const monorepo = path.resolve(PACKAGE_ROOT, '../loop-audit/dist/cli.js');
+ if (await exists(monorepo))
+ return monorepo;
+ try {
+ const { createRequire } = await import('node:module');
+ const require = createRequire(import.meta.url);
+ const pkg = require.resolve('@cobusgreyling/loop-audit/package.json');
+ return path.join(path.dirname(pkg), 'dist/cli.js');
+ }
+ catch {
+ return null;
+ }
+}
+async function runAuditJson(cli, targetDir) {
+ return new Promise((resolve, reject) => {
+ const child = spawn('node', [cli, targetDir, '--json'], {
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ let stdout = '';
+ child.stdout.on('data', (chunk) => {
+ stdout += chunk.toString();
+ });
+ child.on('error', reject);
+ child.on('close', () => {
+ if (stdout.trim())
+ resolve(stdout);
+ else
+ reject(new Error('loop-audit produced no output'));
+ });
+ });
+}
+async function runAuditSummary(targetDir) {
+ const cli = await resolveAuditCli();
+ if (!cli)
+ return null;
+ try {
+ const stdout = await runAuditJson(cli, targetDir);
+ return JSON.parse(stdout);
+ }
+ catch {
+ return null;
+ }
+}
+function formatScoreBar(score, width = 20) {
+ const filled = Math.max(0, Math.min(width, Math.round((score / 100) * width)));
+ return `${'█'.repeat(filled)}${'░'.repeat(width - filled)} ${score}/100`;
+}
+function auditTargetArg(target, targetDir) {
+ return target === '.' ? '.' : targetDir;
+}
async function main() {
const args = parseArgs(process.argv.slice(2));
if (args.help) {
@@ -375,10 +427,29 @@ npm run lint
await writeFile(path.join(targetDir, 'AGENTS.md'), agentsTemplate);
console.log(' created: AGENTS.md (template)');
}
- console.log('\n=== Next steps ===');
- console.log(` npx @cobusgreyling/loop-audit ${target === '.' ? '.' : target} --suggest`);
- console.log(` npx @cobusgreyling/loop-cost --pattern ${pattern}`);
- console.log(` First loop command (${tool}):\n ${firstLoopCommand(pattern, tool)}\n`);
+ const auditArg = auditTargetArg(target, targetDir);
+ if (!dryRun) {
+ const audit = await runAuditSummary(targetDir);
+ if (audit) {
+ console.log('');
+ console.log(`✓ Loop Ready: ${audit.score}/100 (${audit.level})`);
+ console.log(` ${formatScoreBar(audit.score)}`);
+ console.log(` ${audit.assessment}`);
+ console.log('');
+ console.log('Paste badge in README:');
+ console.log(` npx @cobusgreyling/loop-audit ${auditArg} --badge`);
+ }
+ else {
+ console.log('\n=== Loop Ready score ===');
+ console.log(` npx @cobusgreyling/loop-audit ${auditArg} --suggest`);
+ }
+ }
+ console.log('');
+ console.log(`First loop (${tool}):`);
+ console.log(` ${firstLoopCommand(pattern, tool)}`);
+ console.log('');
+ console.log(`Estimate cost: npx @cobusgreyling/loop-cost --pattern ${pattern} --level L1`);
+ console.log('');
}
async function readDirNames(dir) {
const { readdir } = await import('node:fs/promises');
diff --git a/tools/loop-init/package-lock.json b/tools/loop-init/package-lock.json
index 2976dbb..ed090e1 100644
--- a/tools/loop-init/package-lock.json
+++ b/tools/loop-init/package-lock.json
@@ -1,13 +1,16 @@
{
"name": "@cobusgreyling/loop-init",
- "version": "1.2.2",
+ "version": "1.3.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@cobusgreyling/loop-init",
- "version": "1.2.2",
+ "version": "1.3.0",
"license": "MIT",
+ "dependencies": {
+ "@cobusgreyling/loop-audit": "^1.5.0"
+ },
"bin": {
"loop-init": "dist/cli.js"
},
@@ -19,6 +22,18 @@
"node": ">=18"
}
},
+ "node_modules/@cobusgreyling/loop-audit": {
+ "version": "1.5.0",
+ "resolved": "https://registry.npmjs.org/@cobusgreyling/loop-audit/-/loop-audit-1.5.0.tgz",
+ "integrity": "sha512-QsOdHO/+arWu53FervbHNkSRqdULZjhhv+I3vwwLhRu37HzN6sHGa1qY8GAzkXZUJRobUEV5agiOTfJGc+fkbw==",
+ "license": "MIT",
+ "bin": {
+ "loop-audit": "dist/cli.js"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
"node_modules/@types/node": {
"version": "26.0.1",
"resolved": "https://registry.npmjs.org/@types/node/-/node-26.0.1.tgz",
diff --git a/tools/loop-init/package.json b/tools/loop-init/package.json
index a27f0e0..bd65a21 100644
--- a/tools/loop-init/package.json
+++ b/tools/loop-init/package.json
@@ -1,6 +1,6 @@
{
"name": "@cobusgreyling/loop-init",
- "version": "1.2.3",
+ "version": "1.3.0",
"description": "Scaffold loop engineering patterns and starters into any project. Supports Grok, Claude Code, Codex and more. npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok",
"type": "module",
"bin": {
@@ -48,6 +48,9 @@
"publishConfig": {
"access": "public"
},
+ "dependencies": {
+ "@cobusgreyling/loop-audit": "^1.5.0"
+ },
"devDependencies": {
"@types/node": "^26.0.0",
"typescript": "^6.0.3"
diff --git a/tools/loop-init/src/cli.ts b/tools/loop-init/src/cli.ts
index 301147c..fcc5ee7 100644
--- a/tools/loop-init/src/cli.ts
+++ b/tools/loop-init/src/cli.ts
@@ -1,4 +1,5 @@
#!/usr/bin/env node
+import { spawn } from 'node:child_process';
import { cp, mkdir, readFile, writeFile, access } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -314,6 +315,58 @@ function firstLoopCommand(pattern: Pattern, tool: Tool): string {
return cmds[pattern][tool];
}
+async function resolveAuditCli(): Promise<string | null> {
+ const monorepo = path.resolve(PACKAGE_ROOT, '../loop-audit/dist/cli.js');
+ if (await exists(monorepo)) return monorepo;
+ try {
+ const { createRequire } = await import('node:module');
+ const require = createRequire(import.meta.url);
+ const pkg = require.resolve('@cobusgreyling/loop-audit/package.json');
+ return path.join(path.dirname(pkg), 'dist/cli.js');
+ } catch {
+ return null;
+ }
+}
+
+async function runAuditJson(cli: string, targetDir: string): Promise<string> {
+ return new Promise((resolve, reject) => {
+ const child = spawn('node', [cli, targetDir, '--json'], {
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ let stdout = '';
+ child.stdout.on('data', (chunk: Buffer | string) => {
+ stdout += chunk.toString();
+ });
+ child.on('error', reject);
+ child.on('close', () => {
+ if (stdout.trim()) resolve(stdout);
+ else reject(new Error('loop-audit produced no output'));
+ });
+ });
+}
+
+async function runAuditSummary(
+ targetDir: string,
+): Promise<{ score: number; level: string; assessment: string } | null> {
+ const cli = await resolveAuditCli();
+ if (!cli) return null;
+ try {
+ const stdout = await runAuditJson(cli, targetDir);
+ return JSON.parse(stdout) as { score: number; level: string; assessment: string };
+ } catch {
+ return null;
+ }
+}
+
+function formatScoreBar(score: number, width = 20): string {
+ const filled = Math.max(0, Math.min(width, Math.round((score / 100) * width)));
+ return `${'█'.repeat(filled)}${'░'.repeat(width - filled)} ${score}/100`;
+}
+
+function auditTargetArg(target: string, targetDir: string): string {
+ return target === '.' ? '.' : targetDir;
+}
+
async function main() {
const args = parseArgs(process.argv.slice(2));
@@ -452,10 +505,30 @@ npm run lint
console.log(' created: AGENTS.md (template)');
}
- console.log('\n=== Next steps ===');
- console.log(` npx @cobusgreyling/loop-audit ${target === '.' ? '.' : target} --suggest`);
- console.log(` npx @cobusgreyling/loop-cost --pattern ${pattern}`);
- console.log(` First loop command (${tool}):\n ${firstLoopCommand(pattern, tool)}\n`);
+ const auditArg = auditTargetArg(target, targetDir);
+
+ if (!dryRun) {
+ const audit = await runAuditSummary(targetDir);
+ if (audit) {
+ console.log('');
+ console.log(`✓ Loop Ready: ${audit.score}/100 (${audit.level})`);
+ console.log(` ${formatScoreBar(audit.score)}`);
+ console.log(` ${audit.assessment}`);
+ console.log('');
+ console.log('Paste badge in README:');
+ console.log(` npx @cobusgreyling/loop-audit ${auditArg} --badge`);
+ } else {
+ console.log('\n=== Loop Ready score ===');
+ console.log(` npx @cobusgreyling/loop-audit ${auditArg} --suggest`);
+ }
+ }
+
+ console.log('');
+ console.log(`First loop (${tool}):`);
+ console.log(` ${firstLoopCommand(pattern, tool)}`);
+ console.log('');
+ console.log(`Estimate cost: npx @cobusgreyling/loop-cost --pattern ${pattern} --level L1`);
+ console.log('');
}
async function readDirNames(dir: string): Promise<string[]> {
diff --git a/tools/loop-init/test/cli.test.mjs b/tools/loop-init/test/cli.test.mjs
index 4d74327..87923b0 100644
--- a/tools/loop-init/test/cli.test.mjs
+++ b/tools/loop-init/test/cli.test.mjs
@@ -43,6 +43,25 @@ test('loop-init dry-run scaffolds daily-triage', async () => {
}
});
+test('loop-init prints Loop Ready score after scaffold', async () => {
+ const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-audit-'));
+ try {
+ const { stdout } = await exec('node', [
+ CLI,
+ dir,
+ '--pattern',
+ 'daily-triage',
+ '--tool',
+ 'grok',
+ ]);
+ assert.match(stdout, /Loop Ready:/);
+ assert.match(stdout, /\/100/);
+ assert.match(stdout, /--badge/);
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+});
+
test('loop-init scaffolds issue-triage with bundled assets', async () => {
const dir = await mkdtemp(path.join(tmpdir(), 'loop-init-'));
try {