agent-harness-kit 0.3.0

package/src/templates/_adapter-typescript/harness/eval-runner.mjs

@@ -0,0 +1,322 @@
+// harness/eval-runner.mjs — drive Claude Code through .harness/eval/tasks/*.json
+// and grade each on outcome / process / style / efficiency.
+//
+// Per-task JSONL row goes to .harness/eval/results/<sha>.jsonl. On regression
+// (any task failing in CI), exit 1 so the workflow blocks merge.
+//
+// Transports:
+//   --transport=claude-cli  spawn `claude -p` and capture stream-json transcript (default)
+//   --transport=mock        synthetic transcript — use in CI smoke-tests, no API key needed
+//
+// Sets:
+//   --quick                 first 3 tasks (~$0.30, ~2 min on Sonnet)
+//   --full                  all tasks (~$2, ~15 min)
+//   --tasks <glob>          custom set
+//
+// Usage:
+//   node harness/eval-runner.mjs --quick
+//   node harness/eval-runner.mjs --full --transport=mock     # CI smoke-test
+//   node harness/eval-runner.mjs --tasks 01-trivial-endpoint.json
+
+import { readFile, writeFile, mkdir, readdir, appendFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { spawn, execSync } from "node:child_process";
+import { argv, exit, env, cwd } from "node:process";
+
+function parseArgs(argv) {
+  const opts = {
+    quick: false,
+    full: false,
+    tasksGlob: null,
+    transport: "claude-cli",
+    out: null,
+  };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--quick") opts.quick = true;
+    else if (a === "--full") opts.full = true;
+    else if (a === "--tasks") opts.tasksGlob = argv[++i];
+    else if (a.startsWith("--tasks=")) opts.tasksGlob = a.slice("--tasks=".length);
+    else if (a === "--transport") opts.transport = argv[++i];
+    else if (a.startsWith("--transport=")) opts.transport = a.slice("--transport=".length);
+    else if (a === "--out") opts.out = argv[++i];
+    else if (a.startsWith("--out=")) opts.out = a.slice("--out=".length);
+    else if (a === "--help" || a === "-h") {
+      console.log(USAGE);
+      exit(0);
+    }
+  }
+  return opts;
+}
+
+const USAGE = `Usage: node harness/eval-runner.mjs [--quick|--full|--tasks <glob>] [--transport <name>]
+
+Transports:
+  claude-cli   (default)  spawn \`claude -p\` and capture stream-json
+  mock                    synthetic transcript for CI smoke-tests
+
+See PUBLISHING.md for token budget and cost notes.`;
+
+async function loadTasks(opts) {
+  const dir = resolve(cwd(), ".harness/eval/tasks");
+  if (!existsSync(dir)) {
+    console.error(`No tasks directory at ${dir}. Run \`agent-harness-kit init\` first.`);
+    exit(1);
+  }
+  let files = (await readdir(dir)).filter((f) => f.endsWith(".json")).sort();
+  if (opts.tasksGlob) {
+    files = files.filter((f) => f === opts.tasksGlob || f.includes(opts.tasksGlob));
+  } else if (opts.quick) {
+    files = files.slice(0, 3);
+  }
+  const tasks = [];
+  for (const f of files) {
+    const t = JSON.parse(await readFile(join(dir, f), "utf8"));
+    tasks.push({ ...t, _file: join(dir, f) });
+  }
+  return tasks;
+}
+
+// ---- transports ----
+
+const TRANSPORTS = {
+  // Real driver: spawn `claude -p` with stream-json output and flatten the
+  // wire format into the same shape the mock transport produces (so the
+  // graders don't have to know about both shapes).
+  //
+  // Real wire format (Claude Code 2.1.x):
+  //   {type:"assistant", message:{content:[{type:"tool_use", name, input}]}}
+  //   {type:"user", message:{content:[{type:"tool_result", ...}]}}
+  //   {type:"result", usage:{input_tokens, output_tokens, cache_*}, total_cost_usd}
+  //
+  // Flat shape graders consume:
+  //   {type:"tool_use", tool:<name>, path:<input.file_path|input.path>}
+  //   {type:"token_usage", total:<sum of all token fields>}
+  "claude-cli": (task) =>
+    new Promise((resolve, reject) => {
+      const proc = spawn(
+        "claude",
+        [
+          "-p",
+          task.input,
+          "--output-format",
+          "stream-json",
+          "--verbose",
+          "--max-turns",
+          "20",
+        ],
+        { stdio: ["ignore", "pipe", "pipe"] },
+      );
+      const events = [];
+      let stderr = "";
+      let buf = "";
+      const ingest = (raw) => {
+        // Always keep the raw event for debugging.
+        events.push({ raw, type: raw.type });
+        // Flatten tool_use blocks from assistant messages.
+        if (raw.type === "assistant" && raw.message?.content) {
+          for (const block of raw.message.content) {
+            if (block.type !== "tool_use") continue;
+            // /skill invocations come in as the Skill tool with input.skill.
+            if (block.name === "Skill" && block.input?.skill) {
+              events.push({ type: "tool_use", tool: block.input.skill });
+            }
+            const path =
+              block.input?.file_path ?? block.input?.path ?? null;
+            events.push({ type: "tool_use", tool: block.name, path });
+          }
+        }
+        // Final result has aggregated usage.
+        if (raw.type === "result" && raw.usage) {
+          const u = raw.usage;
+          const total =
+            (u.input_tokens ?? 0) +
+            (u.output_tokens ?? 0) +
+            (u.cache_creation_input_tokens ?? 0) +
+            (u.cache_read_input_tokens ?? 0);
+          events.push({ type: "token_usage", total });
+        }
+      };
+      proc.stdout.on("data", (chunk) => {
+        buf += chunk.toString();
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            ingest(JSON.parse(line));
+          } catch {
+            /* non-JSON line (rare) — ignore */
+          }
+        }
+      });
+      proc.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+      proc.on("error", reject);
+      proc.on("exit", (code) => {
+        if (code !== 0) {
+          return reject(new Error(`claude exited ${code}: ${stderr.slice(0, 500)}`));
+        }
+        resolve({ events, stderr });
+      });
+    }),
+
+  // Mock transport — produces a synthetic transcript that satisfies the
+  // default expectations of the shipped tasks. Used in CI to verify the
+  // driver shape end-to-end without burning API tokens.
+  mock: async (task) => {
+    const expected = task.expected ?? {};
+    const events = [];
+    for (const skill of expected.skillsInvoked ?? []) {
+      events.push({ type: "tool_use", tool: skill });
+    }
+    const minFiles = expected.filesChanged?.min ?? 1;
+    for (let i = 0; i < minFiles; i++) {
+      events.push({ type: "tool_use", tool: "Write", path: `src/mock-${i}.ts` });
+    }
+    events.push({
+      type: "token_usage",
+      total: Math.min(expected.tokensMax ?? 5000, 5000),
+    });
+    return { events, stderr: "" };
+  },
+};
+
+// ---- graders ----
+
+function gradeOutcome(task) {
+  if (task.expected?.structuralTest !== "pass") {
+    return { dim: "outcome", score: null, info: "no expectation" };
+  }
+  try {
+    execSync("npm run --silent harness:check", { stdio: "ignore" });
+    return { dim: "outcome", score: 1, info: "structural test passed" };
+  } catch {
+    return { dim: "outcome", score: 0, info: "structural test failed" };
+  }
+}
+
+function gradeProcess(task, transcript) {
+  const expected = task.expected?.skillsInvoked ?? [];
+  if (expected.length === 0) return { dim: "process", score: null };
+  const invoked = new Set(
+    transcript.events.filter((e) => e.type === "tool_use").map((e) => e.tool),
+  );
+  const missing = expected.filter((s) => !invoked.has(s));
+  return {
+    dim: "process",
+    score: missing.length === 0 ? 1 : 0,
+    info:
+      missing.length === 0
+        ? "all expected skills invoked"
+        : `missing skills: ${missing.join(", ")}`,
+  };
+}
+
+function gradeStyle(task, transcript) {
+  const range = task.expected?.filesChanged;
+  if (!range) return { dim: "style", score: null };
+  const writes = transcript.events.filter(
+    (e) => e.type === "tool_use" && (e.tool === "Write" || e.tool === "Edit" || e.tool === "MultiEdit"),
+  );
+  const distinct = new Set(writes.map((e) => e.path).filter(Boolean)).size;
+  const ok = distinct >= range.min && distinct <= range.max;
+  return {
+    dim: "style",
+    score: ok ? 1 : 0,
+    info: `${distinct} files changed (expected ${range.min}-${range.max})`,
+  };
+}
+
+function gradeEfficiency(task, transcript) {
+  const cap = task.expected?.tokensMax;
+  if (!cap) return { dim: "efficiency", score: null };
+  const tokens = transcript.events
+    .filter((e) => e.type === "token_usage")
+    .reduce((sum, e) => sum + (e.total ?? 0), 0);
+  return {
+    dim: "efficiency",
+    score: tokens <= cap ? 1 : 0,
+    info: `${tokens} tokens (cap ${cap})`,
+  };
+}
+
+function gitSha() {
+  try {
+    return execSync("git rev-parse --short HEAD", { stdio: ["ignore", "pipe", "ignore"] })
+      .toString()
+      .trim();
+  } catch {
+    return "no-git";
+  }
+}
+
+export async function runEval(opts = {}) {
+  const tasks = await loadTasks(opts);
+  if (tasks.length === 0) {
+    console.error("No tasks matched.");
+    return { results: [], passed: 0 };
+  }
+  const transport = TRANSPORTS[opts.transport ?? "claude-cli"];
+  if (!transport) {
+    console.error(
+      `Unknown transport: ${opts.transport}. Try: ${Object.keys(TRANSPORTS).join(", ")}`,
+    );
+    exit(2);
+  }
+
+  const sha = gitSha();
+  const outPath = opts.out ?? resolve(cwd(), `.harness/eval/results/${sha}.jsonl`);
+  await mkdir(dirname(outPath), { recursive: true });
+
+  const results = [];
+  for (const task of tasks) {
+    let transcript;
+    try {
+      transcript = await transport(task);
+    } catch (err) {
+      transcript = { events: [], stderr: err.message };
+    }
+    const grades = [
+      gradeOutcome(task),
+      gradeProcess(task, transcript),
+      gradeStyle(task, transcript),
+      gradeEfficiency(task, transcript),
+    ].filter((g) => g.score !== null);
+
+    const passed = grades.length > 0 && grades.every((g) => g.score === 1);
+    const row = {
+      taskId: task.id,
+      sha,
+      ts: new Date().toISOString(),
+      grades,
+      passed,
+    };
+    results.push(row);
+    await appendFile(outPath, JSON.stringify(row) + "\n");
+  }
+
+  return { results, passed: results.filter((r) => r.passed).length, outPath, sha };
+}
+
+function summarize({ results, passed, outPath, sha }) {
+  console.log(`\nEval run ${sha} — ${passed}/${results.length} passed (${outPath})`);
+  for (const r of results) {
+    const mark = r.passed ? "✓" : "✗";
+    console.log(`  ${mark} ${r.taskId}`);
+    for (const g of r.grades) {
+      const m = g.score === 1 ? "✓" : "✗";
+      console.log(`      ${m} ${g.dim}: ${g.info}`);
+    }
+  }
+}
+
+// CLI entry — only runs when invoked directly, not when imported by tests.
+if (import.meta.url === `file://${argv[1]}`) {
+  const opts = parseArgs(argv);
+  const summary = await runEval(opts);
+  summarize(summary);
+  if (env.CI === "true" && summary.passed < summary.results.length) exit(1);
+}

package/src/templates/_adapter-typescript/harness/structural-test.mjs

@@ -0,0 +1,125 @@
+// harness/structural-test.mjs — forward-only layer enforcement.
+//
+// Reads harness.config.json. For each domain, parses every source file's
+// imports (via ts-morph) and asserts that no import goes "backward" through
+// the layer order. New violations on existing code are baselined into
+// .harness/structural-baseline.json on first run.
+//
+// Exit codes:
+//   0 — clean (or only baselined violations)
+//   2 — new violations found (Claude Code reads stderr and re-prompts)
+
+import { readFileSync, existsSync, writeFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { mkdirSync } from "node:fs";
+
+let Project;
+try {
+  ({ Project } = await import("ts-morph"));
+} catch {
+  console.error(
+    "ts-morph is not installed. Run `npm install --save-dev ts-morph`.",
+  );
+  process.exit(1);
+}
+
+const ROOT = process.cwd();
+const cfg = JSON.parse(readFileSync(resolve(ROOT, "harness.config.json"), "utf8"));
+const baselinePath = resolve(ROOT, ".harness/structural-baseline.json");
+const baseline = existsSync(baselinePath)
+  ? new Set(JSON.parse(readFileSync(baselinePath, "utf8")))
+  : new Set();
+
+// CLI flag --file <path> scopes the check to one file (used by the hook).
+const args = process.argv.slice(2);
+let scopedFile = null;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--file" && i + 1 < args.length) scopedFile = resolve(ROOT, args[i + 1]);
+}
+
+function layerOf(filePath) {
+  for (const d of cfg.domains) {
+    if (!filePath.includes(`/${d.root}/`) && !filePath.endsWith(`/${d.root}`)) {
+      // also accept relative match
+      const rel = filePath.startsWith(ROOT) ? filePath.slice(ROOT.length + 1) : filePath;
+      if (!rel.startsWith(d.root)) continue;
+    }
+    for (const layer of d.layers) {
+      if (filePath.includes(`/${layer}/`) || filePath.endsWith(`/${layer}.ts`)) {
+        return { layer, domain: d };
+      }
+    }
+  }
+  return null;
+}
+
+function indexOf(layer, layers) {
+  return layers.indexOf(layer);
+}
+
+const project = new Project({
+  tsConfigFilePath: existsSync(resolve(ROOT, "tsconfig.json"))
+    ? resolve(ROOT, "tsconfig.json")
+    : undefined,
+  skipAddingFilesFromTsConfig: false,
+});
+if (!existsSync(resolve(ROOT, "tsconfig.json"))) {
+  project.addSourceFilesAtPaths("**/*.{ts,tsx,mts,cts}");
+}
+
+const violations = [];
+for (const sf of project.getSourceFiles()) {
+  const sourcePath = sf.getFilePath();
+  if (scopedFile && sourcePath !== scopedFile) continue;
+  const src = layerOf(sourcePath);
+  if (!src) continue;
+  const sourceIdx = indexOf(src.layer, src.domain.layers);
+
+  for (const imp of sf.getImportDeclarations()) {
+    const target = imp.getModuleSpecifierSourceFile();
+    if (!target) continue;
+    const tgt = layerOf(target.getFilePath());
+    if (!tgt || tgt.domain.name !== src.domain.name) continue;
+    const targetIdx = indexOf(tgt.layer, tgt.domain.layers);
+    // forward-only: source layer index must be >= target layer index
+    if (sourceIdx < targetIdx) {
+      const key = `${sourcePath}::${target.getFilePath()}`;
+      if (baseline.has(key)) continue;
+      violations.push({
+        file: sourcePath,
+        line: imp.getStartLineNumber(),
+        from: src.layer,
+        to: tgt.layer,
+        domain: src.domain.name,
+        key,
+      });
+    }
+  }
+}
+
+// First-run baseline behavior: if no baseline file exists, write the current
+// set as the baseline and exit clean. Subsequent runs only block on NEW
+// violations.
+if (!existsSync(baselinePath) && violations.length > 0) {
+  mkdirSync(dirname(baselinePath), { recursive: true });
+  writeFileSync(baselinePath, JSON.stringify(violations.map((v) => v.key), null, 2) + "\n");
+  console.log(
+    `✓ structural test: baselined ${violations.length} existing violations (.harness/structural-baseline.json).`,
+  );
+  console.log(
+    `  New violations introduced after this point will block. Existing ones can be fixed incrementally.`,
+  );
+  process.exit(0);
+}
+
+if (violations.length === 0) {
+  console.log("✓ structural test passed");
+  process.exit(0);
+}
+
+for (const v of violations) {
+  console.error(`✖ ${v.file}:${v.line}  layer=${v.from} → ${v.to}  (must be forward-only)`);
+}
+console.error(`\n${violations.length} new layer violation(s). Fix the import direction.`);
+console.error(`Layer order for domain "${cfg.domains[0]?.name}": ${cfg.domains[0]?.layers?.join(" → ")}`);
+process.exit(2);

package/src/templates/_ci/.github/workflows/eval-nightly.yml

@@ -0,0 +1,59 @@
+name: harness eval (nightly)
+
+on:
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+    inputs:
+      set:
+        description: "quick (3 tasks) or full (all tasks)"
+        type: choice
+        options: [quick, full]
+        default: quick
+      transport:
+        description: "claude-cli (real run, costs tokens) or mock (CI smoke-test, free)"
+        type: choice
+        options: [mock, claude-cli]
+        default: mock
+
+permissions:
+  contents: read
+
+jobs:
+  eval:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm ci || npm install
+      - name: Verify Claude Code CLI is available
+        if: ${{ inputs.transport == 'claude-cli' || (github.event_name == 'schedule') }}
+        run: npx -y @anthropic-ai/claude-code --version
+      - name: Run eval
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CI: "true"
+        run: |
+          SET="${{ inputs.set || 'quick' }}"
+          # Default to mock for unattended schedule runs unless ANTHROPIC_API_KEY is set.
+          TRANSPORT="${{ inputs.transport }}"
+          if [ -z "$TRANSPORT" ]; then
+            if [ -n "${{ secrets.ANTHROPIC_API_KEY }}" ]; then
+              TRANSPORT="claude-cli"
+            else
+              TRANSPORT="mock"
+            fi
+          fi
+          if [ -f harness.config.json ] && grep -q '"language": "python"' harness.config.json; then
+            python -m harness.eval_runner --$SET --transport=$TRANSPORT
+          else
+            node harness/eval-runner.mjs --$SET --transport=$TRANSPORT
+          fi
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: eval-results
+          path: .harness/eval/results/

package/src/templates/_ci/.github/workflows/harness.yml

@@ -0,0 +1,55 @@
+name: harness
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  structural:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install Node deps (if package.json present)
+        run: |
+          if [ -f package.json ]; then
+            if [ -f pnpm-lock.yaml ]; then npm i -g pnpm && pnpm install --frozen-lockfile
+            elif [ -f yarn.lock ]; then npm i -g yarn && yarn install --frozen-lockfile
+            else npm ci || npm install
+            fi
+          fi
+      - name: Install Python deps (if pyproject.toml present)
+        run: |
+          if [ -f pyproject.toml ]; then
+            python -m pip install --upgrade pip
+            pip install libcst import-linter ruff || true
+            pip install -e '.[dev]' || pip install -e . || true
+          fi
+      - name: Structural test
+        run: |
+          if [ -f harness.config.json ] && grep -q '"language": "python"' harness.config.json; then
+            python -m harness.structural_test
+          else
+            npm run --silent harness:check
+          fi
+      - name: Lint
+        continue-on-error: true
+        run: |
+          if [ -f package.json ] && grep -q '"lint"' package.json; then
+            npm run --silent lint
+          elif command -v ruff >/dev/null 2>&1; then
+            ruff check .
+          fi

package/src/templates/docs/adr/0001-use-agent-harness-kit.md.hbs

@@ -0,0 +1,56 @@
+# ADR 0001 — Adopt agent-harness-kit
+
+- **Status:** accepted
+- **Date:** {{now "yyyy-MM-dd"}}
+- **Deciders:** project owner
+
+## Context
+
+This is a single-developer project that uses Claude Code for the bulk of
+implementation work. Agent-driven development without a harness produces
+predictable failure modes:
+
+- duplicated helpers across modules
+- backward layer dependencies
+- silent test removal or skip
+- doc drift from code reality
+- unbounded retries and missing timeouts
+
+Hand-engineering each preventive against these failures is achievable but
+slow and easy to forget. A shared starter kit codifies the patterns that
+OpenAI, Stripe, Anthropic, and Mitchell Hashimoto have publicly demonstrated
+work.
+
+## Decision
+
+Adopt `agent-harness-kit v{{kitVersion}}` as the harness layer. Specifically:
+
+- Use the layer order `{{layersJoined}}` and enforce it via the structural
+  test bundled with the kit.
+- Run the PostToolUse + Stop hooks shipped by the kit unmodified.
+- Use the 10 starter skills and 5 reviewer subagents as the baseline; add or
+  remove via subsequent ADRs.
+- Run `/garbage-collection` weekly.
+
+## Consequences
+
+Positive
+
+- Time-to-mistake-fix drops to ~30 seconds (PostToolUse hook).
+- The `feature_list.json` + `PROGRESS.md` pair gives every session a clean
+  starting context, regardless of conversation length.
+
+Negative
+
+- The layer order is opinionated. Some valid architectures (hexagonal,
+  vertical-slice) require an ADR override.
+- The kit upgrades introduce sidecar files (`*.harness-new`) that must be
+  diffed manually for user-modified files.
+
+## Alternatives considered
+
+- **Roll our own.** Rejected: too slow, and the literature converges on the
+  same patterns.
+- **Use Claudify (1700 skills, 9 subagents).** Rejected: the over-engineered
+  antipattern this kit explicitly avoids.
+- **No harness.** Rejected: see Context.

package/src/templates/docs/agent-failures.md

@@ -0,0 +1,25 @@
+# Agent failures log
+
+This is the running log of agent mistakes that triggered a harness
+improvement. Each entry should answer: what happened, what we did to make
+sure it never happens again, and where the prevention now lives.
+
+The `/propose-harness-improvement` skill appends entries here automatically.
+
+> "Anytime you find an agent makes a mistake, you take the time to engineer
+> a solution such that the agent never makes that mistake again."
+> — Mitchell Hashimoto, _My AI Adoption Journey_ (Feb 5, 2026)
+
+## Format
+
+```
+### YYYY-MM-DD  <slug>
+- **Symptom:** <what went wrong>
+- **Classification:** (a) missing context | (b) missing rule | (c) missing tool/skill | (d) wrong layer
+- **Fix applied:** <what we did>
+- **Fix lives in:** path/or/file
+```
+
+## Entries
+
+_(empty — this file fills up over time as `/propose-harness-improvement` is invoked.)_

package/src/templates/docs/architecture.md.hbs

@@ -0,0 +1,47 @@
+# Architecture — {{projectName}}
+
+This document is the source of truth for how code is organized. Any deviation
+must be justified in an ADR under `docs/adr/`.
+
+## Layer order (forward-only)
+
+```
+{{layersJoined}}
+```
+
+Code in a higher layer may import from any lower layer. Code in a lower layer
+**must not** import from a higher layer. The structural test enforces this
+mechanically — see `harness.config.json` and the
+`{{#if isPython}}python -m harness.structural_test{{else}}npm run harness:check{{/if}}` command.
+
+## Layer responsibilities
+
+| Layer       | Responsibility                                                              |
+| ----------- | --------------------------------------------------------------------------- |
+| `types`     | Pure data shapes. No I/O, no business logic, no framework imports.          |
+| `config`    | Static configuration (env loading, feature flags, constants).               |
+| `repo`      | Persistence and external-system gateways. Returns plain values.             |
+| `service`   | Business logic. Orchestrates `repo` calls. Pure where possible.             |
+| `runtime`   | Framework adapters: HTTP routes, CLI commands, queue handlers.              |
+| `ui`        | Rendering, components, presentation logic.                                  |
+
+## Cross-cutting concerns: `providers/`
+
+Auth, telemetry, feature flags, observability — anything that would otherwise
+cut across layers — enters through `providers/`. Each provider exposes a
+single typed interface; consumers depend on the interface, not the
+implementation.
+
+## Adding a new module
+
+1. Decide which layers it touches.
+2. Run `/inspect-module <existing-similar-module>` to mirror the pattern.
+3. Create files under `src/{domain}/{layer}/`.
+4. Write tests in the same layer.
+5. Run the structural test. If it fails, do **not** disable it — fix the import.
+
+## Recent decisions
+
+(Most recent first. Created automatically by `/add-adr`.)
+
+- `0001-use-agent-harness-kit.md` — Adopt agent-harness-kit as the harness layer.