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.md entrypoint;
• 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:

1. Fresh installation: the declared core is installed without fabricated application truth or hidden lifecycle state.
2. Repository navigation: an agent follows repository authority, avoids speculative product policy, and can stop at a real decision boundary.
3. 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.