agent-harness-kit 0.3.0

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

@@ -0,0 +1,43 @@
+---
+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:*)
+suggested-turns: 12
+---
+
+## Steps
+
+1. **Extract references.** From `docs/**/*.md` and `CLAUDE.md`, extract:
+   - Backtick paths matching `[a-z0-9_/.\\-]+\\.(md|ts|tsx|js|py|json|yml|yaml|sh)`
+   - Backtick commands (first token after a backtick).
+   - Markdown links to local files (`./...` or `../...`).
+2. **Validate each.**
+   - Paths: `test -e <path>`. If missing, mark as drift.
+   - Commands: `command -v <cmd>`. If not on PATH, mark as drift (but allow
+     a configured allowlist for known optional tools).
+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

@@ -0,0 +1,55 @@
+---
+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.hbs

@@ -0,0 +1,49 @@
+---
+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:*)
+suggested-turns: 15
+---
+
+## Steps
+
+1. **Capture baseline.** Run the full suite and save the 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}}
+   - Save to `.harness/gc-<date>.json`.
+2. **Classify violations.** For each finding:
+   - **Layer violation** → fix.
+   - **Duplicate utility** (same function body in 2+ places) → propose
+     extraction to `src/shared/`.
+   - **Dead import** → remove.
+   - **Doc drift** (a path in `docs/architecture.md` no longer exists) →
+     invoke `doc-drift-scan` skill.
+   - **Hand-rolled helper** matching a shared utility → propose replacement.
+3. **Score** each candidate fix on three 1–5 dimensions:
+   - **Risk**: 1 = trivial rename, 5 = touches multiple modules.
+   - **Cost**: tokens + minutes.
+   - **Benefit**: how often this drift recurs (read `.harness/gc-history.json`).
+4. **Propose ONLY the top 3** cleanups (solo-dev cap; OpenAI does dozens, you
+   do 3). Open them as separate PRs with `gh pr create --label gc --draft`.
+5. **Append a row** to `.harness/gc-history.json`:
+   `{ "date": "...", "violations_found": N, "fixes_opened": M, "total_tokens": K }`.
+6. **Stop.** Do not merge anything. Human review required at solo scale.
+
+## 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
+
+- Don't open more than 3 PRs in one run. The cap is a feature, not a bug.
+- Don't auto-merge — the entire point of solo-scale GC is human review.
+- Don't suppress findings that score low; record them in
+  `.harness/gc-history.json` so trends surface over time.

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

@@ -0,0 +1,57 @@
+---
+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.

package/src/templates/.claude/skills/inspect-module/SKILL.md.hbs

@@ -0,0 +1,53 @@
+---
+name: inspect-module
+description: Use this skill whenever the user mentions "explore", "inspect", "understand", "what does X do", "where is Y", or before adding a new feature in an unfamiliar area. Produces a structured map of one module — files, exports, dependencies, layer assignment, and recent commits — without reading the entire codebase. Always invoke this skill before editing an unfamiliar module so the agent has accurate context, not guesses.
+allowed-tools: Read, Glob, Grep, Bash(git log:*), Bash(git ls-tree:*), Bash(tree:*)
+suggested-turns: 6
+---
+
+## When to use
+
+The user asked any of: "how does X work", "what's in src/foo", "before I add
+feature Y, what's in the area?", "explore <path>", "show me the shape of
+<module>".
+
+## Steps
+
+1. **Resolve the target.** If the user gave a feature name (not a path), grep
+   `feature_list.json` for it. If multiple paths match, ask the user which.
+2. **Recent activity.** Run `git log --oneline -20 -- <target>` and read the
+   top 3 commit messages.
+3. **Layer.** Cross-reference the path against `harness.config.json` →
+   `domains[].layers` to determine the layer.
+4. **Public surface.** List exported symbols:
+   - TypeScript: `grep -nE "^export " <target>/**/*.ts`
+   - Python: `grep -nE "^def |^class |^[A-Z_][A-Z0-9_]+ ?=" <target>/**/*.py`
+5. **Dependencies.** List inbound imports (who depends on this module) and
+   outbound imports (what this module depends on). Verify both respect the
+   forward-only layer order; if not, **stop and report the violation** before
+   proceeding with any change plan.
+6. **Risks.** Flag any of: dynamic imports, eval, shell-out with
+   interpolation, missing tests for an exported function.
+
+## Output contract
+
+Produce a Markdown report with these sections, in this order:
+
+```
+### Module: <path>
+### Layer: <layer-name>
+### Public surface: <list>
+### Inbound deps: <list of paths>
+### Outbound deps: <list of paths or external packages>
+### Recent changes: <top 3 commit messages>
+### Risks: <bulleted list, "none" if clean>
+```
+
+End with: "I am ready to make changes to `<module>`. The architecture-reviewer
+subagent will be invoked on completion."
+
+## Anti-patterns
+
+- Don't read every file in the module — sample exports, then drill in only
+  where the user's task points.
+- Don't propose changes in this skill. This is read-only context-gathering.

package/src/templates/.claude/skills/propose-harness-improvement/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: propose-harness-improvement
+description: Use this skill whenever the agent makes a mistake, the user observes an avoidable failure, a pattern recurs, or someone says "the agent keeps doing X". Files an "Engineer the Harness" entry — Mitchell Hashimoto's discipline: every failure becomes a permanent prevention mechanism. Always invoke this instead of just fixing the immediate symptom.
+allowed-tools: Read, Edit, Write, Bash(git diff:*)
+suggested-turns: 8
+---
+
+## Steps
+
+1. **Triage.** Ask: "What just went wrong? What was the agent's intended
+   behavior? What's the symptom?"
+2. **Classify.** One of:
+   - **(a) Missing context** — the agent didn't know something. Fix: add to
+     `docs/`.
+   - **(b) Missing rule** — the agent did something forbidden by an
+     unwritten rule. Fix: invoke `/structural-test-author`.
+   - **(c) Missing tool/skill** — the agent reached for the wrong tool. Fix:
+     invoke `/write-skill`.
+   - **(d) Wrong layer / architecture** — the structure invited the
+     mistake. Fix: write an ADR via `/add-adr`.
+3. **Append entry** to `docs/agent-failures.md` with: date, symptom, fix,
+   fix-type, file modified.
+4. **Apply the fix in the right place.** NEVER paper over with a CLAUDE.md
+   "be careful" sentence unless rule (a) applies — and even then, only as a
+   pointer to a longer doc.
+5. **Update PROGRESS.** Append `harness-improvement: <slug>` to
+   `.harness/PROGRESS.md`.
+
+## Output contract
+
+```
+### Failure: <one-line summary>
+### Classification: (a|b|c|d) <name>
+### Fix applied at: <file:line>
+### docs/agent-failures.md entry: §<n>
+```
+
+## Anti-patterns (block on these)
+
+- Don't add a vague "be careful with X" sentence to CLAUDE.md.
+- Don't add a rule whose enforcement is also LLM-based.
+- Don't use this skill to log unrelated cleanup ideas — those go in
+  `docs/tech-debt-tracker.md`.

package/src/templates/.claude/skills/structural-test-author/SKILL.md.hbs

@@ -0,0 +1,46 @@
+---
+name: structural-test-author
+description: Use this skill whenever the user wants to add a new architectural rule, prevent a recurring agent mistake, or codify a pattern from golden-principles.md. Generates a {{#if isPython}}libcst-based Python{{else}}ts-morph-based TypeScript{{/if}} structural test plus the matching {{#if isPython}}import-linter contract{{else}}eslint-plugin-boundaries rule{{/if}} entry. Always prefer this over leaving rules in prose.
+allowed-tools: Read, Edit, Write, Bash(npm test:*), Bash(pytest:*)
+suggested-turns: 15
+---
+
+## Steps
+
+1. **Phrase the rule.** Ask the user: "What invariant do you want enforced?
+   Phrase it as: 'No code in layer X may import from layer Y' or 'Every
+   <thing> must <do>'."
+2. **Layer rules first.** If the rule is layer-based, edit `harness.config.json`
+   `domains[].layers` and the {{#if isPython}}`.importlinter`{{else}}`eslint.config.js`{{/if}}
+   config — DO NOT write a custom test for layer rules; the existing test
+   already supports them via configuration.
+3. **Structural rules.** If the rule is structural but not layer-based (e.g.
+   "every controller must call validateAt"), open
+   `{{#if isPython}}harness/structural_test.py{{else}}harness/structural-test.ts{{/if}}`:
+   - {{#if isPython}}Use `libcst.CSTVisitor` subclass — preserves whitespace and comments.{{else}}Use `Project` + `getSourceFiles()` + AST visitors — the canonical ts-morph pattern.{{/if}}
+4. **Add a fixture test.** Create a file in `tests/structural/` that contains
+   a deliberately-violating snippet, and verify the rule fails on it.
+5. **Run against the whole repo.** If the rule fails on existing code, choose:
+   - **(a)** fix the existing code, OR
+   - **(b)** add the existing violations to `.harness/structural-baseline.json`
+     so only **new** violations block. (PMD/baseline pattern.)
+6. **Document.** Append the rule and its rationale (one paragraph traced to a
+   specific past failure) to `docs/golden-principles.md`.
+7. **Log the harness change.** Run `/propose-harness-improvement` to record
+   this as a permanent harness improvement.
+
+## Output contract
+
+```
+### Rule added: <one-line description>
+### Files changed: <list>
+### New violations on existing code: <count> — baselined: yes/no
+### golden-principles.md entry: §<n>
+```
+
+## Anti-patterns
+
+- Don't write a rule whose enforcement is also LLM-based — that just recurses.
+- Don't write a rule that requires runtime information to evaluate (e.g.
+  "this function must not take more than 100ms"). Those go in evals or
+  observability, not structural tests.

package/src/templates/.claude/skills/write-skill/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: write-skill
+description: Use this skill whenever the user asks to "create a skill", "add a slash command", "package a workflow", or "make X reusable across sessions". Generates a SKILL.md with valid YAML frontmatter (name regex, description ≤ 1024 chars, body ≤ 500 lines) and supporting scripts/references/assets. Tests the skill by simulating an auto-discovery prompt.
+allowed-tools: Read, Edit, Write, Bash(ls:*)
+suggested-turns: 8
+---
+
+## Steps
+
+1. **Validate the name.** Must match `^[a-z0-9]+(-[a-z0-9]+)*$` and be ≤ 64
+   characters.
+2. **Write a "pushy" description.** Third-person, ≤ 1024 chars. Explicitly
+   mention triggers ("Use this skill whenever the user mentions <X>, <Y>,
+   <Z>"). Models under-trigger skills with shy descriptions.
+3. **Body sections,** in this order: `## When to use`, `## Steps`,
+   `## Output contract`, `## Anti-patterns`. Cap body at 500 lines.
+4. **Externalize deterministic logic.** If the skill needs deterministic work
+   (parsing, formatting, computation), put it in `scripts/<name>.sh` (or `.py`
+   / `.mjs`) under the skill directory and reference it via a `Bash(...)`
+   tool call. SKILL.md stays declarative.
+5. **Test discovery.** Open a fresh Claude Code session and prompt with one
+   of the description triggers. Verify the skill auto-loads.
+
+## Output contract
+
+```
+### Skill: /<name>
+### Description bytes: <count>/1024
+### Body lines: <count>/500
+### Allowed tools: <list>
+### Discovery trigger tested: yes/no
+```
+
+## Anti-patterns
+
+- Don't write a description that starts with "This skill…" — start with "Use
+  this skill whenever the user…" so triggers are front-loaded.
+- Don't pack two unrelated workflows into one skill. Split them.
+- Don't grant `Bash(*:*)` in `allowed-tools`. Pin specific commands.

package/src/templates/CLAUDE.md.hbs

@@ -0,0 +1,70 @@
+# {{projectName}} — Agent Working Notes
+
+{{description}} {{language}}/{{framework}} project. Single-developer hobby
+project. This file is intentionally short — it is a **table of contents**, not
+an encyclopedia.
+
+## Build & Run
+
+- Install:    `{{installCmd}}`
+- Dev:        `{{devCmd}}`
+- Test:       `{{testCmd}}`
+- Lint:       `{{lintCmd}}`
+- Structural: `{{#if isPython}}python -m harness.structural_test{{else}}npm run harness:check{{/if}}` (must pass before any PR)
+
+## Architecture (brief)
+
+Layer order, enforced mechanically:
+
+**{{layersJoined}}** — code may only depend forward. Cross-cutting concerns
+enter via `providers/`.
+
+Full diagram and rationale: `docs/architecture.md`.
+
+## Golden principles (must hold)
+
+1. Prefer shared utilities in `src/shared/` over new helpers.
+2. Validate at boundaries; never probe data shape "YOLO-style".
+3. Each test is end-to-end through one feature in `feature_list.json`.
+
+Full list: `docs/golden-principles.md`.
+
+## Where to look (read on demand)
+
+- `docs/architecture.md`     — read when adding a new module or moving code.
+- `docs/adr/`                — read when changing public APIs.
+- `docs/golden-principles.md` — read before any refactor.
+- `feature_list.json`        — read before claiming a feature is done.
+- `.harness/PROGRESS.md`     — read at session start; write at session end.
+
+## Skills you should use
+
+- `/inspect-module <path>`            when you need to understand existing code.
+- `/add-feature <description>`        when adding new capability — never freestyle.
+- `/structural-test-author <layer>`   when adding a new structural rule.
+- `/garbage-collection`               every Friday or before tagging a release.
+- `/eval-runner`                      before merging any change to a skill or agent file.
+
+## Subagents you should delegate to (do NOT inline these reviews)
+
+- `architecture-reviewer` — for any cross-layer change.
+- `security-reviewer`     — for any auth, input handling, or secret-touching change.
+- `reliability-reviewer`  — for any new error path, retry loop, or async boundary.
+
+## Workflow contract
+
+1. Start session: run `/inspect-module .` and read `.harness/PROGRESS.md`.
+2. Pick ONE feature from `feature_list.json` whose `passes: false`.
+3. Implement. Run the structural test. If it fails, FIX before continuing.
+4. Self-verify with the matching reviewer subagent(s).
+5. Commit with descriptive message. Append a line to `.harness/PROGRESS.md`.
+6. Update `feature_list.json` (`passes: true`) **only after** end-to-end test passes.
+
+## What NOT to do
+
+- Don't add a new layer without an ADR.
+- Don't disable the structural test to make a PR pass.
+- Don't write code that the structural test cannot reason about (no dynamic
+  imports across layers).
+- Don't update CLAUDE.md without proposing a harness improvement
+  (`/propose-harness-improvement`).

package/src/templates/_adapter-python/.importlinter

@@ -0,0 +1,14 @@
+[importlinter]
+root_package = app
+include_external_packages = True
+
+[importlinter:contract:layered]
+name = Forward-only layer flow per domain
+type = layers
+layers =
+    app.ui
+    app.runtime
+    app.service
+    app.repo
+    app.config
+    app.types