repository-harness
Turn a software repository into a legible, agent-ready workspace.
repository-harness installs a small repository protocol and a safe updater.
The repository remains the system of record: product documents, decisions,
plans, code, tests, CI, and runtime evidence define the work.
It is not a task database, story tracker, agent orchestrator, or application runtime.
What It Solves
Coding agents often fail for ordinary engineering reasons:
- important intent exists only in chat;
- the repository does not identify authoritative documents;
- small changes acquire unnecessary process;
- long changes lose decisions and recovery context;
- completion is claimed without behavior-level proof; and
- an agent invents product policy when the request leaves a material choice open.
Harness provides a compact entrypoint, a navigable repository map, durable plans only when work needs them, explicit judgment boundaries, and mechanical validation.
Default Workflow
read-only request
-> inspect the smallest authoritative surface
-> answer with evidence
bounded change
-> inspect authority and affected behavior
-> implement the smallest coherent change
-> run relevant proof
multi-session or coordinated change
-> create docs/plans/active/<plan>.md
-> keep decisions, progress, recovery, and validation current
-> move the validated plan to docs/plans/completed/
material product ambiguity
-> stop before mutation
-> present the concrete choice and consequences
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.
Start with AGENTS.md, then
docs/WORKFLOW.md.
What Gets Installed
The default core contains:
- a compact
AGENTS.mdentrypoint; - the repository workflow and documentation map;
- product, decision, and execution-plan structure;
- optional templates for durable plans, decisions, application runbooks, and evidence-backed Harness improvements; and
- an invariant-encoding pattern and skill, plus 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.
Install
From a target repository:
curl -fsSL "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)" |
bash -s -- --yes
On PowerShell:
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.ps1"))) -Yes
Use --merge / -Merge to preserve existing files and add only missing
Harness paths. Use --override / -Override only when replacement is
intentional. Use --dry-run / -DryRun to preview.
The bootstrap downloads a versioned harness binary and checksum, verifies
release identity, and delegates installation to that candidate.
Maintain An Installation
scripts/bin/harness status
scripts/bin/harness doctor
scripts/bin/harness update --dry-run
scripts/bin/harness 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.
If 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. After a human resolves the semantic choice:
scripts/bin/harness update --continue --dry-run
scripts/bin/harness update --continue
Use scripts/bin/harness update --abort to discard only the staged resolution.
Optional Skills
Invariant enforcement routes accepted rules through repository-native validation:
$encode-invariant
Brownfield onboarding is explicit and read-only first:
$onboard-repository
Harness improvement is also explicit and requires baseline-to-rerun evidence:
$improve-harness
Engineering advice is a separate opt-in payload:
scripts/install-harness.sh --with-engineering-wisdom --yes /path/to/project
No skill runs during installation. Onboarding and Harness improvement remain explicit-only; invariant encoding responds only to matching work requests.
What We Prove
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.
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.
Protocol V1 End Of Life
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.
See
decision 0027.
Development
scripts/validate-premerge.sh
The contract runs Rust formatting, tests, Clippy, installer and workflow
checks, release guards, documentation checks, shell syntax, and
git diff --check.