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
#!/usr/bin/env node
/**
* @cobusgreyling/loop — unified front door for Loop Engineering CLIs.
* Additive: loop-init, loop-audit, and siblings stay fully supported.
*/
import { runTool } from './pass-through.js';
import { runDoctor, formatDoctorHuman } from './doctor.js';
import { runStatus, formatStatusHuman } from './status.js';
import { defaultPlan, executePlan, printNonInteractiveHelp, resolvePattern, resolveTool, runInteractiveWizard, } from './wizard.js';
const VERSION = '0.2.0';
const PASS_THROUGH = new Set([
'init',
'audit',
'cost',
'sync',
'context',
'worktree',
'gate',
'mcp',
'sandbox',
]);
function printHelp() {
console.log(`loop — Loop Engineering unified CLI v${VERSION}
Usage:
loop Week-one help (or wizard if TTY + --interactive)
loop init [args…] → loop-init (scaffold)
loop audit [args…] → loop-audit (Loop Ready score)
loop cost [args…] → loop-cost
loop sync [args…] → loop-sync
loop doctor [path] [--json] Audit + sync + files → top 3 actions
loop status [path] [--json] Day-2 dashboard from STATE / run-log
loop badge [path] README badge (→ loop-audit --badge)
loop wizard [--yes] Guided scaffold + doctor
loop context|worktree|gate|mcp|sandbox [args…]
Week-one (recommended):
npx @cobusgreyling/loop init . --pattern daily-triage --tool claude
npx @cobusgreyling/loop doctor .
Doctor exit codes:
0 healthy
1 warnings (score/sync/budget gaps)
2 blocked (score < 40, critical drift, or unscaffolded)
Compatibility (old doors stay open):
npx @cobusgreyling/loop-init .
npx @cobusgreyling/loop-audit . --suggest
Docs: https://github.com/cobusgreyling/loop-engineering/blob/main/docs/QUICKSTART.md
Showcase: https://cobusgreyling.github.io/loop-engineering/
`);
}
async function cmdDoctor(args) {
const json = args.includes('--json');
const target = args.find((a) => !a.startsWith('-')) || '.';
if (args.includes('--help') || args.includes('-h')) {
console.log(`loop doctor [path] [--json]
Combines loop-audit + loop-sync + structural file checks.
Prints severity and the top 3 next actions.
Exit: 0 healthy · 1 warning · 2 blocked
`);
return 0;
}
const report = await runDoctor(target);
if (json)
console.log(JSON.stringify(report, null, 2));
else
console.log(formatDoctorHuman(report));
return report.exitCode;
}
async function cmdStatus(args) {
const json = args.includes('--json');
const target = args.find((a) => !a.startsWith('-')) || '.';
if (args.includes('--help') || args.includes('-h')) {
console.log(`loop status [path] [--json]
Shows pattern, Loop Ready score, last runs from loop-run-log.md, ledger, budget.
`);
return 0;
}
const report = await runStatus(target);
if (json)
console.log(JSON.stringify(report, null, 2));
else
console.log(formatStatusHuman(report));
return 0;
}
async function cmdBadge(args) {
const target = args.find((a) => !a.startsWith('-')) || '.';
return runTool('audit', [target, '--badge']);
}
async function cmdWizard(args) {
const yes = args.includes('--yes') || args.includes('-y');
const interactive = args.includes('--interactive') || args.includes('-i');
// Allow: loop wizard -p daily-triage -t claude .
let plan = defaultPlan();
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--pattern' || a === '-p')
plan.pattern = resolvePattern(args[++i] ?? '');
else if (a === '--tool' || a === '-t')
plan.tool = resolveTool(args[++i] ?? '');
else if (a === '--with-foundry')
plan.withFoundry = true;
else if (a === '--yes' || a === '-y' || a === '--interactive' || a === '-i')
continue;
else if (!a.startsWith('-'))
plan.target = a;
}
if (interactive && process.stdin.isTTY) {
plan = await runInteractiveWizard();
return executePlan(plan);
}
if (yes || args.some((a) => a === '--pattern' || a === '-p')) {
return executePlan(plan);
}
printNonInteractiveHelp();
return 0;
}
async function main() {
const argv = process.argv.slice(2);
if (argv.length === 0) {
if (process.stdin.isTTY && argv.includes('--interactive')) {
// unreachable when length 0 — handled below
}
printNonInteractiveHelp();
return;
}
const [cmd, ...rest] = argv;
if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
printHelp();
return;
}
if (cmd === '--version' || cmd === '-V' || cmd === 'version') {
console.log(VERSION);
return;
}
if (cmd === '--interactive' || cmd === '-i') {
// Mirrors cmdWizard()'s TTY gate below: runInteractiveWizard() drives
// readline.question(), which resolves immediately with '' when stdin
// isn't a TTY (a CI step, piped input, `< /dev/null`) instead of
// waiting for a human. Without this guard, loop --interactive in a
// non-interactive context silently ran the wizard with every prompt
// answered blank and scaffolded files nobody asked for.
if (!process.stdin.isTTY) {
printNonInteractiveHelp();
process.exitCode = 0;
return;
}
const plan = await runInteractiveWizard();
process.exitCode = await executePlan(plan);
return;
}
if (PASS_THROUGH.has(cmd)) {
const code = await runTool(cmd, rest);
process.exitCode = code;
return;
}
if (cmd === 'doctor') {
process.exitCode = await cmdDoctor(rest);
return;
}
if (cmd === 'status') {
process.exitCode = await cmdStatus(rest);
return;
}
if (cmd === 'badge') {
process.exitCode = await cmdBadge(rest);
return;
}
if (cmd === 'wizard') {
process.exitCode = await cmdWizard(rest);
return;
}
// Unknown: if it looks like a path or init flags, hint; else help
console.error(`Unknown command: ${cmd}\n`);
printHelp();
process.exitCode = 1;
}
main().catch((err) => {
console.error('loop failed:', err instanceof Error ? err.message : err);
process.exit(1);
});