loop-engineering 1.0.0

package/src/lib/audit.mjs

@@ -0,0 +1,137 @@
+// audit.mjs — scores a project's loop-readiness 0-100 against this skill's spec format.
+//
+// Rubric (documented here, not just in code, so the score is explainable):
+//   20 pts — LOOP_SPEC.md exists
+//   30 pts — spec passes lint_spec.mjs (5 pts removed per category of issue: missing
+//            section, placeholder content, weak verification, weak termination, weak
+//            scope, weak escalation — capped at 0)
+//   15 pts — at least one run has been recorded in .loop/state.json
+//   15 pts — most recent run did not end in an unresolved stop-escalate
+//            (i.e. either it succeeded, or a later run after it succeeded)
+//   10 pts — skill is installed for at least one supported tool in this project
+//   10 pts — project is a git repo (no-progress detection is more reliable with
+//            real git-diff signal than the content-hash fallback)
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { TOOLS } from "./detect.mjs";
+
+function scoreSpecExists(root) {
+  const specPath = join(root, "LOOP_SPEC.md");
+  return { points: existsSync(specPath) ? 20 : 0, max: 20, label: "LOOP_SPEC.md exists", specPath };
+}
+
+function scoreLint(root, lintModulePath) {
+  const specPath = join(root, "LOOP_SPEC.md");
+  if (!existsSync(specPath)) {
+    return { points: 0, max: 30, label: "Spec passes lint", detail: "no spec to lint" };
+  }
+  try {
+    execSync(`node "${lintModulePath}" "${specPath}"`, { stdio: "pipe" });
+    return { points: 30, max: 30, label: "Spec passes lint", detail: "PASS" };
+  } catch (err) {
+    const stderr = err.stderr ? err.stderr.toString() : "";
+    const issueCount = (stderr.match(/^\s+-/gm) || []).length || 1;
+    const deduction = Math.min(30, issueCount * 5);
+    return {
+      points: Math.max(0, 30 - deduction),
+      max: 30,
+      label: "Spec passes lint",
+      detail: `${issueCount} issue(s) reported by linter`,
+    };
+  }
+}
+
+function scoreRunHistory(root) {
+  const statePath = join(root, ".loop", "state.json");
+  if (!existsSync(statePath)) {
+    return { points: 0, max: 15, label: "Run history exists", detail: "no .loop/state.json" };
+  }
+  try {
+    const state = JSON.parse(readFileSync(statePath, "utf-8"));
+    const hasAnyRun = Object.values(state).some((entry) => entry.iterations && entry.iterations.length > 0);
+    return {
+      points: hasAnyRun ? 15 : 0,
+      max: 15,
+      label: "Run history exists",
+      detail: hasAnyRun ? "at least one recorded run" : "state file present but empty",
+    };
+  } catch {
+    return { points: 0, max: 15, label: "Run history exists", detail: "state.json unreadable" };
+  }
+}
+
+function scoreResolvedRuns(root) {
+  const statePath = join(root, ".loop", "state.json");
+  if (!existsSync(statePath)) {
+    return { points: 0, max: 15, label: "Last run resolved cleanly", detail: "no run history" };
+  }
+  try {
+    const state = JSON.parse(readFileSync(statePath, "utf-8"));
+    const entries = Object.values(state);
+    if (entries.length === 0) {
+      return { points: 0, max: 15, label: "Last run resolved cleanly", detail: "no run history" };
+    }
+    // "Resolved cleanly" here means: the most recent iteration recorded for any tracked
+    // spec exited 0. We can't see an explicit "escalated" flag in state.json (run_loop.mjs
+    // determines that at decision time, not storage time), so exitCode 0 on the latest
+    // iteration is the best proxy available from stored state alone.
+    const allResolved = entries.every((entry) => {
+      const last = entry.iterations[entry.iterations.length - 1];
+      return last && last.exitCode === 0;
+    });
+    return {
+      points: allResolved ? 15 : 0,
+      max: 15,
+      label: "Last run resolved cleanly",
+      detail: allResolved ? "most recent iteration succeeded" : "most recent iteration did not succeed",
+    };
+  } catch {
+    return { points: 0, max: 15, label: "Last run resolved cleanly", detail: "state.json unreadable" };
+  }
+}
+
+function scoreToolInstalled(root) {
+  let anyInstalled = false;
+  const found = [];
+  for (const [id, tool] of Object.entries(TOOLS)) {
+    const paths = tool.installPaths(root);
+    for (const p of paths) {
+      const checkPath = typeof p === "string" ? p : p.path;
+      if (existsSync(checkPath)) {
+        anyInstalled = true;
+        found.push(id);
+      }
+    }
+  }
+  return {
+    points: anyInstalled ? 10 : 0,
+    max: 10,
+    label: "Skill installed for at least one tool",
+    detail: found.length > 0 ? found.join(", ") : "none found",
+  };
+}
+
+function scoreGitRepo(root) {
+  try {
+    execSync("git rev-parse --is-inside-work-tree", { cwd: root, stdio: "pipe" });
+    return { points: 10, max: 10, label: "Project is a git repo", detail: "git detected — reliable no-progress signal" };
+  } catch {
+    return { points: 0, max: 10, label: "Project is a git repo", detail: "no git — falls back to content-hash signal" };
+  }
+}
+
+export function auditProject(root, lintModulePath) {
+  const checks = [
+    scoreSpecExists(root),
+    scoreLint(root, lintModulePath),
+    scoreRunHistory(root),
+    scoreResolvedRuns(root),
+    scoreToolInstalled(root),
+    scoreGitRepo(root),
+  ];
+  const total = checks.reduce((sum, c) => sum + c.points, 0);
+  const max = checks.reduce((sum, c) => sum + c.max, 0);
+  return { score: total, max, checks };
+}

package/src/lib/cost.mjs

@@ -0,0 +1,72 @@
+// cost.mjs — rough token cost estimate for running a loop spec, BEFORE committing to a run.
+//
+// This is deliberately a rough range, not a precise prediction — token usage depends on
+// the specific model, how much surrounding context the agent's harness re-reads each
+// turn, and how verbose the verification output is. The goal is to catch "this will burn
+// through my plan before lunch" before it happens, not to bill accurately.
+//
+// Model (stated so it can be argued with):
+//   per-iteration tokens ≈ SKILL_OVERHEAD (re-reading SKILL.md + the relevant reference
+//     file, ~1 time per session, amortized) + SPEC_TOKENS (the spec itself, read every
+//     iteration) + VERIFIER_OUTPUT_TOKENS (stdout/stderr fed back, varies a lot by command)
+//     + AGENT_EDIT_TOKENS (the actual code-editing turn — by far the most variable and
+//     the dominant cost on anything beyond a trivial fix)
+//
+// Defaults below are deliberately conservative (biased toward overestimating) since the
+// failure mode of underestimating is worse (surprise bill) than overestimating (caution).
+
+const DEFAULTS = {
+  specTokens: 400, // a loop-ready spec with all 5 sections, read every iteration
+  verifierOutputTokens: 300, // typical test/build/lint stdout+stderr on failure
+  agentEditTokensPerIteration: 2000, // conservative floor for "read failure, make a real edit"
+  skillOverheadTokens: 1500, // SKILL.md + one reference file, paid once per session not per iteration
+};
+
+/**
+ * @param {object} opts
+ * @param {number} opts.maxIterations — from the spec's Termination section
+ * @param {number} [opts.specTokens]
+ * @param {number} [opts.verifierOutputTokens]
+ * @param {number} [opts.agentEditTokensPerIteration]
+ * @param {number} [opts.skillOverheadTokens]
+ */
+export function estimateCost(opts) {
+  const {
+    maxIterations,
+    specTokens = DEFAULTS.specTokens,
+    verifierOutputTokens = DEFAULTS.verifierOutputTokens,
+    agentEditTokensPerIteration = DEFAULTS.agentEditTokensPerIteration,
+    skillOverheadTokens = DEFAULTS.skillOverheadTokens,
+  } = opts;
+
+  if (!maxIterations || maxIterations < 1) {
+    throw new Error("maxIterations must be a positive integer (read it from the spec's Termination section)");
+  }
+
+  const perIteration = specTokens + verifierOutputTokens + agentEditTokensPerIteration;
+  // Best case: succeeds on iteration 1. Worst case: runs the full cap.
+  const lowEstimate = skillOverheadTokens + perIteration * 1;
+  const highEstimate = skillOverheadTokens + perIteration * maxIterations;
+
+  return {
+    maxIterations,
+    perIterationTokens: perIteration,
+    lowEstimateTokens: lowEstimate,
+    highEstimateTokens: highEstimate,
+    assumptions: {
+      specTokens,
+      verifierOutputTokens,
+      agentEditTokensPerIteration,
+      skillOverheadTokens,
+    },
+    note: "Rough range, not a prediction. agentEditTokensPerIteration is the dominant and most variable term — override it with --edit-tokens if you have a sense of how big the actual changes will be.",
+  };
+}
+
+export function extractMaxIterationsFromSpec(specContent) {
+  const re = /(?:^|\n)##\s+Termination\s*\n([\s\S]*?)(?=\n##\s+|$)/;
+  const m = specContent.match(re);
+  if (!m) return null;
+  const numMatch = m[1].match(/max\s+iterations?\s*:?\s*(\d+)/i);
+  return numMatch ? parseInt(numMatch[1], 10) : null;
+}

package/src/lib/detect.mjs

@@ -0,0 +1,108 @@
+// detect.mjs — detects which AI coding tool directories exist in a project,
+// and maps each supported tool to where this skill should be installed for it.
+//
+// Detection is presence-based (does the tool's config dir/file already exist?),
+// not capability-based — we don't probe whether the tool is actually installed
+// on the machine, just whether the project has already been touched by it.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// Each entry: id, human label, a "signal" path (relative to project root) that indicates
+// the tool is already in use in this project, and the install path(s) for the skill.
+export const TOOLS = {
+  "claude-code": {
+    label: "Claude Code",
+    signal: (root) => join(root, ".claude"),
+    installPaths: (root) => [join(root, ".claude", "skills", "loop-engineering")],
+  },
+  codex: {
+    label: "Codex",
+    // .agents/skills is the specific convention (bare .agents/ is too generic a dirname
+    // to safely infer Codex usage from).
+    signal: (root) => join(root, ".agents", "skills"),
+    installPaths: (root) => [
+      join(root, ".agents", "skills", "loop-engineering"),
+      join(homedir(), ".codex", "skills", "loop-engineering"),
+    ],
+  },
+  windsurf: {
+    label: "Windsurf",
+    signal: (root) => join(root, ".windsurf"),
+    installPaths: (root) => [join(root, ".windsurf", "skills", "loop-engineering")],
+  },
+  antigravity: {
+    label: "Antigravity",
+    // No reliable per-PROJECT signal exists for Antigravity — its skills dir is global
+    // (~/.gemini/antigravity), so "does it exist" tells us about the machine, not this
+    // project, and would false-positive for any project once Antigravity has been used
+    // anywhere. Excluded from auto-detection; only included via explicit --tool or --all.
+    signal: () => null,
+    installPaths: () => [join(homedir(), ".gemini", "antigravity", "skills", "loop-engineering")],
+  },
+  cursor: {
+    label: "Cursor",
+    signal: (root) => join(root, ".cursor"),
+    installPaths: (root) => [
+      // Cursor has no skills mechanism — command + a script copy live separately.
+      { kind: "cursor-command", path: join(root, ".cursor", "commands", "loop.md") },
+      { kind: "cursor-scripts", path: join(root, ".loop", "scripts") },
+    ],
+  },
+  kiro: {
+    label: "Kiro",
+    signal: (root) => join(root, ".kiro"),
+    installPaths: (root) => [
+      // Kiro uses "Steering" files — individual markdown files in .kiro/steering/.
+      { kind: "kiro-steering", path: join(root, ".kiro", "steering", "loop-engineering.md") },
+      { kind: "kiro-scripts", path: join(root, ".loop", "scripts") },
+    ],
+  },
+  trae: {
+    label: "Trae",
+    signal: (root) => join(root, ".trae"),
+    installPaths: (root) => [
+      // Trae uses "Rules" — individual markdown files in .trae/rules/.
+      { kind: "trae-rule", path: join(root, ".trae", "rules", "loop-engineering.md") },
+      { kind: "trae-scripts", path: join(root, ".loop", "scripts") },
+    ],
+  },
+  opencode: {
+    label: "OpenCode",
+    signal: (root) => join(root, ".opencode"),
+    installPaths: (root) => [
+      join(root, ".opencode", "skills", "loop-engineering"),
+      join(homedir(), ".config", "opencode", "skills", "loop-engineering"),
+    ],
+  },
+  rovodev: {
+    label: "Rovodev",
+    signal: (root) => join(root, ".rovodev"),
+    installPaths: (root) => [
+      join(root, ".rovodev", "skills", "loop-engineering"),
+      join(homedir(), ".rovodev", "skills", "loop-engineering"),
+    ],
+  },
+  qoder: {
+    label: "Qoder",
+    signal: (root) => join(root, ".qoder"),
+    installPaths: (root) => [
+      join(root, ".qoder", "skills", "loop-engineering"),
+      join(homedir(), ".qoder", "skills", "loop-engineering"),
+    ],
+  },
+};
+
+export function detectTools(root) {
+  const detected = [];
+  for (const [id, tool] of Object.entries(TOOLS)) {
+    const signalPath = tool.signal(root);
+    if (signalPath && existsSync(signalPath)) detected.push(id);
+  }
+  return detected;
+}
+
+export function allToolIds() {
+  return Object.keys(TOOLS);
+}

package/src/lib/install.mjs

@@ -0,0 +1,112 @@
+// install.mjs — copies the skill payload to wherever a given tool expects it.
+
+import { existsSync, mkdirSync, cpSync, copyFileSync, chmodSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TOOLS } from "./detect.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// This file lives at <package>/src/lib/install.mjs — the skill payload is at <package>/skill.
+const SKILL_SRC = join(__dirname, "..", "..", "skill");
+
+function copySkillDir(destDir) {
+  if (existsSync(destDir)) {
+    return { installed: false, path: destDir, reason: "already exists" };
+  }
+  mkdirSync(dirname(destDir), { recursive: true });
+  cpSync(SKILL_SRC, destDir, { recursive: true });
+  const scriptsDir = join(destDir, "scripts");
+  if (existsSync(scriptsDir)) {
+    for (const f of readdirSync(scriptsDir)) {
+      if (f.endsWith(".mjs")) chmodSync(join(scriptsDir, f), 0o755);
+    }
+  }
+  return { installed: true, path: destDir };
+}
+
+function installScriptsOnly(destDir) {
+  if (existsSync(destDir)) {
+    return { installed: false, path: destDir, reason: "already exists" };
+  }
+  mkdirSync(destDir, { recursive: true });
+  for (const f of readdirSync(join(SKILL_SRC, "scripts"))) {
+    copyFileSync(join(SKILL_SRC, "scripts", f), join(destDir, f));
+    chmodSync(join(destDir, f), 0o755);
+  }
+  return { installed: true, path: destDir };
+}
+
+function installSingleFile(srcFile, destFile) {
+  if (existsSync(destFile)) {
+    return { installed: false, path: destFile, reason: "already exists" };
+  }
+  mkdirSync(dirname(destFile), { recursive: true });
+  copyFileSync(srcFile, destFile);
+  return { installed: true, path: destFile };
+}
+
+function installKiro(root) {
+  const steeringFile = join(root, ".kiro", "steering", "loop-engineering.md");
+  const scriptsDir = join(root, ".loop", "scripts");
+  return [
+    installSingleFile(join(SKILL_SRC, "SKILL.md"), steeringFile),
+    installScriptsOnly(scriptsDir),
+  ];
+}
+
+function installTrae(root) {
+  const ruleFile = join(root, ".trae", "rules", "loop-engineering.md");
+  const scriptsDir = join(root, ".loop", "scripts");
+  return [
+    installSingleFile(join(SKILL_SRC, "SKILL.md"), ruleFile),
+    installScriptsOnly(scriptsDir),
+  ];
+}
+
+function installCursor(root) {
+  const results = [];
+  const commandPath = join(root, ".cursor", "commands", "loop.md");
+  const cursorSrcCommand = join(__dirname, "..", "..", "patterns", "cursor-loop.md");
+  if (existsSync(commandPath)) {
+    results.push({ installed: false, path: commandPath, reason: "already exists" });
+  } else {
+    mkdirSync(dirname(commandPath), { recursive: true });
+    copyFileSync(cursorSrcCommand, commandPath);
+    results.push({ installed: true, path: commandPath });
+  }
+
+  const scriptsDestDir = join(root, ".loop", "scripts");
+  if (existsSync(scriptsDestDir)) {
+    results.push({ installed: false, path: scriptsDestDir, reason: "already exists" });
+  } else {
+    mkdirSync(scriptsDestDir, { recursive: true });
+    for (const f of readdirSync(join(SKILL_SRC, "scripts"))) {
+      copyFileSync(join(SKILL_SRC, "scripts", f), join(scriptsDestDir, f));
+      chmodSync(join(scriptsDestDir, f), 0o755);
+    }
+    results.push({ installed: true, path: scriptsDestDir });
+  }
+  return results;
+}
+
+/**
+ * Install the skill for a single tool id. Returns an array of result objects
+ * ({ installed, path, reason? }) — most tools produce one, cursor produces two.
+ */
+export function installTool(toolId, root) {
+  if (toolId === "cursor") return installCursor(root);
+  if (toolId === "kiro") return installKiro(root);
+  if (toolId === "trae") return installTrae(root);
+  const tool = TOOLS[toolId];
+  if (!tool) throw new Error(`Unknown tool: ${toolId}`);
+  const paths = tool.installPaths(root);
+  return paths.map((p) => copySkillDir(p));
+}
+
+export function installTools(toolIds, root) {
+  const report = {};
+  for (const id of toolIds) {
+    report[id] = installTool(id, root);
+  }
+  return report;
+}