repository-harness

July 25, 2026 · View on GitHub

Turn a software repository into a legible, agent-ready workspace.

repository-harness gives coding agents a small entrypoint, structured repository knowledge, durable execution plans when work truly needs them, and mechanical validation. The repository—not a hidden workflow database—is the default system of record.

The app is what users touch. The harness is what makes the app and its rules easy for agents and humans to understand.

Why This Exists

Coding agents commonly fail for ordinary engineering reasons:

  • important constraints live only in chat or in someone's head;
  • the repository does not say which documents are authoritative;
  • small changes are wrapped in process that obscures the actual work;
  • large changes lose decisions and progress between sessions;
  • validation is vague, late, or disconnected from user-visible behavior.

The answer is not a longer mandatory workflow. It is a repository that exposes the right context at the right time and enforces important invariants with tests and scripts.

This direction is anchored in OpenAI's Harness engineering account: keep the agent entrypoint small, make repository knowledge navigable, store complex execution plans durably, make application behavior directly inspectable, and enforce architectural rules mechanically.

The Default Workflow

Start with AGENTS.md, then follow the map in docs/WORKFLOW.md. The size of the request determines the amount of durable process:

read-only question
  -> inspect the smallest authoritative surface
  -> answer with evidence

bounded change
  -> inspect locally
  -> change code or docs
  -> run relevant proof
  -> report the result

multi-session or coordination-heavy change
  -> create docs/plans/active/<plan>.md
  -> record progress, decisions, and validation in Git
  -> move the finished plan to docs/plans/completed/

consequential ambiguity
  -> pause before mutation
  -> present the concrete choice and its effects
  -> continue after authority is clear

A typo fix does not need intake, a story row, or a trace. A migration spanning several sessions does need a durable plan. A request to “simplify permissions” without saying whether existing access may be revoked needs human judgment before code changes. These are independent decisions, not risk levels on one process ladder.

Repository Knowledge

The default path requires no local database. Product documents, code, tests, plans, decisions, and Git history form one inspectable source of truth.

Install Harness Into A Project

From a target project directory, run:

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

On Windows PowerShell:

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

Use --merge / -Merge to add missing Harness files without replacing existing project files. Use --override / -Override only when replacement is intentional. Use --dry-run / -DryRun to preview writes.

The default installation downloads a checksum-verified Rust binary named harness, then uses it to install the small repository-centered core. It does not install the optional SQLite compatibility CLI, discover schemas, install database bootstrap scripts, or add database ignore rules. It also does not copy this upstream repository's README or architecture over consumer-owned truth. The core includes the explicit-only $onboard-repository and $audit-onboarding-proposal skills. They never run during installation or ordinary tasks.

To map a brownfield repository after installation, ask the agent to run:

$onboard-repository

The first pass is read-only and returns evidence-backed proposals. Exact user approval is required before a later pass may apply selected repository guidance.

Optional Engineering Wisdom

The neutral default does not install engineering philosophy. To add the explicit-only engineering-wisdom advisory pack to a fresh project:

scripts/install-harness.sh --with-engineering-wisdom --yes /path/to/project

./scripts/install-harness.ps1 -WithEngineeringWisdom -Yes -Directory C:\path\to\project

For a project that already has Harness, add --merge / -Merge. This preserves existing files and fills only the missing pack files:

scripts/install-harness.sh --merge --with-engineering-wisdom --yes /path/to/project

Installation does not run or activate the skill. Invoke it explicitly:

$engineering-wisdom review this payment change

Its review separates repository observations, contextual heuristics, counter-pressure, proposed repository-owned enforcement, and verification. Advice cannot silently become policy or trigger an architecture rewrite. Repository intent and tests remain authoritative.

Without the opt-in flag, a fresh or normal installation does not copy the pack. Re-running the installer without the flag also leaves an already installed pack untouched; omission is non-activation, not removal. To remove the stateless pack, delete only .agents/skills/engineering-wisdom/:

rm -r .agents/skills/engineering-wisdom

Remove-Item -Recurse .agents/skills/engineering-wisdom

The concise bibliography acknowledges Robert C. Martin's broader body of work, including code, design, testing, refactoring, architecture, and professional practice. Its ideas are paraphrased and presented as fallible heuristics.

After installation, preview and apply future core upgrades with:

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

update reads the published core-release pointer, downloads the platform binary and checksum from that exact versioned harness-v* GitHub release, verifies its bytes and version identity, and lets that candidate merge its embedded core. It refuses downgrades and replaces only the selected repository's local executable. The updater keeps the installed upstream base under .harness-core/, performs a three-way merge, and backs up changed files before activation. On Windows, use scripts\bin\harness.exe.

An overlapping local/upstream edit stops without changing managed files or the installed executable. Harness stages BASE, LOCAL, UPSTREAM, and RESOLVED copies under .harness-core/update/, freezes all other managed inputs, and retains the remotely re-verifiable candidate under .harness-core/update-candidate/. After an agent explains the semantic choice and receives human direction, edit the RESOLVED copy and run:

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

Use scripts/bin/harness update --abort to discard the staged resolution. A continuation fails if any managed file or staged input changed after conflict detection.

Installations older than the first release containing self-update discovery cannot discover that release with their old executable. Refresh those once with the platform installer; subsequent releases use harness update directly.

For an older installation with a generated, long AGENTS.md, refresh it to the small marked block:

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

For Claude Code, add --claude (PowerShell: -Claude). This creates or updates a marked block in CLAUDE.md that imports AGENTS.md; existing local instructions are preserved and backed up before changes.

Try The Flow

docs/demo/README.md follows concrete examples through the four workflow cases. The important cause and effect is simple:

  • small entrypoint → less instruction loading and less drift;
  • authoritative repository map → agents retrieve only relevant context;
  • plans only for genuinely durable work → small changes stay cheap while long work survives session boundaries;
  • repo-native tests → completion is proved by behavior rather than workflow bookkeeping;
  • explicit pause conditions → consequential product choices remain human-owned.

Optional Compatibility Control Plane

The Rust CLI, SQLite schema, feature intake, story matrix, trace scoring, improvement proposals, and orchestration contract remain supported for an external runner or team that explicitly selects them. They are not prerequisites for ordinary repository work.

Install that complete compatibility bundle explicitly:

scripts/install-harness.sh --with-cli --yes /path/to/project

./scripts/install-harness.ps1 -WithCli -Yes -Directory C:\path\to\project

Then bootstrap its ignored local database:

scripts/bootstrap-harness.sh

.\scripts\bootstrap-harness.ps1

Then use scripts/bin/harness-cli (or the Windows .exe). See scripts/README.md and the compatibility index. One independent consumer is Symphony; it is not installed as part of this repository. Symphony owns work selection, agent runs, worktrees, conflict/retry policy, changeset coordination, PR/review synchronization, and its runtime evidence. Harness retains only the generic atomic protocol primitives that protect repository state.

Repository Structure

project/
  .agents/
    skills/
      onboard-repository/
      audit-onboarding-proposal/
  AGENTS.md
  docs/
    WORKFLOW.md
    HARNESS.md
    ARCHITECTURE.md
    product/
    plans/
      active/
      completed/
    decisions/
    templates/
  scripts/
  tests/

Contributing

See the contributing guide. Especially useful contributions are real agent failure cases, examples of application legibility, mechanical architecture checks, smaller default instructions, and validation that proves user-visible behavior.

Short description:

A repository-centered engineering harness for coding agents: compact instructions, navigable context, durable plans when needed, decisions, and executable validation.