repository-harness: an agent-ready protocol for Claude Code and Codex

The failure mode repository-harness targets: intent that lives only in chat

The README lists six ordinary engineering reasons coding agents fail: intent trapped in chat, no authoritative documents, process bloat on small changes, lost decisions on long changes, completion claimed without behavior-level proof, and agents inventing product policy when a request leaves a material choice open. None of these are model problems. They are repository problems, and the project treats them that way.

The audience is teams already running Claude Code, Codex, Cursor or similar agents against a real codebase. The repository stays the system of record: product documents, decisions, plans, code, tests, CI and runtime evidence define the work. repository-harness is not a task database, story tracker, agent orchestrator or application runtime, and the README says so directly. That negative list matters more than the feature list, because it tells you where to stop expecting help.

How the protocol routes work: four paths and a stop condition

The default workflow is a routing table, not a pipeline. A read-only request inspects the smallest authoritative surface and answers with evidence. A bounded change inspects authority and affected behavior, implements the smallest coherent change, then runs relevant proof. A multi-session or coordinated change creates docs/plans/active/<plan>.md, keeps decisions, progress, recovery and validation current, and moves the validated plan to docs/plans/completed/. Material product ambiguity stops before mutation and presents the concrete choice and consequences.

The examples are the clearest part of the design. A typo does not need a plan. A migration spanning sessions does. A request to "add rate limiting" without a quota, identity key, enforcement owner, shared state topology or response contract must stop before implementation. That last case is the interesting one: the protocol forces the agent to surface missing product policy rather than guess it, which is a deliberate refusal to be helpful.

The installed core is correspondingly small: a compact AGENTS.md entrypoint, the repository workflow and documentation map, product and decision and execution-plan structure, optional templates for durable plans, decisions, runbooks and evidence-backed improvements, plus an invariant-encoding pattern and skill and explicit-only onboarding and proposal-audit skills. It does not install application architecture, product policy, validation commands, credentials, a database, schemas, orchestration or background processes. The exact payload is declared in scripts/harness-install-files.txt, which is the file to read before you trust any summary.

Installing repository-harness and running a first bounded change

Installation runs from the target repository, not from a clone of the harness. The bootstrap downloads a versioned harness binary and checksum, verifies release identity, and delegates installation to that candidate. The README gives this one-liner, with a cache-busting timestamp appended to the raw URL:

curl -fsSL "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)" |
  bash -s -- --yes

On PowerShell the equivalent is:

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.ps1"))) -Yes

Three flags control what happens to files already in your tree. --merge (or -Merge) preserves existing files and adds only missing Harness paths. --override (or -Override) replaces, and the README says to use it only when replacement is intentional. --dry-run (or -DryRun) previews. On a repository that already has its own AGENTS.md, --merge is the only sane first run.

After installing, the README says to start with AGENTS.md and then docs/WORKFLOW.md. Those two files are the entrypoint an agent reads before touching anything else. The first real use is deliberately unglamorous: point your agent at a bounded change and check that it inspects the smallest authoritative surface before editing, rather than proposing a plan for a one-line fix. If it proposes a plan, the routing logic is not being read.

Maintenance is a separate binary under scripts/bin:

scripts/bin/harness status
scripts/bin/harness doctor
scripts/bin/harness update --dry-run
scripts/bin/harness update

status and doctor are the read-only checks. update --dry-run shows what a merge would do before it does it.

The updater's three-way merge is the real engineering, and its conflict path is manual

The updater stores the exact upstream base under .harness-core/, performs a three-way merge, backs up changed files, and activates the result transactionally. When local and upstream edits overlap, no managed file or executable changes. Harness retains BASE, LOCAL, UPSTREAM and RESOLVED copies plus the frozen managed input set, and a human resolves the semantic choice before continuing:

scripts/bin/harness update --continue --dry-run
scripts/bin/harness update --continue

scripts/bin/harness update --abort discards only the staged resolution. That abort semantics is narrower than most people assume: it throws away the staged merge, not your local edits, which is the correct behavior but worth knowing before you reach for it in a panic.

The limitation is that conflict resolution is not automated and the README does not claim it will be. If your team edits managed files often, every upstream release can become a manual merge with four copies on disk. The README also does not document rollback of an already-activated update, so treat activation as the point of no easy return and rely on the backups the updater takes. Teams that want set-and-forget upgrades should read that constraint before adopting.

Protocol v1 end of life and what the repository no longer builds

The former SQLite harness-cli and machine protocol v1 ended support on 2026-08-10. The last published compatibility release is harness-cli-v0.1.22. Existing consumers may pin that immutable release, but the current repository no longer builds, installs, tests or publishes it. Harness does not automatically delete legacy binaries, databases, schemas or state from consumer repositories. Decision 0027 in docs/decisions/ records the reasoning.

For anyone evaluating the project from an older blog post or an old package reference, this is the single most important fact. The project pivoted from a stateful CLI with a machine protocol to a repository protocol with an installer. If your workflow depended on the SQLite CLI, the upgrade path is pinning harness-cli-v0.1.22 and cleaning up your own state, not migrating forward. The README is clear that cleanup is your job.

What the project claims to prove, and where its evidence stops

Harness owns three release-evidence boundaries. Fresh installation: the declared core is installed without fabricated application truth or hidden lifecycle state. Repository navigation: an agent follows repository authority, avoids speculative product policy, and can stop at a real decision boundary. Safe maintenance: updates verify identity and checksum, preserve local edits, stage conflicts, reject drift, and recover interrupted transactions.

Those are narrow claims, and the README is honest about the edge. Operating an arbitrary consumer application end to end remains consumer-owned research. Harness does not claim that installation alone supplies runtimes, fixtures, credentials, logs or interface automation. So the first boundary covers the installer, the second covers agent behavior under the protocol, and the third covers the updater. Nothing covers whether your application actually works, which is where most teams will still need their own CI.

Optional skills follow the same restraint. Invariant enforcement routes accepted rules through repository-native validation via $encode-invariant. Brownfield onboarding is explicit and read-only first via $onboard-repository. Harness improvement is explicit and requires baseline-to-rerun evidence via $improve-harness. No skill runs during installation, and onboarding and improvement remain explicit-only. Engineering advice is a separate opt-in payload installed with --with-engineering-wisdom.

repository-harness against AGENTS.md alone or a spec-driven framework

The closest alternative is doing nothing beyond a hand-written AGENTS.md. The difference is maintenance: a single file drifts, and there is no mechanism to detect that your local copy has diverged from upstream guidance. repository-harness adds the base copy under .harness-core/ and the three-way merge, which is the part a hand-rolled file cannot give you. If you never intend to pull upstream updates, the hand-written file is cheaper and you lose only the templates and routing table.

The other alternative is a spec-driven or task-tracking framework that owns the plan lifecycle inside its own store. repository-harness deliberately keeps plans as files under docs/plans/active/ and docs/plans/completed/ in your repository. That means plans are reviewable in a pull request and survive tool churn, but it also means no querying across projects, no dashboards and no status roll-ups. If you need portfolio visibility into agent work, this is the wrong tool and the README's refusal to be a task database is not a gap you can configure away.

Development contract, licence and upgrade cost

The project is MIT licensed, declared both in the repository LICENSE file and under [workspace.package] in Cargo.toml. The workspace uses resolver 3 and a single member, crates/harness, on edition 2021. MIT is permissive, so embedding the installed templates in a commercial repository is not the interesting question; the interesting one is attribution and what your own legal review says about the templates you copy. Nothing here is legal advice.

The pre-merge contract is scripts/validate-premerge.sh, which runs Rust formatting, tests, Clippy, installer and workflow checks, release guards, documentation checks, shell syntax and git diff --check. If you fork and modify the installer, that script is the gate the maintainers use. The last push was on 2026-08-13, and the releases listed are harness-v0.1.8, harness-v0.1.9 and harness-v0.1.10, all from August 2026.

Upgrade cost is the three-way merge described above. Every upstream release that touches a file you have edited produces a staged conflict and a manual decision. The cost scales with how much you customize the managed files, so the cheapest posture is to leave the core untouched and put your own material outside the managed set.

Editorial conclusion

Adopt repository-harness if your agents keep inventing product policy or losing decisions between sessions and you want a repo-level protocol with a transactional updater. Skip it if you want task tracking, orchestration or an application runtime, because the README says it is none of those. Before installing, read scripts/harness-install-files.txt to see the exact payload, and run scripts/bin/harness update --dry-run after the first install to confirm the three-way merge behaves on your tree.

Frequently asked questions

Official sources

1. hoangnb24/repository-harness on GitHub
2. Issues
3. License: MIT
4. README
5. Releases