Skip to content

Configuration

Who is this for? Someone with the tool installed, writing or changing harnessimo.config.json. When should I read it? When you want a key you have not used before. To choose which check to turn on, the guide's table maps symptoms to sections.


Every section is optional, and a section that is absent is a check that does not run — harnessimo doctor prints that list, and it is the honest answer to what a repository enforces.

This page is generated from schema/harnessimo.config.schema.json. Editing it by hand is pointless: npm run docs:sync regenerates it and a test fails when the two disagree.

docs

Turns on: proof

Proof markers: every claim in prose names the evidence that makes it true.

Key Type What it does
roots array of string Directories to scan for Markdown. "." means the repository root, non-recursively.
skip array of string Directory names never descended into.
maxDepth integer How deep to descend below each root. Keeps a scan from wandering into a vendored tree.
mustCarryProof array of string Documents that must carry at least one marker in strict mode. Put the ones that make promises here.
commands object Marker prefix to the file that declares those commands, e.g. { "make": "Makefile", "task": "Taskfile.yml", "pnpm run": "package.json" }.
migrations string or null Directory backing migration:<prefix> markers.

tracks

Turns on: tracks

Handoff-driven development: the index of live work tracks and the handoffs it points at.

Key Type What it does
file string The index of live work tracks — one line per track, with a status and a next step.
log string Where a closed track's outcome is distilled.
specsDir string Where a lane's spec, tasks and handoff live, one directory per lane.
taskFile string The file inside a lane holding its task list, whose checked boxes the task gate reads.
gateTasks boolean Require a checked box in a live lane's task list to carry a proof marker.
staleAfterDays integer Days after which a live track line that nobody has refreshed is reported. A lane abandoned mid-flight keeps its status, its next step and the paths it declared, and none of that decays on its own. 0 (the default) turns the rule off.

queue

Turns on: queue

The work queue. State moves only through a passing verification, and CI re-runs every claim.

Key Type What it does
file string The queue itself: every item, its state, and the command that verifies it.
timeoutMinutes number A verification that runs longer than this is a failure with a stated cause, not a hang.
terminalByKind object Where an item lands when its verification passes, per kind.
maxActive integer How many queue items may be active at once (default 1). The queue file's wip_limit still applies when it is higher. Raise it where goals switch mid-item, rather than marking work blocked that is not.

locked

Turns on: locked

The files that define or enforce the acceptance signal, which an agent commit may not touch.

Key Type What it does
paths array of string Path prefixes. Empty means the check is off.
baseline string File naming the commit from which enforcement applies.
agentTrailer string The commit-message trailer that marks agent authorship.

coldStart

Turns on: cold-start

Can a fresh clone install and verify itself using nothing but the repository?

Key Type What it does
requiredFiles array of string Files a fresh clone must contain before anything is run — the ones the first command assumes.
entryDocs array of string Documents checked for paths that only resolve on one machine.
commands array of string The documented commands, run inside the fresh clone.

cleanExit

Turns on: clean-exit

Clean state at session exit (lecture 12): no debris left behind, and progress written down.

Key Type What it does
scan array of string Path prefixes whose changed files are read. Empty means the check is off.
markers array or null Strings that pass a build and mean the work is unfinished. Null uses the defaults.
allow array of string Path fragments exempted — typically the files that name the markers themselves.
progressFile string The file a session must update when it changed code.
codePrefixes array of string What counts as code for the progress rule. Empty means anything that is not Markdown.
progressThreshold number Changed lines below which the progress rule stays quiet, so a one-line fix is not told to write a progress note. Defaults to 50.
requireCleanTree boolean Also fail when the working tree has uncommitted changes.

instructions

Turns on: instructions

The instruction file kept a router rather than a manual (lecture 04).

Key Type What it does
limits object Path to maximum line count.

boundaries

Lines the code may not cross: a pattern that must not appear in a particular part of the tree, and the reason it must not. Both repositories this package came from wrote this rule by hand, differently, because there was no way to declare it.

Key Type What it does
scan array of string Directories to read. Everything under them is checked against the rules whose paths cover it.
rules array of object The boundaries themselves. An empty list is a check that finds nothing.

thresholds

A scored metric has a declared floor, and a run below it is not finished. This check does not run the scoring: the project's own command writes a results file, and this reads it and compares. Floors only — a metric where lower is better is the same rule mirrored, and inventing a direction on zero real cases would be a guess.

Key Type What it does
results string The file the scoring command writes: JSON of { metric: number }.
floors string The file declaring the lowest acceptable score for each metric. Put it in locked.paths: an agent that can lower its own pass mark grades itself.
command string The command that produces the results file. Named in the failure when the file is missing, and never run from here — the project owns its commands.

release

Turns on: release

The version is a claim made on several surfaces: they must agree.

Key Type What it does
manifest string Where the version being shipped is declared. Usually package.json.
changelog string The file describing each released version.
tagPrefix string What a tag for x.y.z looks like: "v" gives v1.2.3.

tokens

The read guard: a re-read of a file that has not changed is refused, and what a session cost is reported. Enforcement while the work happens, not a check on whether it is finished.

Key Type What it does
windowMinutes integer How long a read is remembered. Past this, the same file may be read again — a session that ran longer is not one piece of work. Defaults to 20.
statePath string Where the per-session state is kept. It describes one run, so it belongs outside git.

autonomy

How much of this repository's work is watched while it happens. A floor, not a setting: harnessimo check runs at this level or higher, and --autonomy can only raise it. Each level adds the checks that supervision at the level below could no longer catch.

Key Type What it does
level "watched" | "reviewed" | "unattended" watched — a person is reading each step; the fast checks. reviewed — nobody watched the steps but a person will read the diff; adds re-verification and the locked-surface check. unattended — nobody looked at all; adds clean exit and cold start.

worktree

harnessimo worktree: one git worktree per independent stream of work, beside the main checkout, with its dependencies installed. Not a check — the command that opens, merges and removes parallel streams.

Key Type What it does
prefix string Branch prefix. wt- (the default) puts worktree add search on branch wt-search.
dir string Where worktrees go, relative to the main checkout. .. (the default) puts <repo>-<name> beside it.
install array or null Commands run inside a fresh worktree, so its first commit can pass the pre-commit hook. Null (the default) takes the install step of coldStart.commands, such as npm ci; [] runs nothing.

herd

harnessimo herd: one herdr pane, one worktree and one agent per lane that can run now, started a few at a time to stay under API rate limits. Not a check — the command that plans and starts parallel lanes.

Key Type What it does
maxWorking integer Lane agents working at once (default 3). herd plan and herd up never start more, counting the ones already running.
staggerSeconds number Seconds between two agent starts (default 20), so their first requests do not hit the rate limit together.
agentKind string The herdr agent kind each lane agent is started as, via herdr agent start --kind (default claude).
agentArgs array of string Arguments passed to every lane agent after the role's own flags, e.g. ["--model", "sonnet"]. A --model or --effort here wins over the role's for that flag. Default none.
defaultRole string The role a lane agent plays unless laneRoles names another (default implementer). Its model and effort come from .claude/agents/<role>.md, passed as --model and --effort when the agent starts.
laneRoles object Lane slug to role name, for a lane that is not an implementer's, e.g. { "billing-review": "architect" }.
roles object Role name to { model, effort }, used where the role's file is missing or names neither. The file wins. Sonnet gets high effort when nothing says otherwise.
panesPerTab integer Panes in one herdr tab, the coordinator's included (default 4). herd up fills the current tab to this many, then opens a new tab, named for its first lane, for the rest.
backoffSeconds array of number Waits before each retry after a rate-limit error (429), in seconds (default [60, 120, 240]). Written into every kickoff prompt.