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 status — day-2 dashboard over existing markdown artifacts.
*/
import path from 'node:path';
import { runToolCapture } from './pass-through.js';
import {
extractLastRun,
extractPatternsFromLoop,
fileExists,
findStateFile,
parseLedger,
parseRunLog,
readText,
type RunLogEntry,
type LedgerSummary,
} from './files.js';
export interface StatusReport {
target: string;
patterns: string[];
stateFile: string | null;
lastRunFromState: string | null;
ready: { score: number | null; level: string | null };
recentRuns: RunLogEntry[];
ledger: LedgerSummary;
budget: { present: boolean; path: string };
gate: { present: boolean };
constraints: { present: boolean };
nextHint: string;
}
function parseJsonLoose(stdout: string): unknown | null {
const t = stdout.trim();
if (!t) return null;
try {
return JSON.parse(t);
} catch {
const start = t.indexOf('{');
if (start < 0) return null;
try {
return JSON.parse(t.slice(start));
} catch {
return null;
}
}
}
export async function runStatus(target: string): Promise<StatusReport> {
const root = path.resolve(target);
const stateName = await findStateFile(root);
const stateRaw = stateName ? await readText(path.join(root, stateName)) : null;
const loopRaw = await readText(path.join(root, 'LOOP.md'));
const runLogRaw = await readText(path.join(root, 'loop-run-log.md'));
const ledgerRaw = await readText(path.join(root, 'loop-ledger.json'));
const budgetPresent = await fileExists(path.join(root, 'loop-budget.md'));
const gatePresent = await fileExists(path.join(root, 'gate.yaml'));
const constraintsPresent = await fileExists(path.join(root, 'loop-constraints.md'));
let readyScore: number | null = null;
let readyLevel: string | null = null;
try {
const auditRun = await runToolCapture('audit', [root, '--json']);
const j = parseJsonLoose(auditRun.stdout) as { score?: number; level?: string } | null;
if (j && typeof j.score === 'number') {
readyScore = j.score;
readyLevel = j.level ?? null;
}
} catch {
/* status still useful without audit */
}
const recentRuns = runLogRaw ? parseRunLog(runLogRaw, 5) : [];
const patterns = extractPatternsFromLoop(loopRaw);
if (recentRuns[0]?.pattern && !patterns.includes(recentRuns[0].pattern)) {
patterns.unshift(recentRuns[0].pattern);
}
let nextHint = 'Run: npx @cobusgreyling/loop doctor .';
if (!stateName && !loopRaw) {
nextHint = 'Scaffold: npx @cobusgreyling/loop init . --pattern daily-triage --tool claude';
} else if (recentRuns.length === 0) {
nextHint = 'Schedule a report-only first run and append loop-run-log.md';
} else if (readyScore !== null && readyScore >= 80) {
nextHint = 'Optional: npx @cobusgreyling/loop badge .';
}
return {
target: root,
patterns,
stateFile: stateName,
lastRunFromState: extractLastRun(stateRaw),
ready: { score: readyScore, level: readyLevel },
recentRuns,
ledger: parseLedger(ledgerRaw),
budget: { present: budgetPresent, path: 'loop-budget.md' },
gate: { present: gatePresent },
constraints: { present: constraintsPresent },
nextHint,
};
}
export function formatStatusHuman(r: StatusReport): string {
const lines: string[] = [];
lines.push('');
lines.push(`Loop status · ${r.target}`);
lines.push('═'.repeat(50));
lines.push(
` Pattern: ${r.patterns.length ? r.patterns.join(', ') : '(none detected — check LOOP.md)'}`,
);
lines.push(
` Ready: ${r.ready.score !== null ? `${r.ready.score}/100 ${r.ready.level ?? ''}` : 'n/a'}`.trimEnd(),
);
lines.push(` State: ${r.stateFile ?? 'missing'}${r.lastRunFromState ? ` · ${r.lastRunFromState}` : ''}`);
lines.push(
` Budget: ${r.budget.present ? 'loop-budget.md' : 'missing'} · gate=${r.gate.present ? 'yes' : 'no'} · constraints=${r.constraints.present ? 'yes' : 'no'}`,
);
if (r.ledger.present) {
lines.push(
` Ledger: present${r.ledger.pattern ? ` · ${r.ledger.pattern}` : ''}${r.ledger.attempts != null ? ` · ${r.ledger.attempts} attempt(s)` : ''}`,
);
}
lines.push('');
lines.push(' Recent runs:');
if (!r.recentRuns.length) {
lines.push(' (none in loop-run-log.md)');
} else {
for (const e of r.recentRuns) {
const bits = [
e.run_id ?? '?',
e.pattern ?? '?',
e.outcome ?? '?',
e.tokens_estimate != null ? `~${e.tokens_estimate} tok` : null,
].filter(Boolean);
lines.push(` · ${bits.join(' · ')}`);
}
}
lines.push('');
lines.push(` Next: ${r.nextHint}`);
lines.push('');
return lines.join('\n');
}