Stop 7 of 7

Reference

Built for the second visit, not the first.

Commands

Command	When	What it does
`/harness-init`	Once per project	Scaffolds `.harness/`, installs the hooks, proposes initial features
`/harness-continue`	Start of every session	Mode choice, smoke test, workflow planning — on top of the auto-injected orientation
`/harness-issue-prep`	Before implementing	Verifies a spec until buildable, normalizes it, records proof of verification
`/harness-issue-debug`	After something broke	Live repair session on a failed feature or a parked issue
`/harness-doctor`	On upgrade or odd failure	Report-first health check; `--fix` applies the mechanical upgrade steps
`/harness-improve`	After a bad run	Observation-first improvement loop: one intervention, verified at the claim boundary
`/harness-dashboard`	Watching a run	Opens the live session view (the session must have opted in beforehand)
`/plugin update vv-harness`	Periodically	Updates the plugin — remember to run `/harness-doctor` per project after

Test targets

.harness/init.sh smoke_test                  # fast compile/syntax check, <15s
.harness/init.sh focused_test <test_file>    # exactly one test file
.harness/init.sh full_test                   # complete suite with coverage
.harness/init.sh                             # ⚠ defaults to full_test

focused_test exits 3 and reports a skip when the file doesn't exist or the stack has no per-file runner — a skip, deliberately, rather than a fake green.

The feature object

Canonical definition: schemas/feature.schema.json, enforced by scripts/validate-features.py and wired into the test suite. Ten fields are required.

Field	Required	Meaning
`id`	yes	e.g. `F001`. Assigned by the lead, never reused
`description`	yes	What the feature is. Editing it after a spec is attached invalidates `spec.hash`
`priority`	yes	Lower numbers claim first
`status`	yes	`pending` · `in-progress` · `blocked` · `passing` · `failed`
`scope`	yes	Directories and files this feature owns; pasted into agent prompts and enforced on Edit/Write
`depends_on`	yes	Feature ids that must reach `passing` first
`assigned_to`	yes	Agent name, `"single-session"`, or null
`test_file`	yes	The test proving this feature. Must be non-null once status is `passing`
`coverage`	yes	Percentage on touched code, or a descriptive string where no tooling exists
`notes`	yes	Free-form: issue id, decisions, anything the other fields don't capture
`correction_cycles`	—	How many correction rounds this took. ≥3 in a scope is a signal to upgrade the next implementer
`scope_expansions`	—	Files added to scope after assignment. ≥3 means assign a broader initial scope next time
`approaches_tried`	—	What was attempted before the passing approach
`failure_reason`	—	Why it reached `failed`
`discovered_via`	—	Id of the feature whose implementation revealed this one
`spec`	—	Spec-verification record. Absent or null means unverified — excluded from parallel batches
`risk` / `require_plan_approval`	—	Elevation flags; escalate the review stage, not the implementer
`coverage_target`	—	Overrides the default coverage gate
`qa_binding` / `proof`	—	Declared at prep time; claim-matched evidence recorded at completion

Completion checklist

Before declaring any task complete:

All tests pass, including the new ones written via TDD
No uncommitted changes remain
Sub-agent and workflow-agent work validated against lead context
Documentation updated — existing docs only
context_summary.md updated with decisions, patterns, or gotchas
The user told what changed

And additionally, in a harness project:

features.json audited against the actual work — every touched feature has updated status, test_file, coverage; unmapped work gets a new entry with discovered_via
Non-obvious root causes and gotchas recorded in context_summary.md
Retrospective written under ## Meta-Session [DATE] — mandatory even for single-session work
.harness/mld/YYYY-MM-DD-<session-id>.md written — lead only, and not a substitute for the retrospective
claude-progress.txt has the session handoff
Task list is current — no stale in-progress or pending tasks

Ten things newcomers get wrong

Belief	Correction
Installing the plugin sets up my repo	It does nothing to a repo until `/harness-init` runs
`./.harness/init.sh` runs the quick check	Its default is `full_test`. Pass `smoke_test` explicitly
The retrospective and MLD are the same	The retrospective is read by future sessions; MLD is read by nothing, by guarantee
Elevated risk means a stronger implementer	It escalates the review. Executors stay on the execution tier
Fewer than 5 files ⇒ single-session	Two verified independent features beat single-session regardless of file count
Worktree isolation is always safer	Not when agents share an interface — they need to see each other's changes
No Workflow tool means no parallel work	Fall back to worktree-isolated subagents with the same agent types
The hooks make cheating impossible	Edit/Write enforcement is exact; Bash enforcement is pattern-based and evadable
A green task gate means the suite passes	It means smoke plus that one feature's test file. The suite runs at commit and session end
Coverage is measured for me	It is self-reported and compared against a target; it skips where no tooling exists

Glossary

Lead

The orchestrating session. Owns features.json, context_summary.md, and claude-progress.txt; in workflow mode it never edits feature code.

Scope

The directories and files a feature owns. Enforced mechanically on Edit/Write, best-effort on Bash.

Orientation

The block the SessionStart hook injects before you type: feature status, next claimable, last handoff, Active Context, warnings.

Spec gate

Read-only agents proving a spec is testable and unambiguous before implementation. PASS / ASK / BLOCK.

Readiness stamp

Signed proof of spec verification posted to an issue, validated by hash and HMAC by an external consumer.

MLD

Mistakes / Learnings / Desires. A raw per-session log, written by the lead, read back into context by nothing.

Worker epoch

A period during which the model and coding agent are held constant. Material changes trigger a requalification pass.

SESSION_INCOMPLETE

Discipline gaps recorded at session end and surfaced at the next session start. Self-healing, not preventive.

What it costs to have loaded

Always-on overhead is CLAUDE.md at roughly 4.2K tokens. The rule files are not auto-loaded — they cost tokens only when the model reads them, following pointers in the orientation block: parallel-work.md about 4K, code-quality.md about 0.3K. That is down from roughly 14.7K always-on in v3.2.1. In a project without .harness/, the orientation hook stays silent and neither rule file is pointed to or read.

Read the source

Everything on this site came out of the plugin repository. When this guide and the repository disagree, the repository is right.

oeftimie/vv-claude-harness — the plugin
INSTALL.md — full prerequisites, upgrades, optional telemetry and spec-gate signing
docs/history.md — where the design came from, and how it changed across six major versions
analysis/ — the working notes this site was built from, with citations
Effective harnesses for long-running agents — the write-up that framed the shift problem