repository-harness: a repository protocol and three-way-merge updater for coding agents
Turn any repo into an agent-ready workspace for Claude Code, Codex, Cursor, and other coding agents.
At a glance
- What is it?
- repository-harness is an MIT-licensed Rust tool that installs a small set of Markdown conventions and a versioned updater into an existing repository so coding agents read authoritative documents instead of guessing. It is not an orchestrator, and its value depends entirely on whether a team already keeps product and decision records in the repo.
- Who is it for?
- Adopt repository-harness if your team already treats the repository as the system of record and wants coding agents to follow that authority instead of inventing policy. Do not adopt it if you expect it to run your application, hold your tasks, or work without a real documentation practice behind it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 33 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure mode repository-harness was built around
The README lists six reasons coding agents fail, and none of them are model problems. Intent lives only in chat. The repository does not say which document is authoritative. Small changes pick up process they do not need. Long changes lose their decisions. Completion gets claimed without behaviour-level proof. And when a request leaves a material choice open, the agent invents product policy rather than asking. That last one is the sharpest. A request to add rate limiting, with no quota, identity key, enforcement owner, shared state topology or response contract, is not an instruction. It is a question the agent should refuse to answer on its own. repository-harness is aimed at teams that already write things down and want an agent to respect that record. It is not aimed at someone who wants an agent to generate the record.
What the installer actually writes, and what it deliberately does not
The default core is small on purpose. It installs a compact AGENTS.md entrypoint, a workflow and documentation map, product and decision and execution-plan structure, optional templates for durable plans and decisions and application runbooks, and an invariant-encoding pattern plus explicit-only onboarding and proposal-audit skills. The exact file list is declared in scripts/harness-install-files.txt, which is the first thing to read before running anything. What it does not install is equally explicit: no application architecture, no product policy, no validation commands, no credentials, no database, no schemas, no orchestration, no background processes. That boundary is the project's central design claim. The README states plainly that the repository remains the system of record, and that harness is not a task database, story tracker, agent orchestrator or application runtime. Teams that want the last four things will be disappointed, and the README says so before they install.
The four workflow branches and the plan lifecycle
The workflow is written as four branches rather than one pipeline. A read-only request inspects the smallest authoritative surface and answers with evidence. A bounded change inspects authority and affected behaviour, implements the smallest coherent change, then runs relevant proof. A multi-session or coordinated change creates docs/plans/active/<plan>.md and keeps decisions, progress, recovery and validation current until the validated plan moves to docs/plans/completed/. Material product ambiguity stops before mutation and presents the concrete choice and its consequences. The README gives two calibration examples that make the threshold concrete: a typo does not need a plan, a migration spanning sessions does. That is a judgement call left to the agent, not a rule enforced by code. Nothing in the described mechanism prevents an agent from filing a plan for a typo or skipping one for a migration. The protocol supplies the vocabulary and the directory layout; discipline supplies the rest.
Installing from a target repository
From a target repository, the documented bootstrap is a curl pipe into bash with a cache-busting timestamp, passing --yes. The PowerShell equivalent builds a scriptblock from an irm call and passes -Yes. Both accept --merge or -Merge to preserve existing files and add only missing Harness paths, --override or -Override when replacement is intentional, and --dry-run or -DryRun to preview. The bootstrap downloads a versioned harness binary and checksum, verifies release identity, and delegates installation to that candidate. Engineering advice is a separate opt-in payload: scripts/install-harness.sh --with-engineering-wisdom --yes /path/to/project. The README states that no skill runs during installation, that onboarding and harness improvement are explicit-only, and that invariant encoding responds only to matching work requests. The curl-pipe pattern means the first execution is a remote script; the checksum verification described applies to the binary the script downloads, not to the script itself.
Maintenance, the three-way merge, and what happens on conflict
Day-to-day maintenance is four commands: scripts/bin/harness status, doctor, update --dry-run, and update. 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, the README states that no managed file or executable changes. Harness retains BASE, LOCAL, UPSTREAM and RESOLVED copies plus the frozen managed input set. A human resolves the semantic choice, then runs scripts/bin/harness update --continue --dry-run followed by update --continue. update --abort discards only the staged resolution. This is the strongest engineering detail in the repository: conflict handling that refuses to write anything until a person has decided. It is also the main ongoing cost. Every upstream release that touches a file you have edited becomes a manual merge, and the release cadence visible in the material is fast, with harness-v0.1.8, v0.1.9 and v0.1.10 all published within four days in August 2026. A team that edits AGENTS.md heavily should expect to spend time in --continue.
Licence, end of life for protocol v1, and the state you inherit
The project is MIT-licensed, which permits commercial and private use with the usual attribution and warranty terms. This is not legal advice. The more operationally relevant item is the protocol v1 end of life. The README states that the former SQLite harness-cli and machine protocol v1 ended support on 2026-08-10, that the last published compatibility release is harness-cli-v0.1.22, and that the current repository no longer builds, installs, tests or publishes it. Consumers may pin that immutable release. Critically, harness does not automatically delete legacy binaries, databases, schemas or state from consumer repositories. Decision 0027 in docs/decisions/ records the reasoning. Anyone upgrading from an older setup should locate that SQLite state themselves rather than assume the installer cleaned it up.
What the project claims to prove, and the boundary it draws
The README names three release-evidence boundaries: fresh installation of the declared core without fabricated application truth or hidden lifecycle state; repository navigation, meaning an agent follows repository authority, avoids speculative product policy and can stop at a real decision boundary; and safe maintenance, meaning updates verify identity and checksum, preserve local edits, stage conflicts, reject drift and recover interrupted transactions. Then it draws a line. Operating an arbitrary consumer application end to end remains consumer-owned research, and harness does not claim that installation alone supplies runtimes, fixtures, credentials, logs or interface automation. That is an unusually honest scope statement, and it should be read as the real answer to whether this tool will help. If your agent's failures are about not knowing which document is authoritative, harness addresses that. If your agent's failures are about not being able to run your test suite, harness does not, and it says so.
How this differs from a rules file or a task tracker
The nearest thing most teams already have is a single AGENTS.md or CLAUDE.md file, plus a task tracker such as Linear or Jira. A hand-written rules file has no updater, so it drifts and nobody notices until an agent follows a stale instruction. A task tracker holds work items outside the repository, which is exactly the split the README argues against when it says important intent exists only in chat. repository-harness takes a third position: the protocol lives in the repository next to the code, the plan artefacts live under docs/plans/, and a versioned binary with a three-way merge keeps the protocol current without overwriting local edits. The trade is that you now maintain a tool and a conflict-resolution habit. A team whose documentation practice is one README and a Slack channel will get less from this than a team that already writes decision records, because the protocol only routes an agent to authority that exists.
Editorial conclusion
Adopt repository-harness if your team already treats the repository as the system of record and wants coding agents to follow that authority instead of inventing policy. Do not adopt it if you expect it to run your application, hold your tasks, or work without a real documentation practice behind it. Before installing, read scripts/harness-install-files.txt to see the exact payload, confirm that your repository has an owner for AGENTS.md and docs/plans/, and check whether any legacy harness-cli SQLite state still exists, because the project states it will not delete it for you.
Community notes