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 .monows/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/tinhtute/monoharness/blob/master/README.md and, once they exist, this repo's AGENTS.md and .monows/WORKFLOW.md. If zharness is not on PATH or outdated, install/upgrade it with scripts/install-zharness.sh. If this repo has no .monows/WORKFLOW.md, run zharness install. Before upgrading, independently install the six workflow skills (brainstorm, to-plan, work, check, handoff, watzup) using the skills instructions below. If a required skill or reference is missing, report the dependency and stop workflow execution. If the repo is initialized or zharness install reports drifted files, run zharness update to refresh WORKFLOW and conservatively retire recorded legacy procedures (edited/unknown files and recovery data are retained; PROJECT.md is never overwritten, and an edited AGENTS.md block makes update refuse with a diff). Plans live only in .monows/plans/ — multi-session or complex work uses exactly one file at .monows/plans/active/{slug}.md, moved to .monows/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 poteto 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 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 skills/stages/check/references/check-durable.md instead of implying coverage.
• Portable across agents. The spine skills are thin triggers; the operating logic sits in independently installed skill references. Skill-capable hosts resolve each stage through their skill metadata; the CLI installs the repository router, not the procedures.
• 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

Start a task with /mono <task>. The router matches one playbook, copies its steps into a todo list, and calls the skill each step names.

Playbook	Steps
feature	brainstorm (grill or wayfinder first when needed) → to-plan (high-risk only) → work → check → git (on request) → handoff
bug-fix	hunt → failing test → work (bounded) → check → git (on request)
refactoring	think → pin behavior → work (subtract, then reshape) → check
perf	baseline → hunt → mantras, cheapest first → work → check before/after
hillclimb	metric + stop predicate → frozen harness → loop: one change, measure, keep or revert → check
prototype	throwaway variants → observe in the real app → decide
fanout	separate → spawn sub-agents → aggregate → check (one in-session wave)
orchestrate	standing program: coordinator decides, PR owners and workers build, verify each unit; multi-day
autopilot	brainstorm → PR owner per PR → full check → fix rounds → /loop → stack or land via ship § Land
investigation	think or hunt; read-only, changes nothing
research	read (search, fetch) → learn → mono-write; notes only
ambition	ambition (depth, altitude or range) → lint the rewrite → route on request
babysit	/loop over review threads and CI until the PR is ready
ship	watzup → security-review → check → land → changelog → tag → verify → rollback
session-pickup	watzup → reconcile → route to the next playbook
pause	safe boundary → handoff → chore(wip) commit; resume with session-pickup
retro	watzup → retro → save approved lessons

A typo does not need a plan. A migration spanning sessions does: it gets one .monows/plans/active/<plan>.md, moved to .monows/plans/completed/ after validation. When a request leaves a material product choice open, the agent stops before mutation and asks.

Diagram sources are tldraw files in site/assets/diagrams/. To edit or regenerate them, install the tldraw-diagram skill from monoclaudian.

What gets installed

The managed set is:

• a compact AGENTS.md entrypoint (marked ZHARNESS block only);
• .monows/WORKFLOW.md, the stage router;
• a .monows/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

.monows/WORKFLOW.md is a pure upstream mirror: update always overwrites it with the latest bytes. Legacy procedures are retired only using recorded hashes and ownership. Matching installer-created copies are removed; matching copies with proven pre-install originals are restored. Edited or uncertain files and their recovery data are retained with notices. See the migration guide. .monows/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.

Workflow skills and optional extensions

Install brainstorm, to-plan, work, check, handoff and watzup independently before upgrading to skill-owned procedures. Verify that the host exposes all six skills and can read their installed references. A missing dependency is unsupported for workflow execution; retained legacy files are not a fallback. Other skills are optional extensions.

poteto sits at skills/poteto; the other skills live in three groups: stages (the six workflow skills plus grill, wayfinder and retro), reason (think, hunt, arena, learn, ambition) and tools (git, librarian, mono-write, read). retro is gated: it runs only from a poteto playbook step or when the user names it. mono-write covers only what the playbooks need: polishing a research draft and writing CHANGELOG entries and release notes.

General-purpose skills outside the workflow (the full write, diagram, prompt, skill-authoring, CLI-design and monorepo skills) live in monoclaudian; install it for the full set.

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. Installing over SSH needs local SSH keys:

npx skills add git@github.com:tinhtute/monoharness.git --list   # list without installing
npx skills add git@github.com:tinhtute/monoharness.git -a claude-code -g -y

No skill runs during installation.

The harness agents (scout, worker, engineer, verifier, architect) install from a clone of this repository; the installer retires the pre-rename mono-* and lead agent files as <name>.md.retired.<timestamp>:

bash scripts/install-agents.sh

The Claude Code setup (global CLAUDE.md, rules, settings, statusline) lives in the separate monoclaudian repository:

git clone https://github.com/tinhtute/monoclaudian ~/monoclaudian && bash ~/monoclaudian/install.sh

To reinstall rules and skills from scratch, from a monoclaudian clone:

cp CLAUDE.md ~/.claude/CLAUDE.md
cp rules/*.md ~/.claude/rules/
npx skills add git@github.com:tinhtute/monoharness.git -a claude-code -g -y
npx skills add git@github.com:tinhtute/monoclaudian.git -a claude-code -g -y

cp never removes a rule that was dropped from rules/; bash install.sh in that repository retires the known ones. npx skills add never removes a skill that was dropped from either repository. Trash each dropped skill by name from ~/.claude/skills/ and ~/.agents/skills/ before reinstalling.

Versions

Current release: v0.33.0; see CHANGELOG.md. Since v0.15 the binary has three verbs and no lifecycle CLI or SQLite; pin v0.14.x for the old binary. Existing harness.db files are consumer-owned; nothing here deletes them.

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

Development

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

This repository is the source of the binary and skills. Edit workflow procedures in skills/stages/<stage>/references/. Edit the managed router in cli/docs/embedded/WORKFLOW.md, then copy it to .monows/WORKFLOW.md. Machine-wide Claude Code bootstrap is install.sh in monoclaudian; 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