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
feat(loop-sync): make --auto-fix actually fix things (#523)
JonyT Agenticb5054c886055
diff --git a/tools/loop-sync/README.md b/tools/loop-sync/README.mdindex 1794137..d0f924f 100644--- a/tools/loop-sync/README.md+++ b/tools/loop-sync/README.md@@ -31,8 +31,8 @@ loop-sync [target-dir] [options]| Option | Description ||--------|-------------|-| `-a, --auto-fix` | Attempt to auto-fix issues (experimental) |-| `-d, --dry-run` | Show what would be done without making changes |+| `-a, --auto-fix` | Scaffold missing STATE.md, gate.yaml, loop-budget.md, and loop-run-log.md with minimal defaults, and add a missing STATE.md reference to LOOP.md. LOOP.md and AGENTS.md are never fabricated — run `loop-init` for those. |+| `-d, --dry-run` | With `--auto-fix`, report what would be scaffolded/changed without writing anything || `-v, --verbose` | Show detailed information || `--json` | Output JSON format || `-h, --help` | Show help |@@ -48,6 +48,12 @@ loop-sync ./my-project -v# JSON output for scriptingloop-sync ./my-project --json++# Preview what --auto-fix would scaffold/change, without writing anything+loop-sync ./my-project --auto-fix --dry-run++# Scaffold the safely-fixable files and fix the LOOP.md/STATE.md reference+loop-sync ./my-project --auto-fix```## What it checksdiff --git a/tools/loop-sync/dist/cli.js b/tools/loop-sync/dist/cli.jsindex 4525d89..315acc5 100644--- a/tools/loop-sync/dist/cli.js+++ b/tools/loop-sync/dist/cli.js@@ -38,8 +38,13 @@ Usage:loop-sync [target-dir] [options]Options:- -a, --auto-fix Attempt to auto-fix issues (experimental)- -d, --dry-run Show what would be done without making changes+ -a, --auto-fix Scaffold missing STATE.md, gate.yaml, loop-budget.md, and+ loop-run-log.md with minimal defaults, and add a missing+ STATE.md reference to LOOP.md. LOOP.md and AGENTS.md are+ never fabricated -- their content is pattern-specific,+ so a missing one still just suggests loop-init.+ -d, --dry-run With --auto-fix, report what would be scaffolded/changed+ without writing anything-v, --verbose Show detailed information--json Output JSON format-h, --help Show this help@@ -48,6 +53,8 @@ Examples:loop-sync .loop-sync ./my-project -vloop-sync ./my-project --json+ loop-sync ./my-project --auto-fix --dry-run+ loop-sync ./my-project --auto-fixThe tool checks:- STATE.md ↔ LOOP.md consistencydiff --git a/tools/loop-sync/dist/sync.js b/tools/loop-sync/dist/sync.jsindex 7c99b4c..d9900da 100644--- a/tools/loop-sync/dist/sync.js+++ b/tools/loop-sync/dist/sync.js@@ -7,7 +7,7 @@* 3. Missing required files* 4. Configuration drift from starters*/-import { readFile, access } from 'node:fs/promises';+import { readFile, writeFile, access, mkdir } from 'node:fs/promises';import { readdir, stat } from 'node:fs/promises';import path from 'node:path';/**@@ -110,6 +110,131 @@ function compareMarkdownFiles(file1Content, file2Content, threshold = 0.5) {const similarity = allHeadings.size === 0 ? 1 : matchingHeadings / allHeadings.size;return { similarity, differences };}+/**+ * Required files whose content is pattern-agnostic enough to scaffold a+ * correct, minimal default without knowing which of loop-init's patterns+ * (daily-triage, pr-babysitter, ci-sweeper, ...) the project actually uses.+ * STATE.md, gate.yaml, loop-budget.md, and loop-run-log.md all have exactly+ * this shape upstream (see templates/*.template) -- LOOP.md and AGENTS.md+ * don't, since their content *is* the pattern-specific goal and workflow, so+ * auto-fix intentionally leaves those two as report-only rather than+ * fabricating wrong content.+ *+ * These are inlined rather than read from templates/*.template because+ * loop-sync ships as a standalone npm package (files: ["dist"]) that runs+ * against arbitrary target directories -- a path relative to this package's+ * own install location wouldn't resolve once installed outside this+ * monorepo checkout.+ */+const AUTO_FIXABLE_FILES = new Set(['STATE.md', 'gate.yaml', 'loop-budget.md', 'loop-run-log.md']);+function projectNameFrom(targetDir) {+ return path.basename(path.resolve(targetDir)) || 'this project';+}+function scaffoldContent(file, projectName) {+ switch (file) {+ case 'STATE.md':+ return `# Loop State — ${projectName}++Last run: (set by loop on each run)++## High Priority (loop is acting or waiting on human)++<!-- Format:+- [ ] ID — one-line description+ Loop action: what the loop did last+ Human decision: (if any)+-->++## Watch List++<!-- Items to monitor but not act on yet -->++## Recent Noise (ignored this run)++<!-- Brief list — helps tune triage skill -->++---+Run log: (timestamp) | findings | actions | escalations+`;+ case 'gate.yaml':+ return `# Machine-readable twin of your project's safety policy. Adjust denylist+# and autoMergeAllowlist for your project's own sensitive paths.+version: 1++denylist:+ - ".env"+ - ".env.*"+ - "**/secrets/**"+ - "**/credentials/**"+ - "**/*_key*"+ - "**/*_secret*"+ - ".terraform/**"+ - "k8s/production/**"+ - "**/migrations/**"+ - "auth/**"+ - "payments/**"+ - "billing/**"++# Escalate instead of auto-merging when a change touches more than this many files.+maxFiles: 10++# --action auto-merge only proceeds if every changed path matches one of these.+autoMergeAllowlist:+ - "docs/**"+ - "**/*.md"+`;+ case 'loop-budget.md':+ return `# Loop Budget — ${projectName}++## Daily limits++| Loop | Max runs/day | Max tokens/day | Max sub-agent spawns/run |+|------|--------------|----------------|--------------------------|+| Daily Triage | 2 | 100k | 0 (L1) / 2 (L2) |+| PR Babysitter | 288 | 2M | 3 |+| CI Sweeper | 96 | 1M | 3 |+| Dependency Sweeper | 4 | 500k | 3 |+| Post-Merge Cleanup | 1 | 200k | 2 |++## On budget exceed++1. Pause all schedulers (\`scheduler_delete\` or disable automations)+2. Append event to \`loop-run-log.md\`+3. Notify human (Slack / issue / STATE.md High Priority)++## Kill switch++- Command or issue label: \`loop-pause-all\`+- Resume only after human clears the flag in STATE.md+`;+ case 'loop-run-log.md':+ return `# Loop Run Log — ${projectName}++Append one entry per run. Prune entries older than 30 days.++## Format++\`\`\`json+{+ "run_id": "2026-06-09T08:15:00Z",+ "pattern": "daily-triage",+ "duration_s": 45,+ "items_found": 4,+ "actions_taken": 1,+ "escalations": 0,+ "tokens_estimate": 52000,+ "outcome": "report-only | fix-proposed | escalated | no-op"+}+\`\`\`++## Recent Runs++<!-- Loop appends below this line -->+`;+ default:+ throw new Error(`No auto-fix scaffold defined for ${file}.`);+ }+}/*** Scan skills directory for version information*/@@ -165,12 +290,31 @@ export async function runSync(options) {for (const file of requiredFiles) {const filePath = path.join(targetDir, file);if (!await fileExists(filePath)) {+ const fixable = AUTO_FIXABLE_FILES.has(file);+ if (autoFix && fixable) {+ if (!dryRun) {+ await mkdir(path.dirname(filePath), { recursive: true });+ await writeFile(filePath, scaffoldContent(file, projectNameFrom(targetDir)));+ }+ issues.push({+ type: 'missing',+ file,+ message: dryRun+ ? `${file} is missing — would scaffold a minimal default (--dry-run, no changes made)`+ : `${file} was missing — scaffolded a minimal default`,+ severity: 'info',+ suggestion: 'Review the generated content and adjust it for your project.',+ });+ continue;+ }issues.push({type: 'missing',file,message: `${file} is missing`,severity: 'error',- suggestion: `Run 'npx @cobusgreyling/loop-init . --pattern daily-triage' to scaffold required files`,+ suggestion: fixable+ ? `Run with --auto-fix to scaffold a minimal default, or 'npx @cobusgreyling/loop-init . --pattern daily-triage' for pattern-specific content`+ : `Run 'npx @cobusgreyling/loop-init . --pattern daily-triage' to scaffold required files`,});}}@@ -187,13 +331,30 @@ export async function runSync(options) {const stateFiles = extractStateFiles(loopContent);// Check if STATE.md is referenced in LOOP.mdif (!stateFiles.includes('STATE.md')) {- issues.push({- type: 'inconsistent',- file: 'LOOP.md',- message: 'LOOP.md does not reference STATE.md',- severity: 'warning',- suggestion: 'Add STATE.md to the state files list in LOOP.md',- });+ if (autoFix) {+ if (!dryRun) {+ const separator = /\n\n$/.test(loopContent) ? '' : loopContent.endsWith('\n') ? '\n' : '\n\n';+ await writeFile(loopPath, `${loopContent}${separator}Update STATE.md after each run.\n`);+ }+ issues.push({+ type: 'inconsistent',+ file: 'LOOP.md',+ message: dryRun+ ? 'LOOP.md does not reference STATE.md — would append a reference (--dry-run, no changes made)'+ : 'LOOP.md did not reference STATE.md — appended a reference',+ severity: 'info',+ suggestion: 'Review the appended line and reword it if you prefer.',+ });+ }+ else {+ issues.push({+ type: 'inconsistent',+ file: 'LOOP.md',+ message: 'LOOP.md does not reference STATE.md',+ severity: 'warning',+ suggestion: 'Add STATE.md to the state files list in LOOP.md, or run with --auto-fix',+ });+ }}// Compare structural similarityconst { similarity, differences } = compareMarkdownFiles(stateContent, loopContent, 0.5);diff --git a/tools/loop-sync/src/cli.ts b/tools/loop-sync/src/cli.tsindex da1e490..731a889 100644--- a/tools/loop-sync/src/cli.ts+++ b/tools/loop-sync/src/cli.ts@@ -38,8 +38,13 @@ Usage:loop-sync [target-dir] [options]Options:- -a, --auto-fix Attempt to auto-fix issues (experimental)- -d, --dry-run Show what would be done without making changes+ -a, --auto-fix Scaffold missing STATE.md, gate.yaml, loop-budget.md, and+ loop-run-log.md with minimal defaults, and add a missing+ STATE.md reference to LOOP.md. LOOP.md and AGENTS.md are+ never fabricated -- their content is pattern-specific,+ so a missing one still just suggests loop-init.+ -d, --dry-run With --auto-fix, report what would be scaffolded/changed+ without writing anything-v, --verbose Show detailed information--json Output JSON format-h, --help Show this help@@ -48,6 +53,8 @@ Examples:loop-sync .loop-sync ./my-project -vloop-sync ./my-project --json+ loop-sync ./my-project --auto-fix --dry-run+ loop-sync ./my-project --auto-fixThe tool checks:- STATE.md ↔ LOOP.md consistencydiff --git a/tools/loop-sync/src/sync.ts b/tools/loop-sync/src/sync.tsindex 942f54d..f0567f6 100644--- a/tools/loop-sync/src/sync.ts+++ b/tools/loop-sync/src/sync.ts@@ -156,6 +156,134 @@ function compareMarkdownFiles(return { similarity, differences };}+/**+ * Required files whose content is pattern-agnostic enough to scaffold a+ * correct, minimal default without knowing which of loop-init's patterns+ * (daily-triage, pr-babysitter, ci-sweeper, ...) the project actually uses.+ * STATE.md, gate.yaml, loop-budget.md, and loop-run-log.md all have exactly+ * this shape upstream (see templates/*.template) -- LOOP.md and AGENTS.md+ * don't, since their content *is* the pattern-specific goal and workflow, so+ * auto-fix intentionally leaves those two as report-only rather than+ * fabricating wrong content.+ *+ * These are inlined rather than read from templates/*.template because+ * loop-sync ships as a standalone npm package (files: ["dist"]) that runs+ * against arbitrary target directories -- a path relative to this package's+ * own install location wouldn't resolve once installed outside this+ * monorepo checkout.+ */+const AUTO_FIXABLE_FILES = new Set(['STATE.md', 'gate.yaml', 'loop-budget.md', 'loop-run-log.md']);++function projectNameFrom(targetDir: string): string {+ return path.basename(path.resolve(targetDir)) || 'this project';+}++function scaffoldContent(file: string, projectName: string): string {+ switch (file) {+ case 'STATE.md':+ return `# Loop State — ${projectName}++Last run: (set by loop on each run)++## High Priority (loop is acting or waiting on human)++<!-- Format:+- [ ] ID — one-line description+ Loop action: what the loop did last+ Human decision: (if any)+-->++## Watch List++<!-- Items to monitor but not act on yet -->++## Recent Noise (ignored this run)++<!-- Brief list — helps tune triage skill -->++---+Run log: (timestamp) | findings | actions | escalations+`;+ case 'gate.yaml':+ return `# Machine-readable twin of your project's safety policy. Adjust denylist+# and autoMergeAllowlist for your project's own sensitive paths.+version: 1++denylist:+ - ".env"+ - ".env.*"+ - "**/secrets/**"+ - "**/credentials/**"+ - "**/*_key*"+ - "**/*_secret*"+ - ".terraform/**"+ - "k8s/production/**"+ - "**/migrations/**"+ - "auth/**"+ - "payments/**"+ - "billing/**"++# Escalate instead of auto-merging when a change touches more than this many files.+maxFiles: 10++# --action auto-merge only proceeds if every changed path matches one of these.+autoMergeAllowlist:+ - "docs/**"+ - "**/*.md"+`;+ case 'loop-budget.md':+ return `# Loop Budget — ${projectName}++## Daily limits++| Loop | Max runs/day | Max tokens/day | Max sub-agent spawns/run |+|------|--------------|----------------|--------------------------|+| Daily Triage | 2 | 100k | 0 (L1) / 2 (L2) |+| PR Babysitter | 288 | 2M | 3 |+| CI Sweeper | 96 | 1M | 3 |+| Dependency Sweeper | 4 | 500k | 3 |+| Post-Merge Cleanup | 1 | 200k | 2 |++## On budget exceed++1. Pause all schedulers (\`scheduler_delete\` or disable automations)+2. Append event to \`loop-run-log.md\`+3. Notify human (Slack / issue / STATE.md High Priority)++## Kill switch++- Command or issue label: \`loop-pause-all\`+- Resume only after human clears the flag in STATE.md+`;+ case 'loop-run-log.md':+ return `# Loop Run Log — ${projectName}++Append one entry per run. Prune entries older than 30 days.++## Format++\`\`\`json+{+ "run_id": "2026-06-09T08:15:00Z",+ "pattern": "daily-triage",+ "duration_s": 45,+ "items_found": 4,+ "actions_taken": 1,+ "escalations": 0,+ "tokens_estimate": 52000,+ "outcome": "report-only | fix-proposed | escalated | no-op"+}+\`\`\`++## Recent Runs++<!-- Loop appends below this line -->+`;+ default:+ throw new Error(`No auto-fix scaffold defined for ${file}.`);+ }+}+/*** Scan skills directory for version information*/@@ -202,7 +330,7 @@ export async function runSync(options: SyncOptions): Promise<DriftReport> {const { targetDir, autoFix, dryRun, verbose } = options;const issues: DriftIssue[] = [];const suggestions: string[] = [];-+// Define required filesconst requiredFiles = ['STATE.md',@@ -212,17 +340,36 @@ export async function runSync(options: SyncOptions): Promise<DriftReport> {'loop-budget.md','loop-run-log.md',];-+// Check for missing required filesfor (const file of requiredFiles) {const filePath = path.join(targetDir, file);if (!await fileExists(filePath)) {+ const fixable = AUTO_FIXABLE_FILES.has(file);+ if (autoFix && fixable) {+ if (!dryRun) {+ await mkdir(path.dirname(filePath), { recursive: true });+ await writeFile(filePath, scaffoldContent(file, projectNameFrom(targetDir)));+ }+ issues.push({+ type: 'missing',+ file,+ message: dryRun+ ? `${file} is missing — would scaffold a minimal default (--dry-run, no changes made)`+ : `${file} was missing — scaffolded a minimal default`,+ severity: 'info',+ suggestion: 'Review the generated content and adjust it for your project.',+ });+ continue;+ }issues.push({type: 'missing',file,message: `${file} is missing`,severity: 'error',- suggestion: `Run 'npx @cobusgreyling/loop-init . --pattern daily-triage' to scaffold required files`,+ suggestion: fixable+ ? `Run with --auto-fix to scaffold a minimal default, or 'npx @cobusgreyling/loop-init . --pattern daily-triage' for pattern-specific content`+ : `Run 'npx @cobusgreyling/loop-init . --pattern daily-triage' to scaffold required files`,});}}@@ -244,13 +391,29 @@ export async function runSync(options: SyncOptions): Promise<DriftReport> {// Check if STATE.md is referenced in LOOP.mdif (!stateFiles.includes('STATE.md')) {- issues.push({- type: 'inconsistent',- file: 'LOOP.md',- message: 'LOOP.md does not reference STATE.md',- severity: 'warning',- suggestion: 'Add STATE.md to the state files list in LOOP.md',- });+ if (autoFix) {+ if (!dryRun) {+ const separator = /\n\n$/.test(loopContent) ? '' : loopContent.endsWith('\n') ? '\n' : '\n\n';+ await writeFile(loopPath, `${loopContent}${separator}Update STATE.md after each run.\n`);+ }+ issues.push({+ type: 'inconsistent',+ file: 'LOOP.md',+ message: dryRun+ ? 'LOOP.md does not reference STATE.md — would append a reference (--dry-run, no changes made)'+ : 'LOOP.md did not reference STATE.md — appended a reference',+ severity: 'info',+ suggestion: 'Review the appended line and reword it if you prefer.',+ });+ } else {+ issues.push({+ type: 'inconsistent',+ file: 'LOOP.md',+ message: 'LOOP.md does not reference STATE.md',+ severity: 'warning',+ suggestion: 'Add STATE.md to the state files list in LOOP.md, or run with --auto-fix',+ });+ }}// Compare structural similaritydiff --git a/tools/loop-sync/test/sync.test.mjs b/tools/loop-sync/test/sync.test.mjsindex 1690da1..b649b5a 100644--- a/tools/loop-sync/test/sync.test.mjs+++ b/tools/loop-sync/test/sync.test.mjs@@ -1,7 +1,7 @@import { test, describe, beforeEach, afterEach } from 'node:test';import assert from 'node:assert/strict';import path from 'node:path';-import { mkdir, writeFile, rm } from 'node:fs/promises';+import { mkdir, writeFile, rm, readFile, access } from 'node:fs/promises';import { execFile } from 'node:child_process';import { promisify } from 'node:util';import { runSync, formatReport, extractFrontmatter } from '../dist/sync.js';@@ -83,6 +83,67 @@ describe('runSync', () => {});});+describe('runSync auto-fix', () => {+ const fixDir = path.join(process.cwd(), '.test-tmp-autofix');++ beforeEach(() => mkdir(fixDir, { recursive: true }));+ afterEach(() => rm(fixDir, { recursive: true, force: true }));++ test('scaffolds STATE.md, gate.yaml, loop-budget.md, and loop-run-log.md when missing', async () => {+ const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: false, verbose: false });++ for (const file of ['STATE.md', 'gate.yaml', 'loop-budget.md', 'loop-run-log.md']) {+ const content = await readFile(path.join(fixDir, file), 'utf8');+ assert.ok(content.length > 0, `${file} should have been scaffolded with content`);+ const issue = report.issues.find((i) => i.file === file);+ assert.equal(issue.severity, 'info');+ assert.match(issue.message, /scaffolded/i);+ }+ // loop-run-log.md must keep the marker append-run-log.mjs depends on.+ const runLog = await readFile(path.join(fixDir, 'loop-run-log.md'), 'utf8');+ assert.match(runLog, /<!-- Loop appends below this line -->/);+ });++ test('does not fabricate LOOP.md or AGENTS.md -- still reported as missing', async () => {+ const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: false, verbose: false });++ assert.equal(await fileExists(path.join(fixDir, 'LOOP.md')), false);+ assert.equal(await fileExists(path.join(fixDir, 'AGENTS.md')), false);+ const loopIssue = report.issues.find((i) => i.file === 'LOOP.md');+ assert.equal(loopIssue.severity, 'error');+ assert.match(loopIssue.suggestion, /loop-init/);+ });++ test('--dry-run with --auto-fix reports without writing anything', async () => {+ const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: true, verbose: false });++ assert.equal(await fileExists(path.join(fixDir, 'STATE.md')), false);+ const issue = report.issues.find((i) => i.file === 'STATE.md');+ assert.match(issue.message, /would scaffold/i);+ assert.match(issue.message, /dry-run/i);+ });++ test('appends a STATE.md reference to LOOP.md when missing', async () => {+ await writeFile(path.join(fixDir, 'STATE.md'), '# Loop State\n');+ await writeFile(+ path.join(fixDir, 'LOOP.md'),+ `# Loop Configuration\n\n## Patterns\n- daily-triage\n`,+ );++ const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: false, verbose: false });++ const loopContent = await readFile(path.join(fixDir, 'LOOP.md'), 'utf8');+ assert.match(loopContent, /Update STATE\.md after each run\./);+ const issue = report.issues.find((i) => i.file === 'LOOP.md' && i.type === 'inconsistent');+ assert.equal(issue.severity, 'info');+ assert.match(issue.message, /appended a reference/i);+ });+});++function fileExists(p) {+ return access(p).then(() => true, () => false);+}+describe('formatReport', () => {test('formats healthy report', () => {const formatted = formatReport({