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
import { spawn } from 'node:child_process';
import { cp, mkdir, readFile, writeFile, access } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { printContributorCta } from './contributor-cta.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const PACKAGE_ROOT = path.resolve(__dirname, '..');
const MONOREPO_STARTERS = path.resolve(PACKAGE_ROOT, '../../starters');
const MONOREPO_TEMPLATES = path.resolve(PACKAGE_ROOT, '../../templates');
const PATTERN_STARTERS = {
'daily-triage': 'minimal-loop',
'pr-babysitter': 'pr-babysitter',
'ci-sweeper': 'ci-sweeper',
'dependency-sweeper': 'dependency-sweeper',
'post-merge-cleanup': 'post-merge-cleanup',
'changelog-drafter': 'changelog-drafter',
'issue-triage': 'issue-triage',
'thin-loop': 'thin-loop',
};
const TOOL_SUFFIX = {
grok: '',
claude: '-claude',
codex: '-codex',
opencode: '-opencode',
};
/** Patterns with a single tool-agnostic starter (no -claude / -codex suffix). */
const TOOL_AGNOSTIC = new Set(['thin-loop']);
const L2_PATTERNS = new Set(['ci-sweeper', 'dependency-sweeper']);
const PATTERNS_NEEDING_FIX = new Set([
'pr-babysitter',
'ci-sweeper',
'dependency-sweeper',
'post-merge-cleanup',
]);
/**
* Patterns that act on human-authored, often underspecified input (issues).
* They get the loop-intake skill so the loop clarifies a vague item or escalates
* it instead of guessing and burning fix attempts.
*/
const PATTERNS_NEEDING_INTAKE = new Set(['issue-triage']);
const STATE_FILES = {
'daily-triage': 'STATE.md',
'pr-babysitter': 'pr-babysitter-state.md',
'ci-sweeper': 'ci-sweeper-state.md',
'dependency-sweeper': 'dependency-sweeper-state.md',
'post-merge-cleanup': 'post-merge-state.md',
'changelog-drafter': 'changelog-drafter-state.md',
'issue-triage': 'issue-triage-state.md',
'thin-loop': 'STATE.md',
};
/** Mirrors patterns/registry.yaml cost caps — used when scaffolding observability files. */
const PATTERN_BUDGET = {
'daily-triage': { name: 'Daily Triage', maxRunsPerDay: 2, dailyCap: 100_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },
'pr-babysitter': { name: 'PR Babysitter', maxRunsPerDay: 288, dailyCap: 2_000_000, maxSpawnsL1: 0, maxSpawnsL2: 3 },
'ci-sweeper': { name: 'CI Sweeper', maxRunsPerDay: 96, dailyCap: 1_000_000, maxSpawnsL1: 0, maxSpawnsL2: 3 },
'dependency-sweeper': { name: 'Dependency Sweeper', maxRunsPerDay: 4, dailyCap: 500_000, maxSpawnsL1: 0, maxSpawnsL2: 3 },
'post-merge-cleanup': { name: 'Post-Merge Cleanup', maxRunsPerDay: 1, dailyCap: 200_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },
'changelog-drafter': { name: 'Changelog Drafter', maxRunsPerDay: 1, dailyCap: 100_000, maxSpawnsL1: 0, maxSpawnsL2: 2 },
'issue-triage': { name: 'Issue Triage', maxRunsPerDay: 12, dailyCap: 80_000, maxSpawnsL1: 0, maxSpawnsL2: 1 },
'thin-loop': { name: 'Thin Loop', maxRunsPerDay: 24, dailyCap: 20_000, maxSpawnsL1: 0, maxSpawnsL2: 0 },
};
/** Map LE patterns → harness-foundry stack presets (report-only → minimal, fix → implementer). */
const PATTERN_FOUNDRY_PRESET = {
'daily-triage': 'minimal',
'issue-triage': 'minimal',
'changelog-drafter': 'minimal',
'pr-babysitter': 'implementer',
'ci-sweeper': 'implementer',
'dependency-sweeper': 'implementer',
'post-merge-cleanup': 'implementer',
'thin-loop': 'minimal',
};
const FOUNDRY_SHOWCASE = 'https://github.com/cobusgreyling/harness-foundry/blob/main/docs/showcase.md';
const MINIMAX_DEFAULT_MODEL = 'MiniMax-M3';
const MINIMAX_DEFAULT_REGION = 'global_en';
const MINIMAX_MODELS = [
{
id: 'MiniMax-M3',
contextWindow: 1_000_000,
inputModalities: ['text', 'image', 'video'],
thinking: ['adaptive', 'disabled'],
pricing: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: null },
},
{
id: 'MiniMax-M2.7',
contextWindow: 204_800,
inputModalities: ['text'],
thinking: ['always_on'],
pricing: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
},
];
const MINIMAX_REGIONS = [
{
region: 'global_en',
openaiBaseUrl: 'https://api.minimax.io/v1',
anthropicBaseUrl: 'https://api.minimax.io/anthropic',
docsRoot: 'https://platform.minimax.io/docs',
},
{
region: 'cn_zh',
openaiBaseUrl: 'https://api.minimaxi.com/v1',
anthropicBaseUrl: 'https://api.minimaxi.com/anthropic',
docsRoot: 'https://platform.minimaxi.com/docs',
},
];
const MINIMAX_MODEL_IDS = MINIMAX_MODELS.map((m) => m.id);
const MINIMAX_REGION_IDS = MINIMAX_REGIONS.map((r) => r.region);
const ORCAROUTER_DEFAULT_MODEL = 'orcarouter/fusion';
const ORCAROUTER_BASE_URL = 'https://api.orcarouter.ai';
const ORCAROUTER_MODELS = [
{
id: 'orcarouter/fusion',
contextWindow: 1_000_000,
thinking: ['adaptive', 'disabled'],
notes: 'Adaptive-routing flagship; multi-model aggregate with automatic failover',
},
{
id: 'orcarouter/fusion-flash',
contextWindow: 200_000,
thinking: ['adaptive', 'disabled'],
notes: 'Fast adaptive-routing tier for high-volume, latency-sensitive loops',
},
{
id: 'orcarouter/auto',
contextWindow: 1_000_000,
thinking: ['adaptive', 'disabled'],
notes: 'Cost-optimized routing tier',
},
{
id: 'orcarouter/free',
contextWindow: 200_000,
thinking: ['disabled'],
notes: 'Zero-cost tier for report-only loops',
},
];
const ORCAROUTER_MODEL_IDS = ORCAROUTER_MODELS.map((m) => m.id);
/**
* Render the `model/orcarouter` interface primitive for the implementer stack.
* OrcaRouter exposes an OpenAI-compatible gateway that routes a single model
* id across many upstream models. Both protocol shapes live on the same
* gateway base URL — the OpenAI and Anthropic-compatible paths are identical
* and the client picks the wire format via its request headers.
*/
function orcarouterInterfaceYaml(model) {
const models = ORCAROUTER_MODELS.map((m) => [
` - id: ${m.id}`,
` context_window: ${m.contextWindow}`,
` thinking: [${m.thinking.join(', ')}]`,
` notes: "${m.notes}"`,
].join('\n')).join('\n');
return ` - primitive: model/orcarouter
config:
model: ${model}
models:
${models}
endpoints:
global:
openai_base_url: ${ORCAROUTER_BASE_URL}/v1
anthropic_base_url: ${ORCAROUTER_BASE_URL}/v1
docs_root: https://www.orcarouter.ai`;
}
const CHEAPERINFERENCE_DEFAULT_MODEL = 'gpt-5.4-mini';
const CHEAPERINFERENCE_BASE_URL = 'https://api.cheaperinference.com';
const CHEAPERINFERENCE_MODELS = [
{ id: 'gpt-5.4-mini', contextWindow: 400_000, notes: 'OpenAI' },
{ id: 'gpt-5.4', contextWindow: 1_000_000, notes: 'OpenAI' },
{ id: 'claude-sonnet-5', contextWindow: 1_000_000, notes: 'Anthropic' },
{ id: 'gemini-3.1-pro', contextWindow: 1_048_576, notes: 'Google' },
{ id: 'deepseek-v4-flash', contextWindow: 1_000_000, notes: 'DeepSeek' },
{ id: 'glm-5.3', contextWindow: 1_000_000, notes: 'Z.ai' },
];
const CHEAPERINFERENCE_MODEL_IDS = CHEAPERINFERENCE_MODELS.map((m) => m.id);
/**
* Render the `model/cheaperinference` interface primitive for the implementer
* stack. Cheaper Inference is an OpenAI-compatible LLM gateway with bare model
* ids from several labs. It also serves the Anthropic Messages API; Anthropic
* clients append `/v1/messages` to the base URL.
*/
function cheaperinferenceInterfaceYaml(model) {
const models = CHEAPERINFERENCE_MODELS.map((m) => [
` - id: ${m.id}`,
` context_window: ${m.contextWindow}`,
` notes: "${m.notes}"`,
].join('\n')).join('\n');
return ` - primitive: model/cheaperinference
config:
model: ${model}
models:
${models}
endpoints:
global:
openai_base_url: ${CHEAPERINFERENCE_BASE_URL}/v1
anthropic_base_url: ${CHEAPERINFERENCE_BASE_URL}
docs_root: https://cheaperinference.com/docs`;
}
/** Render the `model/minimax` interface primitive for the implementer stack. */
function minimaxInterfaceYaml(model, region) {
const models = MINIMAX_MODELS.map((m) => [
` - id: ${m.id}`,
` context_window: ${m.contextWindow}`,
` input_modalities: [${m.inputModalities.join(', ')}]`,
` thinking: [${m.thinking.join(', ')}]`,
` pricing_usd_per_million_tokens:`,
` input: ${m.pricing.input}`,
` output: ${m.pricing.output}`,
` cache_read: ${m.pricing.cacheRead}`,
` cache_write: ${m.pricing.cacheWrite === null ? 'null' : m.pricing.cacheWrite}`,
].join('\n')).join('\n');
const endpoints = MINIMAX_REGIONS.map((r) => [
` ${r.region}:`,
` openai_base_url: ${r.openaiBaseUrl}`,
` anthropic_base_url: ${r.anthropicBaseUrl}`,
` docs_root: ${r.docsRoot}`,
].join('\n')).join('\n');
return ` - primitive: model/minimax
config:
model: ${model}
region: ${region}
models:
${models}
endpoints:
${endpoints}`;
}
function parseArgs(argv) {
let pattern = 'daily-triage';
let tool = 'claude';
let target = '.';
let dryRun = false;
let withFoundry = false;
let withMemory = false;
let withFleet = false;
let modelProvider = 'anthropic';
let region = MINIMAX_DEFAULT_REGION;
let model = MINIMAX_DEFAULT_MODEL;
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (a === '--pattern' || a === '-p')
pattern = argv[++i];
else if (a === '--tool' || a === '-t')
tool = argv[++i];
else if (a === '--dry-run')
dryRun = true;
else if (a === '--with-foundry')
withFoundry = true;
else if (a === '--with-memory')
withMemory = true;
else if (a === '--with-fleet')
withFleet = true;
else if (a === '--model-provider')
modelProvider = argv[++i];
else if (a === '--region')
region = argv[++i];
else if (a === '--model')
model = argv[++i];
else if (a === '--help' || a === '-h')
return { help: true, pattern, tool, target, dryRun, withFoundry, withMemory, withFleet, modelProvider, region, model };
else if (!a.startsWith('-'))
target = a;
}
return { help: false, pattern, tool, target, dryRun, withFoundry, withMemory, withFleet, modelProvider, region, model };
}
function foundryStackYaml(stackName, pattern, preset, provider = 'anthropic', region = MINIMAX_DEFAULT_REGION, model = MINIMAX_DEFAULT_MODEL) {
if (preset === 'implementer') {
const interfaceLayer = provider === 'minimax'
? minimaxInterfaceYaml(model, region)
: provider === 'orcarouter'
? orcarouterInterfaceYaml(model)
: provider === 'cheaperinference'
? cheaperinferenceInterfaceYaml(model)
: ` - primitive: model/anthropic
config:
model: claude-sonnet-4-6`;
return `name: ${stackName}
version: 1.0.0
description: "loop-engineering ${pattern} → implementer harness (loop-init --with-foundry)"
layers:
interface:
${interfaceLayer}
composition:
- primitive: context/state-file
- primitive: tools/git-worktree-write
execution:
- primitive: sandbox/worktree-isolated
- primitive: control/token-budget-100k
reliability:
- primitive: observability/span-per-turn
- primitive: recovery/revert-on-test-fail
- primitive: emit/outerloop-evidence
`;
}
return `name: ${stackName}
version: 1.0.0
description: "loop-engineering ${pattern} → minimal harness (loop-init --with-foundry)"
layers:
interface:
- primitive: model/mock
composition:
- primitive: context/state-file
execution:
- primitive: control/token-budget-100k
- primitive: sandbox/worktree-isolated
reliability:
- primitive: observability/span-per-turn
- primitive: emit/outerloop-evidence
`;
}
/**
* Scaffold a harness-foundry stack next to loop files so LE graduates land in
* a versioned harness in one command (no foundry package dependency).
*/
async function scaffoldFoundry(pattern, targetDir, dryRun, model = {
provider: 'anthropic',
region: MINIMAX_DEFAULT_REGION,
model: MINIMAX_DEFAULT_MODEL,
}) {
const preset = PATTERN_FOUNDRY_PRESET[pattern];
const foundryRoot = path.join(targetDir, '.foundry');
const stackFile = path.join(foundryRoot, 'stack.yaml');
const stackName = path.basename(targetDir) || 'project';
if (await exists(stackFile)) {
console.log(` skip: ${stackFile} already exists`);
return { preset, stackFile };
}
const files = [
{ path: stackFile, content: foundryStackYaml(stackName, pattern, preset, model.provider, model.region, model.model) },
{
path: path.join(foundryRoot, 'hooks', 'outerloop.yaml'),
content: `enabled: false
adapter: outerloop
emitOn:
- session.end
`,
},
{
path: path.join(foundryRoot, 'README.md'),
content: `# Harness stack (from loop-engineering)
Scaffolded by \`loop-init --with-foundry\` for pattern **${pattern}** (preset: **${preset}**).
\`\`\`
loop-engineering → harness-foundry → outerloop
(patterns) (runtime) (governance)
\`\`\`
## Next
\`\`\`bash
npx @cobusgreyling/harness-foundry validate
npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"
npx @cobusgreyling/harness-foundry evolve report --session <id>
\`\`\`
Showcase: ${FOUNDRY_SHOWCASE}
`,
},
{
path: path.join(foundryRoot, 'sessions', '.gitkeep'),
content: '',
},
];
for (const f of files) {
if (dryRun) {
console.log(` would write: ${f.path}`);
continue;
}
await mkdir(path.dirname(f.path), { recursive: true });
await writeFile(f.path, f.content);
console.log(` created: ${path.relative(targetDir, f.path)}`);
}
return { preset, stackFile };
}
async function scaffoldFleet(targetDir, templatesRoot, dryRun) {
const registryTemplate = path.join(templatesRoot, 'fleet-registry.md');
if (await exists(registryTemplate)) {
await copyFile(registryTemplate, path.join(targetDir, 'fleet-registry.md'), dryRun);
}
const inboxTemplate = path.join(templatesRoot, 'fleet-inbox.md');
if (await exists(inboxTemplate)) {
await copyFile(inboxTemplate, path.join(targetDir, 'fleet-inbox.md'), dryRun);
}
}
async function scaffoldMemory(targetDir, templatesRoot, dryRun) {
const tiersTemplate = path.join(templatesRoot, 'memory-tiers.md');
const tiersDest = path.join(targetDir, 'memory-tiers.md');
if (!(await exists(tiersDest))) {
await copyFile(tiersTemplate, tiersDest, dryRun);
}
const budgetTemplate = path.join(templatesRoot, 'memory-budget.md');
const budgetDest = path.join(targetDir, 'memory-budget.md');
if (!(await exists(budgetDest))) {
await copyFile(budgetTemplate, budgetDest, dryRun);
}
}
function printFoundryCta(opts) {
const { pattern, withFoundry, preset } = opts;
if (!withFoundry)
return;
const mapped = preset ?? PATTERN_FOUNDRY_PRESET[pattern];
console.log('');
console.log(`Harness stack ready (.foundry/, preset: ${mapped} for ${pattern})`);
console.log(' npx @cobusgreyling/harness-foundry validate');
console.log(' npx @cobusgreyling/harness-foundry run --goal "Verify harness wiring"');
console.log(` Showcase: ${FOUNDRY_SHOWCASE}`);
}
function printFleetCta(opts) {
if (!opts.withFleet)
return;
console.log('');
console.log('Fleet engineering stack ready (fleet-registry.md, fleet-inbox.md)');
}
function printMemoryCta(opts) {
if (!opts.withMemory)
return;
console.log('');
console.log('Memory engineering stack ready (memory-tiers.md, memory-budget.md)');
}
async function exists(p) {
try {
await access(p);
return true;
}
catch {
return false;
}
}
async function copyDir(src, dest, dryRun) {
if (!(await exists(src)))
return false;
if (dryRun) {
console.log(` would copy: ${src} → ${dest}`);
return true;
}
await mkdir(path.dirname(dest), { recursive: true });
await cp(src, dest, { recursive: true });
console.log(` copied: ${src} → ${dest}`);
return true;
}
async function resolveBundledOrMonorepo(name) {
const bundled = path.join(PACKAGE_ROOT, name);
if (await exists(bundled))
return bundled;
return name === 'starters' ? MONOREPO_STARTERS : MONOREPO_TEMPLATES;
}
async function copyTemplateSkill(templatesRoot, templateFile, targetDir, tool, skillName, dryRun) {
const src = path.join(templatesRoot, templateFile);
const destByTool = {
grok: path.join(targetDir, '.grok', 'skills', skillName, 'SKILL.md'),
claude: path.join(targetDir, '.claude', 'skills', skillName, 'SKILL.md'),
codex: path.join(targetDir, '.codex', 'skills', skillName, 'SKILL.md'),
opencode: path.join(targetDir, 'skills', skillName, 'SKILL.md'),
};
const dest = destByTool[tool];
if (await exists(dest))
return;
await copyFile(src, dest, dryRun);
}
async function copyTemplateVerifier(templatesRoot, targetDir, tool, dryRun) {
const verifierPaths = {
grok: path.join(targetDir, '.grok', 'skills', 'loop-verifier', 'SKILL.md'),
claude: path.join(targetDir, '.claude', 'agents', 'loop-verifier.md'),
codex: path.join(targetDir, '.codex', 'agents', 'verifier.toml'),
opencode: path.join(targetDir, 'skills', 'loop-verifier', 'SKILL.md'),
};
const dest = verifierPaths[tool];
if (await exists(dest))
return;
if (tool === 'codex') {
const src = path.join(templatesRoot, 'SKILL.md.verifier');
const body = await readFile(src, 'utf8');
const toml = `name = "loop-verifier"\ndescription = "Independent verification agent for loop-produced changes."\n\n[system_prompt]\ncontent = """\n${body}\n"""\n`;
if (dryRun) {
console.log(` would write verifier: ${dest}`);
return;
}
await mkdir(path.dirname(dest), { recursive: true });
await writeFile(dest, toml);
console.log(` created: ${dest} (from verifier template)`);
return;
}
const src = path.join(templatesRoot, 'SKILL.md.verifier');
await copyFile(src, dest, dryRun);
}
async function copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun) {
if (!PATTERNS_NEEDING_FIX.has(pattern) && !L2_PATTERNS.has(pattern))
return;
await copyTemplateSkill(templatesRoot, 'SKILL.md.minimal-fix', targetDir, tool, 'minimal-fix', dryRun);
if (L2_PATTERNS.has(pattern) || pattern === 'dependency-sweeper') {
await copyTemplateVerifier(templatesRoot, targetDir, tool, dryRun);
}
}
/** Per-pattern goal seeded into loop-ledger.json for the circuit breaker. */
const LEDGER_GOAL = {
'daily-triage': 'Keep the repo healthy and STATE.md current',
'pr-babysitter': 'Get the watched PR review-ready and green',
'ci-sweeper': 'Get failing CI back to green',
'dependency-sweeper': 'Land safe dependency updates',
'post-merge-cleanup': 'Clean up regressions from recent merges',
'changelog-drafter': 'Draft accurate release notes',
'issue-triage': 'Triage the open issue queue',
'thin-loop': 'Snapshot open issues and PRs; do not edit code',
};
/**
* Readiness level seeded into loop-ledger.json so the loop-guard skill can
* resolve a realistic per-run token budget from `loop-cost --json` instead of a
* hand-typed number. Fix-capable loops draft changes with a verifier (a human
* still merges), so L2 is the right default; tune it in the ledger if a loop
* runs unattended (L3) or report-only (L1).
*/
const LEDGER_LEVEL = {
'daily-triage': 'L1',
'pr-babysitter': 'L2',
'ci-sweeper': 'L2',
'dependency-sweeper': 'L2',
'post-merge-cleanup': 'L2',
'changelog-drafter': 'L1',
'issue-triage': 'L1',
'thin-loop': 'L1',
};
/**
* Fix-capable loops retry actions, so they need a circuit breaker: scaffold the
* loop-guard skill plus a seeded loop-ledger.json wired to `loop-context`.
* Report-only patterns (daily-triage, issue-triage, changelog-drafter) don't
* retry fixes, so they skip this to keep the scaffold minimal.
*/
async function scaffoldCircuitBreaker(pattern, tool, targetDir, templatesRoot, dryRun) {
if (!PATTERNS_NEEDING_FIX.has(pattern))
return;
await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-guard', targetDir, tool, 'loop-guard', dryRun);
const ledgerPath = path.join(targetDir, 'loop-ledger.json');
if (await exists(ledgerPath))
return;
const seed = `${JSON.stringify({ goal: LEDGER_GOAL[pattern], pattern, level: LEDGER_LEVEL[pattern], attempts: [] }, null, 2)}\n`;
if (dryRun) {
console.log(` would write: ${ledgerPath}`);
return;
}
await writeFile(ledgerPath, seed);
console.log(' created: loop-ledger.json (circuit breaker)');
}
/**
* Scaffold the loop-intake skill for patterns that receive ambiguous human
* input, so the loop sharpens the goal (or escalates) before acting on it.
*/
async function scaffoldIntake(pattern, tool, targetDir, templatesRoot, dryRun) {
if (!PATTERNS_NEEDING_INTAKE.has(pattern))
return;
await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-intake', targetDir, tool, 'loop-intake', dryRun);
}
function formatTokenCap(n) {
if (n >= 1_000_000)
return `${n / 1_000_000}M`;
if (n >= 1_000)
return `${n / 1_000}k`;
return String(n);
}
function buildLoopBudgetMd(pattern) {
const b = PATTERN_BUDGET[pattern];
return `# Loop Budget — YOUR_PROJECT
> Primary loop: **${b.name}** (scaffolded by loop-init)
## Daily limits
| Loop | Max runs/day | Max tokens/day | Max sub-agent spawns/run |
|------|--------------|----------------|--------------------------|
| ${b.name} | ${b.maxRunsPerDay} | ${formatTokenCap(b.dailyCap)} | ${b.maxSpawnsL1} (L1) / ${b.maxSpawnsL2} (L2) |
## On budget exceed
1. Pause 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
## Estimate spend
\`\`\`bash
npx @cobusgreyling/loop-cost --pattern ${pattern}
\`\`\`
`;
}
async function scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun) {
const budgetPath = path.join(targetDir, 'loop-budget.md');
const runLogTemplate = path.join(templatesRoot, 'loop-run-log.md.template');
const runLogPath = path.join(targetDir, 'loop-run-log.md');
if (!(await exists(budgetPath))) {
const content = buildLoopBudgetMd(pattern);
if (dryRun) {
console.log(` would write: ${budgetPath}`);
}
else {
await writeFile(budgetPath, content);
console.log(` created: loop-budget.md`);
}
}
if (!(await exists(runLogPath))) {
await copyFile(runLogTemplate, runLogPath, dryRun);
}
await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-budget', targetDir, tool, 'loop-budget', dryRun);
}
async function scaffoldConstraints(targetDir, templatesRoot, tool, dryRun) {
const constraintsPath = path.join(targetDir, 'loop-constraints.md');
const constraintsTemplate = path.join(templatesRoot, 'loop-constraints.md');
if (!(await exists(constraintsPath)) && (await exists(constraintsTemplate))) {
await copyFile(constraintsTemplate, constraintsPath, dryRun);
}
await copyTemplateSkill(templatesRoot, 'SKILL.md.loop-constraints', targetDir, tool, 'loop-constraints', dryRun);
}
async function copyFile(src, dest, dryRun) {
if (!(await exists(src)))
return false;
if (dryRun) {
console.log(` would copy: ${src} → ${dest}`);
return true;
}
await mkdir(path.dirname(dest), { recursive: true });
await cp(src, dest);
console.log(` copied: ${src} → ${dest}`);
return true;
}
const OPENCODE_RUN = 'opencode run';
function firstLoopCommand(pattern, tool) {
const cmds = {
'daily-triage': {
grok: '/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.',
claude: '/loop 1d $loop-triage — update STATE.md. Report-only week one.',
codex: 'Automation daily: $loop-triage → update STATE.md. Report-only.',
opencode: `${OPENCODE_RUN} "Run loop-triage. Read STATE.md first. Update High Priority and Watch List. No auto-fix in week one." --agent loop-triage`,
},
'pr-babysitter': {
grok: '/loop 10m Run pr-review-triage. Update pr-babysitter-state.md. Worktree + minimal-fix + verifier for allowlisted PRs only. Escalate after 3 attempts.',
claude: '/loop 10m $pr-review-triage — update pr-babysitter-state.md. No auto-merge.',
codex: 'Automation 10m: pr-review-triage → pr-babysitter-state.md. No auto-merge.',
opencode: `${OPENCODE_RUN} "Run PR babysitter triage. Read pr-babysitter-state.md first. Report only — no code edits." --title "PR babysitter"`,
},
'ci-sweeper': {
grok: '/loop 15m Run ci-triage on failing CI. Update ci-sweeper-state.md. Fix only regressions in worktree. Max 3 attempts.',
claude: '/loop 15m $ci-triage — update ci-sweeper-state.md. Max 3 fix attempts.',
codex: 'Automation 15m: ci-triage on CI failures. Max 3 attempts.',
opencode: `${OPENCODE_RUN} "Run ci-triage on failing CI. Update ci-sweeper-state.md. Report only in week one."`,
},
'dependency-sweeper': {
grok: '/loop 6h Run dependency-triage. Patch-only auto-fix in worktree + verifier. Escalate majors and denylist.',
claude: '/loop 6h $dependency-triage — patch-only with verifier. Escalate risky bumps.',
codex: 'Automation 6h: dependency-triage. Patch-only with verifier.',
opencode: `${OPENCODE_RUN} "Run dependency-triage. Update dependency-sweeper-state.md. Report only — escalate majors."`,
},
'post-merge-cleanup': {
grok: '/loop 1d Run post-merge-scan on recent merges. Update post-merge-state.md. Small fixes only in worktree.',
claude: '/loop 1d $post-merge-scan — update post-merge-state.md. Small fixes only.',
codex: 'Automation daily: post-merge-scan → post-merge-state.md.',
opencode: `${OPENCODE_RUN} "Run post-merge-scan. Update post-merge-state.md. Report only in week one."`,
},
'changelog-drafter': {
grok: '/loop 1d Run changelog-scan on merges since last tag. Produce categorized draft in RELEASE_NOTES_DRAFT.md using draft-release-notes. Update changelog-drafter-state.md. Human review only.',
claude: '/loop 1d $changelog-scan + draft-release-notes — write RELEASE_NOTES_DRAFT.md and update state. Human approves before publish.',
codex: 'Automation daily: changelog-scan + draft-release-notes → RELEASE_NOTES_DRAFT.md. Human review.',
opencode: `${OPENCODE_RUN} "Run changelog-scan. Draft RELEASE_NOTES_DRAFT.md. Human review only — no publish."`,
},
'issue-triage': {
grok: '/loop 2h Run issue-triage. Update issue-triage-state.md. Propose labels and priority only. No auto-apply. Human reviews the needs-human slice.',
claude: '/loop 2h $issue-triage — update issue-triage-state.md. Suggest labels on allowlisted areas only. Report mode week one.',
codex: 'Automation 2h: issue-triage → issue-triage-state.md. Propose only.',
opencode: `${OPENCODE_RUN} "Run issue-triage. Update issue-triage-state.md. Propose labels only — no auto-apply."`,
},
'thin-loop': {
grok: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md, no /loop required.',
claude: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md, no /loop required.',
codex: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md required.',
opencode: 'Commit .github/workflows/thin-loop.yml. The Action is the loop — no STATE.md required.',
},
};
return cmds[pattern][tool];
}
async function resolveAuditCli() {
const monorepo = path.resolve(PACKAGE_ROOT, '../loop-audit/dist/cli.js');
if (await exists(monorepo))
return monorepo;
try {
const { createRequire } = await import('node:module');
const require = createRequire(import.meta.url);
const pkg = require.resolve('@cobusgreyling/loop-audit/package.json');
return path.join(path.dirname(pkg), 'dist/cli.js');
}
catch {
return null;
}
}
async function runAuditJson(cli, targetDir) {
return new Promise((resolve, reject) => {
const child = spawn('node', [cli, targetDir, '--json'], {
stdio: ['ignore', 'pipe', 'pipe'],
});
let stdout = '';
child.stdout.on('data', (chunk) => {
stdout += chunk.toString();
});
child.on('error', reject);
child.on('close', () => {
if (stdout.trim())
resolve(stdout);
else
reject(new Error('loop-audit produced no output'));
});
});
}
async function runAuditSummary(targetDir) {
const cli = await resolveAuditCli();
if (!cli)
return null;
try {
const stdout = await runAuditJson(cli, targetDir);
return JSON.parse(stdout);
}
catch {
return null;
}
}
function formatScoreBar(score, width = 20) {
const filled = Math.max(0, Math.min(width, Math.round((score / 100) * width)));
return `${'█'.repeat(filled)}${'░'.repeat(width - filled)} ${score}/100`;
}
function auditTargetArg(target, targetDir) {
return target === '.' ? '.' : targetDir;
}
async function main() {
const args = parseArgs(process.argv.slice(2));
if (args.help) {
console.log(`loop-init — scaffold loop engineering starters
Usage:
loop-init [target-dir] --pattern <name> --tool <grok|claude|codex|opencode> [--with-foundry]
Patterns:
daily-triage (default)
pr-babysitter
ci-sweeper
dependency-sweeper
post-merge-cleanup
changelog-drafter (new low-risk release notes pattern)
issue-triage (new low-risk issue queue health companion to daily triage)
thin-loop (GitHub Action snapshot — no STATE.md)
Options:
-p, --pattern Pattern to scaffold
-t, --tool Tool target (default: claude)
--with-foundry Also scaffold .foundry/ stack (harness-foundry runtime)
--with-memory Also scaffold memory-engineering tiers and budget
--with-fleet Also scaffold fleet-engineering registry and inbox
--model-provider Implementer interface provider (default: anthropic; minimax, orcarouter, cheaperinference)
--region MiniMax region when --model-provider minimax (global_en, cn_zh)
--model Provider model when --model-provider minimax/orcarouter/cheaperinference (default: MiniMax-M3 / orcarouter/fusion / gpt-5.4-mini)
--dry-run Print actions without copying
-h, --help This help
Foundry presets (with --with-foundry):
report-only patterns → minimal
fix-capable patterns → implementer
Examples:
npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude
npx @cobusgreyling/loop-init . --pattern thin-loop --tool claude
npx @cobusgreyling/loop-init . --pattern daily-triage --tool claude --with-foundry
npx @cobusgreyling/loop-init . -p pr-babysitter -t claude --with-foundry
npx @cobusgreyling/loop-init . -p ci-sweeper -t grok --with-foundry --model-provider minimax
npx @cobusgreyling/loop-init . -p ci-sweeper -t grok --with-foundry --model-provider minimax --region cn_zh --model MiniMax-M2.7
npx @cobusgreyling/loop-init . -p ci-sweeper -t claude --with-foundry --model-provider orcarouter --model orcarouter/auto
npx @cobusgreyling/loop-init . -p ci-sweeper -t claude --with-foundry --model-provider cheaperinference --model claude-sonnet-5
npx @cobusgreyling/loop-init . -p daily-triage -t opencode
npx @cobusgreyling/loop-init . --with-memory
npx @cobusgreyling/loop-init . --with-fleet
`);
process.exit(0);
}
let { pattern, tool, target, dryRun, withFoundry, withMemory, withFleet, modelProvider, region, model } = args;
const validPatterns = Object.keys(PATTERN_STARTERS);
const validTools = Object.keys(TOOL_SUFFIX);
if (!validPatterns.includes(pattern)) {
console.error(`Unknown pattern: ${pattern}. Valid: ${validPatterns.join(', ')}`);
process.exit(1);
}
if (!validTools.includes(tool)) {
console.error(`Unknown tool: ${tool}. Valid: ${validTools.join(', ')}`);
process.exit(1);
}
const validProviders = ['anthropic', 'minimax', 'orcarouter', 'cheaperinference'];
if (!validProviders.includes(modelProvider)) {
console.error(`Unknown model provider: ${modelProvider}. Valid: ${validProviders.join(', ')}`);
process.exit(1);
}
if (modelProvider === 'minimax') {
if (!MINIMAX_REGION_IDS.includes(region)) {
console.error(`Unknown region: ${region}. Valid: ${MINIMAX_REGION_IDS.join(', ')}`);
process.exit(1);
}
if (!MINIMAX_MODEL_IDS.includes(model)) {
console.error(`Unknown model: ${model}. Valid: ${MINIMAX_MODEL_IDS.join(', ')}`);
process.exit(1);
}
}
if (modelProvider === 'orcarouter') {
// `model` defaults to the MiniMax default; if the user did not pass
// `--model` explicitly, fall back to the OrcaRouter default instead.
if (!ORCAROUTER_MODEL_IDS.includes(model)) {
if (model === MINIMAX_DEFAULT_MODEL) {
model = ORCAROUTER_DEFAULT_MODEL;
}
else {
console.error(`Unknown model: ${model}. Valid: ${ORCAROUTER_MODEL_IDS.join(', ')}`);
process.exit(1);
}
}
}
if (modelProvider === 'cheaperinference') {
// `model` defaults to the MiniMax default; if the user did not pass
// `--model` explicitly, fall back to the Cheaper Inference default instead.
if (!CHEAPERINFERENCE_MODEL_IDS.includes(model)) {
if (model === MINIMAX_DEFAULT_MODEL) {
model = CHEAPERINFERENCE_DEFAULT_MODEL;
}
else {
console.error(`Unknown model: ${model}. Valid: ${CHEAPERINFERENCE_MODEL_IDS.join(', ')}`);
process.exit(1);
}
}
}
const targetDir = path.resolve(target);
const baseStarter = PATTERN_STARTERS[pattern];
const suffix = TOOL_AGNOSTIC.has(pattern) ? '' : TOOL_SUFFIX[tool];
const starterName = `${baseStarter}${suffix}`;
const startersRoot = await resolveBundledOrMonorepo('starters');
const templatesRoot = await resolveBundledOrMonorepo('templates');
const starterRoot = path.join(startersRoot, starterName);
if (!(await exists(starterRoot))) {
const fallback = path.join(startersRoot, baseStarter);
if (!(await exists(fallback))) {
console.error(`Starter not found: ${starterRoot}`);
process.exit(1);
}
console.log(`Note: no ${tool} variant for ${pattern} — using ${baseStarter} (Grok paths)`);
}
const effectiveStarter = (await exists(starterRoot))
? starterRoot
: path.join(startersRoot, baseStarter);
console.log(`\nloop-init: ${pattern} → ${targetDir} (${tool})${dryRun ? ' [dry-run]' : ''}\n`);
if (tool === 'opencode') {
const skillsDir = path.join(effectiveStarter, 'skills');
if (await exists(skillsDir)) {
const entries = await readDirNames(skillsDir);
for (const entry of entries) {
await copyDir(path.join(skillsDir, entry), path.join(targetDir, 'skills', entry), dryRun);
}
}
const agentsMd = path.join(effectiveStarter, 'AGENTS.md');
if (await exists(agentsMd)) {
await copyFile(agentsMd, path.join(targetDir, 'AGENTS.md'), dryRun);
}
const opencodeJson = path.join(effectiveStarter, 'opencode.json.example');
if (await exists(opencodeJson)) {
await copyFile(opencodeJson, path.join(targetDir, 'opencode.json'), dryRun);
}
}
else {
const skillRoots = [
path.join(effectiveStarter, '.grok', 'skills'),
path.join(effectiveStarter, '.claude', 'skills'),
path.join(effectiveStarter, '.codex', 'skills'),
];
for (const skillsDir of skillRoots) {
if (!(await exists(skillsDir)))
continue;
const toolPrefix = skillsDir.includes('.grok')
? '.grok/skills'
: skillsDir.includes('.claude')
? '.claude/skills'
: '.codex/skills';
const entries = await readDirNames(skillsDir);
for (const entry of entries) {
await copyDir(path.join(skillsDir, entry), path.join(targetDir, toolPrefix, entry), dryRun);
}
}
const agentFiles = [
{ src: path.join(effectiveStarter, '.claude', 'agents'), dest: path.join(targetDir, '.claude', 'agents') },
{ src: path.join(effectiveStarter, '.codex', 'agents'), dest: path.join(targetDir, '.codex', 'agents') },
];
for (const { src, dest } of agentFiles) {
if (await exists(src)) {
const entries = await readDirNames(src);
for (const entry of entries) {
await copyFile(path.join(src, entry), path.join(dest, entry), dryRun);
}
}
}
}
const stateFile = STATE_FILES[pattern];
const stateExample = path.join(effectiveStarter, `${stateFile}.example`);
if (await exists(stateExample)) {
await copyFile(stateExample, path.join(targetDir, stateFile), dryRun);
}
else {
const alt = path.join(effectiveStarter, 'STATE.md.example');
if (await exists(alt)) {
await copyFile(alt, path.join(targetDir, stateFile), dryRun);
}
}
const loopMd = path.join(effectiveStarter, 'LOOP.md');
if (await exists(loopMd)) {
await copyFile(loopMd, path.join(targetDir, 'LOOP.md'), dryRun);
}
const wfSrc = path.join(effectiveStarter, '.github', 'workflows');
if (await exists(wfSrc)) {
const wfEntries = await readDirNames(wfSrc);
for (const entry of wfEntries) {
if (!entry.endsWith('.yml') && !entry.endsWith('.yaml'))
continue;
await copyFile(path.join(wfSrc, entry), path.join(targetDir, '.github', 'workflows', entry), dryRun);
}
}
if (pattern !== 'thin-loop') {
await copyL2Templates(pattern, tool, targetDir, templatesRoot, dryRun);
await scaffoldCircuitBreaker(pattern, tool, targetDir, templatesRoot, dryRun);
await scaffoldObservability(pattern, tool, targetDir, templatesRoot, dryRun);
await scaffoldIntake(pattern, tool, targetDir, templatesRoot, dryRun);
await scaffoldConstraints(targetDir, templatesRoot, tool, dryRun);
}
if (tool !== 'opencode' && pattern !== 'thin-loop' && !dryRun && !(await exists(path.join(targetDir, 'AGENTS.md')))) {
const agentsTemplate = `# AGENTS.md
## Test commands
npm test
npm run lint
## Loop conventions
- Report-only week one (L1) before enabling auto-fix (L2)
- See LOOP.md for cadence and human gates
`;
await writeFile(path.join(targetDir, 'AGENTS.md'), agentsTemplate);
console.log(' created: AGENTS.md (template)');
}
let foundryPreset;
if (withFoundry) {
console.log('');
console.log('Harness foundry:');
const foundry = await scaffoldFoundry(pattern, targetDir, dryRun, {
provider: modelProvider,
region,
model,
});
foundryPreset = foundry?.preset;
}
if (withMemory) {
console.log('');
console.log('Memory engineering:');
await scaffoldMemory(targetDir, templatesRoot, dryRun);
}
if (withFleet) {
console.log('');
console.log('Fleet engineering:');
await scaffoldFleet(targetDir, templatesRoot, dryRun);
}
const auditArg = auditTargetArg(target, targetDir);
let auditScore = null;
if (!dryRun) {
const audit = await runAuditSummary(targetDir);
if (audit) {
auditScore = audit.score;
console.log('');
console.log(`✓ Loop Ready: ${audit.score}/100 (${audit.level})`);
console.log(` ${formatScoreBar(audit.score)}`);
console.log(` ${audit.assessment}`);
console.log('');
console.log('Paste badge in README:');
console.log(` npx @cobusgreyling/loop-audit ${auditArg} --badge`);
}
else {
console.log('\n=== Loop Ready score ===');
console.log(` npx @cobusgreyling/loop-audit ${auditArg} --suggest`);
}
}
if (PATTERNS_NEEDING_FIX.has(pattern)) {
console.log('');
console.log('Circuit breaker wired (loop-guard skill + loop-ledger.json):');
console.log(' npx @cobusgreyling/loop-context --check --ledger loop-ledger.json');
}
if (PATTERNS_NEEDING_INTAKE.has(pattern)) {
console.log('');
console.log('Intake wired (loop-intake skill): clarify a vague item or escalate before acting.');
}
console.log('');
console.log(`First loop (${tool}):`);
console.log(` ${firstLoopCommand(pattern, tool)}`);
console.log('');
console.log(`Estimate cost: npx @cobusgreyling/loop-cost --pattern ${pattern} --level L1`);
printFoundryCta({
pattern,
tool,
withFoundry,
score: auditScore,
preset: foundryPreset,
});
printMemoryCta({
pattern,
tool,
withMemory,
score: auditScore,
});
printFleetCta({
pattern,
tool,
withFleet,
score: auditScore,
});
printContributorCta();
}
async function readDirNames(dir) {
const { readdir } = await import('node:fs/promises');
const entries = await readdir(dir, { withFileTypes: true });
return entries.filter((e) => e.isDirectory() || e.isFile()).map((e) => e.name);
}
main().catch((err) => {
console.error('loop-init failed:', err instanceof Error ? err.message : err);
process.exit(1);
});