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.6 KB
Raw Blame
/**
 * 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';

export type DoctorSeverity = 'healthy' | 'warning' | 'blocked';

export interface DoctorAction {
  priority: number;
  text: string;
  command?: string;
}

export interface DoctorReport {
  target: string;
  severity: DoctorSeverity;
  exitCode: number;
  ready: {
    score: number | null;
    level: string | null;
    assessment: string | null;
  };
  sync: {
    score: number | null;
    level: string | null;
    issueCount: number;
  };
  files: {
    state: string | null;
    loopMd: boolean;
    budget: boolean;
    runLog: boolean;
    constraints: boolean;
    gate: boolean;
    agentsMd: boolean;
  };
  actions: DoctorAction[];
  notes: string[];
}

function parseJsonLoose(stdout: string): unknown | null {
  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: string): Promise<DoctorReport> {
  const root = path.resolve(target);
  const notes: string[] = [];
  const actions: DoctorAction[] = [];

  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: number | null = null;
  let readyLevel: string | null = null;
  let assessment: string | null = null;
  let auditRecs: string[] = [];

  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) as {
      score?: number;
      level?: string;
      assessment?: string;
      recommendations?: string[];
    } | null;
    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: number | null = null;
  let syncLevel: string | null = 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) as {
      score?: number;
      level?: string;
      issues?: unknown[];
      suggestions?: string[];
    } | null;
    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<string, DoctorAction>();
  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: DoctorSeverity = '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: DoctorReport): string {
  const lines: string[] = [];
  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: boolean): string {
  return b ? 'yes' : 'no';
}