agent-harness-kit 0.3.0

package/src/templates/docs/core-beliefs.md.hbs

@@ -0,0 +1,41 @@
+# Core beliefs
+
+Beliefs are higher-level than golden principles. Beliefs explain *why* the
+project exists; principles explain *how* the code is shaped. If a belief
+changes, expect the principles to ripple.
+
+## What this codebase is
+
+{{description}}
+
+## Why these constraints exist
+
+1. **Solo developer, no review queue.** Every constraint must pull weight
+   without a second pair of eyes. The harness IS the review queue.
+2. **Agent-driven development is the default mode.** Code is written by
+   Claude Code with a human in the loop, not the other way around. Patterns
+   that humans tolerate but agents abuse (vague names, "just one more flag",
+   lazy `any` / `Dict[str, Any]`) are out.
+3. **Time-to-mistake-fix matters more than time-to-write.** A mistake that
+   surfaces in the PostToolUse hook costs ~30 seconds. The same mistake in
+   a code review costs minutes. The same mistake in production costs hours.
+   Every constraint is timed against this gradient.
+
+## What we're optimizing for
+
+- Throughput per dev-hour at constant quality.
+- Refactor blast radius — changes should stay within one domain.
+- Decisional consistency — two consecutive sessions should produce the same
+  shape of solution to the same problem.
+
+## What we're NOT optimizing for
+
+- Multi-team coordination, RFC queues, or governance.
+- Frontier-grade test coverage. Agent-written unit tests are a liability;
+  feature-level tests are the floor.
+- Maximum flexibility. The harness is opinionated on purpose.
+
+---
+
+_Edit this file when the project's purpose changes — not when you change a
+library or a layer name. For those, write an ADR._

package/src/templates/docs/golden-principles.md.hbs

@@ -0,0 +1,80 @@
+# Golden principles
+
+These are invariants that must hold across the codebase. Each one traces to a
+specific past failure or a deliberate trade-off. **Every line here must be
+mechanically enforceable** — if it can't be, it doesn't belong here; promote
+it to a structural test or demote it to a comment in the affected file.
+
+The garbage-collection ritual (`/garbage-collection`) diffs the codebase
+against this file weekly.
+
+## 1. Forward-only layer dependencies
+
+`{{layersJoined}}`
+
+Why: prevents circular imports, makes refactors local, mirrors OpenAI's Codex
+codebase rule.
+Enforced by: structural test (`harness.config.json` `domains[].layers`).
+
+## 2. Validate at boundaries; trust internals
+
+External input (HTTP body, CLI arg, file content) is parsed into a typed
+object at the runtime boundary. Internal code assumes the type holds.
+
+Why: removes "defensive" type checks scattered across services that hide
+bugs.
+Enforced by: code review + `security-reviewer` subagent.
+
+## 3. Shared utilities live in `src/shared/`
+
+Before adding a helper to a module, search `src/shared/` for an existing one.
+If you write a duplicate, the garbage-collection skill will surface it.
+
+Why: a real recurring failure mode in agent-generated code is duplicated
+helpers. OpenAI's Codex team explicitly tracks this.
+Enforced by: `garbage-collection` skill (duplicate-utility scan).
+
+## 4. Tests are end-to-end through one feature
+
+A test exercises one entry from `feature_list.json` end-to-end. We don't
+write isolated unit tests for inner helpers unless a bug repro demands one.
+
+Why: agent-generated unit tests mock everything and verify nothing.
+Enforced by: code review.
+
+## 5. Bounded retries and timeouts on every external call
+
+Every `fetch`/`httpx`/`requests` call has an explicit timeout. Every retry
+loop has both `maxAttempts` and a deadline. No `while True:` in production
+code.
+
+Why: agents love infinite retries.
+Enforced by: `reliability-reviewer` subagent.
+
+## 6. JSON beats Markdown for state the agent updates
+
+`feature_list.json`, `.harness/installed.json`, structural-baseline — all
+JSON. Anthropic's long-running-agent guide: "the model is less likely to
+inappropriately change or overwrite JSON files compared to Markdown files."
+
+Why: the agent treats Markdown as freely-editable prose.
+Enforced by: file format choice.
+
+## 7. Every agent failure becomes a permanent prevention
+
+When the agent does something wrong, the response is **not** to add a "be
+careful about X" line to CLAUDE.md. It is to:
+
+- add context to `docs/`, OR
+- add a structural test rule, OR
+- add a hook, OR
+- add a skill.
+
+Why: Mitchell Hashimoto's discipline. CLAUDE.md is a table of contents — it
+won't be re-read on every action.
+Enforced by: `/propose-harness-improvement` skill.
+
+---
+
+_Add new principles via `/structural-test-author`, which forces you to
+codify the enforcement mechanism alongside the rule._

package/src/templates/docs/tech-debt-tracker.md

@@ -0,0 +1,30 @@
+# Tech debt tracker
+
+A flat append-only log of known compromises. Each entry has a date, a
+location, a description, and a payoff condition.
+
+> "Technical debt is a high-interest loan best paid down in continuous
+> small increments." — OpenAI Codex harness team
+
+The `/garbage-collection` skill scans this file every Friday and proposes
+the top-3 highest-leverage entries to address.
+
+## Format
+
+```
+### YYYY-MM-DD  <slug>
+- Location: path/or/area
+- Why it's debt: <one paragraph>
+- Cost: <effort to fix>
+- Payoff condition: <what should trigger the fix>
+- Status: open | in-progress | closed
+```
+
+## Entries
+
+### 2026-01-01  example-entry
+- Location: src/example/repo/legacy.ts
+- Why it's debt: hand-rolled fetch wrapper instead of the shared client
+- Cost: 1 hour
+- Payoff condition: when we add the next external call
+- Status: open

package/src/templates/feature_list.json.hbs

@@ -0,0 +1,29 @@
+{
+  "$schema": "./.harness/feature-list.schema.json",
+  "version": "0.1",
+  "project": "{{projectName}}",
+  "features": [
+    {
+      "id": "health-endpoint",
+      "title": "GET /health returns {status:'ok'}",
+      "passes": false,
+      "steps": [
+        { "id": "type", "title": "Define HealthResponse in types/", "done": false },
+        { "id": "service", "title": "Implement getHealth() in service/", "done": false },
+        { "id": "runtime", "title": "Wire route in runtime/", "done": false },
+        { "id": "smoke", "title": "curl localhost returns 200 + {status:'ok'}", "done": false }
+      ],
+      "domain": "default"
+    },
+    {
+      "id": "not-found-page",
+      "title": "Custom 404 page (or handler)",
+      "passes": false,
+      "steps": [
+        { "id": "ui", "title": "Add 404 view/handler in ui/ or runtime/", "done": false },
+        { "id": "smoke", "title": "curl /no-such-path returns 404 with the custom body", "done": false }
+      ],
+      "domain": "default"
+    }
+  ]
+}

package/src/templates/harness.config.json.hbs

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://raw.githubusercontent.com/tuanle96/agent-harness-kit/v{{kitVersion}}/schema.json",
+  "version": "{{kitVersion}}",
+  "language": "{{language}}",
+  "framework": "{{framework}}",
+  "preset": "{{preset}}",
+  "domains": [
+    {
+      "name": "default",
+      "root": "{{#if isPython}}app{{else}}src{{/if}}",
+      "layers": [{{#each layers}}"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}]
+    }
+  ],
+  "providers": ["auth", "telemetry", "feature-flags"],
+  "goldenPrinciples": "docs/golden-principles.md",
+  "structuralTest": {
+    "engine": "{{#if isPython}}libcst{{else}}ts-morph{{/if}}",
+    "configPath": ".harness/structural-test.config.json",
+    "blockOnViolation": true
+  },
+  "evals": {
+    "tasksDir": ".harness/eval/tasks",
+    "scheduleCron": "0 6 * * *",
+    "dimensions": ["outcome", "process", "style", "efficiency"]
+  },
+  "garbageCollection": {
+    "frequency": "weekly",
+    "maxFixesPerRun": 3,
+    "scope": ["dead-imports", "duplicate-utils", "layer-violations", "doc-drift"]
+  },
+  "models": {
+    "main": "claude-sonnet-4-6",
+    "reviewers": "claude-sonnet-4-6",
+    "explore": "claude-haiku-4-5"
+  },
+  "budgets": {
+    "perRunUsd": 2.0,
+    "perDayUsd": 10.0
+  }
+}

package/src/templates/scripts/dev-up.sh.hbs

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Start the dev server and wait until it answers a readiness probe.
+# Used by `/debug-flow` and by humans during interactive work.
+set -euo pipefail
+
+PORT="${PORT:-3000}"
+{{#if isFastapi}}PORT="${PORT:-8000}"{{/if}}
+{{#if isDjango}}PORT="${PORT:-8000}"{{/if}}
+{{#if isFlask}}PORT="${PORT:-5000}"{{/if}}
+HEALTH_PATH="${HEALTH_PATH:-/}"
+
+echo "[dev-up] starting dev server on port $PORT…"
+{{#if isNextjs}}
+npm run dev &
+{{else if isFastapi}}
+uvicorn app.main:app --reload --port "$PORT" &
+{{else if isDjango}}
+python manage.py runserver "$PORT" &
+{{else if isFlask}}
+flask --app app run --debug --port "$PORT" &
+{{else if isExpress}}
+node ./src/server.js &
+{{else if isFastify}}
+node ./src/server.js &
+{{else if isNestjs}}
+npm run start:dev &
+{{else if isPython}}
+python -m app &
+{{else}}
+npm run dev &
+{{/if}}
+SERVER_PID=$!
+
+cleanup() {
+  if kill -0 "$SERVER_PID" 2>/dev/null; then
+    kill "$SERVER_PID" || true
+  fi
+}
+trap cleanup EXIT INT TERM
+
+# Wait for readiness (max 30s).
+for i in $(seq 1 60); do
+  if curl -fs "http://localhost:$PORT$HEALTH_PATH" >/dev/null 2>&1; then
+    echo "[dev-up] ready at http://localhost:$PORT$HEALTH_PATH"
+    break
+  fi
+  sleep 0.5
+done
+
+# Hand control back to the foreground process.
+wait "$SERVER_PID"

package/src/templates/scripts/harness-report.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// harness:report — aggregate eval results + skill telemetry into a per-skill
+// summary. Reads .harness/eval/results/*.jsonl and .harness/telemetry.jsonl.
+//
+// Output:
+//   ### Eval results (last 7 days)
+//   <per-task: pass/fail counts, avg tokens>
+//   ### Skill invocations (last 7 days)
+//   <per-skill: invocation count, sessions, last seen>
+//   ### Drift signals
+//   <skills that haven't been invoked in N days; tasks that have started failing>
+//
+// No external deps — pure Node stdlib.
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+const ROOT = process.cwd();
+const RESULTS_DIR = resolve(ROOT, ".harness/eval/results");
+const TELEMETRY = resolve(ROOT, ".harness/telemetry.jsonl");
+const NOW = Date.now();
+const SEVEN_DAYS = 7 * 24 * 60 * 60 * 1000;
+
+async function readJsonl(path) {
+  if (!existsSync(path)) return [];
+  const raw = await readFile(path, "utf8");
+  const out = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      /* skip malformed line */
+    }
+  }
+  return out;
+}
+
+async function loadEvalResults() {
+  if (!existsSync(RESULTS_DIR)) return [];
+  const files = await readdir(RESULTS_DIR);
+  const all = [];
+  for (const f of files) {
+    if (!f.endsWith(".jsonl")) continue;
+    const path = join(RESULTS_DIR, f);
+    const st = await stat(path);
+    const rows = await readJsonl(path);
+    for (const r of rows) {
+      r._mtime = st.mtimeMs;
+      all.push(r);
+    }
+  }
+  return all;
+}
+
+function recent(rows, key = "ts") {
+  return rows.filter((r) => {
+    const t = r[key] ? new Date(r[key]).getTime() : r._mtime ?? 0;
+    return NOW - t <= SEVEN_DAYS;
+  });
+}
+
+function tokensOf(row) {
+  return (row.grades ?? [])
+    .filter((g) => g.dim === "efficiency")
+    .reduce((sum, g) => {
+      const m = g.info?.match(/^(\d+) tokens/);
+      return sum + (m ? parseInt(m[1], 10) : 0);
+    }, 0);
+}
+
+function fmtPct(num, total) {
+  if (total === 0) return "n/a";
+  return `${Math.round((num / total) * 100)}%`;
+}
+
+function summarizeEvals(rows) {
+  const byTask = new Map();
+  for (const r of rows) {
+    const arr = byTask.get(r.taskId) ?? [];
+    arr.push(r);
+    byTask.set(r.taskId, arr);
+  }
+  console.log(`\n### Eval results (last 7 days, ${rows.length} runs)`);
+  if (rows.length === 0) {
+    console.log("  (no recent runs — try `npm run harness:eval -- --quick --transport=mock`)");
+    return;
+  }
+  console.log(
+    "  task                    pass-rate    runs   avg-tokens",
+  );
+  console.log(
+    "  ----------------------  ----------   -----  ----------",
+  );
+  for (const [taskId, taskRows] of [...byTask.entries()].sort()) {
+    const passed = taskRows.filter((r) => r.passed).length;
+    const tokens = taskRows.reduce((s, r) => s + tokensOf(r), 0);
+    const avgTokens = taskRows.length > 0 ? Math.round(tokens / taskRows.length) : 0;
+    const pct = fmtPct(passed, taskRows.length);
+    console.log(
+      `  ${taskId.padEnd(22)}  ${pct.padStart(8)}     ${String(taskRows.length).padStart(3)}    ${String(avgTokens).padStart(8)}`,
+    );
+  }
+}
+
+function summarizeTelemetry(rows) {
+  console.log(`\n### Skill invocations (last 7 days, ${rows.length} events)`);
+  if (rows.length === 0) {
+    console.log(
+      "  (no skill invocations recorded — telemetry hook may not be installed)",
+    );
+    console.log(
+      "  Verify `.claude/hooks/hooks.json` includes the Skill matcher.",
+    );
+    return;
+  }
+  const bySkill = new Map();
+  for (const r of rows) {
+    const arr = bySkill.get(r.skill) ?? [];
+    arr.push(r);
+    bySkill.set(r.skill, arr);
+  }
+  console.log("  skill                          invocations   last-seen");
+  console.log("  -----------------------------  -----------   --------------------");
+  for (const [skill, events] of [...bySkill.entries()].sort(
+    (a, b) => b[1].length - a[1].length,
+  )) {
+    const last = events
+      .map((e) => e.ts)
+      .sort()
+      .at(-1);
+    console.log(
+      `  ${skill.padEnd(29)}  ${String(events.length).padStart(8)}      ${last ?? "?"}`,
+    );
+  }
+}
+
+function driftSignals(evalRows, telemetryRows) {
+  console.log(`\n### Drift signals`);
+  const knownSkills = [
+    "inspect-module",
+    "inspect-app",
+    "garbage-collection",
+    "doc-drift-scan",
+    "add-feature",
+    "add-adr",
+    "structural-test-author",
+    "propose-harness-improvement",
+    "write-skill",
+    "debug-flow",
+    "eval-runner",
+  ];
+  const seen = new Set(telemetryRows.map((r) => r.skill));
+  const unseen = knownSkills.filter((s) => !seen.has(s));
+  if (unseen.length > 0) {
+    console.log(`  skills not invoked in 7 days: ${unseen.join(", ")}`);
+  }
+  // Tasks failing in their most recent run.
+  const latest = new Map();
+  for (const r of evalRows.sort((a, b) => (a.ts ?? "").localeCompare(b.ts ?? ""))) {
+    latest.set(r.taskId, r);
+  }
+  const regressing = [...latest.values()].filter((r) => !r.passed);
+  if (regressing.length > 0) {
+    console.log(
+      `  tasks failing in their latest run: ${regressing.map((r) => r.taskId).join(", ")}`,
+    );
+  }
+  if (unseen.length === 0 && regressing.length === 0) {
+    console.log("  (none)");
+  }
+}
+
+async function main() {
+  const evalAll = await loadEvalResults();
+  const telemetryAll = await readJsonl(TELEMETRY);
+  const evalRows = recent(evalAll);
+  const telemetryRows = recent(telemetryAll);
+
+  console.log("=== agent-harness-kit report ===");
+  console.log(`Generated: ${new Date().toISOString()}`);
+  summarizeEvals(evalRows);
+  summarizeTelemetry(telemetryRows);
+  driftSignals(evalRows, telemetryRows);
+  console.log("");
+}
+
+await main();

package/src/templates/scripts/install-git-hooks.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Install scripts/pre-push.sh as the git pre-push hook for this repo.
+set -e
+
+if [ ! -d .git ]; then
+  echo "Not a git repo — run this script from the repo root." >&2
+  exit 1
+fi
+
+mkdir -p .git/hooks
+
+cat > .git/hooks/pre-push <<'HOOK'
+#!/usr/bin/env bash
+exec bash scripts/pre-push.sh "$@"
+HOOK
+chmod +x .git/hooks/pre-push
+
+echo "✓ git pre-push hook installed (delegates to scripts/pre-push.sh)"

package/src/templates/scripts/pre-push.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# pre-push hook — Stripe "shift-feedback-left" pattern. Runs only the
+# deterministic checks (structural test + linter + tests on changed files).
+# Lives in scripts/ so it ships with the repo; install via install-git-hooks.sh.
+set -e
+
+echo "[pre-push] running structural test…"
+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
+
+echo "[pre-push] running lint…"
+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
+
+echo "[pre-push] OK"

package/src/templates/scripts/precompletion-checklist.sh.hbs

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Stop hook — LangChain's "PreCompletionChecklist" / Ralph Wiggum loop.
+# On first stop: run deterministic checks; if any fail, re-inject *structured*
+# failure context (not just check names) via stderr and exit 2. On second
+# stop (stop_hook_active=true), exit 0 to allow real exit.
+#
+# Optional: set AHK_HEADLESS_RECOVER=1 to spawn `claude -p` in the background
+# for one turn of recovery (costs tokens; off by default).
+set -e
+
+INPUT=$(cat)
+
+# CRITICAL: avoid infinite loops. If the hook already ran, do not block again.
+if command -v jq >/dev/null 2>&1; then
+  if [ "$(echo "$INPUT" | jq -r '.stop_hook_active // false')" = "true" ]; then
+    exit 0
+  fi
+fi
+
+# Capture structured output per check. We use temp files so we can quote the
+# tail back to Claude verbatim — names alone are not enough context for the
+# agent to act on.
+TMPDIR_HOOK=$(mktemp -d -t ahk-stop-hook.XXXXXX)
+# Preserve the script's exit code through the cleanup trap — otherwise the
+# trailing `rm` resets the final status to 0 and Claude never sees the block.
+trap 'rc=$?; rm -rf "$TMPDIR_HOOK"; exit $rc' EXIT
+
+run_check() {
+  local name="$1"
+  shift
+  local out="$TMPDIR_HOOK/$name.out"
+  if "$@" >"$out" 2>&1; then
+    return 0
+  else
+    echo "$name" >> "$TMPDIR_HOOK/failed.list"
+    return 1
+  fi
+}
+
+# Structural test.
+if [ -f harness.config.json ]; then
+  if grep -q '"language": "python"' harness.config.json; then
+    run_check structural-test python -m harness.structural_test || true
+  else
+    run_check structural-test npm run --silent harness:check || true
+  fi
+fi
+
+# Lint.
+if [ -f package.json ] && grep -q '"lint"' package.json; then
+  run_check lint npm run --silent lint || true
+elif [ -f pyproject.toml ] && command -v ruff >/dev/null 2>&1; then
+  run_check ruff ruff check . || true
+fi
+
+if [ ! -s "$TMPDIR_HOOK/failed.list" ]; then
+  exit 0
+fi
+
+# Build a structured failure report for Claude. The agent gets: which checks
+# failed, the last 50 lines of each failure, and the files most recently
+# touched (so the agent can correlate failures with its own edits).
+{
+  echo
+  echo "=== Pre-completion checklist failed ==="
+  while read -r failed; do
+    echo
+    echo "--- $failed ---"
+    tail -50 "$TMPDIR_HOOK/$failed.out" 2>/dev/null || true
+  done < "$TMPDIR_HOOK/failed.list"
+
+  echo
+  echo "--- recent changes (last 10 modified files) ---"
+  if command -v git >/dev/null 2>&1; then
+    git status --short 2>/dev/null | head -10 || true
+    echo
+    echo "--- last 3 commits ---"
+    git log --oneline -3 2>/dev/null || true
+  fi
+
+  echo
+  echo "Fix the failing check(s) and re-run them locally before declaring"
+  echo "the task complete. Do NOT disable a check to make the hook pass."
+} >&2
+
+# Optional: opt-in headless recovery. Spawns a one-turn `claude -p` to
+# attempt the fix autonomously. Useful for unattended CI / cron contexts.
+# Off by default because it costs tokens.
+if [ "${AHK_HEADLESS_RECOVER:-}" = "1" ] && command -v claude >/dev/null 2>&1; then
+  FAILED_LIST=$(tr '\n' ' ' < "$TMPDIR_HOOK/failed.list")
+  echo "[ahk] AHK_HEADLESS_RECOVER=1 — spawning recovery turn for: $FAILED_LIST" >&2
+  claude -p \
+    "The pre-completion checklist failed: $FAILED_LIST. Read the failure output in $TMPDIR_HOOK and apply the smallest fix. Do not disable any check." \
+    --max-turns 5 \
+    >"$TMPDIR_HOOK/recover.out" 2>&1 &
+  # Don't wait — let the next session pick up the partially-applied fix.
+fi
+
+exit 2

package/src/templates/scripts/structural-test-on-edit.sh.hbs

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# PostToolUse hook — runs the structural test on the file just edited.
+# Defensive: never blocks on missing tooling. Exit code 2 = block + Claude reads stderr.
+set -e
+
+INPUT=$(cat)
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0  # jq missing — silently skip rather than spuriously blocking
+fi
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+[ -z "$FILE" ] && exit 0
+
+# Only run on source files, and only inside the configured roots.
+case "$FILE" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs)  ENGINE=ts ;;
+  *.py)                               ENGINE=py ;;
+  *)                                  exit 0 ;;
+esac
+
+# Allow opt-out via env var — useful on Windows / macOS where some hook
+# events are flaky (open issues #45065 and #6305).
+if [ "${AHK_HOOK_MODE:-}" = "warn" ]; then
+  echo "[ahk] hook running in warn-only mode (AHK_HOOK_MODE=warn)" >&2
+  exit 0
+fi
+
+# Run the structural test scoped to this file. Capture output so we can
+# return only the relevant lines via stderr to Claude.
+if [ "$ENGINE" = "ts" ]; then
+  if ! npm run --silent harness:check -- --file "$FILE" 2>&1 | tail -50 >&2; then
+    cat >&2 <<EOF
+
+Structural test failed for $FILE.
+Layer order: see harness.config.json.
+Run \`npm run harness:check\` for full output.
+Fix the violation before continuing — do NOT disable the test.
+EOF
+    exit 2
+  fi
+elif [ "$ENGINE" = "py" ]; then
+  if ! python -m harness.structural_test --file "$FILE" 2>&1 | tail -50 >&2; then
+    cat >&2 <<EOF
+
+Structural test failed for $FILE.
+Layer order: see harness.config.json.
+Run \`python -m harness.structural_test\` for full output.
+Fix the violation before continuing — do NOT disable the test.
+EOF
+    exit 2
+  fi
+fi
+exit 0

package/src/templates/scripts/telemetry-on-skill.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# PostToolUse telemetry hook — logs every Skill invocation to
+# .harness/telemetry.jsonl. Pure observation; never blocks.
+#
+# Used by harness:report to compute per-skill success rate, average duration,
+# and to surface drift over time.
+set -e
+
+INPUT=$(cat)
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0  # jq missing — skip silently rather than spuriously blocking
+fi
+
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
+[ "$TOOL" = "Skill" ] || exit 0
+
+SKILL=$(echo "$INPUT" | jq -r '.tool_input.skill // empty')
+[ -z "$SKILL" ] && exit 0
+
+mkdir -p .harness
+LINE=$(jq -nc --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+              --arg skill "$SKILL" \
+              --arg sha "$(git rev-parse --short HEAD 2>/dev/null || echo 'no-git')" \
+              '{ts: $ts, event: "skill_invoked", skill: $skill, sha: $sha}')
+echo "$LINE" >> .harness/telemetry.jsonl
+exit 0