vv-harness · a Claude Code plugin
Your agent forgets everything at midnight.
The harness is what it reads when it comes back. It gives a coding agent the three things it structurally lacks: memory across sessions, coordination when several run in parallel, and quality rules it cannot skip — by writing state to plain files and enforcing rules with shell exit codes instead of prose.
The problem
The shift problem
Every AI coding agent has the same Achilles heel, and it is not the context window. Start a complex project, work for an hour, hit a limit or close the session, come back tomorrow. The agent has no idea what happened. You are onboarding a new contractor every morning who has never seen the codebase.
Anthropic's engineering team named it the shift problem: a project staffed by engineers working shifts, each arriving with no memory of the last shift. Two failures follow, and you should be able to spot both.
Overreach
The agent tries to one-shot the whole project, runs out of context mid-implementation, and leaves a half-built mess.
Premature victory
The more insidious one. The agent looks around, sees working code, and declares the project done at 30 % complete.
What a session boundary does to state
Without a harness
knowledge lives in the conversation
✗ session 2 starts from zero
With the harness
knowledge is written to .harness/
✓ handoff written → session 2 resumes
The fix is not a bigger model. It is infrastructure: externalize state into files the next session reads, and enforce the rules that matter with code instead of prose.
The design choice
Why files, and not a memory system
This looks primitive next to a vector store. It is deliberate, and the third reason is the one people miss.
Simplicity
Files need no infrastructure. The agent writes, the agent reads, done.
Transparency
When an agent goes off the rails you open the file and see what it thinks it is doing. You cannot debug a vector database mid-hallucination.
Structure
features.json is JSON because a model is less likely to
inappropriately change or overwrite JSON than Markdown. The format itself
enforces discipline.
The filesystem is connective tissue not because files are the optimal data structure for agent memory — they are not — but because they are the optimal trade-off between simplicity, transparency, and effectiveness.
Mental model
The install has two halves, and they live in different places
This is the single most common early confusion. Installing the plugin does
nothing to any repository. The plugin is the global half; the per-project
half only appears when you run /harness-init inside a repo.
Global — installed once, travels with you
Per-project — written by /harness-init
.harness/ is the project's memory. .claude/hooks/ is the
project's immune system. The plugin ships neither — it ships the machinery that
writes them.
The thesis
Mechanical over instructional
There are reliability tiers for agent coordination, and it matters which tier a rule lives in. A rule that only exists as prose gets followed most of the time. A rule that exists as an exit code gets followed every time.
The harness's own TDD rule says this about itself: the same discipline lived as always-on prose for a full measurement window, and buggy code still led the friction table at 33 %. What measurably worked was wiring TDD to a gate.
Four more principles have held steady across every version: predictable input (every sub-agent verifies the same initialization state, so it does not wander off fixing things outside its prompt), prescribed output format (every sub-agent has defined exit expectations, so work returns at the same level of quality), progressive discovery (context storage is hierarchical to protect the context window — drop MCP tools you do not need), and filesystem as connective tissue.