The shape of it
Three layers, and a human at the top.
The harness carries only the generic process. It reads each project's own AGENTS.md for the toolchain, the board, the CI gate names, and the merge rules, then drives the work down three layers. You sit above them as a veto gate, not an oracle.
The always-on entry for any build. It agrees the North Stars with you, freezes the contracts between work-units, then fans a wave across a team: a Builder per unit, each in its own git worktree. It never writes feature code.
It decomposes, adjudicates contract defects mid-wave, edits North Stars by your veto, and collects the result as one integration PR for a coupled wave, or N for independent units. One unit passing on its own isn't proof the whole wave works, so the integration sink rebuilds every app the wave's changes touched before any of it counts as done.
Owns exactly one contract-bound unit from nothing to a merge-ready PR, running the loop: worklog → dev-start → plan → implement TDD → simplify → auto-deep-review → pr-to-merged. It never crosses a unit boundary or changes a frozen contract; when it hits either, it routes the decision back up to the Overseer instead of guessing. This is where solo coding actually lives: the layer that touches the code.
A single vertical slice behind a frozen seam (a typed interface plus a canonical fake) so Builders run in parallel without stepping on each other's edits. Traceability runs North Star → unit, so every slice knows which agreed goal it serves and nothing orphaned gets built. The units form a dependency DAG; independent ones ship as their own PRs, coupled ones converge at an integration sink that lands last.
Contracts are frozen at decomposition time, not retrofitted. That is what makes the parallelism safe: a Builder can trust the seam it was handed because changing it is the Overseer's call, logged, not a Builder's improvisation.
Nothing merges ungated
A chain, not a checklist.
Each link only opens when the one before it closes. The discipline lives in the pipeline, not in a human remembering to run the step. A skipped lane counts as red, and "done" means the last link earned its green, not that the text stopped. And the chain does not end at the merge: the same discipline carries the change past the pull request, through provisioning to a verified release, the ground the agents that stop at the PR never reach.
- 01
Agree the goal.
North Stars settled with you, testable, before a line of code exists.
north-stars - 02
Freeze the contract.
Interfaces locked so builders can fan out in parallel, not step on each other.
freeze-contracts · plan-ready · TDD - 03
Survive real review.
Every finding attacked, not skimmed, then re-verified until it's actually fixed.
auto-deep-review · cx-verify - 04
Earn the merge.
Owned to the squash. A skipped test lane counts as red, not green.
pr-to-merged
Off the happy path, incident handles a production fire, pr-auto-fix classifies and repairs a red CI check on an open PR, and skill-evolve turns a run's own deviation into a versioned fix to the harness itself. The rule under all of them is the same: read the logs, not the badge.
For the curious
You never have to name a single one.
The harness runs the whole loop for you. But nothing here is a black box. It's made of small, named parts: nineteen skills, each doing one job, each one you can read and run yourself inside Claude Code.
Open the toolbox: all nineteen skills
Converges a fuzzy idea into agreed, testable North Stars before any decomposition or code. The source of truth every later phase is checked against.
Contract-first decomposition: recon the real seams, freeze the interfaces, then slice into a vertical-unit DAG with North Star → unit traceability.
The Overseer (L1). Agrees North Stars, freezes contracts, spawns a Builder per unit, adjudicates defects, and collects one PR per coupled wave or N for independent units.
The Builder (L2). Drives one contract-bound work-unit from nothing to a merge-ready PR: worklog → plan → TDD → simplify → deep-review → ship.
Provisions a fresh, isolated git worktree off the latest default branch, so each Builder works without colliding with a sibling's edits.
Wires a repo for the team with ready ensure: .gitignore entries, pipeline labels, CI gates, and the durable stores. Idempotent.
Multi-round adversarial review that also fixes what it finds, driving a branch to merge-ready. Claimed fixes are verified against the committed ref, not the working tree.
Runs a change through the validate / lint / test / PR / CI pipeline in one pass before it reaches upstream: the single-shot gate check.
Drives the affected flow end to end and observes behaviour, so a change is confirmed to actually work, not just that its tests are green.
The sanctioned merge path: preflight the gates, push, open the PR, review to convergence, clear bot review on current HEAD, and babysit CI to a squash.
Stands up a project's cloud footprint so a built app can actually run: remote, hosting, database, third-party services, env vars, domain, and seed data, in verified order. The day-0 counterpart to ready, stopping only at the real human gates.
Takes an already-merged change from merged to live and verified: sequences the rollout (env, additive migrations, code, destructive migrations), deploys, smoke-tests the live flows, and rolls back on failure.
A production firefight: gather the symptom, reproduce, root-cause, write a failing test, ship the fix. For a live deployed surface that misbehaves.
A CI check went red on an open PR: classify the failure, fix it, repush to green. Reads the actual logs, not the status badge.
The shared per-project coordination ledger every teammate reads on pickup and appends on wrap: what we did, decided, and learned across sessions.
Turns a skill-run deviation (where the skill and reality diverged) into a surgical, verified fix to the skill itself, shipped as a versioned release.
Evolves the harness itself (add, remove, or redesign a skill) through six charter gates, landing as a versioned release. The macro counterpart to the surgical skill-evolve.
Turns a dense doc (spec, RFC, plan) into a single self-contained interactive HTML explainer that teaches by operating, not by walls of prose.
A queryable design-principles library distilled from Interface Craft, linking mindsets and techniques to per-concept reference files.
Project specifics live in each package's AGENTS.md, never in these skills. The harness carries the generic process; the repo tells it the toolchain, the CI gate names, and the merge rules. A new package onboards by writing those into its own AGENTS.md.
The worklog hivemind
The wave remembers itself.
Every Builder in a wave reads one shared ledger on pickup (what we did, what we decided and why, and what we learned) while a single writer, the Overseer, appends on wrap. On a new session, a resumed unit, or a handed-off branch, the next Builder inherits the record first, so no one re-litigates a settled call or re-explains a constraint. One writer means write collisions are impossible by construction.
It's hot working memory scoped to the build. Data lives under <repo>/.harness/worklog/<project>/, a gitignored worktree of a DO-NOT-DELETE-hivemind orphan branch, so the record rides with the repo across machines and teammates without polluting the main history. One memory, many minds share it, with every entry still cited.
The cold, cross-project half of that memory is a second brain →
$ harness:worklog pickup # loading .harness/worklog/csv-export/ decided MIME = text/csv; not app/vnd · wave-3 · why: excel learned export suite skipped in CI · counts as red open header row on empty result? · blocks on you ✓ context loaded · nobody re-decides
Get the work
One install, every repo you open.
AgentHarness is a Claude Code plugin, installed once at user scope with your own GitHub auth. No hosted service, no proxy.
# inside Claude Code, once per machine, user scope /plugin marketplace add SmartStoreAI/agent-harness /plugin install harness@agent-harness # then wire a repo for the team harness:ready ensure
User-scope install works in every repo automatically. ready ensure wires ignores, pipeline labels, CI gates, and durable stores. Idempotent.
The stream
The harness maintains itself.
The repo that ships AgentHarness is governed by it. When a live run exposes a gap between what a skill says and what actually had to happen, skill-evolve turns that deviation into a surgical, verified fix, shipped as a versioned release you pull on the next update.
That loop is the product. Not the files on disk: the stream behind them.
Same model. Different discipline, and a memory.
A worked example: the same small feature request, given to the same model, twice. Left, vanilla Claude Code. Right, governed by Hyperception. Two definitions of "done", and only one that remembers.
| stage | Vanilla | With Hyperception |
|---|---|---|
| scope | guesses scope, columns, MIME type ✗ nothing agreed | goals agreed with you ✓ testable, signed off |
| build | code + tests in one pass ✗ grades its own work | contracts frozen · builders fan out ✓ parallel, frozen interfaces |
| defect | MIME type challenged mid-build ✓ verified → contract amended | |
| review | looks fine to me ✗ self-approved | findings attacked, not skimmed ✓ every fix re-verified |
| merge | first green check ✗ export suite skipped | earned, babysat to the squash ✓ skipped lanes count as red |
| later | it looked done ✕ production disagreed · patched at 2am | still green ✓ and this time it means done |
| next session | re-asks the same scope; the MIME decision is gone; a teammate re-litigates it | hyp search returns the decision with its supersede history; the worklog loads the why on pickup so nobody re-decides |
The work
Work that can't skip a step. A wave that can't forget one.
Install AgentHarness, wire one repo, and judge the pipeline by the PRs it sends you. The memory half is one page over.