mono-harness

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

zharness 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. The binary scaffolds docs; it does not run the lifecycle.

Start with AGENTS.md, then docs/WORKFLOW.md.

Give this to a coding agent

Copy the block into the consumer repository chat when you want the agent to
install, refresh, or work with zharness.

Work in this git repository. Read https://github.com/therealtinhtute/mono-harness/blob/master/README.md and, once they exist, this repo's AGENTS.md and docs/WORKFLOW.md. If zharness is not on PATH or outdated, install/upgrade it with scripts/install-zharness.sh. If this repo has no docs/WORKFLOW.md, run zharness install. If the repo is already initialized, playbooks are outdated, or zharness install reports drifted files, run zharness update to refresh the latest playbooks (fresh-overwrite; PROJECT.md is never overwritten, and an edited AGENTS.md block makes update refuse with a diff). Plans live only in docs/plans/ — multi-session or complex work uses exactly one file at docs/plans/active/{slug}.md, moved to docs/plans/completed/ upon verified handoff. Small changes need no plan. zharness only manages the doc set (install/update/uninstall) — it does not run the lifecycle. Missing AGENTS.md: zharness install, do not invent the file. Claude Code reads CLAUDE.md, not AGENTS.md; if CLAUDE.md is missing, the consumer writes a thin file containing the line @AGENTS.md.

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.

zharness provides a compact entrypoint, a navigable repository map, durable
plans only when work needs them, and playbooks that stay reduced for read-only
and bounded work.

Goals

• Skills and the harness are one goal. This repository builds an agent
  skill set for the SDLC alongside zharness, the protocol that keeps that
  lifecycle legible and portable across coding agents.
• The repository stays the system of record. Plans, decisions, and
  validation live in tracked markdown that a human can read and git can
  history. There is no database — tracked markdown and git history are
  the only record.
• Process proportional to the work. A read-only question and a
  multi-session refactor should not cost the same ceremony. Reduced playbook
  paths write no lifecycle rows; durable plans exist only for work that needs
  recovery context.
• Invariants enforced, not assumed. Where a rule can be checked it is
  checked — the pre-commit and CI plan guards fail on violation rather than
  letting a broken state travel silently. What they cannot check, they say so
  in docs/playbooks/check.md instead of implying coverage.
• Portable across agents. The spine skills are thin triggers; the
  operating logic sits in playbooks the CLI scaffolds into the repository.
  Any agent that reads a file and runs a CLI follows the same protocol.
• Diagnostics that name the next action. A finding states the violating
  item, the rule it breaks, its authority, and what to do — never a bare
  validation failure.
• Safe to adopt and to leave. install/update/uninstall manage only
  the doc set, merging rather than clobbering the files a project owns; the one
  exception is update migrating a 9-section active plan, Validation bytes kept.

Non-goals

• Not a task database, tracker, or orchestrator. zharness scaffolds and
  checks documents. It does not run the lifecycle, assign work, or drive an
  agent.
• No database. Anything that must outlive the working copy belongs
  in tracked markdown or in git history.
• No hosted or shared state. The CLI makes no network calls. Everything
  the harness knows lives in the working copy.
• Not a replacement for git. The harness records intent and validation;
  git remains the record of what changed.
• No derived-fact documents. Routes, environment variables, and file
  inventories are not hand-maintained in docs/ — the code is authoritative
  for what can be re-derived from it.
• No automatic remediation. Gates report verdicts and findings; deciding
  what to do about them stays with the operator.

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.

What gets installed

The managed set is:

• a compact AGENTS.md entrypoint (marked ZHARNESS block only);
• docs/WORKFLOW.md, the six stage playbooks, and their six companions;
• a docs/PROJECT.md identity scaffold;
• .zharness/base/ for update tracking (a sha256 manifest and the ownership ledger).

It does not write CLAUDE.md. It does not install application architecture,
product policy, skills, git hooks, credentials, a database, schemas,
orchestration, or background processes.

Install

From a target repository, with zharness on PATH:

zharness install

Get the binary once per machine (gh + tar; Linux or macOS, amd64 or arm64):

bash scripts/install-zharness.sh
zharness --version

install is idempotent. It records upstream hashes, prints a read-only
brownfield report, and exits 0. Use --root <dir> when cwd is not the
consumer repo.

Maintain an installation

zharness update
zharness update --force
zharness update --check [--all]
zharness uninstall

docs/WORKFLOW.md and the stage playbooks are pure upstream mirrors: update
always overwrites them with the latest bytes. docs/PROJECT.md is written only
when absent; after that it belongs to the project. The marked AGENTS.md block
is replaced between its markers; if it was edited since zharness last wrote it,
update prints the diff, writes nothing, and exits non-zero until you move the
edit outside the markers or pass --force (rerunning install resets the block without asking). --check reports drift without
writing (--all: every repository in ~/.config/zharness/repos). A single active
plan in the older 9-section format is migrated in place to the 5-section format
with its ## Validation bytes unchanged; any other heading set, or more than one
active plan, is left alone with a notice. Uninstall
removes managed files only; consumer-owned bytes are never deleted.

Optional skills

Skills are not part of zharness install. They live in this source repository,
the stable release of the skills; the former orkit-tui incubator is archived
and no longer syncs here. The repository is private, so installing over SSH
needs local SSH keys with access to it:

npx skills add [email protected]:therealtinhtute/mono-harness.git --list   # list without installing
npx skills add [email protected]:therealtinhtute/mono-harness.git -a claude-code -g -y

No skill runs during installation.

To reinstall rules and skills from scratch, from this repository:

cp rules/*.md ~/.claude/rules/
npx skills add [email protected]:therealtinhtute/mono-harness.git -a claude-code -g -y

npx skills add never removes a skill that was dropped from this repository.
Trash each dropped skill by name from ~/.claude/skills/ and ~/.agents/skills/
before reinstalling.

v0.16

Protocol on the v0.15 three-verb binary: absorb at handoff close, at most
one active plan, independent judge for full checks. Pin v0.14.x to keep
the old lifecycle CLI. Existing harness.db files are consumer-owned;
nothing here deletes them.

See cli/docs/CONTRACT.md and
docs/ARCHITECTURE.md.

v0.15

Breaking cut: the lifecycle CLI and SQLite were deleted. The three verbs
remain. Pin v0.14.x if you still need that binary.

Development

cd cli && cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test
bash scripts/verify-doc-links.sh
bash scripts/test-guards.sh

This repository is the source of the binary, the embedded playbooks, and the
skills. Edit playbooks in cli/docs/embedded/playbooks/, then copy to
docs/playbooks/. Machine-wide Claude Code bootstrap is setup/install.sh;
that is not how a consumer app repo receives zharness.

Contributing and security

Read CONTRIBUTING.md before opening a pull request.
Report vulnerabilities privately through SECURITY.md.

License

MIT