agent-harness-kit 0.3.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "agent-harness-kit-marketplace",
+  "owner": {
+    "name": "Tuan Le"
+  },
+  "description": "Solo-dev harness engineering kit for Claude Code.",
+  "plugins": [
+    {
+      "name": "agent-harness-kit",
+      "source": {
+        "source": "github",
+        "repo": "tuanle96/agent-harness-kit",
+        "ref": "v0.3.0"
+      },
+      "version": "0.3.0",
+      "description": "Solo-dev harness engineering kit — layered architecture, GC ritual, structural tests, review subagents.",
+      "category": "development",
+      "keywords": [
+        "harness",
+        "architecture",
+        "review",
+        "solo-dev"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "agent-harness-kit",
+  "version": "0.3.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"
+  },
+  "homepage": "https://github.com/tuanle96/agent-harness-kit",
+  "repository": "https://github.com/tuanle96/agent-harness-kit",
+  "license": "MIT",
+  "keywords": [
+    "harness-engineering",
+    "claude-code",
+    "structural-tests",
+    "layered-architecture",
+    "solo-dev",
+    "code-review",
+    "agents",
+    "skills"
+  ],
+  "skills": "./src/templates/.claude/skills/",
+  "agents": "./src/templates/.claude/agents/",
+  "hooks": "./src/templates/.claude/hooks/hooks.json",
+  "commands": "./src/templates/.claude/skills/"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tuan Le
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# agent-harness-kit
+
+Solo-dev harness engineering kit for Claude Code. One command, ~30 minutes,
+and your hobby project gets the patterns OpenAI used to ship 1M lines of
+agent-generated code: layered architecture, structural tests, garbage
+collection, review subagents, JSON feature tracking, and pre-completion
+checklists — without the Stripe/OpenAI overhead.
+
+## Why
+
+- Claude Code 2.1+ merged slash commands and Skills into one format.
+- Plugins are now a stable distribution channel.
+- LangChain proved harness changes alone can take a coding agent from Top 30
+  to Top 5 on Terminal-Bench 2.0.
+- Mitchell Hashimoto's "engineer the harness" + Anthropic's two-fold
+  initializer/coding-agent pattern + OpenAI's golden-principles GC ritual
+  scale down nicely to one developer.
+
+## Install
+
+Option A: scaffold into an existing repo
+
+```bash
+npx agent-harness-kit init
+```
+
+Option B: install as a Claude Code plugin
+
+```text
+/plugin marketplace add tuanle96/agent-harness-kit
+/plugin install agent-harness-kit@agent-harness-kit-marketplace
+```
+
+## What ships
+
+- 10 skills (`inspect-module`, `add-feature`, `garbage-collection`,
+  `propose-harness-improvement`, `write-skill`, `debug-flow`, `eval-runner`,
+  `add-adr`, `doc-drift-scan`, `structural-test-author`)
+- 5 read-only review subagents (`architecture-reviewer`, `security-reviewer`,
+  `reliability-reviewer`, `performance-reviewer`, `api-consistency-reviewer`)
+- 1 PostToolUse hook (structural-test on every edit) + 1 Stop hook
+  (pre-completion checklist with `stop_hook_active` loop guard)
+- TypeScript adapter (ts-morph + eslint-plugin-boundaries +
+  dependency-cruiser)
+- Python adapter (libcst + import-linter)
+- Eval harness (outcome / process / style / efficiency dimensions)
+
+## Slash commands generated
+
+| Command                          | Purpose                                                  |
+| -------------------------------- | -------------------------------------------------------- |
+| `/inspect-module <path>`         | Map a module before editing                              |
+| `/add-feature <description>`     | Implement one item from `feature_list.json`              |
+| `/garbage-collection`            | Friday cleanup (top-3 fixes only at solo scale)          |
+| `/structural-test-author`        | Codify a new architectural rule mechanically             |
+| `/propose-harness-improvement`   | Convert an agent failure into a permanent prevention     |
+| `/eval-runner`                   | Regression-test the harness itself                       |
+| `/write-skill`                   | Create a new SKILL.md with valid frontmatter             |
+| `/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                    |
+
+## Philosophy (4 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
+   is ~100 lines). The kit's CLAUDE.md is 50–80 lines.
+2. **Every agent failure becomes a permanent harness change** (Hashimoto's
+   discipline). The `/propose-harness-improvement` skill enforces this.
+3. **Computational sensors before LLM sensors** (Fowler/Böckeler). The TS and
+   Python adapters ship one deterministic structural test per language; LLM
+   subagents are reserved for semantic judgment.
+4. **Garbage collection over Friday cleanup, scaled to solo** (OpenAI's
+   ritual, shrunk to top-3 fixes per week).
+
+## Directory the kit drops into your repo
+
+```text
+your-repo/
+├── CLAUDE.md                          # 50–80 line table of contents
+├── AGENTS.md                          # symlink → CLAUDE.md
+├── docs/
+│   ├── architecture.md
+│   ├── core-beliefs.md
+│   ├── golden-principles.md
+│   ├── tech-debt-tracker.md
+│   └── adr/
+│       └── 0001-use-agent-harness-kit.md
+├── feature_list.json                  # JSON, not Markdown — Anthropic pattern
+├── harness.config.json
+├── .claude/
+│   ├── settings.json
+│   ├── skills/                        # 10 skills as SKILL.md files
+│   ├── agents/                        # 5 reviewer personas
+│   └── hooks/hooks.json
+├── .harness/
+│   ├── installed.json                 # kit lockfile (sha-tracked)
+│   ├── PROGRESS.md                    # session log
+│   └── structural-baseline.json       # existing-violation baseline
+└── scripts/
+    ├── structural-test-on-edit.sh     # PostToolUse hook target
+    ├── precompletion-checklist.sh     # Stop hook target
+    ├── dev-up.sh
+    ├── pre-push.sh
+    └── install-git-hooks.sh
+```
+
+## Configuration (`harness.config.json`)
+
+```json
+{
+  "version": "0.1.0",
+  "language": "typescript",
+  "framework": "nextjs",
+  "preset": "nextjs",
+  "domains": [
+    {
+      "name": "default",
+      "root": "src",
+      "layers": ["types", "config", "repo", "service", "runtime", "ui"]
+    }
+  ],
+  "providers": ["auth", "telemetry", "feature-flags"],
+  "models": {
+    "main": "claude-sonnet-4-6",
+    "reviewers": "claude-sonnet-4-6",
+    "explore": "claude-haiku-4-5"
+  },
+  "budgets": { "perRunUsd": 2.0, "perDayUsd": 10.0 }
+}
+```
+
+## CLI commands
+
+```text
+agent-harness-kit init        # scaffold a repo (interactive)
+agent-harness-kit init --yes  # accept all detected defaults
+agent-harness-kit upgrade     # non-destructive upgrade, preserves user edits
+agent-harness-kit doctor      # diagnose installed kit + Claude Code env
+agent-harness-kit --version
+```
+
+## Token / cost expectations
+
+A typical day with the default model split (Sonnet 4.6 main + Haiku 4.5
+explore + Sonnet 4.6 reviewers) stays under ~$2 of API traffic for a single
+developer. The `eval-runner` skill enforces a per-run budget set in
+`harness.config.json`.
+
+## Support matrix
+
+| Stack                          | Adapter      | Preset      | Dev command                            | Status |
+| ------------------------------ | ------------ | ----------- | -------------------------------------- | ------ |
+| Next.js 14 + TypeScript        | typescript   | `nextjs`    | `npm run dev`                          | v0.1   |
+| Express                        | typescript   | `node-api`  | `node ./src/server.js`                 | v0.1   |
+| Fastify                        | typescript   | `node-api`  | `node ./src/server.js`                 | v0.1   |
+| NestJS                         | typescript   | `node-api`  | `npm run start:dev`                    | v0.1   |
+| FastAPI                        | python       | `fastapi`   | `uvicorn app.main:app --reload`        | v0.1   |
+| Django                         | python       | `django`    | `python manage.py runserver`           | v0.1   |
+| Flask                          | python       | `flask`     | `flask --app app run --debug`          | v0.1   |
+| Go / Rust                      | core only    | none        | (manual)                               | v0.4   |
+
+## License
+
+MIT.

package/bin/cli.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// agent-harness-kit CLI — solo-dev harness scaffolder for Claude Code.
+// Implements: init, upgrade, doctor.
+
+import { Command } from "commander";
+import { input, select, confirm } from "@inquirer/prompts";
+import pc from "picocolors";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+
+import { detectStack } from "../src/core/detect-stack.mjs";
+import { renderAll } from "../src/core/render-templates.mjs";
+import { upgrade } from "../src/core/upgrade.mjs";
+import { doctor } from "../src/core/doctor.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgJsonPath = resolve(__dirname, "..", "package.json");
+const pkg = JSON.parse(await readFile(pkgJsonPath, "utf8"));
+
+const program = new Command();
+program
+  .name("agent-harness-kit")
+  .description(
+    "Solo-dev harness engineering kit for Claude Code (skills + subagents + hooks + structural tests).",
+  )
+  .version(pkg.version);
+
+program
+  .command("init")
+  .description("Scaffold the harness into the current repository")
+  .option("-y, --yes", "accept all detected defaults", false)
+  .option("--cwd <path>", "target directory (defaults to process.cwd())")
+  .option("--no-hooks", "skip hook installation")
+  .option("--no-ci", "skip GitHub Actions workflow")
+  .option(
+    "--allow-polyglot-root",
+    "force init at the root of a polyglot monorepo (not recommended — kit enforces one layered architecture per init)",
+    false,
+  )
+  .option(
+    "--allow-unsupported",
+    "force init for languages without a structural-test adapter yet (go, rust, swift, kotlin)",
+    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`)));
+    console.log(`Target: ${pc.dim(cwd)}\n`);
+
+    const stack = await detectStack(cwd);
+    console.log(
+      `Detected: ${pc.green(stack.language)} / ${pc.green(stack.framework ?? "generic")} ` +
+        `(package manager: ${pc.green(stack.packageManager)}` +
+        (stack.monorepo ? `, ${pc.yellow("monorepo")}` : "") +
+        ")\n",
+    );
+
+    if (stack.polyglotSignals.length >= 2 && stack.appCandidates.length > 0) {
+      console.log(pc.yellow("⚠  Polyglot monorepo detected."));
+      console.log(
+        `   Languages found in subdirectories: ${pc.yellow(stack.polyglotSignals.join(", "))}.`,
+      );
+      console.log(
+        `   The kit's structural test enforces ${pc.yellow("one")} layered architecture per repo.`,
+      );
+      console.log(
+        `   ${pc.bold("Recommended:")} run \`agent-harness-kit init\` once per app instead of at the root:`,
+      );
+      for (const app of stack.appCandidates.slice(0, 5)) {
+        console.log(`     ${pc.dim("→")} cd ${app.path} && agent-harness-kit init  ${pc.dim("# " + app.languages.join("+"))}`);
+      }
+      if (stack.appCandidates.length > 5) {
+        console.log(pc.dim(`     ...and ${stack.appCandidates.length - 5} more.`));
+      }
+      console.log("");
+
+      if (!opts.allowPolyglotRoot) {
+        if (opts.yes) {
+          console.error(
+            pc.red(
+              `Aborting: refusing to init at the root of a polyglot monorepo in --yes mode.`,
+            ),
+          );
+          console.error(
+            pc.dim(
+              `  Run init in each app directory above, or pass --allow-polyglot-root to override.`,
+            ),
+          );
+          process.exit(1);
+        }
+        const ok = await confirm({
+          message: "Continue init at root anyway?",
+          default: false,
+        });
+        if (!ok) {
+          console.log(pc.yellow("Aborted. Run init inside one of the listed app directories."));
+          process.exit(0);
+        }
+      }
+    }
+
+    // Unsupported-language guard. Kit ships TS + Python adapters today;
+    // 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"]);
+    if (UNSUPPORTED.has(stack.language) && !opts.allowUnsupported) {
+      console.log(
+        pc.yellow(
+          `⚠  No structural-test adapter for ${pc.bold(stack.language)} yet (deferred to v0.4).`,
+        ),
+      );
+      console.log(
+        pc.dim(
+          `   You'll get skills + reviewers + hooks, but \`harness:check\` will be a no-op.`,
+        ),
+      );
+      if (opts.yes) {
+        console.error(
+          pc.red(`Aborting: pass --allow-unsupported to init anyway, or wait for v0.4.`),
+        );
+        process.exit(1);
+      }
+      const ok = await confirm({
+        message: `Continue with the generic harness (skills + reviewers only)?`,
+        default: false,
+      });
+      if (!ok) {
+        console.log(pc.yellow("Aborted."));
+        process.exit(0);
+      }
+    }
+
+    let projectName = stack.suggestedName;
+    let preset = stack.suggestedPreset;
+    let layers = ["types", "config", "repo", "service", "runtime", "ui"];
+    let installHooks = opts.hooks !== false;
+    let installCi = opts.ci !== false;
+
+    if (!opts.yes) {
+      projectName = await input({
+        message: "Project name",
+        default: stack.suggestedName,
+      });
+
+      const presetChoices = stack.availablePresets.map((p) => ({
+        name: p,
+        value: p,
+      }));
+      presetChoices.push({ name: "(none — generic)", value: "generic" });
+      preset = await select({
+        message: "Preset",
+        default: stack.suggestedPreset,
+        choices: presetChoices,
+      });
+
+      const layersOk = await confirm({
+        message: `Use default layer order [${layers.join(" → ")}]?`,
+        default: true,
+      });
+      if (!layersOk) {
+        const custom = await input({
+          message: "Custom layer order (comma separated, low → high)",
+          default: layers.join(","),
+        });
+        layers = custom.split(",").map((s) => s.trim()).filter(Boolean);
+      }
+
+      installHooks = await confirm({
+        message: "Install Claude Code hooks (PostToolUse + Stop)?",
+        default: true,
+      });
+
+      installCi = await confirm({
+        message: "Set up GitHub Actions nightly eval workflow?",
+        default: false,
+      });
+    }
+
+    const result = await renderAll({
+      cwd,
+      projectName,
+      preset,
+      layers,
+      stack,
+      installHooks,
+      installCi,
+      kitVersion: pkg.version,
+    });
+
+    console.log("");
+    for (const f of result.written) {
+      console.log(`  ${pc.green("✓")} ${pc.dim("wrote")} ${f}`);
+    }
+    if (result.skipped.length > 0) {
+      console.log("");
+      for (const f of result.skipped) {
+        console.log(`  ${pc.yellow("~")} ${pc.dim("skipped (existed)")} ${f}`);
+      }
+    }
+
+    console.log(pc.bold("\nNext steps:"));
+    const nextSteps = renderNextSteps(stack);
+    nextSteps.forEach((s, i) => console.log(`  ${i + 1}. ${s}`));
+    console.log("");
+  });
+
+program
+  .command("upgrade")
+  .description("Upgrade installed kit version, preserving user edits")
+  .option("--cwd <path>", "target directory (defaults to process.cwd())")
+  .option("-y, --yes", "apply without confirmation prompts", false)
+  .action(async (opts) => {
+    const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+    await upgrade({ cwd, kitVersion: pkg.version, yes: opts.yes });
+  });
+
+program
+  .command("doctor")
+  .description("Diagnose installed kit + Claude Code environment")
+  .option("--cwd <path>", "target directory (defaults to process.cwd())")
+  .action(async (opts) => {
+    const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+    await doctor({ cwd, kitVersion: pkg.version });
+  });
+
+function renderNextSteps(stack) {
+  const out = [];
+  if (stack.language === "typescript") {
+    out.push(`Run ${pc.cyan("npm install")} to install dev dependencies.`);
+  } else if (stack.language === "python") {
+    out.push(
+      `Run ${pc.cyan("pip install -e '.[dev]'")} (or your tool of choice) to pull dev deps.`,
+    );
+  } else {
+    out.push(
+      `Install your language's deps manually — kit shipped without an adapter for ${pc.yellow(stack.language)}.`,
+    );
+  }
+  out.push(
+    `Run ${pc.cyan("bash scripts/install-git-hooks.sh")} to enable pre-push checks.`,
+  );
+  out.push(
+    `Open Claude Code in this repo and run ${pc.cyan("/inspect-module .")} to bootstrap context.`,
+  );
+  out.push(
+    `Try ${pc.cyan("/add-feature \"a small first feature\"")} to see the workflow end-to-end.`,
+  );
+  return out;
+}
+
+program.parseAsync(process.argv).catch((err) => {
+  if (err && err.name === "ExitPromptError") {
+    console.error(pc.yellow("\naborted by user."));
+    process.exit(130);
+  }
+  console.error(pc.red("\nagent-harness-kit failed:"));
+  console.error(err && err.stack ? err.stack : err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "agent-harness-kit",
+  "version": "0.3.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": {
+    "agent-harness-kit": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "schema.json",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "claude-code",
+    "harness-engineering",
+    "layered-architecture",
+    "structural-tests",
+    "solo-dev",
+    "code-review",
+    "agents",
+    "skills"
+  ],
+  "author": "Tuan Le",
+  "license": "MIT",
+  "homepage": "https://github.com/tuanle96/agent-harness-kit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tuanle96/agent-harness-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tuanle96/agent-harness-kit/issues"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "lint": "echo 'no-op (kit is plain ESM JS)'",
+    "selftest": "node bin/cli.mjs --version"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "commander": "^12.1.0",
+    "handlebars": "^4.7.8",
+    "picocolors": "^1.1.1"
+  },
+  "peerDependencies": {
+    "ts-morph": ">=24",
+    "eslint-plugin-boundaries": ">=5",
+    "dependency-cruiser": ">=16"
+  },
+  "peerDependenciesMeta": {
+    "ts-morph": { "optional": true },
+    "eslint-plugin-boundaries": { "optional": true },
+    "dependency-cruiser": { "optional": true }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}