loop-engineering 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rithvik Shetty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# loop-engineering
+
+Turn a goal description into a loop-ready spec, install it into your AI coding tool, then verify, run, audit, and cost-estimate the loop — all from one CLI.
+
+```bash
+npx loop-engineering install
+```
+
+No goal description converts cleanly into something an autonomous agent loop can terminate correctly on its own. "Make it look good" has no pass/fail check; a loop built on it either declares false victory or never stops. This package gives your agent a skill that refuses to start looping until the goal has five real things: a concrete end state, a verification command, termination conditions (success + cap + no-progress exit), scope, and an escalation path — then gives you a small CLI to check, run, score, and estimate that loop mechanically, without trusting the agent's own promise to behave.
+
+## Install the skill into your tool
+
+```bash
+npx loop-engineering install                  # auto-detects what's in your project, installs there
+npx loop-engineering install --tool all        # installs for every supported tool
+npx loop-engineering install --tool cursor      # installs for one specific tool
+```
+
+Supported tools:
+
+| Tool | Install path | Detection signal |
+|---|---|---|
+| Claude Code | `.claude/skills/loop-engineering/` | `.claude/` exists |
+| Codex | `.agents/skills/loop-engineering/` + `~/.codex/skills/…` | `.agents/skills/` exists |
+| Windsurf | `.windsurf/skills/loop-engineering/` | `.windsurf/` exists |
+| Cursor | `.cursor/commands/loop.md` + `.loop/scripts/` | `.cursor/` exists |
+| Kiro | `.kiro/steering/loop-engineering.md` + `.loop/scripts/` | `.kiro/` exists |
+| Trae | `.trae/rules/loop-engineering.md` + `.loop/scripts/` | `.trae/` exists |
+| OpenCode | `.opencode/skills/loop-engineering/` + `~/.config/opencode/skills/…` | `.opencode/` exists |
+| Rovodev | `.rovodev/skills/loop-engineering/` + `~/.rovodev/skills/…` | `.rovodev/` exists |
+| Qoder | `.qoder/skills/loop-engineering/` + `~/.qoder/skills/…` | `.qoder/` exists |
+| Antigravity | `~/.gemini/antigravity/skills/loop-engineering/` (global only) | `--tool antigravity` |
+
+Auto-detection is presence-based — if the tool's config directory exists in your project, it's detected. Antigravity is global-only so it's never auto-detected; use `--tool antigravity` or `--tool all` explicitly.
+
+Once installed, ask your agent (inside Claude Code, Cursor, Kiro, etc.) to build a loop spec for your goal — it loads the skill and interviews you for whatever's missing. Authoring the spec (`new`/`harden`) happens inside the agent conversation, not on this CLI; the CLI handles everything mechanical around it.
+
+## CLI commands
+
+```bash
+npx loop-engineering verify [path]    # checks LOOP_SPEC.md has all 5 required sections, non-placeholder
+npx loop-engineering run [path]       # runs one verification pass, tracks iteration + no-progress state
+npx loop-engineering status [path]    # reads iteration history, no execution
+npx loop-engineering audit            # scores a project's loop-readiness 0-100
+npx loop-engineering cost [path]      # rough token cost estimate before committing to a run
+```
+
+### `verify`
+
+Exits 0 if `LOOP_SPEC.md` has a real Goal, a runnable Verification command (or an explicitly-flagged LLM-judge fallback), all three Termination conditions (success / max-iterations / no-progress), a Scope with at least one forbidden action, and an Escalation behavior. Exits 1 with an itemized list otherwise — no partial credit for "looks complete."
+
+### `run`
+
+Runs the spec's verification command once, hashes both its output and the working tree (so two failures that print an identical generic error but came from genuinely different code states aren't wrongly flagged as stuck), and reports `success`, `continue`, or `stop-escalate`. State persists to `.loop/state.json` so the iteration count survives across turns — the calling agent can't lose count or talk itself past the cap.
+
+### `audit`
+
+```
+Loop Readiness Score: 70/100
+
+  ✓ LOOP_SPEC.md exists: 20/20
+  ✓ Spec passes lint: 30/30 — PASS
+  ✗ Run history exists: 0/15 — no .loop/state.json
+  ✗ Last run resolved cleanly: 0/15 — no run history
+  ✓ Skill installed for at least one tool: 10/10 — claude-code
+  ✓ Project is a git repo: 10/10 — git detected — reliable no-progress signal
+```
+
+Add `--badge` to print a shields.io badge for your README.
+
+### `cost`
+
+```
+Estimated token cost for up to 6 iterations:
+  Best case (succeeds iteration 1):  ~4,200 tokens
+  Worst case (runs full cap):         ~17,700 tokens
+  Per-iteration:                      ~2,700 tokens
+```
+
+A rough range, not a prediction — override the dominant term with `--edit-tokens N` if you have a sense of how big the actual code changes will be. The point is catching "this will burn through a plan before lunch" before it happens, not billing precisely.
+
+## The spec format
+
+```markdown
+# Loop: <name>
+
+## Goal
+<concrete, observable end state — not an adjective>
+
+## Verification
+```
+<exact command that returns pass/fail>
+```
+
+## Termination
+- Success: verification exits 0
+- Max iterations: <N>
+- No-progress: stop if 2 consecutive iterations produce identical result + unchanged tree
+- Budget: <optional>
+
+## Scope
+- Allowed: <paths/stack>
+- Forbidden: <at least one explicit thing>
+
+## Escalation
+On cap or no-progress: stop, summarize attempts, wait for human review.
+```
+
+## Why a script, not just instructions
+
+Most loop-engineering failures are goal-description failures, not model failures. `skill/scripts/lint_spec.mjs` is the actual gate — it parses the file and checks each section against specific criteria (not "does this look done"). `skill/scripts/run_loop.mjs` is the actual executor — it enforces the cap and no-progress exit itself rather than asking the agent to count correctly. Both are plain Node scripts with no dependencies, auditable in under 200 lines each.
+
+## License
+
+MIT

package/bin/loop-engineering.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+// bin/loop-engineering.mjs — CLI entry point.
+//
+// Subcommands:
+//   install [--tool <id>|all] [--target <path>]
+//   verify  [path]
+//   run     [path]
+//   status  [path]
+//   audit   [--target <path>]
+//   cost    [path] [--edit-tokens N] [--verify-tokens N] [--max-iterations N]
+//
+// Deliberately dependency-free (no commander/yargs): the command surface is small enough
+// that hand-rolled parsing is more auditable than pulling in a flag-parsing dependency for
+// a tool whose whole pitch is "minimal, mechanical, no magic."
+
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+
+import { detectTools, allToolIds, TOOLS } from "../src/lib/detect.mjs";
+import { installTools } from "../src/lib/install.mjs";
+import { auditProject } from "../src/lib/audit.mjs";
+import { estimateCost, extractMaxIterationsFromSpec } from "../src/lib/cost.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILL_SCRIPTS_DIR = join(__dirname, "..", "skill", "scripts");
+const LINT_SCRIPT = join(SKILL_SCRIPTS_DIR, "lint_spec.mjs");
+const RUN_SCRIPT = join(SKILL_SCRIPTS_DIR, "run_loop.mjs");
+
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+function cmdInstall(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const target = resolve(flags.target || process.cwd());
+  let toolIds;
+
+  if (flags.tool === "all" || (!flags.tool && positional.length === 0)) {
+    const detected = detectTools(target);
+    toolIds = detected.length > 0 ? detected : allToolIds();
+    console.log(
+      detected.length > 0
+        ? `Detected: ${detected.join(", ")}. Installing for detected tools only. Use --tool all to install everywhere.`
+        : `No tool config detected in ${target}. Installing for all supported tools as a safe default.`
+    );
+  } else if (flags.tool) {
+    toolIds = [flags.tool];
+  } else {
+    toolIds = positional; // allow: loop-engineering install claude-code cursor
+  }
+
+  const unknown = toolIds.filter((id) => !allToolIds().includes(id));
+  if (unknown.length > 0) {
+    console.error(`Unknown tool id(s): ${unknown.join(", ")}. Valid: ${allToolIds().join(", ")}`);
+    process.exit(1);
+  }
+
+  const report = installTools(toolIds, target);
+  for (const [id, results] of Object.entries(report)) {
+    const label = TOOLS[id].label;
+    for (const r of results) {
+      const status = r.installed ? "installed" : `skipped (${r.reason})`;
+      console.log(`[${label}] ${status}: ${r.path}`);
+    }
+  }
+  console.log("\nDone. Restart your tool / start a new session to load the skill.");
+}
+
+function resolveSpecPath(positional) {
+  return resolve(positional[0] || "LOOP_SPEC.md");
+}
+
+function cmdVerify(argv) {
+  const { positional } = parseFlags(argv);
+  const specPath = resolveSpecPath(positional);
+  try {
+    execFileSync("node", [LINT_SCRIPT, specPath], { stdio: "inherit" });
+    process.exit(0);
+  } catch (err) {
+    process.exit(err.status ?? 1);
+  }
+}
+
+function cmdRun(argv) {
+  const { positional } = parseFlags(argv);
+  const specPath = resolveSpecPath(positional);
+  try {
+    execFileSync("node", [RUN_SCRIPT, "check", specPath], { stdio: "inherit" });
+    process.exit(0);
+  } catch (err) {
+    process.exit(err.status ?? 1);
+  }
+}
+
+function cmdStatus(argv) {
+  const { positional } = parseFlags(argv);
+  const specPath = resolveSpecPath(positional);
+  try {
+    execFileSync("node", [RUN_SCRIPT, "status", specPath], { stdio: "inherit" });
+  } catch (err) {
+    process.exit(err.status ?? 1);
+  }
+}
+
+function cmdAudit(argv) {
+  const { flags } = parseFlags(argv);
+  const target = resolve(flags.target || process.cwd());
+  const result = auditProject(target, LINT_SCRIPT);
+  console.log(`Loop Readiness Score: ${result.score}/${result.max}\n`);
+  for (const check of result.checks) {
+    const mark = check.points === check.max ? "✓" : check.points > 0 ? "~" : "✗";
+    console.log(`  ${mark} ${check.label}: ${check.points}/${check.max}${check.detail ? ` — ${check.detail}` : ""}`);
+  }
+  if (flags.badge) {
+    const color = result.score >= 80 ? "brightgreen" : result.score >= 50 ? "yellow" : "red";
+    const url = `https://img.shields.io/badge/Loop%20Readiness-${result.score}%2F100-${color}`;
+    console.log(`\nBadge markdown:\n![Loop Readiness](${url})`);
+  }
+}
+
+function cmdCost(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const specPath = resolveSpecPath(positional);
+  let maxIterations = flags["max-iterations"] ? parseInt(flags["max-iterations"], 10) : null;
+
+  if (!maxIterations) {
+    if (!existsSync(specPath)) {
+      console.error(`${specPath} not found, and no --max-iterations given. Either point at a spec or pass --max-iterations N.`);
+      process.exit(1);
+    }
+    const content = readFileSync(specPath, "utf-8");
+    maxIterations = extractMaxIterationsFromSpec(content);
+    if (!maxIterations) {
+      console.error(`Could not find "Max iterations: N" in ${specPath}'s Termination section. Pass --max-iterations N explicitly.`);
+      process.exit(1);
+    }
+  }
+
+  const opts = { maxIterations };
+  if (flags["edit-tokens"]) opts.agentEditTokensPerIteration = parseInt(flags["edit-tokens"], 10);
+  if (flags["verify-tokens"]) opts.verifierOutputTokens = parseInt(flags["verify-tokens"], 10);
+
+  const result = estimateCost(opts);
+  console.log(`Estimated token cost for up to ${result.maxIterations} iterations:`);
+  console.log(`  Best case (succeeds iteration 1):  ~${result.lowEstimateTokens.toLocaleString()} tokens`);
+  console.log(`  Worst case (runs full cap):         ~${result.highEstimateTokens.toLocaleString()} tokens`);
+  console.log(`  Per-iteration:                      ~${result.perIterationTokens.toLocaleString()} tokens`);
+  console.log(`\nAssumptions (override with --edit-tokens / --verify-tokens):`);
+  console.log(`  ${JSON.stringify(result.assumptions)}`);
+  console.log(`\n${result.note}`);
+}
+
+function printHelp() {
+  console.log(`loop-engineering — turn a goal description into a loop-ready spec, then run it.
+
+Usage:
+  npx loop-engineering install [--tool <id>|all] [--target <path>]
+  npx loop-engineering verify  [path]                 (default path: ./LOOP_SPEC.md)
+  npx loop-engineering run     [path]
+  npx loop-engineering status  [path]
+  npx loop-engineering audit   [--target <path>] [--badge]
+  npx loop-engineering cost    [path] [--max-iterations N] [--edit-tokens N] [--verify-tokens N]
+
+Tool ids for install: ${allToolIds().join(", ")}, or "all"
+
+Writing the spec itself (the "new" and "harden" workflows) happens inside your AI coding
+tool, not on this CLI — install the skill, then ask your agent to author or fix a spec.
+This CLI handles the mechanical parts: installing, linting, running, scoring, estimating.
+`);
+}
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  switch (command) {
+    case "install":
+      cmdInstall(rest);
+      break;
+    case "verify":
+      cmdVerify(rest);
+      break;
+    case "run":
+      cmdRun(rest);
+      break;
+    case "status":
+      cmdStatus(rest);
+      break;
+    case "audit":
+      cmdAudit(rest);
+      break;
+    case "cost":
+      cmdCost(rest);
+      break;
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      break;
+    default:
+      console.error(`Unknown command: ${command}\n`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "loop-engineering",
+  "version": "1.0.0",
+  "description": "Turn a goal description into a loop-ready spec, install it into Claude Code, Codex, Windsurf, Cursor, Kiro, Trae, OpenCode, Rovodev, Qoder, or Antigravity, then verify, run, audit, and cost-estimate the loop.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Rithvik Shetty",
+  "keywords": [
+    "loop-engineering",
+    "ai-agents",
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "antigravity",
+    "kiro",
+    "trae",
+    "opencode",
+    "rovodev",
+    "qoder",
+    "skill",
+    "agentic"
+  ],
+  "bin": {
+    "loop-engineering": "bin/loop-engineering.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill",
+    "patterns",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "build": "node scripts/build.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/<your-username>/loop-engineering.git"
+  },
+  "homepage": "https://github.com/<your-username>/loop-engineering#readme",
+  "bugs": {
+    "url": "https://github.com/<your-username>/loop-engineering/issues"
+  }
+}

package/patterns/cursor-loop.md

@@ -0,0 +1,57 @@
+Act as a loop-engineering specialist. The user is invoking `/loop`, optionally followed by a sub-command and an argument: `/loop <new|harden|verify|run|status> [goal description or path]`.
+
+This command does NOT build the feature directly. It authors/checks/runs a **loop spec** — a goal description hardened into something an autonomous agent loop can act on without a human re-prompting every turn.
+
+## The hard rule
+
+A spec is never "loop-ready" because it reads complete. It is loop-ready when `node .loop/scripts/lint_spec.mjs LOOP_SPEC.md` exits 0 (this repo's installer places the scripts at `.loop/scripts/` specifically because Cursor has no native skills folder — if that path doesn't exist, check whether `.claude/skills/loop-engineering/scripts/`, `.agents/skills/loop-engineering/scripts/`, or `.windsurf/skills/loop-engineering/scripts/` exists instead, from another tool's install). Do not eyeball a spec and call it done. Run the script.
+
+Iteration counts, the no-progress check, and the cap are tracked by `.loop/scripts/run_loop.mjs`, not by you counting in your head. It persists state to `.loop/state.json` so the count can't be lost or argued past.
+
+## Routing
+
+- **`new <goal>`** (or any goal description with no existing `LOOP_SPEC.md`): interview for Goal precision and a real Verification command — don't accept vague adjectives like "better" or "cleaner" without converting them to an observable, checkable end state. Default Termination (max iterations 8–10, no-progress = 2 identical consecutive results), Scope (ask for at least one forbidden action), and Escalation (stop + summarize + wait for human) unless told otherwise. Write `LOOP_SPEC.md` with sections `## Goal`, `## Verification`, `## Termination`, `## Scope`, `## Escalation`. Run the lint script immediately after writing it; fix what it flags; re-run until it exits 0.
+
+- **`harden [path]`**: run the lint script first, always — don't guess what's wrong by reading the file. Fix exactly what it reports, in the order reported. Re-run until clean. Report before/after issue list.
+
+- **`verify [path]`**: run the lint script only. Report exit 0 (ready) or the itemized issue list verbatim. Do not execute the verification command itself or modify the file — that's `run` and `harden` respectively.
+
+- **`run [path]`**: precondition — must pass `verify` first. Loop: call `node .loop/scripts/run_loop.mjs check <path>`, read the JSON `status` field. `"success"` → stop, report. `"continue"` → make a real code change closing the gap described in the failure, then check again. `"stop-escalate"` → stop immediately, report the reason and history verbatim, wait for the user — never bypass the script by running the verification command directly to "see if it would have passed."
+
+- **`status [path]`**: run `node .loop/scripts/run_loop.mjs status <path>`, report iteration history read-only. No execution, no file changes.
+
+## Absolute bans
+
+- Never mark a spec ready without running the lint script.
+- Never mark a loop iteration "success" without the literal exit code being 0.
+- Never silently exceed the stated iteration cap, and never re-run the verifier manually outside `run_loop.mjs` to dodge a `stop-escalate` verdict.
+- Never write a Scope section with zero forbidden actions.
+- Never present LLM-as-judge verification as equivalent to a deterministic check — flag it as the weakest link every time it's used.
+- Never accept a goal phrased only as a vague adjective without converting it to an observable end state first.
+
+## Spec shape (for `new`/`harden` to produce)
+
+```markdown
+# Loop: <name>
+
+## Goal
+<concrete, observable end state>
+
+## Verification
+```
+<exact command>
+```
+
+## Termination
+- Success: ...
+- Max iterations: ...
+- No-progress: ...
+- Budget: ...
+
+## Scope
+- Allowed: ...
+- Forbidden: ...
+
+## Escalation
+...
+```

package/skill/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: loop-engineering
+description: Turn a goal description into a loop spec an AI agent can iterate against autonomously, then optionally run that loop with enforced caps. Use when the user invokes /loop or any sub-command (new, harden, verify, run, status), asks to "build until done" or "iterate until X passes," describes a goal they want an agent to work toward without manual re-prompting each turn, or asks for a spec/PRD meant to drive an autonomous coding agent (Claude Code, Codex, Cursor, Windsurf, Antigravity). Also trigger when a goal description is vague, untestable, or missing a stop condition — hardening weak goal descriptions into loop-ready specs is this skill's primary job, and it refuses to hand a vague goal to an agent loop without fixing it first.
+version: 1.1.0
+user-invocable: true
+argument-hint: "[new|harden|verify|run|status] [goal description or path to LOOP_SPEC.md]"
+license: MIT
+---
+
+# Loop Engineering
+
+Converts a goal description into a **loop spec**: Goal, Verification, Termination, Scope, Escalation. Then, optionally, runs the loop — act, verify, decide continue/stop — with caps enforced by a script, not by the agent's own promise to behave.
+
+## Why this exists
+
+Old model: human types a prompt, agent responds, human reads and re-prompts. Human is the loop.
+
+Loop engineering: human writes the goal once; a system prompts the agent, checks the result, and decides whether to continue — without the human in the cycle. The loop's quality is bottlenecked entirely on the goal description. A vague goal makes a loop that either declares false victory or never stops.
+
+**Most "loop engineering" failures are goal-description failures, not model failures.** This skill's job is to catch that before iteration 1, and to make the cap/no-progress/escalation logic mechanical rather than a promise the agent makes to itself.
+
+## Setup (run before any sub-command)
+
+1. **Resolve the scripts directory once per session.** The two scripts this skill depends on (`lint_spec.mjs`, `run_loop.mjs`) live alongside this SKILL.md, but their absolute path depends on which tool installed them. Check, in order, and use the first that exists: `.claude/skills/loop-engineering/scripts/`, `.agents/skills/loop-engineering/scripts/`, `.windsurf/skills/loop-engineering/scripts/`, `.opencode/skills/loop-engineering/scripts/`, `.rovodev/skills/loop-engineering/scripts/`, `.qoder/skills/loop-engineering/scripts/`, `.loop/scripts/` (Cursor, Kiro, and Trae install scripts here), `~/.codex/skills/loop-engineering/scripts/`, `~/.gemini/antigravity/skills/loop-engineering/scripts/`, `~/.config/opencode/skills/loop-engineering/scripts/`, `~/.rovodev/skills/loop-engineering/scripts/`, `~/.qoder/skills/loop-engineering/scripts/`. Every reference file in this skill writes commands as `node <skill-dir>/scripts/lint_spec.mjs` — substitute the real resolved path for `<skill-dir>/scripts/`, don't run `node scripts/...` relative to an assumed cwd.
+2. Check whether `LOOP_SPEC.md` (or a user-specified spec path) exists in the working directory. Also check whether `LOOP_CONTEXT.md` exists — if it does, read it now; it contains standing project conventions (test command, forbidden paths) that pre-fill defaults for `new` and `harden`.
+3. If a sub-command was given (`init`, `new`, `harden`, `verify`, `run`, `status`), read `reference/<command>.md` next — non-optional, it defines that command's exact flow.
+4. Never skip the linter. The lint script is the actual gate, not a suggestion — see "The hard rule" below.
+
+## The hard rule
+
+**A spec is never "loop-ready" because the agent says so. It is loop-ready when `node <skill-dir>/scripts/lint_spec.mjs <path>` exits 0.** Do not eyeball a spec and decide it looks fine. Do not skip the lint step because the spec "seems complete." Run the script, read its actual output, fix exactly what it flags. This is the difference between a skill that's foolproof and one that's just well-written prose — prose can be rationalized past; a non-zero exit code cannot.
+
+Same for running a loop: **iteration counts, the no-progress check, and the cap are tracked by `<skill-dir>/scripts/run_loop.mjs`, not by the agent counting in its head.** The script persists state to `.loop/state.json` specifically so a model can't lose count, restart the count by accident, or talk itself into "just one more try" past the cap.
+
+## Commands
+
+| Command | Category | Description | Reference |
+|---|---|---|---|
+| `init` | Setup | Capture standing project conventions (test command, build command, forbidden paths) into `LOOP_CONTEXT.md` so future specs don't re-ask for them | [reference/init.md](reference/init.md) |
+| `new [goal]` | Build | Interview the user, author a fresh `LOOP_SPEC.md` from a goal description | [reference/new.md](reference/new.md) |
+| `harden [path]` | Build | Take an existing weak/incomplete spec and fix exactly what the linter flags | [reference/harden.md](reference/harden.md) |
+| `verify [path]` | Evaluate | Run the lint check only — confirm a spec is loop-ready without executing anything | [reference/verify.md](reference/verify.md) |
+| `run [path]` | Iterate | Actually execute the loop: verify, report, decide continue/stop/escalate, repeat | [reference/run.md](reference/run.md) |
+| `status [path]` | Evaluate | Read `.loop/state.json` and report iteration history without running anything | [reference/status.md](reference/status.md) |
+
+### Routing rules
+
+1. **No argument**: ask what goal they want to loop, or if a `LOOP_SPEC.md` already exists in the working directory, ask whether they want to `verify`, `run`, or `harden` it. Don't guess — a missing argument here means genuine ambiguity between "I have no spec yet" and "I have one, do something with it." If neither a spec nor a `LOOP_CONTEXT.md` exists and the user seems to be starting fresh in a project, suggest `init` first.
+2. **First word matches a command** (table above): load its reference file, treat everything after the command name as its argument, follow the reference's flow exactly.
+3. **First word doesn't match, but intent clearly maps to one command** (e.g. "is this spec actually ready?" → `verify`; "just start building and don't stop till tests pass" → `new` then `run`; "this spec sucks, fix it" → `harden`): load that reference and proceed as if invoked. If genuinely two could fit (e.g. they want both `new` and `run`), do `new` first, confirm the spec passes `verify`, then ask before `run`.
+4. **A goal description with no command word, and no existing spec in the working directory**: treat as `new`.
+5. **A goal description with no command word, and a spec already exists**: ask whether they mean to replace it (`new`) or check it (`verify`) — don't silently overwrite an existing spec.
+
+## Absolute bans
+
+Match-and-refuse. If you're about to do any of these, stop and do the alternative instead.
+
+- **Never mark a spec loop-ready without running `lint_spec.mjs`.** Reading it and thinking "looks complete" is not verification. Run the script.
+- **Never mark a loop iteration "success" without the verification command's actual exit code being 0.** Not "the code looks right," not "this should pass" — the literal exit code from `run_loop.mjs check`.
+- **Never silently exceed the stated iteration cap.** If `run_loop.mjs` reports `stop-escalate`, stop. Do not run "just one more" manually outside the script to see if it would have worked — that defeats the entire point of a mechanical cap.
+- **Never write a Scope section with no forbidden actions**, and never let a user's "just do whatever it takes" stand unchallenged — ask for at least one explicit boundary (untouched files, no force-push, no editing tests to force a pass).
+- **Never propose LLM-as-judge as the verification method without saying out loud that it's the weakest link.** It's sometimes the only option; it must never be presented as equivalent to a deterministic check.
+- **Never accept a goal phrased only as a vague adjective** ("better," "polished," "cleaner") without converting it to an observable end state during `new` or `harden`. That conversion is most of the actual work — see `reference/examples.md`.
+
+## Reference files
+
+- `reference/init.md` — interview flow for capturing project conventions into `LOOP_CONTEXT.md`
+- `reference/new.md` — interview flow for authoring a fresh spec
+- `reference/harden.md` — fixing an existing spec against linter output
+- `reference/verify.md` — running the lint check, reporting results
+- `reference/run.md` — executing the loop end-to-end, including how to act between iterations
+- `reference/status.md` — reading and reporting iteration history
+- `reference/ide-natives.md` — which native loop primitive to hand off to per IDE (Codex's `/goal`, Windsurf Workflows, etc.)
+- `reference/examples.md` — worked weak-goal → loop-ready-spec conversions
+
+## Scripts
+
+- `<skill-dir>/scripts/lint_spec.mjs` — the hard gate; validates a spec has all 5 sections, non-placeholder, with section-specific deep checks (verification has a real command or flags LLM-judge; termination has all three exits; scope names a forbidden action; escalation names a stop behavior)
+- `<skill-dir>/scripts/run_loop.mjs check|reset|status` — executes one verification pass, tracks iteration + no-progress state via a composite hash of (verifier output) + (working tree changes), enforces the cap, never trusts the calling agent's own iteration count

package/skill/reference/examples.md

@@ -0,0 +1,72 @@
+# Worked examples: weak goal → loop-ready spec
+
+The actual work of loop engineering is converting a subjective adjective into something `lint_spec.mjs` and `run_loop.mjs` can both act on mechanically. These are full conversions, both passing the linter.
+
+## Example 1 — UI build
+
+**Weak (fails `verify` immediately):**
+> "Build me a landing page that looks good and works well."
+
+Problems: no verifier, no termination, "looks good" is unjudgeable mechanically. `lint_spec.mjs` would report missing Verification command, missing Termination, missing Scope forbidden-action, missing Escalation.
+
+**Loop-ready (passes `verify`):**
+```markdown
+# Loop: landing page build
+
+## Goal
+Landing page at /index.html: hero, 3-feature grid, signup form. Mobile-responsive at 375px and 1440px widths.
+
+## Verification
+```
+npm run build && npm run lint && npx playwright test tests/landing.spec.ts
+```
+(visual check folded in: Lighthouse mobile score >= 90, captured via `npx lighthouse --output=json`)
+
+## Termination
+- Success: all commands above exit 0 AND Lighthouse score >= 90
+- Max iterations: 8
+- No-progress: stop if 2 consecutive iterations produce identical result + unchanged working tree
+- Budget: none
+
+## Scope
+- Allowed: /src, /tests, /public
+- Forbidden: do not edit playwright config to skip failing assertions; do not touch /api
+
+## Escalation
+On cap: write attempts.md summarizing each iteration's score + diff, stop, wait for human review.
+```
+
+## Example 2 — Bug fix / refactor
+
+**Weak:**
+> "Fix the flaky tests."
+
+**Loop-ready:**
+```markdown
+# Loop: stabilize integration tests
+
+## Goal
+All tests in /tests/integration pass on 5 consecutive runs (currently ~30% flake rate).
+
+## Verification
+```
+for i in 1 2 3 4 5; do npm test -- tests/integration || exit 1; done
+```
+
+## Termination
+- Success: loop above exits 0
+- Max iterations: 10
+- No-progress: stop if same test name fails with the same error message 2 iterations in a row with no code change
+- Budget: none
+
+## Scope
+- Allowed: /src, /tests/integration
+- Forbidden: do not increase timeouts as the only fix; do not mark tests as skip/pending to "pass"
+
+## Escalation
+On cap: report which test(s) still flake + last 3 stack traces, stop.
+```
+
+## Pattern to notice
+
+Both conversions turn a subjective adjective ("looks good," "flaky tests") into something a shell command returns pass/fail on. If you can't find a command that returns pass/fail, you're stuck with LLM-as-judge — say so explicitly in the Verification section rather than hiding it, and expect `lint_spec.mjs` to accept it only because it was named, not because it's as trustworthy as a real test command.

package/skill/reference/harden.md

@@ -0,0 +1,31 @@
+# `harden` — fix an existing weak spec
+
+Triggered by: `/loop harden [path]`, or "this spec isn't good enough" / "fix my loop spec" / intent that clearly means improving an existing spec rather than writing one.
+
+## Flow
+
+1. **Run the linter first, always.** Do not read the spec and guess what's wrong — run it:
+
+```bash
+node <skill-dir>/scripts/lint_spec.mjs LOOP_SPEC.md
+```
+
+(or whatever path the user gave). This produces a specific, itemized list of what's missing or weak. That list is your TODO list — not your own read of the document.
+
+2. **Fix exactly what's flagged, in the order reported.** Common fixes:
+   - Missing section header → add it with real content, not a placeholder.
+   - Placeholder text still present (`<...>`, `TBD`, `...`) → replace with the actual concrete answer; ask the user if you don't know it.
+   - Verification has no command and doesn't flag LLM-judge → either find the actual test/build/lint command for this project (check `package.json` scripts, a Makefile, CI config) or explicitly write the LLM-judge rubric and flag it as the weakest link.
+   - Termination missing success/cap/no-progress → add whichever is missing; don't just add a stub, make it match the actual goal (e.g. cap of 3 for a destructive task, not the generic default of 8).
+   - Scope has no forbidden action → ask the user for at least one real boundary; don't invent a generic one if you can ask.
+   - Escalation doesn't describe a stop behavior → default to "stop, summarize, wait for human" unless told otherwise.
+
+3. **Re-run the linter after every fix pass.** Don't fix all 5 issues blind and assume it's clean — re-run:
+
+```bash
+node <skill-dir>/scripts/lint_spec.mjs LOOP_SPEC.md
+```
+
+Iterate until it exits 0. Report the before/after issue list to the user so they can see what changed.
+
+4. If the user provided a goal description instead of a path (no existing file), this is actually a `new` request — load `reference/new.md` instead.