agent-harness-kit 0.7.0 → 0.9.0

package/.claude-plugin/marketplace.json

@@ -11,9 +11,9 @@
       "source": {
         "source": "github",
         "repo": "tuanle96/agent-harness-kit",
-        "ref": "v0.7.0"
+        "ref": "v0.9.0"
       },
-      "version": "0.7.0",
+      "version": "0.9.0",
       "description": "Solo-dev harness engineering kit — layered architecture, GC ritual, structural tests, review subagents.",
       "category": "development",
       "keywords": [

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Solo-dev harness engineering kit — layered architecture, garbage-collection ritual, structural tests, review subagents. Optimized for Claude Code 2.1+.",
   "author": {
     "name": "Tuan Le"

package/bin/cli.mjs

@@ -48,6 +48,15 @@ program
     "human language for the CLAUDE.md template (en, vi)",
     "en",
   )
+  .option(
+    "--model <id>",
+    "Claude model to pin in .claude/settings.json (e.g. claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5)",
+  )
+  .option(
+    "--with-mcp",
+    "copy .mcp.json.example to .mcp.json (enables Playwright + GitHub MCP servers — credentials still required)",
+    false,
+  )
   .action(async (opts) => {
     const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
     console.log(pc.bold(pc.cyan(`\nagent-harness-kit v${pkg.version}\n`)));
@@ -196,8 +205,25 @@ program
       installCi,
       kitVersion: pkg.version,
       humanLanguage: opts.lang || "en",
+      model: opts.model,
     });
 
+    // --with-mcp: promote the shipped .mcp.json.example to .mcp.json so
+    // the user gets a working starting point. Idempotent — if .mcp.json
+    // already exists we leave it alone (user owns it after first write).
+    if (opts.withMcp) {
+      const examplePath = resolve(cwd, ".mcp.json.example");
+      const mcpPath = resolve(cwd, ".mcp.json");
+      const { existsSync: fsExists } = await import("node:fs");
+      const { copyFile } = await import("node:fs/promises");
+      if (fsExists(examplePath) && !fsExists(mcpPath)) {
+        await copyFile(examplePath, mcpPath);
+        result.written.push(".mcp.json (from --with-mcp)");
+      } else if (fsExists(mcpPath)) {
+        console.log(pc.yellow(`  ~ .mcp.json already present — left untouched (--with-mcp skipped overwrite)`));
+      }
+    }
+
     console.log("");
     for (const f of result.written) {
       console.log(`  ${pc.green("✓")} ${pc.dim("wrote")} ${f}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Solo-dev harness engineering kit for Claude Code. Layered architecture, structural tests, garbage-collection ritual, review subagents — without the enterprise overhead.",
   "type": "module",
   "bin": {

package/src/core/doctor.mjs

@@ -6,6 +6,7 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { execSync } from "node:child_process";
 import pc from "picocolors";
+import { SUPPORTED_MODELS } from "./render-templates.mjs";
 
 function check(name, ok, info = "") {
   const mark = ok ? pc.green("✓") : pc.red("✗");
@@ -99,6 +100,52 @@ export async function doctor({ cwd, kitVersion }) {
     }
   }
 
+  // 4b. MCP probe — warn (don't fail) when .mcp.json is missing but the
+  // example file is shipped. Recommended skills (review-this-pr, garbage-
+  // collection) work better with Playwright + GitHub MCP servers wired up;
+  // running without is fine, just degrades gracefully.
+  const mcpPath = resolve(cwd, ".mcp.json");
+  const mcpExamplePath = resolve(cwd, ".mcp.json.example");
+  const hasMcp = existsSync(mcpPath);
+  const hasMcpExample = existsSync(mcpExamplePath);
+  if (hasMcp) {
+    try {
+      const m = JSON.parse(await readFile(mcpPath, "utf8"));
+      const count = m.mcpServers ? Object.keys(m.mcpServers).length : 0;
+      check(`.mcp.json (${count} server${count === 1 ? "" : "s"})`, count > 0,
+        count > 0 ? "" : "no mcpServers configured");
+    } catch (e) {
+      allOk = false;
+      console.log(pc.red(`  ✗ .mcp.json is not valid JSON: ${e.message}`));
+    }
+  } else if (hasMcpExample) {
+    console.log(
+      `  ${pc.yellow("•")} .mcp.json ${pc.dim("— not enabled (copy .mcp.json.example to .mcp.json to wire up Playwright/GitHub MCP)")}`,
+    );
+  }
+
+  // 5. Model pin in .claude/settings.json (B4). Catches obvious typos
+  // that would silently no-op in Claude Code.
+  const settingsPath = resolve(cwd, ".claude/settings.json");
+  if (existsSync(settingsPath)) {
+    try {
+      const s = JSON.parse(await readFile(settingsPath, "utf8"));
+      if (typeof s.model === "string" && s.model.length > 0) {
+        if (SUPPORTED_MODELS.has(s.model)) {
+          check(`model pin (${s.model})`, true);
+        } else {
+          allOk = false;
+          console.log(
+            pc.red(`  ✗ model pin in .claude/settings.json — "${s.model}" not recognized.`),
+          );
+          console.log(
+            pc.dim(`    Known: ${[...SUPPORTED_MODELS].join(", ")}. Re-run \`agent-harness-kit init --model <id>\`.`),
+          );
+        }
+      }
+    } catch { /* covered by settings parse check elsewhere */ }
+  }
+
   console.log("");
   if (!allOk) {
     process.exit(1);

package/src/core/render-templates.mjs

@@ -23,7 +23,7 @@ const TEMPLATES_ROOT = resolve(__dirname, "..", "templates");
 // Files that the user is expected to edit — they win every time, even on
 // fresh init we won't overwrite if they exist. This list is hard-coded
 // because it's tiny and security-sensitive.
-const USER_OWNED_FILES = new Set([
+export const USER_OWNED_FILES = new Set([
   "CLAUDE.md",
   "AGENTS.md",
   "docs/architecture.md",
@@ -35,7 +35,7 @@ const USER_OWNED_FILES = new Set([
 ]);
 
 // Paths that should be made executable after rendering.
-const EXEC_BITS = new Set([
+export const EXEC_BITS = new Set([
   "scripts/dev-up.sh",
   "scripts/pre-push.sh",
   "scripts/install-git-hooks.sh",
@@ -48,6 +48,10 @@ const EXEC_BITS = new Set([
   "scripts/pretooluse-bash-guard.sh",
   "scripts/pre-compact.sh",
   "scripts/session-end.sh",
+  // v0.9 hook expansion — SubagentStop + PreToolUse(Edit|Write|MultiEdit) + rollup side-car.
+  "scripts/subagent-stop.sh",
+  "scripts/pretooluse-edit-guard.sh",
+  "scripts/session-rollup.mjs",
 ]);
 
 export function registerHelpers() {
@@ -81,6 +85,11 @@ export function registerHelpers() {
 
 async function* walk(dir) {
   const entries = await readdir(dir, { withFileTypes: true });
+  // Sort lexically so locale variants (e.g. "SKILL.md.vi.hbs") sort AFTER
+  // their masters ("SKILL.md.hbs") and overwrite them via the
+  // identical-target writeFile path. Without this, OS readdir order makes
+  // locale overrides non-deterministic.
+  entries.sort((a, b) => a.name.localeCompare(b.name));
   for (const e of entries) {
     const full = join(dir, e.name);
     if (e.isDirectory()) {
@@ -97,7 +106,21 @@ async function* walk(dir) {
 // will route it. Default is "en" → uses the suffix-less CLAUDE.md.hbs.
 export const SUPPORTED_HUMAN_LANGS = new Set(["en", "vi"]);
 
-function buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage }) {
+// SUPPORTED_MODELS — IDs the kit accepts via `--model` and writes verbatim
+// into `.claude/settings.json#model`. The kit does NOT try to be a model
+// registry — it just rejects obvious typos before they silently no-op in
+// Claude Code (which falls back to the org default on unknown IDs).
+export const SUPPORTED_MODELS = new Set([
+  "claude-opus-4-7",
+  "claude-sonnet-4-6",
+  "claude-haiku-4-5",
+  // Legacy IDs we still accept on upgrade paths.
+  "claude-sonnet-4-5",
+  "claude-haiku-3-5",
+]);
+export const DEFAULT_MODEL = "claude-sonnet-4-6";
+
+export function buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage, model }) {
   const installCmd = (() => {
     if (stack.language === "python") return "pip install -e '.[dev]'";
     if (stack.language === "go") return "go mod download";
@@ -164,6 +187,7 @@ function buildContext({ projectName, preset, layers, stack, kitVersion, humanLan
     lintCmd,
     kitVersion,
     humanLanguage: humanLanguage || "en",
+    model: model || DEFAULT_MODEL,
     isTypescript: stack.language === "typescript",
     isPython: stack.language === "python",
     isGo: stack.language === "go",
@@ -183,7 +207,7 @@ function buildContext({ projectName, preset, layers, stack, kitVersion, humanLan
 // Decide whether a template path should be rendered for this stack/preset.
 // Adapter-specific files live under templates/_adapter-<id>/ and are merged
 // into the root.
-function pathForStack(rel, stack, humanLanguage = "en") {
+export function pathForStack(rel, stack, humanLanguage = "en") {
   // CLAUDE.md locale routing. `CLAUDE.md.hbs` (no language suffix) is the
   // English default. `CLAUDE.md.<lang>.hbs` is rendered into the same
   // target path (`CLAUDE.md`) when the user picks that locale. The
@@ -195,6 +219,26 @@ function pathForStack(rel, stack, humanLanguage = "en") {
     if (fileLang !== humanLanguage) return null;
     return "CLAUDE.md.hbs"; // canonical target — strip locale suffix
   }
+  // Generic locale routing for .md.<lang>(.hbs)? under .claude/skills/* or
+  // .claude/agents/*. Variants sort AFTER masters in walk order, so when
+  // both exist the variant overwrites the master via identical writeFile
+  // path. Two forms (mirroring locale-scaffold.mjs):
+  //   Master  .md.hbs   → variant .md.<lang>.hbs    (Handlebars-active)
+  //   Master  .md       → variant .md.<lang>        (plain copy)
+  // Active-locale-only emission: variants for other locales return null.
+  const localeVariantHbs = rel.match(/^\.claude\/(?:skills|agents)\/.*\.md\.([a-z]{2,5})\.hbs$/);
+  if (localeVariantHbs) {
+    if (localeVariantHbs[1] !== humanLanguage) return null;
+    return rel.replace(/\.md\.[a-z]{2,5}\.hbs$/, ".md.hbs");
+  }
+  // "hbs" is excluded because *.md.hbs is the master (Handlebars-active),
+  // not a locale variant. Without this guard, "SKILL.md.hbs" would match
+  // with locale="hbs" and get nulled out under the en routing path.
+  const localeVariantPlain = rel.match(/^\.claude\/(?:skills|agents)\/.*\.md\.([a-z]{2,5})$/);
+  if (localeVariantPlain && localeVariantPlain[1] !== "hbs") {
+    if (localeVariantPlain[1] !== humanLanguage) return null;
+    return rel.replace(/\.md\.[a-z]{2,5}$/, ".md");
+  }
   if (rel.startsWith("_adapter-typescript/")) {
     const stripped = rel.slice("_adapter-typescript/".length);
     if (stack.language === "typescript") return stripped;
@@ -243,6 +287,59 @@ function sha256(buf) {
   return createHash("sha256").update(buf).digest("hex");
 }
 
+// Inject a statusLine block into .claude/settings.json. Idempotent: if the
+// existing statusLine already references the kit's script, leave it; otherwise
+// set it to invoke scripts/statusline.mjs via node. Doesn't clobber a
+// user-customised type:"command" entry that points at a different command.
+//
+// Returns {changed, rawContent} for the lockfile bookkeeping (mirrors the
+// mergeHooksIntoSettings contract).
+export async function mergeStatusLineIntoSettings(cwd) {
+  const settingsPath = resolve(cwd, ".claude/settings.json");
+  const scriptPath = resolve(cwd, "scripts/statusline.mjs");
+  if (!existsSync(scriptPath)) return { changed: false, rawContent: "" };
+  let settings = {};
+  let raw = "";
+  if (existsSync(settingsPath)) {
+    raw = await readFile(settingsPath, "utf8");
+    try {
+      settings = JSON.parse(raw);
+    } catch {
+      throw new Error(
+        `mergeStatusLineIntoSettings: ${settingsPath} is not valid JSON`,
+      );
+    }
+  }
+  const desired = {
+    type: "command",
+    command: "node scripts/statusline.mjs",
+  };
+  // Preserve a user-customised entry if it already points elsewhere. We only
+  // inject when statusLine is absent OR explicitly references our script.
+  const cur = settings.statusLine;
+  if (
+    cur &&
+    typeof cur === "object" &&
+    cur.type === "command" &&
+    typeof cur.command === "string" &&
+    !/statusline\.mjs/.test(cur.command)
+  ) {
+    return { changed: false, rawContent: Buffer.from(raw) };
+  }
+  if (
+    cur &&
+    typeof cur === "object" &&
+    cur.type === desired.type &&
+    cur.command === desired.command
+  ) {
+    return { changed: false, rawContent: Buffer.from(raw) };
+  }
+  settings.statusLine = desired;
+  const out = JSON.stringify(settings, null, 2) + "\n";
+  await writeFile(settingsPath, out);
+  return { changed: true, rawContent: Buffer.from(out) };
+}
+
 // Merge .claude/hooks/hooks.json#hooks into .claude/settings.json#hooks.
 // Claude Code only reads hooks from settings.json — a free-standing
 // hooks.json is ignored by the runtime. Kept as a file because the plugin
@@ -295,6 +392,7 @@ export async function renderAll({
   installCi,
   kitVersion,
   humanLanguage = "en",
+  model,
 }) {
   registerHelpers();
   if (!SUPPORTED_HUMAN_LANGS.has(humanLanguage)) {
@@ -302,7 +400,12 @@ export async function renderAll({
       `Unsupported humanLanguage "${humanLanguage}". Supported: ${[...SUPPORTED_HUMAN_LANGS].join(", ")}`,
     );
   }
-  const ctx = buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage });
+  if (model && !SUPPORTED_MODELS.has(model)) {
+    throw new Error(
+      `Unsupported model "${model}". Supported: ${[...SUPPORTED_MODELS].join(", ")}`,
+    );
+  }
+  const ctx = buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage, model });
 
   const written = [];
   const skipped = [];
@@ -365,6 +468,17 @@ export async function renderAll({
     }
   }
 
+  // v0.8 — statusLine injection. Runs after hook merge so the lockfile
+  // captures the final settings.json bytes. Idempotent; never clobbers a
+  // user-customised entry that points elsewhere.
+  if (existsSync(resolve(cwd, "scripts/statusline.mjs"))) {
+    const stat = await mergeStatusLineIntoSettings(cwd);
+    if (stat.changed) {
+      lockfile.files[".claude/settings.json"] = sha256(stat.rawContent);
+      written.push(".claude/settings.json (statusLine)");
+    }
+  }
+
   // Write the lockfile last (after we know the full set of files).
   const lockTarget = resolve(cwd, ".harness/installed.json");
   await mkdir(dirname(lockTarget), { recursive: true });

package/src/core/upgrade.mjs

@@ -7,7 +7,7 @@
 //   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 { readFile, writeFile, mkdir, readdir, chmod } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { resolve, join, relative, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -15,7 +15,15 @@ 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 {
+  registerHelpers,
+  pathForStack,
+  buildContext,
+  mergeHooksIntoSettings,
+  USER_OWNED_FILES as USER_OWNED_FROM_RENDERER,
+  EXEC_BITS,
+  SUPPORTED_HUMAN_LANGS,
+} from "./render-templates.mjs";
 import { detectStack } from "./detect-stack.mjs";
 
 // Sync the two version-pinned fields in harness.config.json after a kit
@@ -101,16 +109,29 @@ export async function ensureWritePermissions(cwd) {
 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",
-]);
+// Single source of truth lives in render-templates.mjs. Re-exported here under
+// the legacy local name to avoid a wider rename in this module.
+const USER_OWNED_FILES = USER_OWNED_FROM_RENDERER;
+
+// Read user preferences from the existing harness.config.json so the rendered
+// templates pick up the user's chosen model + locale instead of falling back
+// to template defaults that would silently overwrite them. Returns soft
+// defaults when the file is missing or invalid; never throws.
+async function readUserPreferences(cwd) {
+  const cfgPath = resolve(cwd, "harness.config.json");
+  if (!existsSync(cfgPath)) return { humanLanguage: "en", model: undefined };
+  try {
+    const cfg = JSON.parse(await readFile(cfgPath, "utf8"));
+    const humanLanguage = cfg?.claudeMd?.humanLanguage || "en";
+    const model = cfg?.models?.main;
+    return {
+      humanLanguage: SUPPORTED_HUMAN_LANGS.has(humanLanguage) ? humanLanguage : "en",
+      model,
+    };
+  } catch {
+    return { humanLanguage: "en", model: undefined };
+  }
+}
 
 function sha256(buf) {
   return createHash("sha256").update(buf).digest("hex");
@@ -171,38 +192,33 @@ export async function upgrade({ cwd, kitVersion, yes }) {
   );
 
   const stack = await detectStack(cwd);
-  const ctx = {
+
+  // Pick up user-chosen model + locale from harness.config.json so the
+  // rendered templates carry them forward instead of falling back to
+  // template defaults. Anything missing falls back to safe defaults inside
+  // buildContext.
+  const { humanLanguage, model } = await readUserPreferences(cwd);
+  registerHelpers();
+  const ctx = buildContext({
     projectName: "your-project",
+    preset: "generic",
     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",
+    stack,
     kitVersion,
-  };
+    humanLanguage,
+    model,
+  });
 
-  const updates = []; // { rel, action: 'overwrite'|'sidecar'|'skip', reason }
+  // { rel, action, reason, content } — rendered content is captured here so
+  // the apply step doesn't have to re-walk the template tree (which was the
+  // source of the v0.7 bug where rust/go/swift/kotlin adapter prefixes leaked
+  // straight into the user's project as literal directory names).
+  const updates = [];
 
   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 stackRel = pathForStack(relFromTemplates, stack, humanLanguage);
+    if (stackRel === null) continue;
     const targetRel = stackRel.endsWith(".hbs")
       ? stackRel.slice(0, -".hbs".length)
       : stackRel;
@@ -215,7 +231,6 @@ export async function upgrade({ cwd, kitVersion, yes }) {
     let newContent;
     if (abs.endsWith(".hbs")) {
       const raw = await readFile(abs, "utf8");
-      registerHelpers();
       const tpl = Handlebars.compile(raw, { noEscape: true });
       newContent = tpl(ctx);
     } else {
@@ -230,7 +245,7 @@ export async function upgrade({ cwd, kitVersion, yes }) {
     const targetExists = existsSync(targetAbs);
 
     if (!targetExists) {
-      updates.push({ rel: targetRel, action: "overwrite", reason: "new" });
+      updates.push({ rel: targetRel, action: "overwrite", reason: "new", content: newContent });
       continue;
     }
     const currentBuf = await readFile(targetAbs);
@@ -241,9 +256,9 @@ export async function upgrade({ cwd, kitVersion, yes }) {
       continue;
     }
     if (currentSha === previousSha) {
-      updates.push({ rel: targetRel, action: "overwrite", reason: "user-untouched" });
+      updates.push({ rel: targetRel, action: "overwrite", reason: "user-untouched", content: newContent });
     } else {
-      updates.push({ rel: targetRel, action: "sidecar", reason: "user-modified" });
+      updates.push({ rel: targetRel, action: "sidecar", reason: "user-modified", content: newContent });
     }
   }
 
@@ -266,29 +281,35 @@ export async function upgrade({ cwd, kitVersion, yes }) {
     }
   }
 
-  // Apply.
+  // Apply — content was rendered in the first pass; just write it out.
   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);
+    await writeFile(targetAbs, u.content);
+    if (EXEC_BITS.has(u.rel) && u.action === "overwrite") {
+      try {
+        await chmod(targetAbs, 0o755);
+      } catch {
+        // ignore on platforms where chmod is a no-op
+      }
+    }
     if (u.action === "overwrite") {
-      lockfile.files[u.rel] = sha256(typeof content === "string" ? Buffer.from(content) : content);
+      lockfile.files[u.rel] = sha256(
+        typeof u.content === "string" ? Buffer.from(u.content) : u.content,
+      );
+    }
+  }
+
+  // Critical fix (v0.7 + idempotent upgrade): merge .claude/hooks/hooks.json
+  // into .claude/settings.json#hooks. Claude Code ONLY reads hooks from
+  // settings.json — a stand-alone hooks.json is silently ignored. renderAll
+  // does this on init; upgrade has to redo it because hooks.json may have
+  // changed across versions (and pre-v0.7 installs never had it merged).
+  if (existsSync(resolve(cwd, ".claude/hooks/hooks.json"))) {
+    const merged = await mergeHooksIntoSettings(cwd);
+    if (merged.changed) {
+      lockfile.files[".claude/settings.json"] = sha256(merged.rawContent);
+      console.log(pc.dim(`  ${pc.green("~")} .claude/settings.json (hooks merged)`));
     }
   }
 

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

@@ -0,0 +1,37 @@
+<!-- LOCALE_TODO: translate body to vi -->
+<!-- Source: .claude/agents/api-consistency-reviewer.md -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+---
+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.vi.hbs

@@ -0,0 +1,45 @@
+<!-- LOCALE_TODO: translate body to vi -->
+<!-- Source: .claude/agents/architecture-reviewer.md.hbs -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+---
+name: architecture-reviewer
+description: Use this agent when the Stop hook surfaces a `multi-layer-review` flag (changes span ≥2 layers in a single domain — mechanical count, not self-judgment), or when a change adds a new domain / 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.vi

@@ -0,0 +1,39 @@
+<!-- LOCALE_TODO: translate body to vi -->
+<!-- Source: .claude/agents/performance-reviewer.md -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+---
+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.