<div align="center">

AutoHarness

Engineering discipline for coding agents.<br> Prepare before building. Check against the original. Let someone else judge the result.

Works with Claude Code · Codex CLI · Gemini CLI · Antigravity CLI · Qwen Code · GigaCode · Strands

How it works · Quick start · Example · Security · Reference

</div>

---

AutoHarness keeps an agent from taking on a task unprepared. The agent works out what the task needs, gathers the know-how and tools for it, and an independent critic checks the result until the quality is acceptable.

| An agent on its own | The same agent with AutoHarness | |---|---| | Writes from memory | Gets the original first: the real API response, the data sample, the mockup | | Guesses how the work is done | Finds and reads how it is done well, and cites it | | Installs whatever looks right | Installs only what passes a trust check and the user's constraints | | Fills open questions with its own habits | Picks what the person who asked would expect, and writes it down | | Marks its own work "done" | A fresh reviewer that did not do the work rules on it | | Loops on the same fix | Changes approach, then asks an arbiter, then the user | | Forgets everything after the session | Keeps what it learned as skills and recipes for the next task |

A coding agent (Claude Code, Codex CLI, Gemini CLI, Antigravity CLI, Qwen Code, GigaCode, Strands) usually goes at a task head-on. It writes from memory without looking at what the result has to match, without finding out how such work is done well, and then marks its own work "done". The ceiling on quality is then whatever the model remembers. It shows on any task: an integration with someone else's API, tests, setting up an environment, a page built from a mockup, a drawing that has to match a reference image.

Engineers do not work that way. Nobody builds an aircraft from memory: the work is split into disciplines (aerodynamics, materials, strength, control), what is already known in each is looked up, hypotheses are checked on models, and only then is it built. AutoHarness brings that order to the agent:

flowchart LR
    A[Analysis<br><code>init</code>] --> P[Preparation<br>areas · method · reference · facts]
    P --> B[Brief<br>the plan, recorded]
    B --> I[Install<br>trust · constraints]
    I --> S[Base<br>block-in first]
    S --> R{Review<br>independent critic}
    R -- blocking --> L[Learn<br>update the skill, then fix]
    L --> R
    R -- minor or none --> T[Teardown<br>skills · recipes · lessons]
    P -. nothing fits .-> W[Write a skill<br>from the sources read]
    W --> B

The two sides split the work: the agent thinks, the CLI keeps count and guards the order. The agent decides what the task needs and whether the result is good. The autoharness CLI searches registries, scores trust, installs and removes tools, keeps the records, and does not let the agent move on until the previous step is done. Every command answers in JSON with a next field that says what to do next. Exit code 3 always means one thing: stop and ask the user.

The process

1. Analysis: init

autoharness init "<the user's task, verbatim>" --mode light|full|reviewed|auto

• light: a chore that needs no capability from the catalog (a typo, a commit). No search and no brief: do the work, check it, teardown. A task that needs any capability (an API, a browser, tests, debugging, an image) is raised to full by init, whatever the agent chose.
• full: something is missing: what to check against, know-how, a way to verify. The full cycle below applies.
• reviewed: the full cycle plus a mandatory independent critic before the end.

init searches skills.sh and the official MCP registry for the task right away. It shows similar saved setups (recipes), candidates earlier tasks rejected (with the reason), and open follow-ups. A running task can be raised without starting over: autoharness mode full.

2. Preparation: areas of know-how, search, method

This is where quality is decided, and it is the step agents usually skip.

• Areas of know-how. The agent splits the task into the areas the work itself is made of: for a service, its protocol, data model and concurrency; for a drawing, figures, anatomy and light. For each, it looks for something ready-made (autoharness search skill|mcp "<query>", autoharness need) and takes what fits. If nothing fits, it writes its own skill from the sources it read.
• Method. How this kind of work is done well: the algorithm, the order, the known pitfalls. The agent takes it from sources it found and read, with links, not from memory.
• Input. The original the result has to match: the API's real response, a data sample, the mockup, the reference image. A description of it does not count. A search page, a gallery or someone's version of it (fan art, a mockup, a blog example) is not the original either.
• Facts. Before the first result the agent measures with a tool what the result will be judged on: fields and values, sizes, positions, proportions, timings. Then it records them (evidence add <file> --kind facts).
• Open choices. Where the task leaves a choice open (a format, a value or a formula, what a field holds) and the user cannot be asked, the agent picks what the person who asked would take for granted on first look: the plain, simple form, nothing they did not ask for. A tool's or a skill's advice does not decide it.

These are not suggestions. The CLI requires each part:

| What | How it is enforced | |---|---| | Every area is covered | brief --domains "<area>: skill\|mcp\|create <name> (searched: <query>)". The search must actually have run in this task, and the skill or server must be among its results. "I already know how" is not accepted: that knowledge goes into a skill | | Method from sources | brief --method "<technique>: <url>; …; searched: <queries>". Without links only an explicit nothing usable; searched: … is accepted | | Open choices settled | brief --expects "<open choice>: <pick> - <why they would expect it>; …" or none: <why>. Each becomes a brief item the critic checks | | Skills in use, not in words | The first result is refused until the skills taken are installed and the skills to create are created and filled in | | Facts from the reference | --kind facts is refused without a reference. The first result is refused until there are facts taken after the reference |

3. Brief: the plan before the work

autoharness brief --goal "<quality bar>" --domains "..." --method "..." \
  --inputs "<what is missing and where to get it>" --expects "<open choice>: <pick> - <why>; ..." \
  --constraints "<the user's constraints, verbatim>" \
  --verify "<how to check, against what>" --candidates "<name>: take|skip, why; …" \
  --gaps "create <skill>: <what it does>; …"

The brief records what a good result is and how it will be checked, the user's constraints verbatim ("no new dependencies", "offline only"), and a verdict on every candidate. Work that is judged by eye needs --fidelity: the level the result is judged at ("stylised poster, not a photograph"). Browser, API, log and database checks have ready templates (--verify-template browser|api|api-client|logs|database). With the hook the agent cannot change anything until the brief is recorded.

4. Install: trust and constraints

autoharness inspect mcp <name>        # trust score, secrets, where the server connects
autoharness add mcp <name>  |  autoharness add skill <owner/repo@skill>

• Trust score. The curated catalog is trusted. Registry servers are scored by namespace, pinned version and publisher. Anything not "high", anything with secrets and anything remote is installed only after an explicit "yes" from the user.
• Skill scan. A skill is downloaded to a temporary folder and checked for dangerous patterns: ~/.ssh, curl | sh, "don't tell the user", obfuscation.
• Constraints. When the brief has any, a fresh subagent checks the candidate against them (vet), not the agent that wants to install it.
• Network. With allowed_hosts set, a server outside the list is installed only with the user's consent.

After installing, the agent makes one cheap call to try it. If it does not work: remove and the next candidate. There is no point spending long on fixing someone else's tool.

5. Base: the frame first, details later

The first version is a rough base (a block-in): structure, layout, proportions, the main parts from the facts, no polish. A critic looks at it right away, and the first round judges the base only. Unfinished details are at most minor in that round; a wrong base is major. A mistake in the base gets more expensive with every round built on top of it. Edits without a critic are counted: after 20 edits without a fresh critic the hook stops editing.

6. Review: the author is not the judge

autoharness evidence add <file> --kind reference|facts|result   # the result: whole, then close-ups (--closeup)
autoharness evidence diff                                       # for code: the whole working-tree diff
autoharness verify run "<command>" --for B1                     # autoharness runs it; the exit code decides
autoharness critic                                              # a prompt for an independent critic
autoharness review --by critic --answer-file <file>
autoharness critic --run claude|codex|agy                       # or autoharness starts a read-only critic itself

• The critic is a fresh subagent that did not do the work. Its answer is kept as it is. autoharness reads the points, the verdict and a one-time ANSWER-ID from it itself, so a softened retelling cannot be passed off instead. A subagent given a review prompt reviews; it cannot take the task over.
• What the critic checks:
  • that the reference is the original itself;
  • that the facts are right, by checking a few of them against the reference;
  • every brief item (met | partial | missing | contradicts);
  • the open choices, as the person who asked would see them;
  • whether the work follows the method found;
  • what was done beyond the request;
  • whether each verify run really checks its item;
  • whether the work is finished as a whole (ACCEPT). "No" is at least major.
• A check has to be able to fail. true, echo ok or looking for a string in a file do not count. A run is tied to a version of the code and goes stale after an edit.
• Blind comparison. In work judged by eye, the critic compares the current result with the best earlier one under the names A and B. Only autoharness knows which is which. If the earlier one is closer, the answer is "Went backwards", and the earlier result stays the best.
• Two reviewers (brief --review pair). Every round, besides the critic, a code-quality reviewer checks for bugs, unhandled errors, security, and tests that check nothing. The round's verdict is the worse of the two.
• Settled disputes do not come back. A fresh critic rules on a disputed point (critic --dispute). A point the user rejects is recorded (ruling add), an