agent-harness-kit 0.8.0 → 0.10.0

package/.claude-plugin/marketplace.json

@@ -11,9 +11,9 @@
       "source": {
         "source": "github",
         "repo": "tuanle96/agent-harness-kit",
-        "ref": "v0.8.0"
+        "ref": "v0.10.0"
       },
-      "version": "0.8.0",
+      "version": "0.10.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.8.0",
+  "version": "0.10.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/README.md

@@ -59,8 +59,9 @@ Option B: install as a Claude Code plugin
 | `/add-adr`                       | Add a numbered Architecture Decision Record              |
 | `/doc-drift-scan`                | Find stale path/command references in `docs/`            |
 | `/debug-flow`                    | Run the failing flow before fixing it                    |
+| `/deliver-html`                  | Ship an analysis/audit/plan as a self-contained HTML     |
 
-## Philosophy (4 axioms)
+## Philosophy (5 axioms)
 
 1. **CLAUDE.md is a table of contents, not an encyclopedia** (HumanLayer
    measured ~150–200 instructions as the reliable cap; OpenAI's own root file
@@ -76,6 +77,15 @@ Option B: install as a Claude Code plugin
    differentiator — see [Honest expectations](#honest-expectations).
 4. **Garbage collection over Friday cleanup, scaled to solo** (OpenAI's
    ritual, shrunk to top-3 fixes per week).
+5. **HTML for human deliverables, Markdown for agent files.** Markdown is
+   the right format for files an agent reads-and-edits (CLAUDE.md, SKILL.md,
+   ADRs); HTML is the right format for documents a HUMAN reads-and-decides
+   (audit reports, analyses, plans, decision docs). A long Markdown
+   deliverable invites the human to scroll, miss the conclusion, and ask the
+   agent to clarify — burning more tokens than the HTML markup costs. The
+   `/deliver-html` skill writes self-contained HTML at repo root with a
+   shared dark-theme CSS; the rule is documented in golden principle #11 and
+   ADR-0002.
 
 ## Directory the kit drops into your repo
 

package/bin/cli.mjs

@@ -52,6 +52,11 @@ program
     "--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`)));
@@ -203,6 +208,22 @@ program
       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.8.0",
+  "version": "0.10.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

@@ -100,6 +100,30 @@ 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");

package/src/core/render-templates.mjs

@@ -48,6 +48,10 @@ export 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()) {
@@ -210,6 +219,26 @@ export 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;

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.

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

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

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

@@ -35,6 +35,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/pretooluse-edit-guard.sh",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "Notification": [
@@ -95,6 +105,18 @@
         ]
       }
     ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/subagent-stop.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "matcher": "",