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
/**
* loop doctor — single activation check: audit + sync + budget/gate presence.
* Exit: 0 healthy · 1 warnings · 2 blocked
*/
import path from 'node:path';
import { runToolCapture } from './pass-through.js';
import { budgetPresent, fileExists, findStateFile, readText, } from './files.js';
function parseJsonLoose(stdout) {
const t = stdout.trim();
if (!t)
return null;
try {
return JSON.parse(t);
}
catch {
/* Some CLIs may print a banner before JSON — take first object/array */
const startObj = t.indexOf('{');
const startArr = t.indexOf('[');
const candidates = [startObj, startArr].filter((i) => i >= 0);
if (!candidates.length)
return null;
const start = Math.min(...candidates);
try {
return JSON.parse(t.slice(start));
}
catch {
return null;
}
}
}
export async function runDoctor(target) {
const root = path.resolve(target);
const notes = [];
const actions = [];
const stateName = await findStateFile(root);
const loopMd = await fileExists(path.join(root, 'LOOP.md'));
const budgetPath = path.join(root, 'loop-budget.md');
const budgetRaw = await readText(budgetPath);
const runLog = await fileExists(path.join(root, 'loop-run-log.md'));
const constraints = await fileExists(path.join(root, 'loop-constraints.md'));
const gate = await fileExists(path.join(root, 'gate.yaml'));
const agentsMd = await fileExists(path.join(root, 'AGENTS.md'));
let readyScore = null;
let readyLevel = null;
let assessment = null;
let auditRecs = [];
const auditRun = await runToolCapture('audit', [root, '--json']);
if (auditRun.code !== 0 && !auditRun.stdout.trim()) {
notes.push(`loop-audit failed: ${auditRun.stderr.trim() || `exit ${auditRun.code}`}`);
}
else {
const j = parseJsonLoose(auditRun.stdout);
if (j && typeof j.score === 'number') {
readyScore = j.score;
readyLevel = j.level ?? null;
assessment = j.assessment ?? null;
auditRecs = Array.isArray(j.recommendations) ? j.recommendations : [];
}
else {
notes.push('Could not parse loop-audit JSON output');
}
}
let syncScore = null;
let syncLevel = null;
let issueCount = 0;
const syncRun = await runToolCapture('sync', [root, '--json']);
if (syncRun.code !== 0 && !syncRun.stdout.trim()) {
notes.push(`loop-sync failed: ${syncRun.stderr.trim() || `exit ${syncRun.code}`}`);
}
else {
const j = parseJsonLoose(syncRun.stdout);
if (j && typeof j.score === 'number') {
syncScore = j.score;
syncLevel = j.level ?? null;
issueCount = Array.isArray(j.issues) ? j.issues.length : 0;
if (Array.isArray(j.suggestions)) {
for (const s of j.suggestions.slice(0, 2)) {
actions.push({ priority: 40, text: s });
}
}
}
else {
notes.push('Could not parse loop-sync JSON output');
}
}
// Structural actions (highest priority for empty repos)
if (!stateName && !loopMd) {
actions.push({
priority: 1,
text: 'Scaffold a first loop (report-only week one)',
command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude',
});
}
else if (!stateName) {
actions.push({
priority: 2,
text: 'Add a state file (STATE.md or pattern state)',
command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude',
});
}
if (!loopMd) {
actions.push({
priority: 3,
text: 'Add LOOP.md documenting cadence, gates, and kill switch',
});
}
if (!budgetPresent(budgetRaw)) {
actions.push({
priority: 10,
text: 'Add loop-budget.md with daily token caps and kill switch',
command: 'npx @cobusgreyling/loop init . --pattern daily-triage --tool claude',
});
}
if (!runLog) {
actions.push({
priority: 11,
text: 'Add loop-run-log.md so runs are observable',
});
}
if (readyScore !== null && readyScore < 40) {
actions.push({
priority: 5,
text: 'Raise Loop Ready above 40 before scheduling unattended work',
command: `npx @cobusgreyling/loop audit ${target} --suggest`,
});
}
if (syncLevel === 'critical') {
actions.push({
priority: 4,
text: 'Fix STATE ↔ LOOP drift before the next scheduled run',
command: `npx @cobusgreyling/loop sync ${target}`,
});
}
for (const rec of auditRecs.slice(0, 3)) {
actions.push({ priority: 50, text: rec });
}
if (readyScore !== null && readyScore >= 80) {
actions.push({
priority: 90,
text: 'Optional next: version the loop as a harness (Foundry)',
command: 'npx @cobusgreyling/loop init . --with-foundry',
});
actions.push({
priority: 91,
text: 'Share your score',
command: `npx @cobusgreyling/loop badge ${target}`,
});
}
// Dedupe by text, keep best priority
const byText = new Map();
for (const a of actions) {
const prev = byText.get(a.text);
if (!prev || a.priority < prev.priority)
byText.set(a.text, a);
}
const topActions = [...byText.values()].sort((a, b) => a.priority - b.priority).slice(0, 3);
// Severity / exit code
let severity = 'healthy';
let exitCode = 0;
const blocked = (readyScore !== null && readyScore < 40) ||
syncLevel === 'critical' ||
(!stateName && !loopMd);
const warning = (readyScore !== null && readyScore < 58) ||
syncLevel === 'warning' ||
issueCount > 0 ||
!budgetPresent(budgetRaw) ||
!runLog;
if (blocked) {
severity = 'blocked';
exitCode = 2;
}
else if (warning) {
severity = 'warning';
exitCode = 1;
}
return {
target: root,
severity,
exitCode,
ready: {
score: readyScore,
level: readyLevel,
assessment,
},
sync: {
score: syncScore,
level: syncLevel,
issueCount,
},
files: {
state: stateName,
loopMd,
budget: budgetPresent(budgetRaw),
runLog,
constraints,
gate,
agentsMd,
},
actions: topActions,
notes,
};
}
export function formatDoctorHuman(r) {
const lines = [];
lines.push('');
lines.push(`Loop doctor — ${r.target}`);
lines.push('═'.repeat(50));
const score = r.ready.score !== null ? `${r.ready.score}/100 ${r.ready.level ?? ''}`.trim() : 'n/a';
lines.push(`Ready: ${score}`);
if (r.ready.assessment)
lines.push(` ${r.ready.assessment}`);
const sync = r.sync.score !== null
? `${r.sync.score}/100 (${r.sync.level ?? '?'}) · ${r.sync.issueCount} issue(s)`
: 'n/a';
lines.push(`Sync: ${sync}`);
lines.push(`Files: state=${r.files.state ?? 'missing'} LOOP.md=${yn(r.files.loopMd)} budget=${yn(r.files.budget)} run-log=${yn(r.files.runLog)} gate=${yn(r.files.gate)}`);
lines.push(`Status: ${r.severity.toUpperCase()} (exit ${r.exitCode})`);
lines.push('');
if (r.actions.length) {
lines.push('Top next actions:');
r.actions.forEach((a, i) => {
lines.push(` ${i + 1}. ${a.text}`);
if (a.command)
lines.push(` $ ${a.command}`);
});
}
else {
lines.push('No blockers — schedule a report-only run and append loop-run-log.md.');
}
if (r.notes.length) {
lines.push('');
lines.push('Notes:');
for (const n of r.notes)
lines.push(` · ${n}`);
}
lines.push('');
lines.push('Week one: report only. Old packages still work: loop-init, loop-audit, …');
lines.push('Docs: https://github.com/cobusgreyling/loop-engineering/blob/main/docs/QUICKSTART.md');
lines.push('');
return lines.join('\n');
}
function yn(b) {
return b ? 'yes' : 'no';
}