Stop 2 of 7

Quickstart

Two commands install the plugin. One initializes a project. One starts every session after that. Everything else on this page is explaining what those four commands did.

Before you start

  • The Claude Code CLI, working.
  • git initialized in the project — the harness records and checks git identity, and there is nothing to check without a repo.
  • python3 — used by the hooks and the features validator.
  • jq (brew install jq on macOS) — used by the per-project build hooks that /harness-init writes.

1 · Install the plugin

From inside any Claude Code session:

> /plugin marketplace add oeftimie/vv-claude-harness
marketplace added
> /plugin install vv-harness
vv-harness installed — skills, agents and hooks discovered
Claude Code auto-discovers the plugin's skills, agents, and hooks. Updates are atomic — each version gets its own cache directory — and they land only when the plugin's version is bumped, because that field is the update cache key.
Nothing has happened to your code yet

Installing the plugin changes no repository. It makes the commands available. The per-project half appears in the next step.

2 · Initialize a project

Run this in any project that will span more than one session. Below five files and one sitting, the ceremony costs more than it returns.

$ cd ~/Projects/MyApp
$ claude
> /harness-init
The initializer is interactive — it will ask what you are building and confirm your git identity.

It then does ten things, in order:

  1. Detects your tech stack
  2. Captures and confirms git identity
  3. Creates the .harness/ scaffolding — features.json, context_summary.md, init.sh, progress log
  4. Installs async PostToolUse build hooks in .claude/settings.json
  5. Installs the PreToolUse hooks (enforce-scope.sh, verify-git-identity.sh)
  6. Installs the quality gate hook (TaskCompleted)
  7. Wires the status line and permissions allowlist; gitignores .harness/SESSION_INCOMPLETE
  8. Verifies the hooks actually execute
  9. Proposes initial features with scope and dependencies
  10. Commits

The propose-features step is where a spec gate can run: /harness-init can spawn the read-only spec-verification agent to prove each proposed feature is testable and unambiguous before anything gets built.

3 · Read what it wrote

Open these before you do anything else. They are the whole contract between this session and the next one.

your-repo/
├── .claude/
│ ├── settings.json # hook wiring, statusLine, permissions
│ └── hooks/
│ ├── verify-task-quality.sh # TaskCompleted: tests must pass
│ ├── enforce-scope.sh # PreToolUse: stay in your scope
│ ├── verify-git-identity.sh # PreToolUse: right identity to push
│ ├── commit-gate.sh # PreToolUse: commit content gate
│ ├── harness_state.py # shared features.json read/write
│ └── statusline.sh # live feature progress
└── .harness/
├── harness.json # config, git identity, plugin_version
├── features.json # what the work is, and where it stands
├── context_summary.md # what we learned that isn't in the code
├── claude-progress.txt # what the last shift was doing
├── mld/ # optional per-session raw log
└── init.sh # smoke_test | focused_test | full_test
Six hooks and six state files. Nothing else, and no daemon.

Verify the hooks really run

A hook that exists but does not execute is worse than no hook, because you will trust it. Check one directly: 

# exit 0 when tests pass, exit 2 when they fail
echo '{}' | bash .claude/hooks/verify-task-quality.sh; echo "exit: $?"

4 · Every session after that

$ cd ~/Projects/MyApp
$ claude
> /harness-continue
## Harness orientation (auto-injected)
Features: 7/12 passing · Next claimable: F008
Last handoff: F007 complete, F008 blocked on schema decision …
The orientation block is injected by the plugin's SessionStart hook before you type anything. /harness-continue adds what the hook cannot: mode choice, the smoke test, and workflow planning.
Treat orientation as claims, not instructions

The injected block is a summary of files that may have been written by a session that ended badly. If it warns about something, verify it against the file it came from before acting on it.

What happens in a session →

Keeping it current

Two separate things upgrade, and people forget the second one.

# the plugin itself
/plugin update vv-harness

# then each project initialized under an older version
/harness-doctor          # report-first: never writes
/harness-doctor --fix    # applies the mechanical upgrade steps

/harness-doctor is report-first by design: running it never changes anything on disk. It checks python3/git presence, the hook set and its executability, settings.json wiring, .gitignore rules, .harness/ file validity, version drift, and whether a passing feature's recorded test_file actually exists. A clean project prints one word: healthy.

← Why The session loop →