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.

8.1 KB
Raw Blame
#!/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_TEMPLATES = path.resolve(PACKAGE_ROOT, '../../templates');

type Tool = 'grok' | 'claude' | 'codex' | 'opencode';

function parseArgs(argv: string[]) {
  let tool: Tool = 'grok';
  let target = '.';
  let dryRun = false;

  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    if (a === '--tool' || a === '-t') tool = argv[++i] as Tool;
    else if (a === '--dry-run') dryRun = true;
    else if (a === '--help' || a === '-h') return { help: true as const, tool, target, dryRun };
    else if (!a.startsWith('-')) target = a;
  }

  return { help: false as const, tool, target, dryRun };
}

async function exists(p: string): Promise<boolean> {
  try {
    await access(p);
    return true;
  } catch {
    return false;
  }
}

async function copyFile(src: string, dest: string, dryRun: boolean) {
  if (!(await exists(src))) {
    console.error(`Warning: Template not found at ${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: ${path.basename(src)} → ${dest}`);
  return true;
}

async function resolveBundledOrMonorepo(name: 'templates'): Promise<string> {
  const bundled = path.join(PACKAGE_ROOT, name);
  if (await exists(bundled)) return bundled;
  return MONOREPO_TEMPLATES;
}

async function copyTemplateSkill(
  templatesRoot: string,
  templateFile: string,
  targetDir: string,
  tool: Tool,
  skillName: string,
  dryRun: boolean,
) {
  const src = path.join(templatesRoot, templateFile);
  const destByTool: Record<Tool, string> = {
    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 resolveAuditCli(): Promise<string | null> {
  const monorepo = path.resolve(PACKAGE_ROOT, '../goal-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/goal-audit/package.json');
    return path.join(path.dirname(pkg), 'dist/cli.js');
  } catch {
    return null;
  }
}

async function runAuditJson(cli: string, targetDir: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const child = spawn('node', [cli, targetDir, '--json'], {
      stdio: ['ignore', 'pipe', 'pipe'],
    });
    let stdout = '';
    child.stdout.on('data', (chunk: Buffer | string) => {
      stdout += chunk.toString();
    });
    child.on('error', reject);
    child.on('close', () => {
      if (stdout.trim()) resolve(stdout);
      else reject(new Error('goal-audit produced no output'));
    });
  });
}

async function runAuditSummary(
  targetDir: string,
): Promise<{ score: number; level: string; assessment: string } | null> {
  const cli = await resolveAuditCli();
  if (!cli) return null;
  try {
    const stdout = await runAuditJson(cli, targetDir);
    return JSON.parse(stdout) as { score: number; level: string; assessment: string };
  } catch {
    return null;
  }
}

function formatScoreBar(score: number, width = 20): string {
  const filled = Math.max(0, Math.min(width, Math.round((score / 100) * width)));
  return `${'█'.repeat(filled)}${'░'.repeat(width - filled)}  ${score}/100`;
}

function auditTargetArg(target: string, targetDir: string): string {
  return target === '.' ? '.' : targetDir;
}

async function main() {
  const args = parseArgs(process.argv.slice(2));

  if (args.help) {
    console.log(`goal-init — scaffold goal engineering configurations

Usage:
  goal-init [target-dir] --tool <grok|claude|codex|opencode>

Options:
  -t, --tool      Tool target (default: grok)
  --dry-run       Print actions without copying
  -h, --help      This help

Examples:
  npx @cobusgreyling/goal-init . --tool grok
  npx @cobusgreyling/goal-init . -t claude
`);
    process.exit(0);
  }

  const { tool, target, dryRun } = args;

  const validTools = ['grok', 'claude', 'codex', 'opencode'] as Tool[];
  if (!validTools.includes(tool)) {
    console.error(`Unknown tool: ${tool}. Valid: ${validTools.join(', ')}`);
    process.exit(1);
  }

  const targetDir = path.resolve(target);
  const templatesRoot = await resolveBundledOrMonorepo('templates');

  console.log(`\ngoal-init: Scaffolding Goal Workflows → ${targetDir} (${tool})${dryRun ? ' [dry-run]' : ''}\n`);

  // 1. Scaffold GOAL.md
  if (!(await exists(path.join(targetDir, 'GOAL.md')))) {
    await copyFile(path.join(templatesRoot, 'GOAL.md.template'), path.join(targetDir, 'GOAL.md'), dryRun);
  }

  // 2. Scaffold goal-budget.md
  if (!(await exists(path.join(targetDir, 'goal-budget.md')))) {
    await copyFile(path.join(templatesRoot, 'goal-budget.md.template'), path.join(targetDir, 'goal-budget.md'), dryRun);
  }

  // 3. Scaffold goal-run-log.md
  if (!(await exists(path.join(targetDir, 'goal-run-log.md')))) {
    await copyFile(path.join(templatesRoot, 'goal-run-log.md.template'), path.join(targetDir, 'goal-run-log.md'), dryRun);
  }

  // 3.5 Scaffold docs/safety.md
  const safetyPath = path.join(targetDir, 'docs', 'safety.md');
  if (!(await exists(safetyPath)) && !dryRun) {
    await mkdir(path.dirname(safetyPath), { recursive: true });
    await writeFile(safetyPath, '# Safety Policy\n\nEnsure any autonomous tools adhere to safety guidelines.\n');
    console.log('  created: docs/safety.md (stub)');
  } else if (dryRun) {
    console.log(`  would create: docs/safety.md (stub)`);
  }

  // 4. Scaffold skills
  await copyTemplateSkill(templatesRoot, 'SKILL.md.goal-verifier', targetDir, tool, 'goal-verifier', dryRun);
  await copyTemplateSkill(templatesRoot, 'SKILL.md.goal-scoper', targetDir, tool, 'goal-scoper', dryRun);

  // 5. Scaffold or Update AGENTS.md
  const agentsPath = path.join(targetDir, 'AGENTS.md');
  if (!(await exists(agentsPath)) && !dryRun) {
    const agentsTemplate = `# AGENTS.md

## Goal Engineering Rules
- Use /goal and update_goal.
- \`goal-verifier\` MUST PASS before setting completed: true in GOAL.md.
`;
    await writeFile(agentsPath, agentsTemplate);
    console.log('  created: AGENTS.md (template)');
  } else if (!dryRun) {
    const content = await readFile(agentsPath, 'utf8');
    if (!/goal|update_goal|GOAL\.md/i.test(content)) {
      await writeFile(agentsPath, content + '\n## Goal Engineering Rules\n- Use /goal and update_goal.\n- `goal-verifier` MUST PASS before setting completed: true in GOAL.md.\n');
      console.log('  updated: AGENTS.md (appended goal rules)');
    }
  }

  const auditArg = auditTargetArg(target, targetDir);

  if (!dryRun) {
    const audit = await runAuditSummary(targetDir);
    if (audit) {
      console.log('');
      console.log(`✓ Goal 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/goal-audit ${auditArg} --badge`);
    } else {
      console.log('\n=== Goal Ready score ===');
      console.log(`  npx @cobusgreyling/goal-audit ${auditArg} --suggest`);
    }
  }

  console.log('');
  console.log(`To start a new goal (${tool}):`);
  console.log(`  Update GOAL.md and run: /goal Read GOAL.md. Work the objective. goal-verifier before completed: true.`);
  printContributorCta();
}

main().catch((err) => {
  console.error('goal-init failed:', err instanceof Error ? err.message : err);
  process.exit(1);
});