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.

7.2 KB
Raw Blame
import { writeFile, mkdir } from 'node:fs/promises';
import path from 'node:path';
import { execSync } from 'node:child_process';
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.
`;

const GATE_YAML_TEMPLATE = `# Machine-readable twin of docs/safety.md, enforced by \`loop-gate check\`.
# See templates/gate.yaml.template in loop-engineering for the full reference.
version: 1

denylist:
  - "**/.env"
  - "**/.env.*"
  - "**/secrets/**"
  - "**/credentials/**"
  - "**/*_key*"
  - "**/*_secret*"

# 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"
`;

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 (!result.signals.governance.gateYaml) {
    await safeWriteFile('gate.yaml', GATE_YAML_TEMPLATE, 'Explicit human approval gates');
  }

  const shellFix = (cmd: string, label: string) => {
    console.log(`\n⚙️  Applying ${label}...`);
    try {
      execSync(cmd, { stdio: 'inherit', cwd: root });
      console.log(`✅ Applied ${label}`);
      fixesApplied++;
    } catch (err) {
      console.error(`❌ Failed to apply ${label}:`, err instanceof Error ? err.message : String(err));
    }
  };

  if (!result.signals.memory.tiers) {
    shellFix('npx @cobusgreyling/loop-init . --with-memory', 'Memory engineering');
  }

  if (!result.signals.harness.stack) {
    shellFix('npx @cobusgreyling/loop-init . --with-foundry', 'Harness foundry');
  }

  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).');
  }
}