agent-harness-kit 0.5.1 → 0.7.0

package/.claude-plugin/marketplace.json

@@ -11,9 +11,9 @@
       "source": {
         "source": "github",
         "repo": "tuanle96/agent-harness-kit",
-        "ref": "v0.5.1"
+        "ref": "v0.7.0"
       },
-      "version": "0.5.1",
+      "version": "0.7.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.3.0",
+  "version": "0.7.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

@@ -191,6 +191,35 @@ developer. The `eval-runner` skill enforces a per-run budget set in
 | Flask                          | python       | `flask`     | `flask --app app run --debug`          | v0.1   |
 | Go / Rust                      | core only    | none        | (manual)                               | v0.4   |
 
+## CI: real-claude E2E test (v0.7+)
+
+The kit ships a CI job that spawns the real `claude` binary against a fresh
+init of itself and asserts that the SessionStart hook actually fires (with
+the expected `additionalContext` payload). This catches the class of bug
+that v0.6's silent-no-op hooks fell into — every synthetic test passed for
+seven releases while not a single hook ever triggered inside a real Claude
+Code session.
+
+**Behavior:**
+
+- Locally: `npm test` skips the E2E case cleanly when no `ANTHROPIC_API_KEY`
+  is set (1 skip, 0 fail).
+- CI with secret: the `e2e-claude` job runs the driver, installs
+  `@anthropic-ai/claude-code` globally, and exercises one claude turn
+  (~$0.01–0.05). Failure means a hook system regression.
+- CI without secret (fork PRs): emits a GitHub Actions warning and exits 0
+  so the PR can still merge — but you lose the v0.6-class bug guard for
+  that run.
+
+To enable on your own fork: configure the `ANTHROPIC_API_KEY` repository
+secret in GitHub Actions settings.
+
+Local run (uses whatever auth the `claude` binary already has):
+
+```bash
+AHK_E2E_USE_LOCAL_AUTH=1 node scripts/e2e-claude-cli.mjs
+```
+
 ## License
 
 MIT.

package/bin/cli.mjs

@@ -43,6 +43,11 @@ program
     "force init for languages without a structural-test adapter yet (go, rust, swift, kotlin)",
     false,
   )
+  .option(
+    "--lang <code>",
+    "human language for the CLAUDE.md template (en, vi)",
+    "en",
+  )
   .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`)));
@@ -104,7 +109,10 @@ program
     // initing at the root of a Go/Rust/Swift/Kotlin project produces a
     // half-broken harness (structural test missing, ts-morph engine pinned).
     // Skills + reviewers still work, but the user should opt in explicitly.
-    const UNSUPPORTED = new Set(["go", "rust", "swift", "kotlin"]);
+    // Swift + Kotlin shipped regex-based adapters in v0.7; Go + Rust earlier.
+    // No language is "unsupported" today — the set is empty, kept as a hook
+    // for future languages that don't yet have an adapter.
+    const UNSUPPORTED = new Set([]);
     if (UNSUPPORTED.has(stack.language) && !opts.allowUnsupported) {
       console.log(
         pc.yellow(
@@ -187,6 +195,7 @@ program
       installHooks,
       installCi,
       kitVersion: pkg.version,
+      humanLanguage: opts.lang || "en",
     });
 
     console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.5.1",
+  "version": "0.7.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/detect-stack.mjs

@@ -68,6 +68,22 @@ export async function detectStack(cwd) {
   // primary language. Walks 1 level deep into common monorepo dirs.
   await probePolyglot(cwd, result);
 
+  // Rust workspace — must be checked BEFORE package.json because a polyglot
+  // repo (Rust backend + Next.js frontend) typically has BOTH at the root,
+  // and we want the Rust adapter installed by default since structural-test
+  // enforcement matters more for the workspace than for the marketing site.
+  // Single-crate Cargo.toml falls through to the legacy check at the bottom.
+  const rootCargo = await readTextSafe(resolve(cwd, "Cargo.toml"));
+  if (rootCargo && /^\s*\[workspace\]/m.test(rootCargo)) {
+    result.language = "rust";
+    result.framework = "rust-workspace";
+    result.packageManager = "cargo";
+    result.monorepo = true;
+    result.suggestedPreset = "generic";
+    result.availablePresets = ["generic"];
+    return result;
+  }
+
   // JavaScript/TypeScript.
   const pkg = await readJsonSafe(resolve(cwd, "package.json"));
   if (pkg) {
@@ -141,6 +157,22 @@ export async function detectStack(cwd) {
     return result;
   }
 
+  // Swift / Kotlin — regex-based adapters (added in v0.7).
+  if (await exists(resolve(cwd, "Package.swift"))) {
+    result.language = "swift";
+    result.packageManager = "swift";
+    return result;
+  }
+  if (
+    (await exists(resolve(cwd, "build.gradle.kts"))) ||
+    (await exists(resolve(cwd, "settings.gradle.kts"))) ||
+    (await exists(resolve(cwd, "build.gradle")))
+  ) {
+    result.language = "kotlin";
+    result.packageManager = "gradle";
+    return result;
+  }
+
   return result;
 }
 

package/src/core/render-templates.mjs

@@ -43,6 +43,11 @@ const EXEC_BITS = new Set([
   "scripts/precompletion-checklist.sh",
   "scripts/telemetry-on-skill.sh",
   "scripts/harness-report.mjs",
+  // v0.7 hook expansion — SessionStart / PreToolUse / PreCompact / SessionEnd.
+  "scripts/session-start.sh",
+  "scripts/pretooluse-bash-guard.sh",
+  "scripts/pre-compact.sh",
+  "scripts/session-end.sh",
 ]);
 
 export function registerHelpers() {
@@ -86,11 +91,19 @@ async function* walk(dir) {
   }
 }
 
-function buildContext({ projectName, preset, layers, stack, kitVersion }) {
+// SUPPORTED_LANGS — human-language variants the kit ships for CLAUDE.md.
+// Adding a new locale: drop `CLAUDE.md.<code>.hbs` alongside the English
+// CLAUDE.md.hbs, add the code here, and the picker in pathForStack()
+// 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 }) {
   const installCmd = (() => {
     if (stack.language === "python") return "pip install -e '.[dev]'";
     if (stack.language === "go") return "go mod download";
     if (stack.language === "rust") return "cargo build";
+    if (stack.language === "swift") return "swift package resolve";
+    if (stack.language === "kotlin") return "./gradlew build --refresh-dependencies";
     if (stack.packageManager === "pnpm") return "pnpm install";
     if (stack.packageManager === "yarn") return "yarn";
     if (stack.packageManager === "bun") return "bun install";
@@ -109,6 +122,8 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
         if (stack.language === "python") return "python -m app";
         if (stack.language === "go") return "go run ./cmd/...";
         if (stack.language === "rust") return "cargo run";
+        if (stack.language === "swift") return "swift run";
+        if (stack.language === "kotlin") return "./gradlew run";
         return "npm run dev";
     }
   })();
@@ -119,6 +134,8 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
         if (stack.language === "python") return "pytest -x";
         if (stack.language === "go") return "go test ./...";
         if (stack.language === "rust") return "cargo test";
+        if (stack.language === "swift") return "swift test";
+        if (stack.language === "kotlin") return "./gradlew test";
         return "npm test";
     }
   })();
@@ -126,6 +143,8 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
     if (stack.language === "python") return "ruff check .";
     if (stack.language === "go") return "go vet ./...";
     if (stack.language === "rust") return "cargo clippy --all-targets -- -D warnings";
+    if (stack.language === "swift") return "swift build --warnings-as-errors";
+    if (stack.language === "kotlin") return "./gradlew detekt || ./gradlew lint";
     return "npm run lint";
   })();
 
@@ -144,10 +163,13 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
     testCmd,
     lintCmd,
     kitVersion,
+    humanLanguage: humanLanguage || "en",
     isTypescript: stack.language === "typescript",
     isPython: stack.language === "python",
     isGo: stack.language === "go",
     isRust: stack.language === "rust",
+    isSwift: stack.language === "swift",
+    isKotlin: stack.language === "kotlin",
     isNextjs: stack.framework === "nextjs",
     isFastapi: stack.framework === "fastapi",
     isExpress: stack.framework === "express",
@@ -161,7 +183,18 @@ function buildContext({ projectName, preset, layers, stack, kitVersion }) {
 // 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) {
+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
+  // suffixed file is skipped otherwise — and so is the unsuffixed file
+  // when a non-default locale is active, so only one variant lands.
+  if (/^CLAUDE\.md(?:\.[a-z]{2,5})?\.hbs$/.test(rel)) {
+    const m = rel.match(/^CLAUDE\.md(?:\.([a-z]{2,5}))?\.hbs$/);
+    const fileLang = m[1] || "en";
+    if (fileLang !== humanLanguage) return null;
+    return "CLAUDE.md.hbs"; // canonical target — strip locale suffix
+  }
   if (rel.startsWith("_adapter-typescript/")) {
     const stripped = rel.slice("_adapter-typescript/".length);
     if (stack.language === "typescript") return stripped;
@@ -184,6 +217,16 @@ function pathForStack(rel, stack) {
   if (rel.startsWith("_adapter-rust/")) {
     return stack.language === "rust" ? rel.slice("_adapter-rust/".length) : null;
   }
+  if (rel.startsWith("_adapter-swift/")) {
+    const stripped = rel.slice("_adapter-swift/".length);
+    if (stack.language === "swift") return stripped;
+    return null;
+  }
+  if (rel.startsWith("_adapter-kotlin/")) {
+    const stripped = rel.slice("_adapter-kotlin/".length);
+    if (stack.language === "kotlin") return stripped;
+    return null;
+  }
   if (rel.startsWith("_preset-nextjs/")) {
     return stack.framework === "nextjs" ? rel.slice("_preset-nextjs/".length) : null;
   }
@@ -200,6 +243,48 @@ function sha256(buf) {
   return createHash("sha256").update(buf).digest("hex");
 }
 
+// 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
+// install path references it via .claude-plugin/plugin.json. Idempotent:
+// re-running produces the same settings.json bytes when source hasn't
+// changed. Returns {changed, rawContent} for the lockfile.
+export async function mergeHooksIntoSettings(cwd) {
+  const settingsPath = resolve(cwd, ".claude/settings.json");
+  const hooksPath = resolve(cwd, ".claude/hooks/hooks.json");
+  const hooksRaw = await readFile(hooksPath, "utf8");
+  let hooksJson;
+  try {
+    hooksJson = JSON.parse(hooksRaw);
+  } catch (e) {
+    throw new Error(`mergeHooksIntoSettings: invalid JSON in ${hooksPath}: ${e.message}`);
+  }
+  if (!hooksJson.hooks || typeof hooksJson.hooks !== "object") {
+    return { changed: false, rawContent: "" };
+  }
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    const raw = await readFile(settingsPath, "utf8");
+    try {
+      settings = JSON.parse(raw);
+    } catch {
+      // Corrupt settings.json — refuse to clobber user edits. Surface clearly.
+      throw new Error(`mergeHooksIntoSettings: ${settingsPath} is not valid JSON`);
+    }
+    // Idempotency: if hooks key already matches source verbatim, nothing to do.
+    if (
+      settings.hooks &&
+      JSON.stringify(settings.hooks) === JSON.stringify(hooksJson.hooks)
+    ) {
+      return { changed: false, rawContent: Buffer.from(raw) };
+    }
+  }
+  settings.hooks = hooksJson.hooks;
+  const out = JSON.stringify(settings, null, 2) + "\n";
+  await writeFile(settingsPath, out);
+  return { changed: true, rawContent: Buffer.from(out) };
+}
+
 export async function renderAll({
   cwd,
   projectName,
@@ -209,9 +294,15 @@ export async function renderAll({
   installHooks,
   installCi,
   kitVersion,
+  humanLanguage = "en",
 }) {
   registerHelpers();
-  const ctx = buildContext({ projectName, preset, layers, stack, kitVersion });
+  if (!SUPPORTED_HUMAN_LANGS.has(humanLanguage)) {
+    throw new Error(
+      `Unsupported humanLanguage "${humanLanguage}". Supported: ${[...SUPPORTED_HUMAN_LANGS].join(", ")}`,
+    );
+  }
+  const ctx = buildContext({ projectName, preset, layers, stack, kitVersion, humanLanguage });
 
   const written = [];
   const skipped = [];
@@ -219,7 +310,7 @@ export async function renderAll({
 
   for await (const abs of walk(TEMPLATES_ROOT)) {
     const relFromTemplates = relative(TEMPLATES_ROOT, abs).split("\\").join("/");
-    const stackRel = pathForStack(relFromTemplates, stack);
+    const stackRel = pathForStack(relFromTemplates, stack, humanLanguage);
     if (stackRel === null) continue;
     if (relFromTemplates.startsWith("_ci/") && !installCi) continue;
     if (relFromTemplates.includes("hooks.json") && !installHooks) continue;
@@ -258,6 +349,22 @@ export async function renderAll({
     written.push(targetRel);
   }
 
+  // Critical fix (v0.7): merge .claude/hooks/hooks.json into
+  // .claude/settings.json#hooks. Claude Code ONLY reads hooks from
+  // settings.json — a free-standing .claude/hooks/hooks.json is ignored.
+  // Pre-v0.7 the kit silently no-op'd every hook on the scaffold path
+  // because it shipped only the free-standing file. Plugin install path
+  // continues to read .claude/hooks/hooks.json (per plugin.json manifest)
+  // so the file is kept; we just additionally inject it where Claude Code
+  // actually looks.
+  if (installHooks && existsSync(resolve(cwd, ".claude/hooks/hooks.json"))) {
+    const merged = await mergeHooksIntoSettings(cwd);
+    if (merged.changed) {
+      lockfile.files[".claude/settings.json"] = sha256(merged.rawContent);
+      written.push(".claude/settings.json (merged hooks)");
+    }
+  }
+
   // 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/templates/.claude/hooks/hooks.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-hooks.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/session-start.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/pretooluse-bash-guard.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "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
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/pre-compact.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/precompletion-checklist.sh",
+            "timeout": 20
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/session-end.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/templates/CLAUDE.md.hbs

@@ -10,7 +10,7 @@ an encyclopedia.
 - Dev:        `{{devCmd}}`
 - Test:       `{{testCmd}}`
 - Lint:       `{{lintCmd}}`
-- Structural: `{{#if isPython}}python -m harness.structural_test{{else}}{{#if isGo}}go run harness/structural_check.go{{else}}{{#if isRust}}node harness/structural-check.mjs{{else}}npm run harness:check{{/if}}{{/if}}{{/if}}` (must pass before any PR)
+- Structural: `{{#if isPython}}python -m harness.structural_test{{else}}{{#if isGo}}go run harness/structural_check.go{{else}}{{#if isRust}}node harness/structural-check.mjs{{else}}{{#if isSwift}}node harness/structural-check.mjs{{else}}{{#if isKotlin}}node harness/structural-check.mjs{{else}}npm run harness:check{{/if}}{{/if}}{{/if}}{{/if}}{{/if}}` (must pass before any PR)
 
 ## Architecture (brief)
 

package/src/templates/CLAUDE.md.vi.hbs

@@ -0,0 +1,70 @@
+# {{projectName}} — Ghi chú làm việc cho Agent
+
+{{description}} Dự án {{language}}/{{framework}}. Solo-dev hobby. File này
+**cố ý ngắn** — nó là **Mục lục**, không phải Bách khoa toàn thư.
+
+## Build & Run
+
+- Cài đặt:   `{{installCmd}}`
+- Dev:       `{{devCmd}}`
+- Test:      `{{testCmd}}`
+- Lint:      `{{lintCmd}}`
+- Structural: `{{#if isPython}}python -m harness.structural_test{{else}}{{#if isGo}}go run harness/structural_check.go{{else}}{{#if isRust}}node harness/structural-check.mjs{{else}}{{#if isSwift}}node harness/structural-check.mjs{{else}}{{#if isKotlin}}node harness/structural-check.mjs{{else}}npm run harness:check{{/if}}{{/if}}{{/if}}{{/if}}{{/if}}` (phải pass trước mọi PR)
+
+## Kiến trúc (tóm tắt)
+
+Thứ tự layer, ép buộc bằng test cơ học:
+
+**{{layersJoined}}** — code chỉ được phụ thuộc theo chiều tiến. Các mối
+quan tâm cắt ngang (cross-cutting) vào qua `providers/`.
+
+Sơ đồ đầy đủ và lý do: `docs/architecture.md` (chỉ tiếng Anh).
+
+## Nguyên tắc vàng (phải giữ)
+
+1. Ưu tiên utility chung trong `src/shared/` thay vì viết helper mới.
+2. Validate ở biên hệ thống; không bao giờ "đoán mò" hình dạng dữ liệu.
+3. Mỗi test là end-to-end qua một feature trong `feature_list.json`.
+
+Danh sách đầy đủ: `docs/golden-principles.md`.
+
+## Đọc khi cần (read on demand)
+
+- `docs/architecture.md`     — đọc khi thêm module hoặc dời code.
+- `docs/adr/`                — đọc khi đổi public API.
+- `docs/golden-principles.md` — đọc trước mọi refactor.
+- `feature_list.json`        — đọc trước khi tuyên bố một feature đã xong.
+- `.harness/PROGRESS.md`     — đọc đầu session; ghi cuối session.
+
+## Skills nên dùng
+
+- `/inspect-module <path>`            khi cần hiểu code đã có.
+- `/add-feature <description>`        khi thêm khả năng mới — không freestyle.
+- `/structural-test-author <layer>`   khi thêm rule kiến trúc mới.
+- `/garbage-collection`               mỗi thứ Sáu hoặc trước khi tag release.
+- `/eval-runner`                      trước khi merge bất kỳ thay đổi nào ở skill / agent file.
+
+## Subagents nên ủy thác (KHÔNG inline review)
+
+- `architecture-reviewer` — cho mọi thay đổi cross-layer.
+- `security-reviewer`     — cho mọi thay đổi liên quan auth, input, secret.
+- `reliability-reviewer`  — cho mọi error path mới, retry loop, async boundary.
+
+## Workflow contract
+
+1. Bắt đầu session: chạy `/inspect-module .` và đọc `.harness/PROGRESS.md`.
+2. Chọn MỘT feature trong `feature_list.json` có `passes: false`.
+3. Triển khai. Chạy structural test. Nếu fail thì FIX trước khi tiếp tục.
+4. Tự verify bằng subagent reviewer phù hợp.
+5. Commit với message mô tả. Append một dòng vào `.harness/PROGRESS.md`.
+6. Update `feature_list.json` (`passes: true`) **chỉ khi** end-to-end test pass.
+
+## Cấm
+
+- Không thêm layer mới mà không có ADR.
+- Không disable structural test để PR pass.
+- Không viết code mà structural test không thể phân tích (no dynamic
+  imports across layers).
+- Không update CLAUDE.md mà không qua `/propose-harness-improvement`.
+- Không cho CLAUDE.md vượt 200 instruction (hoặc maxTokens nếu đã set)
+  — Stop hook sẽ block. Phần thừa cho vào `docs/` hoặc @-import.