agent-harness-kit 0.3.0

package/src/core/upgrade.mjs

@@ -0,0 +1,274 @@
+// upgrade.mjs — non-destructive version-aware upgrade.
+//
+// Strategy:
+//   1. Read .harness/installed.json (lockfile of last-installed sha per file).
+//   2. For each kit-managed file: if the user has not modified it (sha matches),
+//      overwrite. If modified, drop a sibling `.harness-new` so the user can diff.
+//   3. Never touch USER_OWNED_FILES (CLAUDE.md, docs/architecture.md, etc.).
+//   4. Print a concise summary and update the lockfile.
+
+import { readFile, writeFile, mkdir, readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, join, relative, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { confirm } from "@inquirer/prompts";
+import pc from "picocolors";
+import Handlebars from "handlebars";
+import { registerHelpers } from "./render-templates.mjs";
+import { detectStack } from "./detect-stack.mjs";
+
+// Sync the two version-pinned fields in harness.config.json after a kit
+// upgrade. Everything else in the config is user-owned and left untouched.
+// Uses regex on the raw text instead of JSON round-tripping so user
+// formatting (trailing zeros, key order, indentation, comments-as-strings)
+// survives. Exported for unit tests; called from `upgrade()` below.
+export async function syncHarnessConfigVersion(cwd, kitVersion) {
+  const cfgPath = resolve(cwd, "harness.config.json");
+  if (!existsSync(cfgPath)) return { changed: false, reason: "missing" };
+  const raw = await readFile(cfgPath, "utf8");
+  // Validate JSON first so we never write back a corrupted file.
+  let cfg;
+  try {
+    cfg = JSON.parse(raw);
+  } catch {
+    return { changed: false, reason: "invalid-json" };
+  }
+
+  let next = raw;
+  // Replace top-level "version": "<x.y.z>" — anchored at line start so we
+  // don't touch a "version" key nested inside another object.
+  if (typeof cfg.version === "string" && cfg.version !== kitVersion) {
+    next = next.replace(
+      /^(\s*"version"\s*:\s*")[^"]+(")/m,
+      `$1${kitVersion}$2`,
+    );
+  }
+  // Replace the kit's pinned $schema URL only — leaves user-forked URLs alone.
+  const schemaUrlRe =
+    /https:\/\/raw\.githubusercontent\.com\/tuanle96\/agent-harness-kit\/v[^/"]+\/schema\.json/;
+  if (typeof cfg.$schema === "string" && schemaUrlRe.test(cfg.$schema)) {
+    const newSchema = `https://raw.githubusercontent.com/tuanle96/agent-harness-kit/v${kitVersion}/schema.json`;
+    if (cfg.$schema !== newSchema) {
+      next = next.replace(schemaUrlRe, newSchema);
+    }
+  }
+
+  if (next === raw) {
+    return { changed: false, reason: "already-current" };
+  }
+  // Sanity-check: the regex replace must still produce valid JSON.
+  try {
+    JSON.parse(next);
+  } catch {
+    return { changed: false, reason: "would-corrupt" };
+  }
+  await writeFile(cfgPath, next);
+  return { changed: true, reason: "synced" };
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_ROOT = resolve(__dirname, "..", "templates");
+
+const USER_OWNED_FILES = new Set([
+  "CLAUDE.md",
+  "AGENTS.md",
+  "docs/architecture.md",
+  "docs/core-beliefs.md",
+  "docs/golden-principles.md",
+  "docs/tech-debt-tracker.md",
+  "feature_list.json",
+  "harness.config.json",
+]);
+
+function sha256(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+async function* walk(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      yield* walk(full);
+    } else {
+      yield full;
+    }
+  }
+}
+
+export async function upgrade({ cwd, kitVersion, yes }) {
+  const lockPath = resolve(cwd, ".harness/installed.json");
+  if (!existsSync(lockPath)) {
+    console.error(
+      pc.red(
+        `No .harness/installed.json found. Run \`agent-harness-kit init\` first.`,
+      ),
+    );
+    process.exit(1);
+  }
+  const lockfile = JSON.parse(await readFile(lockPath, "utf8"));
+  const previousVersion = lockfile.version;
+
+  if (previousVersion === kitVersion) {
+    // Lockfile already current — but harness.config.json may still carry an
+    // older `version`/`$schema` (it's user-owned and skipped by the file walk).
+    // Sync those two fields so doctor stops flagging drift.
+    const cfgSync = await syncHarnessConfigVersion(cwd, kitVersion);
+    if (cfgSync.changed) {
+      console.log(
+        pc.green(`harness.config.json version + $schema synced to v${kitVersion}.`),
+      );
+    } else {
+      console.log(pc.green(`Already on v${kitVersion}. Nothing to do.`));
+    }
+    return;
+  }
+
+  console.log(
+    pc.bold(
+      `\nUpgrading agent-harness-kit: ${pc.dim(previousVersion)} → ${pc.green(kitVersion)}\n`,
+    ),
+  );
+
+  const stack = await detectStack(cwd);
+  const ctx = {
+    projectName: "your-project",
+    layers: ["types", "config", "repo", "service", "runtime", "ui"],
+    layersJoined: "types → config → repo → service → runtime → ui",
+    language: stack.language,
+    framework: stack.framework,
+    packageManager: stack.packageManager,
+    isTypescript: stack.language === "typescript",
+    isPython: stack.language === "python",
+    isNextjs: stack.framework === "nextjs",
+    isFastapi: stack.framework === "fastapi",
+    kitVersion,
+  };
+
+  const updates = []; // { rel, action: 'overwrite'|'sidecar'|'skip', reason }
+
+  for await (const abs of walk(TEMPLATES_ROOT)) {
+    const relFromTemplates = relative(TEMPLATES_ROOT, abs).split("\\").join("/");
+    if (relFromTemplates.startsWith("_adapter-typescript/") && stack.language !== "typescript")
+      continue;
+    if (relFromTemplates.startsWith("_adapter-python/") && stack.language !== "python")
+      continue;
+    if (relFromTemplates.startsWith("_preset-nextjs/") && stack.framework !== "nextjs")
+      continue;
+    if (relFromTemplates.startsWith("_preset-fastapi/") && stack.framework !== "fastapi")
+      continue;
+    const stackRel = relFromTemplates
+      .replace(/^_adapter-typescript\//, "")
+      .replace(/^_adapter-python\//, "")
+      .replace(/^_preset-nextjs\//, "")
+      .replace(/^_preset-fastapi\//, "")
+      .replace(/^_ci\//, "");
+    const targetRel = stackRel.endsWith(".hbs")
+      ? stackRel.slice(0, -".hbs".length)
+      : stackRel;
+
+    if (USER_OWNED_FILES.has(targetRel)) {
+      updates.push({ rel: targetRel, action: "skip", reason: "user-owned" });
+      continue;
+    }
+
+    let newContent;
+    if (abs.endsWith(".hbs")) {
+      const raw = await readFile(abs, "utf8");
+      registerHelpers();
+      const tpl = Handlebars.compile(raw, { noEscape: true });
+      newContent = tpl(ctx);
+    } else {
+      newContent = await readFile(abs);
+    }
+
+    const newSha = sha256(
+      typeof newContent === "string" ? Buffer.from(newContent) : newContent,
+    );
+    const targetAbs = resolve(cwd, targetRel);
+    const previousSha = lockfile.files?.[targetRel];
+    const targetExists = existsSync(targetAbs);
+
+    if (!targetExists) {
+      updates.push({ rel: targetRel, action: "overwrite", reason: "new" });
+      continue;
+    }
+    const currentBuf = await readFile(targetAbs);
+    const currentSha = sha256(currentBuf);
+    if (currentSha === newSha) {
+      // Already on the new version — record the new sha but no action.
+      updates.push({ rel: targetRel, action: "skip", reason: "identical" });
+      continue;
+    }
+    if (currentSha === previousSha) {
+      updates.push({ rel: targetRel, action: "overwrite", reason: "user-untouched" });
+    } else {
+      updates.push({ rel: targetRel, action: "sidecar", reason: "user-modified" });
+    }
+  }
+
+  // Group + print summary.
+  const overwrites = updates.filter((u) => u.action === "overwrite");
+  const sidecars = updates.filter((u) => u.action === "sidecar");
+  for (const u of overwrites) console.log(`  ${pc.green("~")} ${u.rel}  ${pc.dim("(" + u.reason + ")")}`);
+  for (const u of sidecars)
+    console.log(
+      `  ${pc.yellow("!")} ${u.rel}  ${pc.dim("user-modified — writing " + u.rel + ".harness-new for you to diff")}`,
+    );
+
+  if (overwrites.length === 0 && sidecars.length === 0) {
+    console.log(pc.green(`No file changes needed. Bumping lockfile to v${kitVersion}.`));
+  } else if (!yes) {
+    const ok = await confirm({ message: "Apply the changes above?", default: true });
+    if (!ok) {
+      console.log(pc.yellow("upgrade aborted."));
+      return;
+    }
+  }
+
+  // Apply.
+  for (const u of [...overwrites, ...sidecars]) {
+    const sourceTplRel = u.rel; // simplified: regenerate
+    let abs = resolve(TEMPLATES_ROOT, sourceTplRel + ".hbs");
+    if (!existsSync(abs)) abs = resolve(TEMPLATES_ROOT, sourceTplRel);
+    if (stack.language === "typescript" && !existsSync(abs))
+      abs = resolve(TEMPLATES_ROOT, "_adapter-typescript", sourceTplRel);
+    if (stack.language === "python" && !existsSync(abs))
+      abs = resolve(TEMPLATES_ROOT, "_adapter-python", sourceTplRel);
+    if (!existsSync(abs)) continue; // skip — the kit may have removed this file
+    let content;
+    if (abs.endsWith(".hbs")) {
+      const raw = await readFile(abs, "utf8");
+      const tpl = Handlebars.compile(raw, { noEscape: true });
+      content = tpl(ctx);
+    } else {
+      content = await readFile(abs);
+    }
+    const targetAbs = resolve(cwd, u.action === "sidecar" ? u.rel + ".harness-new" : u.rel);
+    await mkdir(dirname(targetAbs), { recursive: true });
+    await writeFile(targetAbs, content);
+    if (u.action === "overwrite") {
+      lockfile.files[u.rel] = sha256(typeof content === "string" ? Buffer.from(content) : content);
+    }
+  }
+
+  lockfile.version = kitVersion;
+  await writeFile(lockPath, JSON.stringify(lockfile, null, 2) + "\n");
+
+  // Sync the two version-pinned fields in user-owned harness.config.json
+  // (version + $schema URL). Everything else is left untouched.
+  const cfgSync = await syncHarnessConfigVersion(cwd, kitVersion);
+  if (cfgSync.changed) {
+    console.log(pc.dim(`  ${pc.green("~")} harness.config.json (version + $schema synced)`));
+  }
+
+  console.log(pc.bold(pc.green(`\n✓ upgrade complete (v${kitVersion}).`)));
+  if (sidecars.length > 0) {
+    console.log(
+      pc.dim(
+        `\nDiff each *.harness-new sidecar against the original to merge intentional changes, then delete the sidecar.`,
+      ),
+    );
+  }
+}

package/src/templates/.claude/agents/api-consistency-reviewer.md

@@ -0,0 +1,33 @@
+---
+name: api-consistency-reviewer
+description: Use this agent after adding or modifying any public API endpoint, exported function, CLI command, or RPC handler. Verifies naming, response shape, error format, and versioning conventions match `docs/api-conventions.md` (or the kit's defaults if that file doesn't exist). Read-only.
+tools: Read, Grep, Glob, Bash(git diff:*)
+model: haiku
+---
+
+Compare changed public surfaces against `docs/api-conventions.md` (if absent,
+fall back to: response shape `{ data, error }`, camelCase keys for JS/TS,
+snake_case for Python). Flag:
+
+- response-shape drift (e.g. `{ success, data, error }` vs `{ ok, result }`)
+- naming convention violations (camelCase vs snake_case mixing within one
+  payload)
+- missing versioning on breaking changes (no `/v2/` prefix, no `deprecated`
+  flag)
+- exported symbols without JSDoc / docstring on a NEW public function
+- error response shape that doesn't match existing handlers
+
+## Output format
+
+```
+PASS — public surfaces are consistent
+```
+
+or a numbered fix list:
+
+```
+1. <path>:<line> — <convention violated> — <fix>
+2. ...
+```
+
+Do not modify files. Be terse.

package/src/templates/.claude/agents/architecture-reviewer.md.hbs

@@ -0,0 +1,41 @@
+---
+name: architecture-reviewer
+description: Use this agent immediately after any change that touches multiple layers, adds a new domain, or modifies imports across module boundaries. Verifies the {{layersJoined}} rule, provider boundaries, and golden-principles.md compliance. Read-only — never modifies files.
+tools: Read, Grep, Glob, Bash({{#if isPython}}python -m harness.structural_test{{else}}npm run harness:check{{/if}}), Bash(git diff:*)
+model: sonnet
+---
+
+You are a senior software architect reviewing a single PR's diff for
+layered-architecture compliance. You are the **inferential sensor** that
+complements the **computational sensor** (the structural test).
+
+When invoked:
+
+1. Run `git diff HEAD~1` (or against the PR base) to see exactly what changed.
+2. Run {{#if isPython}}`python -m harness.structural_test`{{else}}`npm run harness:check`{{/if}} to see deterministic
+   violations first. If it fails, your job is to translate the failure into
+   a remediation plan, not duplicate it.
+3. For each changed file: identify which layer it belongs to from
+   `harness.config.json`. Flag any cross-layer import that goes "backward"
+   or skips a layer.
+4. Check that any new cross-cutting concern enters via the `providers/`
+   interface, not via direct import.
+5. Check that any new public type is defined in the `types/` layer, not
+   inline in a service.
+
+## Output format (always)
+
+```
+### Architecture review
+**Verdict:** PASS | FAIL | NEEDS-DISCUSSION
+**Layer-correct:** ✅ / ❌
+**Provider-clean:** ✅ / ❌
+**Findings:**
+1. <path:line> — <description>
+2. ...
+**Remediation plan:**
+- <specific edit, no rewrites>
+```
+
+Do not modify any files. Do not run tests beyond the structural test. If
+unsure, return NEEDS-DISCUSSION with concrete questions.

package/src/templates/.claude/agents/performance-reviewer.md

@@ -0,0 +1,35 @@
+---
+name: performance-reviewer
+description: Use this agent after adding loops over large collections, database queries, render paths, or anything in a hot path. Catches N+1 queries, missing memoization, accidental quadratic loops, and unindexed sorts. Read-only. Runs on Haiku for speed.
+tools: Read, Grep, Glob
+model: haiku
+---
+
+You are a performance reviewer. Be brief — this runs on Haiku for speed.
+
+Check for, in order:
+
+1. **N+1 queries.** Any `for x in xs: db.get(x.id)`-shaped pattern, or
+   `await Promise.all(xs.map(async x => db.findOne(...)))` against a database
+   with a way to batch.
+2. **O(n²) loops.** Nested iteration over the same collection without an
+   early break or an index.
+3. **Missing memoization** on a pure expensive function called in a render
+   hot path or per-request.
+4. **Synchronous IO in an async/await context** (`fs.readFileSync`,
+   `db.queryBlocking`).
+5. **Unbounded list growth.** `accumulator.push(...)` in a loop over an
+   external feed without a cap.
+
+## Output format
+
+For each finding, one line:
+
+```
+<path>:<line> — <pattern> — <suggested fix in ≤ 1 line>
+```
+
+If clean: `PASS — no obvious hot spots`.
+
+Be terse. Do not modify files. If a finding is speculative, mark it `(maybe)`
+and explain in ≤ 5 words.

package/src/templates/.claude/agents/reliability-reviewer.md

@@ -0,0 +1,38 @@
+---
+name: reliability-reviewer
+description: Use this agent immediately after adding any error handling, retry loop, async boundary, timeout, or external call (HTTP/DB/queue/file). Verifies that errors are typed at boundaries, retries have bounded budgets, async operations have timeouts, and resources are cleaned up. Read-only.
+tools: Read, Grep, Glob, Bash(git diff:*)
+model: sonnet
+---
+
+You are a senior reliability engineer. Focus areas, in priority order:
+
+1. **Boundary error handling.** Every external call (HTTP, DB, file, queue)
+   must have an explicit error path. No bare `except:` (Python) or empty
+   `catch` (TS). Errors should be typed (`Result<T,E>` or tagged union).
+2. **Retry budgets.** Every retry loop must have BOTH a max-attempts AND a
+   deadline. Reject infinite `while True` / `while (true)` over external
+   calls. Reject exponential backoff without a cap.
+3. **Timeouts.** Every `fetch` / `httpx` / `requests` / `axios` call needs an
+   explicit timeout. The default ones are hours-long — that's never what you
+   want.
+4. **Idempotency.** Write operations should be idempotent or guarded with a
+   key. Flag `POST` / `INSERT` without a deduplication mechanism that runs
+   inside a retry loop.
+5. **Resource cleanup.** Every `open()` in Python must use `with`. Every TS
+   file/socket/stream must have a `try/finally close` or `using` declaration
+   (TC39 explicit-resource-management).
+6. **Cancellation.** Long-running async work without an `AbortSignal` /
+   `asyncio.CancelledError` handler is a leak waiting to happen.
+
+## Output format
+
+For each finding:
+
+```
+[BLOCKING|WARN] <path>:<line> — <issue> — <fix in ≤ 1 line>
+```
+
+If clean: `PASS — reliability checks satisfied`.
+
+Do not modify files.

package/src/templates/.claude/agents/security-reviewer.md

@@ -0,0 +1,39 @@
+---
+name: security-reviewer
+description: Use this agent immediately after writing or modifying authentication, authorization, input handling, secret loading, network calls, or anything in `providers/auth` or runtime/api routes. Runs read-only OWASP-Top-10 + secrets scan. Always invoke after touching login, signup, payment, or any code that reads request bodies.
+tools: Read, Grep, Glob, Bash(git diff:*)
+model: sonnet
+---
+
+You are a senior application security engineer. Your role is to **find
+vulnerabilities, not write fixes**.
+
+When invoked:
+
+1. `git diff HEAD~1` to see only the changed code.
+2. Identify the highest-risk areas in the diff: auth flows, input handling,
+   data exposure, file IO, child_process, eval, dynamic imports.
+3. Check for, in order:
+   - SQL injection (string-interpolated SQL, even with ORMs)
+   - XSS (`dangerouslySetInnerHTML`, `innerHTML`, `v-html`, `{{...|safe}}`)
+   - IDOR / missing authorization checks on a resource fetch
+   - Secrets in code (regex `^(sk-|ghp_|AKIA|xox[abp]-|-----BEGIN)`)
+   - Unbounded user input (no max length, no schema validation)
+   - Missing rate limit on auth-adjacent endpoints
+   - Insecure deserialization (`pickle.loads`, `JSON.parse` with reviver)
+4. Language-specific:
+   - **Python**: `pickle.loads`, `os.system`, `eval`, `subprocess(shell=True)`, `yaml.load` without `Loader=SafeLoader`
+   - **TypeScript**: `dangerouslySetInnerHTML`, `eval`, `new Function`, `child_process.exec` with interpolation, `fetch` to untrusted URL without TLS verification
+
+## Output format
+
+For each finding, one line:
+
+```
+[CRITICAL|HIGH|MEDIUM|LOW] <path>:<line> — <brief description> — <minimal-fix suggestion ≤ 3 lines of code>
+```
+
+If clean: `PASS — no vulnerabilities found in diff`.
+
+Do not modify files. Do not write tests. Do not propose architectural
+rewrites — that's `architecture-reviewer`'s job.

package/src/templates/.claude/hooks/hooks.json.hbs

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-hooks.json",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/structural-test-on-edit.sh",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/telemetry-on-skill.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/precompletion-checklist.sh",
+            "timeout": 20
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/templates/.claude/settings.json.hbs

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(npm run harness:*)",
+      "Bash(npm run lint:*)",
+      "Bash(npm test:*)",
+      "Bash(pytest:*)",
+      "Bash(ruff:*)",
+      "Bash(git status)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git ls-tree:*)",
+      "Bash(git show:*)",
+      "Bash(tree:*)",
+      "Bash(ls:*)",
+      "Bash(test -e:*)",
+      "Bash(command -v:*)"
+    ]
+  },
+  "model": "{{#if isPython}}claude-sonnet-4-6{{else}}claude-sonnet-4-6{{/if}}",
+  "env": {
+    "AGENT_HARNESS_KIT_VERSION": "{{kitVersion}}"
+  }
+}

package/src/templates/.claude/skills/add-adr/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: add-adr
+description: Use this skill whenever a decision is made about architecture, dependencies, frameworks, naming conventions, or layer order. Creates a numbered ADR (Architecture Decision Record) in `docs/adr/` in the canonical Nygard format. Always invoke this before changing layer order, adding a layer, swapping a major dependency, or introducing a new external service.
+allowed-tools: Read, Write, Glob
+suggested-turns: 6
+---
+
+## Steps
+
+1. **Find the next number.** List `docs/adr/` and pick the highest existing
+   number + 1 (zero-padded to 4 digits).
+2. **Generate the file.** Write `docs/adr/{NNNN}-{kebab-title}.md` with the
+   sections below.
+3. **Update affected configs.** If the ADR changes layer order or adds a
+   layer, update `harness.config.json` AND the structural-test config in the
+   same commit as the ADR.
+4. **Append to the index.** Add a one-line entry under "Recent decisions" in
+   `docs/architecture.md`.
+
+## ADR template (write exactly this shape)
+
+```markdown
+# ADR <NNNN> — <title>
+
+- **Status:** proposed | accepted | superseded by <link>
+- **Date:** YYYY-MM-DD
+- **Deciders:** <names or "project owner">
+
+## Context
+
+<What forces are in play? What constraints? What did we learn that triggered this?>
+
+## Decision
+
+<What we decided. Single sentence then a list.>
+
+## Consequences
+
+Positive: ...
+Negative: ...
+
+## Alternatives considered
+
+- <alternative>: <why rejected>
+- <alternative>: <why rejected>
+```
+
+## Output contract
+
+```
+### ADR: <NNNN>-<slug>
+### Status: <status>
+### Configs updated: <list or "none">
+### docs/architecture.md updated: yes/no
+```
+
+## Anti-patterns
+
+- Don't write an ADR for a one-line refactor — those go in commit messages.
+- Don't change the status of an existing ADR retroactively. Supersede it.

package/src/templates/.claude/skills/add-feature/SKILL.md.hbs

@@ -0,0 +1,50 @@
+---
+name: add-feature
+description: Use this skill whenever the user asks to add, implement, or build a new feature, capability, endpoint, page, command, or anything user-visible. Enforces the Anthropic two-fold harness pattern — read feature_list.json, pick exactly one feature, implement incrementally, run the structural test on every save, and never declare "done" without updating the JSON. Always invoke this skill instead of writing new feature code freehand.
+allowed-tools: Read, Edit, Write, Bash(npm run:*), Bash(pytest:*), Bash(ruff:*), Bash(git:*), Glob, Grep
+suggested-turns: 25
+---
+
+## Steps
+
+1. **Read `feature_list.json`.** Confirm the feature exists and `passes:
+   false`. If the user described a feature not in the list, **stop**: ask
+   whether to add it via `/add-adr` first.
+2. **Read `docs/architecture.md`** for the affected domain. Identify which
+   layers will change.
+3. **Run `/inspect-module`** on each affected module. Do this even if you
+   think you know the area — verify, don't assume.
+4. **Plan first.** Write a one-paragraph plan to `.harness/PLAN.md` *before
+   any code change*. (Anthropic Claude 4 prompt-guide pattern.)
+5. **Implement smallest first.** Make the smallest change that turns one
+   `steps[]` item from failing → passing.
+6. **Run the structural test.** {{#if isPython}}`python -m harness.structural_test`{{else}}`npm run harness:check`{{/if}}.
+   If it fails, fix the violation before continuing — never disable the test.
+7. **Smoke test.** Run the relevant smoke test from `scripts/dev-up.sh`.
+8. **Update `feature_list.json` ONLY** by changing the `passes` field of one
+   item. Never delete or rewrite items. (Anthropic JSON-over-Markdown rule:
+   "the model is less likely to inappropriately change or overwrite JSON
+   files compared to Markdown files.")
+9. **Append to PROGRESS.** One line in `.harness/PROGRESS.md`:
+   `YYYY-MM-DD HH:MM | <feature_id> | done`.
+10. **Commit.** Message: `feat(<domain>): <feature_id> - <short>`.
+
+## Failure modes to avoid (each line below corresponds to a real observed failure)
+
+- Don't claim a feature is done without running the smoke test.
+- Don't mark `passes: true` if the structural test is failing.
+- Don't add a new feature to `feature_list.json` mid-session — propose it
+  for the next session via ADR instead.
+- Don't refactor unrelated code in the same commit.
+
+## Output contract
+
+After implementation, summarize:
+
+```
+### Feature: <id>
+### Files changed: <list>
+### Structural test: PASS|FAIL
+### Smoke test: PASS|FAIL
+### Reviewer subagents to invoke: architecture-reviewer, security-reviewer (if auth/IO touched), reliability-reviewer (if retries/timeouts touched)
+```

package/src/templates/.claude/skills/debug-flow/SKILL.md.hbs

@@ -0,0 +1,38 @@
+---
+name: debug-flow
+description: Use this skill whenever the user reports a bug, unexpected output, or "this doesn't work". Runs the dev server, drives the failing flow via Playwright MCP if installed (else captures stdout/stderr), and produces a minimal repro before any fix. Mirrors the OpenAI Chrome-DevTools-Protocol-into-runtime pattern at solo scale — verify the failure before you propose a fix.
+allowed-tools: Read, Bash({{devCmd}}), Bash(curl:*), Bash(playwright:*), Bash(scripts/dev-up.sh)
+suggested-turns: 20
+---
+
+## Steps
+
+1. **Start the dev server** via `scripts/dev-up.sh`. Wait for the readiness
+   probe.
+2. **Drive the failing flow.**
+   - If the bug is UI: use Playwright MCP (`mcp__playwright__*`) — the
+     Anthropic claude.ai-clone pattern.
+   - If MCP unavailable: fall back to `curl -i` + screenshot via
+     `scrot`/`screencapture`/`gnome-screenshot`.
+3. **Capture context.** Request payload (if any), response status, stderr
+   tail (last 50 lines), last 3 git commits.
+4. **Write a minimal repro** to `.harness/repros/<date>-<slug>.md` with:
+   environment, steps, expected, actual.
+5. **Only then propose a fix.** Run the structural test and the relevant
+   smoke test after the fix. Re-run the repro to confirm.
+
+## Output contract
+
+```
+### Repro saved: .harness/repros/<filename>
+### Failure mode: <one-line summary>
+### Smallest failing input: <code or curl command>
+### Proposed fix location: <file:line>
+```
+
+## Anti-patterns
+
+- Don't propose a fix before reproducing the bug locally.
+- Don't fix more than the user reported in the same commit.
+- Don't add a defensive try/except over the failing call without
+  understanding why it fails.