agent-harness-kit 0.8.0 → 0.9.0

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

@@ -0,0 +1,64 @@
+<!-- LOCALE_TODO: translate body to vi -->
+<!-- Source: .claude/skills/add-adr/SKILL.md -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+---
+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.vi.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
+---
+
+## Các bước
+
+1. **Đọc `feature_list.json`.** Xác nhận feature tồn tại và `passes:
+   false`. Nếu user mô tả feature chưa có trong danh sách, **dừng lại**:
+   hỏi xem có nên thêm qua `/add-adr` trước không.
+2. **Đọc `docs/architecture.md`** cho domain bị ảnh hưởng. Xác định
+   những layer nào sẽ thay đổi.
+3. **Chạy `/inspect-module`** trên mỗi module bị ảnh hưởng. Làm điều này
+   ngay cả khi bạn nghĩ đã hiểu khu vực đó — phải kiểm chứng, không phỏng đoán.
+4. **Lập kế hoạch trước.** Viết một đoạn văn ngắn vào `.harness/PLAN.md`
+   *trước khi thay đổi code*. (Pattern theo Anthropic Claude 4 prompt-guide.)
+5. **Bắt đầu từ thay đổi nhỏ nhất.** Sửa ít nhất đủ để một `steps[]`
+   chuyển từ failing → passing.
+6. **Chạy structural test.** {{#if isPython}}`python -m harness.structural_test`{{else}}`npm run harness:check`{{/if}}.
+   Nếu fail, sửa vi phạm trước khi tiếp tục — không bao giờ disable test.
+7. **Smoke test.** Chạy smoke test liên quan trong `scripts/dev-up.sh`.
+8. **Cập nhật `feature_list.json` CHỈ** bằng cách đổi field `passes` của
+   một item. Không bao giờ xóa hoặc viết lại items. (Quy tắc Anthropic
+   "JSON hơn Markdown": "model ít có khả năng thay đổi/ghi đè JSON files
+   so với Markdown.")
+9. **Append vào PROGRESS.** Một dòng vào `.harness/PROGRESS.md`:
+   `YYYY-MM-DD HH:MM | <feature_id> | done`.
+10. **Commit.** Message: `feat(<domain>): <feature_id> - <ngắn gọn>`.
+
+## Các failure mode cần tránh (mỗi dòng tương ứng một lỗi đã quan sát thực tế)
+
+- Không tuyên bố feature đã xong khi chưa chạy smoke test.
+- Không đánh dấu `passes: true` khi structural test còn failing.
+- Không thêm feature mới vào `feature_list.json` giữa session — đề xuất
+  cho session sau qua ADR.
+- Không refactor code không liên quan trong cùng commit.
+
+## Output contract
+
+Sau khi triển khai, tóm tắt:
+
+```
+### Feature: <id>
+### Files changed: <list>
+### Structural test: PASS|FAIL
+### Smoke test: PASS|FAIL
+### Reviewer subagents to invoke: architecture-reviewer, security-reviewer (nếu chạm auth/IO), reliability-reviewer (nếu chạm retries/timeouts)
+```

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

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

package/src/templates/.claude/skills/doc-drift-scan/SKILL.md.vi

@@ -0,0 +1,52 @@
+<!-- LOCALE_TODO: translate body to vi -->
+<!-- Source: .claude/skills/doc-drift-scan/SKILL.md -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+---
+name: doc-drift-scan
+description: Use this skill weekly, before releases, or when the user mentions "stale docs", "doc drift", "docs are wrong", or "the README is out of date". Cross-checks every code path, file path, and command referenced in `docs/` and `CLAUDE.md` against the current repo state and produces a list of stale references — the doc-gardening agent pattern.
+allowed-tools: Read, Glob, Grep, Bash(test -e:*), Bash(command -v:*), Bash(node .claude/skills/doc-drift-scan/scripts/scan-paths.mjs:*)
+suggested-turns: 8
+---
+
+## Steps
+
+1. **Extract references + validate (deterministic).** Run the side-car
+   script — walks `docs/**/*.md` + `CLAUDE.md`, extracts every backtick-path
+   containing a slash, checks `existsSync` per ref:
+
+   ```bash
+   node .claude/skills/doc-drift-scan/scripts/scan-paths.mjs
+   ```
+
+   Read the JSON: `{ stats: { docs_scanned, refs_found, refs_missing },
+   drift: [{ doc, ref }] }`. Replaces three LLM grep turns.
+2. **Validate commands (LLM judgment, narrow).** Optional second pass for
+   backtick-commands the side-car doesn't classify (no slash → not a path).
+   Use `command -v <cmd>` and allow a small allowlist (`jq`, `gh`, `rg`).
+3. **Group findings.**
+   - `missing-paths`: file moved or deleted.
+   - `wrong-layer-claim`: doc says module is in layer X, structural test
+     says layer Y.
+   - `outdated-commands`: command no longer exists or signature changed.
+4. **Open ONE PR.** Label `doc-drift`. Patch all findings in one commit. Do
+   not merge.
+
+## Output contract
+
+```
+### Doc-drift scan: <date>
+### References checked: <N>
+### Drifted: <count>
+### PR opened: #<n>
+### Top 3 drifts:
+1. ...
+2. ...
+3. ...
+```
+
+## Anti-patterns
+
+- Don't fix code to match docs. Fix docs to match code.
+- Don't propose deleting a doc that drifted — drift means the doc was once
+  useful. Update or supersede it.

package/src/templates/.claude/skills/eval-runner/SKILL.md.vi

@@ -0,0 +1,59 @@
+<!-- LOCALE_TODO: translate body to vi -->
+<!-- Source: .claude/skills/eval-runner/SKILL.md -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+---
+name: eval-runner
+description: Use this skill whenever a skill, subagent, or hook is changed, before merging to main, or when the user mentions "eval", "regression test for the harness", or "is the harness still working". This skill is a thin wrapper — it runs a single shell command (`npm run harness:eval` or `python -m harness.eval_runner`) and summarizes the JSONL output. Do not implement the eval logic yourself; the runner is already deterministic.
+allowed-tools: Bash(npm run harness:eval:*), Bash(python -m harness.eval_runner:*), Read
+suggested-turns: 2
+---
+
+## When to use
+
+The user said any of: "run the evals", "regression-test the harness", "is the
+harness still working", "eval the kit changes".
+
+## Steps
+
+This is a **2-turn skill**. Don't over-engineer.
+
+1. **Run the script.** Pick the right invocation based on stack:
+   - TypeScript: `npm run harness:eval -- --quick --transport=mock`
+   - Python: `python -m harness.eval_runner --quick --transport=mock`
+
+   Use `--quick` (3 tasks, ~30s) by default. Switch to `--full` only if the
+   user asked for it. Use `--transport=claude-cli` only if the user explicitly
+   wants a real (paid) run.
+
+2. **Summarize the JSONL output.** Read the latest file in
+   `.harness/eval/results/` and produce:
+
+   ```
+   ### Eval run: <sha>
+   ### Set: quick | full
+   ### Transport: mock | claude-cli
+   ### Tasks: <pass>/<total>
+   ### Failed dimensions:
+   - <task-id>.outcome: <info>
+   - <task-id>.process: missing skills [<list>]
+   ### Verdict: PASS | FAIL
+   ```
+
+That's it. Stop after the summary.
+
+## What NOT to do
+
+- **Don't re-implement the eval logic.** The runner is a deterministic script.
+  If you find yourself writing tool calls one by one, you've misread this skill.
+- **Don't run `--full --transport=claude-cli` without permission.** That's a
+  ~$2 paid API run. Always confirm first.
+- **Don't fix failing tasks.** This skill reports the result; fixing is a
+  separate task that uses `/structural-test-author` or
+  `/propose-harness-improvement`.
+
+## Anti-pattern flag
+
+If you (the agent reading this skill) feel like you need >3 turns to do this,
+stop and re-read the steps. The whole skill is: spawn a subprocess, read a
+file, format a summary.

package/src/templates/.claude/skills/garbage-collection/SKILL.md.vi.hbs

@@ -0,0 +1,58 @@
+---
+name: garbage-collection
+description: Use this skill on Fridays, before tagging a release, or when the user mentions "cleanup", "tech debt", "AI slop", "GC", or "garbage collection". Runs the deterministic linters, structural tests, and doc-drift scans, then proposes the top-3 highest-leverage cleanups (with risk/cost/benefit) — does NOT auto-merge. This is the solo-dev shrunk version of OpenAI's Friday garbage-collection ritual.
+allowed-tools: Read, Glob, Grep, Bash(npm run:*), Bash(pytest:*), Bash(ruff:*), Bash(git:*), Bash(gh:*), Bash(node .claude/skills/garbage-collection/scripts/gc-classify.mjs:*)
+suggested-turns: 15
+---
+
+## Các bước
+
+1. **Lấy baseline.** Chạy toàn bộ test suite và lưu output:
+   - {{#if isPython}}`python -m harness.structural_test`{{else}}`npm run harness:check`{{/if}}
+   - {{#if isPython}}`ruff check . --output-format json`{{else}}`npm run lint -- --format json`{{/if}}
+   - Lưu vào `.harness/gc-<date>.json`.
+2. **Phân loại vi phạm.** Với mỗi finding:
+   - **Vi phạm layer** → sửa.
+   - **Duplicate utility** (cùng function body ở 2+ chỗ) → đề xuất
+     trích xuất sang `src/shared/`.
+   - **Dead import** → xóa.
+   - **Doc drift** (đường dẫn trong `docs/architecture.md` không còn tồn tại) →
+     gọi skill `doc-drift-scan`.
+   - **Helper viết tay** trùng với shared utility đã có → đề xuất thay thế.
+3. **Chấm điểm** từng candidate fix trên ba thang điểm 1–5 qua side-car
+   script (thay thế LLM-scored turn trước đây — deterministic và có thể
+   kiểm chứng):
+
+   ```bash
+   node .claude/skills/garbage-collection/scripts/gc-classify.mjs \
+     --baseline .harness/gc-<date>.json \
+     --history  .harness/gc-history.json
+   ```
+
+   Script áp dụng rubric cơ học: `risk = 1 + ceil(touched/3)`,
+   `cost = 1 + ceil(lines/30)`, `benefit = recurrenceCount(class)`. Đọc
+   `candidates[]` JSON đã sort theo `(benefit desc, cost asc, risk asc)`.
+4. **Chỉ đề xuất top 3** cleanup (mức cap cho solo-dev; OpenAI làm hàng chục,
+   bạn làm 3). Mở thành các PR riêng bằng `gh pr create --label gc --draft`.
+5. **Append một row** vào `.harness/gc-history.json`:
+   `{ "date": "...", "violations_found": N, "fixes_opened": M, "total_tokens": K }`.
+6. **Dừng lại.** Không merge gì cả. Phải có human review ở scale solo.
+
+## Output contract
+
+```
+### GC run: <date>
+### Violations found: <N>
+### Top 3 fixes proposed:
+1. <slug> — risk:<1-5> cost:<1-5> benefit:<1-5> — PR #<n>
+2. ...
+3. ...
+### Fixes deferred (not in top 3): <count>
+```
+
+## Anti-patterns
+
+- Không mở quá 3 PR trong một lần chạy. Cap đó là feature, không phải bug.
+- Không auto-merge — toàn bộ ý nghĩa của GC ở solo scale là human review.
+- Không bỏ qua các findings điểm thấp; record chúng vào
+  `.harness/gc-history.json` để xu hướng nổi lên theo thời gian.

package/src/templates/.claude/skills/i18n-add-locale/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: i18n-add-locale
+description: Use this skill to scaffold a new human-language locale for the kit's skills/agents/CLAUDE.md. Mirrors every existing SKILL.md.hbs into a SKILL.md.<locale>.hbs stub so a translator (or LLM) can edit copy without touching machine-readable frontmatter. Default locale codes — vi, ja, fr, es, de — but accepts any 2-5 char code.
+allowed-tools: Read, Write, Bash(node scripts/locale-scaffold.mjs:*)
+suggested-turns: 4
+---
+
+## When to invoke
+
+- Adding a new human language to the kit (or a fork's downstream).
+- After upstream adds a new English skill — re-running this skill scaffolds
+  the locale stubs for the new file, leaving translated files untouched.
+
+## Steps
+
+1. **Pick a locale.** Two-to-five char ISO code (vi, ja, fr-CA, etc.).
+2. **Dry-run the scan.**
+   ```
+   node .claude/skills/i18n-add-locale/scripts/locale-scaffold.mjs \
+     --locale <code> --dry-run
+   ```
+   Lists every SKILL.md / SKILL.md.hbs that lacks a `.<locale>.hbs` sibling.
+3. **Materialize stubs.**
+   ```
+   node .claude/skills/i18n-add-locale/scripts/locale-scaffold.mjs \
+     --locale <code>
+   ```
+   For each missing sibling, copies the English master and prepends a
+   `<!-- LOCALE_TODO: translate body --> ` banner so the translator can grep
+   for pending work.
+4. **Register the locale.** Edit `src/core/render-templates.mjs` and add the
+   code to `SUPPORTED_HUMAN_LANGS`. The renderer picks the variant via
+   `--locale <code>` or `HARNESS_LOCALE` env.
+5. **Verify rendering** by running `agent-harness-kit init --locale <code>`
+   in a scratch dir and grepping the output for `LOCALE_TODO` (must be
+   zero before publishing).
+
+## Output contract
+
+```
+locale: <code>
+scaffolded: <N>
+already-present: <M>
+register-in: src/core/render-templates.mjs (SUPPORTED_HUMAN_LANGS)
+```
+
+## Anti-patterns
+
+- Don't translate the YAML frontmatter — the renderer + Claude Code parse
+  it as machine-readable. Translate only the body markdown.
+- Don't drop the master `.hbs` file. The locale stub *augments*; the
+  renderer falls back to the master when the locale variant is missing.

package/src/templates/.claude/skills/i18n-add-locale/SKILL.md.vi

@@ -0,0 +1,56 @@
+<!-- LOCALE_TODO: translate body to vi -->
+<!-- Source: .claude/skills/i18n-add-locale/SKILL.md -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+---
+name: i18n-add-locale
+description: Use this skill to scaffold a new human-language locale for the kit's skills/agents/CLAUDE.md. Mirrors every existing SKILL.md.hbs into a SKILL.md.<locale>.hbs stub so a translator (or LLM) can edit copy without touching machine-readable frontmatter. Default locale codes — vi, ja, fr, es, de — but accepts any 2-5 char code.
+allowed-tools: Read, Write, Bash(node scripts/locale-scaffold.mjs:*)
+suggested-turns: 4
+---
+
+## When to invoke
+
+- Adding a new human language to the kit (or a fork's downstream).
+- After upstream adds a new English skill — re-running this skill scaffolds
+  the locale stubs for the new file, leaving translated files untouched.
+
+## Steps
+
+1. **Pick a locale.** Two-to-five char ISO code (vi, ja, fr-CA, etc.).
+2. **Dry-run the scan.**
+   ```
+   node .claude/skills/i18n-add-locale/scripts/locale-scaffold.mjs \
+     --locale <code> --dry-run
+   ```
+   Lists every SKILL.md / SKILL.md.hbs that lacks a `.<locale>.hbs` sibling.
+3. **Materialize stubs.**
+   ```
+   node .claude/skills/i18n-add-locale/scripts/locale-scaffold.mjs \
+     --locale <code>
+   ```
+   For each missing sibling, copies the English master and prepends a
+   `<!-- LOCALE_TODO: translate body --> ` banner so the translator can grep
+   for pending work.
+4. **Register the locale.** Edit `src/core/render-templates.mjs` and add the
+   code to `SUPPORTED_HUMAN_LANGS`. The renderer picks the variant via
+   `--locale <code>` or `HARNESS_LOCALE` env.
+5. **Verify rendering** by running `agent-harness-kit init --locale <code>`
+   in a scratch dir and grepping the output for `LOCALE_TODO` (must be
+   zero before publishing).
+
+## Output contract
+
+```
+locale: <code>
+scaffolded: <N>
+already-present: <M>
+register-in: src/core/render-templates.mjs (SUPPORTED_HUMAN_LANGS)
+```
+
+## Anti-patterns
+
+- Don't translate the YAML frontmatter — the renderer + Claude Code parse
+  it as machine-readable. Translate only the body markdown.
+- Don't drop the master `.hbs` file. The locale stub *augments*; the
+  renderer falls back to the master when the locale variant is missing.

package/src/templates/.claude/skills/i18n-add-locale/scripts/locale-scaffold.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// locale-scaffold.mjs — deterministic step for /i18n-add-locale.
+// Walks .claude/skills/* (and a small whitelist of other files) and scaffolds
+// missing `.<locale>.hbs` siblings from their English masters.
+//
+// Usage:
+//   locale-scaffold.mjs --locale vi [--dry-run] [--root .claude/skills]
+//
+// A "master" file is either:
+//   - <stem>.md.hbs        → scaffold sibling <stem>.md.<locale>.hbs
+//   - <stem>.md            → scaffold sibling <stem>.md.<locale>.hbs
+//                            (rare; only when no .hbs counterpart exists)
+//
+// Idempotent: if the sibling already exists, the script leaves it alone.
+
+import { readFileSync, existsSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { resolve, join, dirname, basename, relative } from "node:path";
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+function parseArgs(argv) {
+  const out = { locale: null, dryRun: false, roots: [".claude/skills", ".claude/agents"] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--locale") out.locale = argv[++i];
+    else if (argv[i] === "--dry-run") out.dryRun = true;
+    else if (argv[i] === "--root") out.roots = [argv[++i]];
+  }
+  if (!out.locale || !/^[a-z]{2,5}(-[A-Z]{2})?$/.test(out.locale)) {
+    console.error("usage: locale-scaffold.mjs --locale <code> [--dry-run] [--root <dir>]");
+    console.error("  <code> = 2-5 lowercase letters, optional region (e.g. vi, ja, fr-CA)");
+    process.exit(2);
+  }
+  return out;
+}
+
+function* walk(dir) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) yield* walk(full);
+    else yield full;
+  }
+}
+
+function isMaster(path, locale) {
+  // English masters: *.md or *.md.hbs (but NOT *.md.<locale>.hbs already).
+  const name = basename(path);
+  if (!/\.md(?:\.hbs)?$/.test(name)) return false;
+  // Skip locale-specific files of any code.
+  if (/\.md\.[a-z]{2,5}(?:-[A-Z]{2})?\.hbs$/.test(name)) return false;
+  return true;
+}
+
+function siblingPath(masterPath, locale) {
+  // Preserve the master's Handlebars-ness in the variant. Master .md.hbs
+  // → variant .md.<lang>.hbs (Handlebars-active). Master .md (plain) →
+  // variant .md.<lang> (no Handlebars). This matters because plain-md
+  // masters often contain literal `{{...}}` strings as examples (e.g.
+  // XSS demos in security-reviewer.md); promoting them to .hbs would
+  // make Handlebars choke on the example text.
+  const name = basename(masterPath);
+  if (name.endsWith(".md.hbs")) {
+    return join(dirname(masterPath), name.replace(/\.md\.hbs$/, `.md.${locale}.hbs`));
+  }
+  if (name.endsWith(".md")) {
+    return join(dirname(masterPath), name.replace(/\.md$/, `.md.${locale}`));
+  }
+  return null;
+}
+
+function scaffold(masterPath, siblingPathAbs, locale, dryRun) {
+  if (existsSync(siblingPathAbs)) return { status: "skip", reason: "exists" };
+  if (dryRun) return { status: "would-create" };
+  const body = readFileSync(masterPath, "utf8");
+  const banner =
+`<!-- LOCALE_TODO: translate body to ${locale} -->
+<!-- Source: ${relative(ROOT, masterPath)} -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+`;
+  writeFileSync(siblingPathAbs, banner + body);
+  return { status: "created" };
+}
+
+function main() {
+  const { locale, dryRun, roots } = parseArgs(process.argv.slice(2));
+  const masters = [];
+  for (const r of roots) {
+    const abs = resolve(ROOT, r);
+    if (!existsSync(abs)) continue;
+    for (const f of walk(abs)) {
+      if (isMaster(f, locale)) masters.push(f);
+    }
+  }
+  let created = 0;
+  let skipped = 0;
+  const wouldCreate = [];
+  for (const m of masters) {
+    const sib = siblingPath(m, locale);
+    if (!sib) continue;
+    const res = scaffold(m, sib, locale, dryRun);
+    if (res.status === "created") created++;
+    else if (res.status === "would-create") wouldCreate.push(relative(ROOT, sib));
+    else skipped++;
+  }
+  const payload = {
+    locale,
+    dry_run: dryRun,
+    scaffolded: dryRun ? wouldCreate.length : created,
+    already_present: skipped,
+    scanned_masters: masters.length,
+    would_create: dryRun ? wouldCreate : undefined,
+    register_in: "src/core/render-templates.mjs#SUPPORTED_HUMAN_LANGS",
+  };
+  process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+}
+
+main();

package/src/templates/.claude/skills/inspect-app/SKILL.md.vi

@@ -0,0 +1,61 @@
+<!-- LOCALE_TODO: translate body to vi -->
+<!-- Source: .claude/skills/inspect-app/SKILL.md -->
+<!-- Edit only the markdown body — keep frontmatter verbatim so the kit's renderer + Claude Code parse it identically across locales. -->
+
+---
+name: inspect-app
+description: Use this skill whenever the user asks to "test the UI", "check what the app looks like", "inspect the page", "verify the dev server is up", or before claiming a UI feature is done. Boots the dev server via scripts/dev-up.sh and drives the failing flow through Playwright MCP if installed (else falls back to curl + lightweight HTML capture). Mirrors the OpenAI Chrome-DevTools-Protocol-into-runtime pattern at solo scale — verify the running app, don't trust the type checker alone.
+allowed-tools: Read, Bash(scripts/dev-up.sh), Bash(curl:*), Bash(playwright:*), Bash(node:*)
+suggested-turns: 12
+---
+
+## When to use
+
+The user said any of: "what does the page look like", "test the UI flow",
+"is the dev server up", "before merging the UI work", or invoked this skill
+explicitly via `/inspect-app`. Also auto-invokes from `/debug-flow` when the
+bug is UI-shaped.
+
+## Steps
+
+1. **Detect dev server.** Read `harness.config.json` for the framework.
+   - If a process is already listening on the expected port (3000 / 8000 /
+     5000 depending on framework), reuse it.
+   - Else: `bash scripts/dev-up.sh &` in the background and wait up to 30s
+     for the readiness probe.
+2. **Capture mode — Playwright MCP (preferred).** If `mcp__playwright__*`
+   tools are available:
+   - `mcp__playwright__browser_navigate` to the target URL
+   - `mcp__playwright__browser_snapshot` for accessibility tree
+   - `mcp__playwright__browser_take_screenshot` for a visual
+   - Optionally drive a single user flow (click → fill → click → wait)
+3. **Capture mode — curl fallback.** If MCP is unavailable:
+   - `curl -i -s -o response.body "http://localhost:$PORT$PATH"` for headers + body
+   - `wc -l response.body` to size-check
+   - `grep -E '<title>|<h1>' response.body | head -5` for sanity
+4. **Diff against expectation.** If the user gave an expected element /
+   text, grep for it. If not, just report what's on the page.
+5. **Cleanup.** Kill the dev server we started (don't kill ones already
+   running before this session).
+
+## Output contract
+
+```
+### App inspection
+**URL:** http://localhost:<port><path>
+**Status:** <HTTP status>
+**Title:** <page title or first H1>
+**Mode:** playwright-mcp | curl-fallback
+**Screenshot:** <path or "n/a">
+**Findings:** <bulleted list of matches/mismatches against expectation>
+```
+
+## Anti-patterns
+
+- Don't claim a UI feature is done without running this skill once.
+- Don't leave a dev server running after the inspection — kill what you
+  started.
+- Don't grep for "Error" alone as a failure signal — many pages legitimately
+  contain that word. Match against specific expected text instead.
+- Don't take screenshots of pages with secrets or test fixtures with PII —
+  the screenshot lands on disk.