autoharness

name	autoharness
description	Audit and tune the harness for a specific task. Researches what the task needs, checks existing harness against that, and patches gaps. Run before starting any non-trivial task.
disable-model-invocation	true

Auto-Harness Builder

Tune the harness for: $ARGUMENTS

GROUNDING RULE — read before doing anything else: Every structural decision, every harness component, every workflow step must be backed by a concrete finding from research or from reading project files. Do not use training knowledge to fill gaps — if a claim isn't supported by a search result or a file you've read, run another search before writing.

---

Phase 1: Task + Project Read

1. Parse the task from $ARGUMENTS:

   • Domains, tech stack, type of work (migration, feature build, API client, refactor, debug, etc.)
   • Success criteria, definition of done
   • Project paths referenced (CWD + any explicit paths in arguments)

2. Read referenced projects — for each project path:

   Manifests & config: package.json, Cargo.toml, go.mod, pom.xml, pyproject.toml, README

   API surface: OpenAPI/Swagger specs, proto files (**/*.proto), GraphQL schemas, route files (src/routes/**, src/api/**, src/handlers/**)

   Data models: schema files (prisma/schema.prisma, migrations/), type definitions (src/types/**, src/models/**)

   Auth patterns: auth middleware, JWT/OAuth config

   Read what exists — don't force-read files that aren't there.

3. Read project wiki — if project-wiki.md exists in CWD:

   • Reuse Map: note existing implementations — don't propose building what's already there
   • Anti-Patterns: don't propose approaches listed here for this project
   • Tips: prefer confirmed patterns over researched alternatives

---

Phase 2: Structural Research

Launch a single focused agent. Its sole mandate: answer the 6 structural questions with evidence from the web. Not a broad domain survey — just enough to determine what harness shape this task requires.

Agent S — Structural Analysis

For the task in $ARGUMENTS, find and answer each question. Each answer must include a source URL and a one-sentence quote or paraphrase of the evidence:

#	Question	Suggested search angle
1	Is there a natural repeating unit of work (component, endpoint, table, file)?	"how practitioners structure <work type> in <domain>"
2	Are there steps that can fail and must be fixed before proceeding (compile, test, lint, schema validate)?	"<tech stack> build test validate workflow", "<tech stack> CI pipeline"
3	Must units be done in a specific order (dependency graph, migration order, build phases)?	"<work type> ordering dependencies <domain>"
4	Is there a defined "done" check before advancing to the next unit?	"<work type> definition of done <domain>", "acceptance criteria <domain>"
5	Are there external libraries/APIs where the exact current version matters?	Read the project's lock files; check if key libraries have breaking-change histories
6	Do practitioners track progress across sessions?	"<work type> progress tracking <domain>", "migration checklist <domain>"

Return format — one row per question:

Q1 — Unit of work: YES — "practitioners migrate one handler at a time to isolate failures" [url]
Q2 — Feedback loops: YES — "tsc + jest run on every change; type errors surface before runtime" [url]
Q3 — Sequential dependency: YES — "foreign keys require parent tables to exist first" [url]
Q4 — Verification gate: YES — "parity check: same inputs must produce same outputs in both systems" [url]
Q5 — External docs needed: YES — "pg driver v3 introduced breaking changes to connection pooling" [url]
Q6 — State tracking: YES — "teams use a migration checklist to resume across sessions" [url]

No answer should be "probably" or "likely". If evidence is weak, say so and flag it for follow-up.

---

Phase 3: Harness Audit

Read every existing harness component:

• CLAUDE.md in CWD
• All files in .claude/skills/, .claude/rules/, .claude/agents/
• .claude/settings.json, .claude/settings.local.json
• .mcp.json

Using Agent S's answers, map each structural requirement to a harness component:

Requirement	Needed	Evidence	Covered by	Status
Loop skill	YES	Q1: "one handler at a time" — [url]	.claude/skills/migrate-loop	✅ covers TS→Go
Progress tracker	YES	Q3: "FK ordering" — [url]	—	❌ missing
CI gates rule	YES	Q2: "tsc + jest" — [url]	.claude/rules/ci-gates.md	⚠️ missing jest command
mcpdoc (postgres)	YES	Q5: "pg v3 breaking changes" — [url]	—	❌ missing

Coverage rules — not "file exists", but "file handles this task":

• ✅ covered — read the actual file; confirm it handles THIS task's specific tech and the failure modes Agent S found
• ⚠️ partial — exists, covers ≥60%, but missing specific coverage for this task
• ❌ missing — no component exists for this requirement

---

Phase 4: Gap Report

Show the user:

Task: <one-line summary>

Harness audit (backed by <N> research findings):
  ✅ already covers: <list>
  ⚠️  will extend:   <component — what's missing>
  ❌ will create:    <list>

<N> patches needed.

If the gap table is entirely ✅:

Harness is ready for: <task summary>
  <component> → covers <requirement> [source]
  ...
Nothing to build.

Stop here.

Get implicit confirmation — proceed unless the user objects within one reply.

---

Phase 5: Targeted Deep Research

Run only the agents needed for gaps. Skip agents with no relevant gaps.

Agent A — Domain deep research

Run if: ❌ or ⚠️ gaps exist for loop skill, verify skill, workflow rules, or hooks.

For each gap requiring implementation details:

• Read official docs — not blog summaries
• Search for exact commands, flags, tool invocations
• Search "common mistakes", "pitfalls", "anti-patterns" with citations
• Find "definition of done" criteria and quality checklists

Return: workflow steps with sources, anti-patterns with citations, exact commands with sources.

Agent B — MCP server search

Run if: ❌ MCP or mcpdoc gaps exist.

• Search npm: @modelcontextprotocol/<technology>, mcp-server-<technology>
• Search GitHub: "mcp" "<technology>" "server" — repos with recent activity
• Fetch mcp.so and glama.ai/mcp for curated lists
• For each candidate: verify on npm (weekly downloads, last publish date); copy install command from README verbatim

Always search for mcpdoc — find current package name + install command; for each library in the task's stack, verify mcpdoc support by searching <library> llms.txt.

Return: verified servers with exact package names and install commands.

Agent C — Harness pattern research

Run if: ❌ skill or agent gaps exist.

• Search GitHub: ".claude/skills" <technology>, "CLAUDE.md" <technology>
• Search repos: karanb192/awesome-claude-skills, Mindrally/skills
• Fetch found SKILL.md files and read actual content

Return: direct quotes / file contents with source URLs. No paraphrases.

---

Phase 5.5: Research Consolidation

Write all findings — from Agent S (Phase 2) and Agents A/B/C (Phase 5) — into harness-research.md:

# Harness Research: <task>
Generated: <date>

## Structural Analysis (Agent S)
| Question | Answer | Evidence | Source |
[6 rows]

## Gap Table
[copy from Phase 3]

## Domain Findings (Agent A)
### Workflow steps [with sources]
### Anti-patterns [with sources]
### Quality standards / definition of done [with sources]

## MCP Servers Found (Agent B)
| Server | Package | Install | What it does | Verified |
[verified only — exact install commands from READMEs]

## Existing Harness Patterns Found (Agent C)
[direct quotes / file contents with source URLs]

## Research Gaps
[What was searched for but not found]
[Claims that still need a follow-up search]

Reflect on gaps. Run follow-up searches for anything that would materially affect patch quality. Do not proceed to Phase 6 until harness-research.md is written and gaps are resolved or marked unresolvable.

---

Phase 6: Surgical Patch

Open harness-research.md first. Build only what's in the gap table, in this order:

1. CLAUDE.md — if ❌: create from domain findings; if ⚠️: add missing pieces via @imports, never overwrite existing content
2. .claude/settings.json — merge MCP servers + permissions into existing; read before touching
3. .mcp.json — add only missing servers; install commands verbatim from Agent B
4. Loop skill — if ❌ and needed per gap table; use loop skill template below; reference verify skill; use exact gate commands from ci-gates rule
5. Verify skill — if ❌ and needed; include exact gate commands from research
6. Primary skill — workflow steps from Agent A
7. Supporting skills — sub-workflows from research
8. Rules — one file per anti-pattern or quality standard; invariant format
9. Agents — only if research found iterative verify-fix cycles standard in this domain
10. Hooks — if CI gate gap + research confirms immediate feedback is standard; exact build command from rules

For ⚠️ partial: read the existing file first, then add only what's missing. Never rewrite.

Reflection check (after each component)

• Does what I wrote reflect what harness-research.md actually says?
• Did I invent any step, command, or tool name not in research?
• Is there a research finding not yet encoded anywhere?

If invented: replace with a search result or remove it. If unencoded finding: create the component that encodes it.

Patch loop condition

• Is there a ❌/⚠️ gap in the table with no patch?
• Is there a verified MCP server in research not in .mcp.json?
• Is there an anti-pattern in research not in rules?

If yes → create missing component, check again. If no → done.

Hard stop at 10 patches.

---

Writing Standards

CLAUDE.md

• Purpose in one sentence
• Workflow phases with brief descriptions
• Critical MUST/MUST NOT rules (from anti-patterns)
• Under 200 lines — use @path/to/file imports to keep it lean

Skills (.claude/skills/<name>/SKILL.md)

---
name: skill-name
description: ≤250 chars. Front-load use case. Include natural-language keywords. Specific > generic.
disable-model-invocation: true  # side-effect skills: deploy, commit, migrate
user-invocable: false           # background knowledge, always-on patterns
allowed-tools: "Read Grep Glob Bash(git:*)"
model: opus                     # haiku=fast exploration, opus=critical decisions
context: fork                   # isolated subagent for heavy research/analysis
paths: "src/**/*.ts"            # auto-activate only on matching files
---

Use only fields you need. Content: numbered phases from research, failure handling from research, shell injection for live context (e.g. !`git branch --show-current`).

Keep SKILL.md ≤10KB. Detailed reference material (schemas, API docs, checklists) goes in references/ inside the skill directory — loaded on demand, not at startup.

Loop skill pattern

---
name: <verb>-loop
description: Run full <verb> cycle for one <unit>: analyze → implement → build → test → verify. Repeat until green. Use when <condition>.
disable-model-invocation: true
model: opus
---

Run the full cycle for: $ARGUMENTS

## Pre-flight
- Read migration-status.md — confirm $ARGUMENTS is not already complete
- Read project-wiki.md if it exists — check Reuse Map for existing implementations before planning
- Read the source component to understand its contract

## Cycle (repeat until all gates pass, max 5 iterations)

### Step 1 — Implement
Follow `.claude/skills/<implement-skill>/SKILL.md` for $ARGUMENTS

### Step 2 — Build gate
<build command from ci-gates rule> 2>&1
If fails: fix errors, go back to Step 1. Count this as one iteration.

### Step 3 — Test gate
<test command from ci-gates rule> 2>&1
If fails: fix, go back to Step 2.

### Step 4 — Verify
Follow `.claude/skills/<verify-skill>/SKILL.md` for $ARGUMENTS
If BLOCKED: fix the specific failure, go back to Step 2.
If READY: continue.

## Done
Update migration-status.md: mark $ARGUMENTS complete.
Report: what was done, iteration count, any caveats.

## If max iterations reached
Stop. Report: what failed, what was tried, what needs manual attention.

Track progress in migration-status.md:

# Status
| Unit | Status | Notes |
|------|--------|-------|
| A    | ✅ done | |
| B    | 🔄 in progress | |
| C    | ⬜ todo | depends on B |

Rules (.claude/rules/<topic>.md)

One anti-pattern or quality standard per file. Invariant format: "Always X", "Never Y, because [reason from research]".

settings.json + .mcp.json

Minimal permissions. Install commands copy-pasted from research, not reconstructed from memory.

Hooks

asyncRewake: true for background checks; exit 2 to block; if: for fine-grained filtering. Add only if research confirmed that immediate feedback is standard in this domain.

---

Completion Report

Harness patched for: <task summary>
Research: harness-research.md (<N> structural findings, <N> domain findings, <N> verified MCP servers, <N> harness patterns)

Kept intact:  <existing components confirmed sufficient by research>

Effective immediately:
  <rules, CLAUDE.md additions, skill content updates>

Requires restart:
  <MCP servers added to .mcp.json>
  <new skills — auto-invocation index rebuilds on restart>

Gaps not covered by research: <list if any>
Primary entry point: /<main-skill> <what to pass it>

If anything is listed under "Requires restart": tell the user to restart Claude Code before starting the task.