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(loop-audit): add --auto-fix command to self-heal repository structures (#358)

THRISHAL DOMA71de5bc14141
diff --git a/tools/loop-audit/src/autofixer.ts b/tools/loop-audit/src/autofixer.ts
new file mode 100644
index 0000000..5a1b8ad
--- /dev/null
+++ b/tools/loop-audit/src/autofixer.ts
@@ -0,0 +1,209 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileExists } from '@cobusgreyling/readiness-core';
+import { AuditResult } from './auditor.js';
+
+const STATE_MD_TEMPLATE = `# Loop State — YOUR_PROJECT
+
+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
+`;
+
+const LOOP_BUDGET_TEMPLATE = `# Loop Budget — YOUR_PROJECT
+
+## 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
+`;
+
+const LOOP_RUN_LOG_TEMPLATE = `# Loop Run Log — YOUR_PROJECT
+
+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 -->
+`;
+
+const LOOP_CONSTRAINTS_TEMPLATE = `# Loop Constraints
+
+> Add rules below with \`/constraints <rule>\` in your agent.
+> The \`loop-constraints\` skill reads this file at the start of every run.
+> Constraints here are **binding** — the agent MUST follow them.
+
+## Push & Merge
+- Don't push before telling me
+- Never auto-merge to main without human approval
+- Always create a draft PR first; let me review before marking ready
+
+## Paths
+- Never edit .env, .env.*, auth/, payments/, secrets/, credentials/
+- Never edit infrastructure configs without human approval
+
+## Code
+- Always run tests before proposing a fix
+- Never disable tests to make CI green
+- Never refactor unrelated code — one fix per run
+- Max 3 fix attempts per item; escalate after
+- Enforce the attempt limit mechanically: log each try to \`loop-ledger.json\` and run \`loop-context --check\` before retrying (see the \`loop-guard\` skill)
+
+## Communication
+- Always tell me what you're about to do before doing it
+- Never close an issue or PR without my approval
+
+## Budget
+- If token spend hits 80% of daily cap, switch to report-only
+- If loop-pause-all is active, exit immediately
+
+---
+<!-- Add your own rules below. Use plain English. The loop reads this verbatim. -->
+`;
+
+const LOOP_MD_TEMPLATE = `# Loop Configuration — Minimal Triage
+
+## Active Loops
+
+| Pattern | Cadence | Status | Command |
+|---------|---------|--------|---------|
+| Daily Triage | 1d | L1 report-only | See README |
+
+## Human Gates
+
+- No auto-fix until L2 checklist complete
+- All high-risk paths: human review required
+
+## Budget
+
+- Max sub-agent spawns per run: 0 (L1) / 2 (L2)
+- Max tokens/day: 100k (see \`loop-budget.md\`)
+- Append each run to \`loop-run-log.md\`; use \`loop-budget\` skill at start/end
+- Kill switch: \`loop-pause-all\` — pause schedulers and notify human
+- Estimate: \`npx @cobusgreyling/loop-cost --pattern daily-triage\`
+`;
+
+const SAFETY_MD_TEMPLATE = `# Loop Safety Policy
+
+## Auto-merge policy
+- Never auto-merge to main. All code changes require human review.
+
+## Path denylist
+- .github/workflows/
+- secrets/
+- credentials/
+
+## MCP Scopes
+- Read-only unless explicitly allowed.
+`;
+
+const AGENTS_MD_TEMPLATE = `# AGENTS.md — Project Conventions
+
+## Build & Test
+- Run \`npm test\` to verify changes.
+
+## Review Norms
+- Never auto-merge changes.
+- Ensure all loops isolate their work in worktrees.
+`;
+
+export async function autoFixProject(target: string, result: AuditResult): Promise<void> {
+ const root = path.resolve(target);
+ let fixesApplied = 0;
+
+ console.log('\n=== Auto-Fixing Repository ===\n');
+
+ const safeWriteFile = async (relPath: string, content: string, label: string) => {
+ const fullPath = path.join(root, relPath);
+ if (!(await fileExists(fullPath))) {
+ await mkdir(path.dirname(fullPath), { recursive: true });
+ await writeFile(fullPath, content, 'utf8');
+ console.log(`✅ Generated ${relPath} (${label})`);
+ fixesApplied++;
+ } else {
+ console.log(`⏭️ Skipped ${relPath} (already exists)`);
+ }
+ };
+
+ if (!result.signals.stateFile.present) {
+ await safeWriteFile('STATE.md', STATE_MD_TEMPLATE, 'Base state tracking');
+ }
+
+ if (!result.signals.loopConfig.present) {
+ await safeWriteFile('LOOP.md', LOOP_MD_TEMPLATE, 'Loop configuration');
+ }
+
+ if (!result.signals.cost.budgetDoc) {
+ await safeWriteFile('loop-budget.md', LOOP_BUDGET_TEMPLATE, 'Cost caps');
+ }
+
+ if (!result.signals.cost.runLog) {
+ await safeWriteFile('loop-run-log.md', LOOP_RUN_LOG_TEMPLATE, 'Run history');
+ }
+
+ if (!result.signals.constraints.present) {
+ await safeWriteFile('loop-constraints.md', LOOP_CONSTRAINTS_TEMPLATE, 'Agent rules');
+ }
+
+ if (!result.signals.safety.safetyDocPresent) {
+ await safeWriteFile('docs/safety.md', SAFETY_MD_TEMPLATE, 'Safety policy');
+ }
+
+ if (!result.signals.agentsMd.present) {
+ await safeWriteFile('AGENTS.md', AGENTS_MD_TEMPLATE, 'Project conventions');
+ }
+
+ if (fixesApplied > 0) {
+ console.log(`\n✨ Applied ${fixesApplied} automatic fixes. Run loop-audit again to see your new score!`);
+ } else {
+ console.log('\nNo safe automatic fixes could be applied. (Check the suggestions manually).');
+ }
+}
diff --git a/tools/loop-audit/src/cli.ts b/tools/loop-audit/src/cli.ts
index 48213ce..d5795b3 100644
--- a/tools/loop-audit/src/cli.ts
+++ b/tools/loop-audit/src/cli.ts
@@ -2,12 +2,14 @@
import { auditProject } from './auditor.js';
import { printContributorCta } from './contributor-cta.js';
import { formatBadge, formatHuman, formatJson, formatMarkdown } from './reporter.js';
+import { autoFixProject } from './autofixer.js';
const args = process.argv.slice(2);
const target = args.find((a) => !a.startsWith('-')) || '.';
const json = args.includes('--json');
const md = args.includes('--md');
const suggest = args.includes('--suggest') || args.includes('--fix');
+const autoFix = args.includes('--auto-fix');
const badge = args.includes('--badge');
const help = args.includes('--help') || args.includes('-h');
@@ -21,6 +23,7 @@ Options:
--json JSON output (for CI / scripting)
--md Markdown report
--suggest Show copy-from-template commands for missing pieces (recommended on first runs)
+ --auto-fix Auto-heal missing repository structure (STATE, LOOP, budgets, etc.)
--badge Markdown README badge (Loop Ready level + score)
--help, -h This help
@@ -58,7 +61,9 @@ try {
else if (md) console.log(formatMarkdown(result));
else console.log(formatHuman(result));
- if (suggest) {
+ if (autoFix) {
+ await autoFixProject(target, result);
+ } else if (suggest) {
console.log('\n=== Suggested actions (copy & customize) ===');
console.log('From the root of this repo (or after cloning the reference):');
console.log('');