Skip to content
harness-mini
❯minimal · CLI-agnostic · v0.10.0

A minimal, CLI-agnostic agent harness.

Convention + skills + sub-agents + distilled best-practice docs — with only thin shell glue as code. Drop it into any project; any agent that can run a shell can use it.

The harness is the environment, not a program.

Get startedRead the docsGitHub
install
$ git clone https://github.com/harness-mini/harness-mini.git$ bash harness-mini/init.sh /path/to/your/project

What's new in v0.10.0: Session ops for cold resume: `harness.sh status` now ends with a single `ready: <ready|warning|blocked> — <next>` verdict (plan-scoped, so foreign checkpoints no longer lie). Checkpoint gains an additive `## Task state` block; stage-viewer documents a plan-stage write ban for intake/prd/issues. Assumptions A6/A7 registered. Changelog →

skills
16

skills

sub-agents
5

sub-agents

runtime deps
0

runtime deps

the one rule
40%

the one rule

Convention, not code

The harness is a structure of Markdown + thin shell glue. There is no program to run — the repository is the system of record, and any shell-capable agent can read it.

Context firewalls

Heavy reads and broad searches are delegated to disposable sub-agents that burn their own window and return a small distillate. The caller never leaves the smart zone.

CLI-agnostic

Skills and agents install to .claude/ for Claude Code; a neutral manifest points other CLIs — codex, cursor — at the same files. One harness, any agent.

the one rule

The 40% line

Context occupancy below 40% is the smart zone — comfortable headroom to reason and hold the whole task in view. 40% is a conservative checkpoint line, not a hard cliff: our own CIB benchmark found that what degrades quality is interference — competing content in the window — not how full it is. So the mechanisms below earn their keep by keeping that content out.

smart zone · < 40%checkpoint · ≥ 40%
40%

configurable via HARNESS_CTX_THRESHOLD · estimate with bin/ctx.sh <used> [window]

01

Delegate heavy work

Any operation that would read more than ~2k tokens goes to the explorer sub-agent — the load-bearing mechanism that doesn't depend on an agent measuring itself.

02

Checkpoint at 40%

Crossing the line means checkpoint now, while still sharp: write a handoff, update the plan, reset. Waiting until 90% is fatal — the handoff itself would be degraded.

03

Progressive disclosure

AGENTS.md is a ~100-line map of pointers, never an encyclopedia. Start near-empty; pull a file only when you need it. Most headroom for the least effort.

Read the smart/dumb contract
the state machine

A lifecycle you live inside

Every requirement is a file with a stage: field. Work flows through a fixed FSM — and only the main agent may advance it.

  1. intake
  2. prd
  3. issues
  4. implement
  5. evaluate
  6. checkpoint
  7. done

implement ⇄ evaluate loops until acceptance criteria pass. garden runs orthogonally, periodically — across the whole lifecycle.

Anti-self-praise firewall

No worker promotes its own work to done. The evaluator grades from a separate window, and only the main agent advances the stage.

Garden runs orthogonally

Technical debt is paid in small, continuous installments. The gardener periodically demotes stale context and opens small, green, one-move fixes.

how to do a task

16 skills, by stage

Skills install to .claude/skills/ and encode how to do a task — invoked at the right point in the lifecycle.

Orchestrate

5
/stage-viewer

The single authority that moves a plan through the FSM. Main-agent only — no sub-agent self-promotes. Documents a plan-stage write ban (convention only) for intake/prd/issues — no product-code edits until the walking skeleton is authorized.

/ralph-loop

Drive a long-running work → check → repeat loop until criteria pass or a human-judgment flag is raised.

/checkpoint

Write a committed handoff so a fresh session resumes with zero loss — while the agent is still sharp. Includes an additive ## Task state block (acceptance / footprint / last green / open issues) so cold resume is plan-scoped and honest.

/five-step

Apply Musk's algorithm — question, delete, simplify, accelerate, automate — in that order, before building.

/grill-me

Interview the user relentlessly about a plan until every branch of the decision tree is resolved.

Intake

1
/founder-check

Greenfield-only gate: who is the user, the smallest valuable slice, the riskiest assumption, the BML loop.

Plan

2
/to-prd

Turn a raw idea into an executable PRD — a versioned, agent-readable, testable source of truth.

/to-issues

Decompose a PRD into atomic, independently verifiable issues — one vertical slice each.

Implement

5
/tdd

Red → green → refactor. Never write implementation before a failing test; never refactor on red.

/slice-coding

Vertical (one feature end-to-end first) + horizontal (forward-only layering). Read before writing code.

/parallel-slices

The implement stage's write fan-out: once the vertical skeleton passes evaluate, build the independent issues in parallel — one generator each, gated on disjoint file footprints — then a single integration evaluate.

/clean-code

The forward quality constraint: intention-revealing names, small functions, no duplication, why-not-what comments.

/refactor

The recovery constraint: smell → named refactoring, always under green tests, one move at a time.

Evaluate

1
/evaluate

Grade work against acceptance criteria from a separate context, tiered by risk: L0 self-check · L1 lightweight reviewer (default) · L2 full Opus. The firewall is the separate context, not the model — and it writes a committed verdict to .trace/evals/, so "done" is earned, not self-declared.

Maintain

2
/release

Cut a versioned release — bump VERSION, roll the CHANGELOG, tag, and publish a GitHub release. Wraps bin/harness.sh release; owns the semver + changelog judgment the script can't.

/garden

Entropy GC: scan for drift — stale docs, dead context, smells — and open small targeted fixes. Fires on concrete signals — a checkpoint cadence (≥5 since the last sweep) and a committed smell backlog — not a vague "periodically."

who does the work

5 sub-agents

Separate context windows are firewalls. Each agent has a role, a model sized to it, and a strict boundary it never crosses.

planner

sonnetgoal → exec-plan + issues

Expands a goal into a committed PRD and atomic issues. Runs the founder funnel on new projects. Writes no production code.

generator

sonnetbuild one slice via TDD

Implements one issue at a time, test-first, under the layering contract. Hands the slice to the evaluator — never grades its own work.

evaluator

opusgrade vs criteria

Grades work from a separate context window — the firewall. Evaluation scales with risk (L0/L1/L2); the L2 Opus pass is reserved for high-stakes work. Verifies by running tests/app; returns pass/fail with evidence.

explorer

haikudisposable read/search → distillate

Read-only fan-out. Burns its own context on heavy searches, returns a short distillate, and dies. The context firewall.

gardener

haikuentropy GC / doc-gardening

Periodically scans for drift and opens small, green, one-move fixes. Keeps the repo coherent and the smart zone smart.

install

Installs like a skill

Tell your agent “install harness-mini here”, or clone and run the installer. init.sh is additive (never overwrites your files) and idempotent (safe to re-run).

New / empty project

Generative bootstrap — seeds an intake plan and runs the founder funnel: founder-check → five-step → to-prd → to-issues.

Existing project

Recon graft — installs additively and seeds a recon plan; the explorer maps your codebase into ARCHITECTURE.md.

bash
$ git clone https://github.com/harness-mini/harness-mini.git$ bash harness-mini/init.sh /path/to/your/project

Skills install to .claude/skills/ and agents to .claude/agents/ (auto-loaded by Claude Code); harness/manifest.md is a neutral pointer list for other CLIs.

View on GitHubRead the docs