A repo your agent can read. A harness it cannot escape.
Two skills and a viewer. One turns whatever you have into a single contract. One
reads the repo and builds the .claude/ harness it justifies: the seats its purpose
needs, rules on paths that exist, hooks that refuse rather than advise. The viewer reads it all
back off disk and scores it.
For code, research, strategy or docs repos. The floor is shell scripts and exit codes, so swapping the model does not move it.
- Guardrail eval
- 314/314 per hook flavour, strict hooks on
- Licence
- AGPL-3.0 free for any use
- Latest
- v1.23.0 binaries attached
- Port adapter
- 34/34 Cursor and Codex
The idea, in one clip
-
Agent Harness Bootstrap in brief ~167s
The questions teams ask once agents do real work, and the mechanism that answers each one. Narrated and captioned.
Does any of this sound familiar?
Each one is answered by a file in the harness, not by advice in a prompt.
-
I asked for one feature. It touched 14 files across 3 modules and force-pushed to
main.What answers itScoped seats, path-based rules, and a hook that exits 2 and refuses the push before it lands.
-
The session compacted and it forgot the plan it was three steps into.
What answers itTask state lives on disk with a short checkpoint. A fresh session reads the checkpoint and carries on.
-
It opened
.envwhile just fixing a bug.What answers itThose paths are denied before the read happens. It cannot leak what it was never allowed to open.
-
My repo is research notes. The kit gave me a test runner and a database engineer.
What answers itThe first question is the repo's purpose. Research, strategy and docs repos get researchers, strategists, writers and a checker, not dev seats.
-
It fixed a typo in the README, then ran the whole suite and three reviewers.
What answers itA script reads the diff and plans the verification. A docs change gets no reviewer seat; the secret scan always runs.
-
The 40th generated doc quietly contradicts the spec.
What answers itEvery requirement gets a stable ID, and the traceability graph names the document that drifted.
-
It wrote tests that pass no matter what the code does.
What answers itA test's expected value comes from the acceptance criterion, not from running the code.
-
I cannot tell what my
.claude/actually enforces any more.What answers itharness-view reads it off disk, scores it, and names every unwired part.
What answers it
-
spec-builder
Turns an idea, a transcript or a pile of legacy docs into one contract with stable requirement IDs. It never invents a requirement: anything unstated becomes a flagged open issue.
-
harness-bootstrap
Asks what the repo is for, reads what is in it, then builds the
.claude/harness that fits: seats sized to the purpose, rules scoped to real paths, hooks that block. -
harness-view
Reads the result, renders it, scores it, and lets you switch any part off. Because no model is in the loop, a browser and a CI run cannot disagree.
Four handoffs. Step through the net: each stage lights the route it energizes and names what it writes to disk.
Delivery net N1 gold is a live signal
Stage IN raw input
Whatever you have, in the form you have it.
- A one-line idea, a meeting transcript, legacy documents, an existing or empty repository
- PDF and Office sources go through a router that knows when a file cannot be read
writes nothing yet - this is the material
Stage S1 /spec-builder
One contract that you and the agent both read from.
- Stable requirement IDs, so every later change traces back to what asked for it
- Written to ISO/IEC/IEEE 29148, ISO 25010, BABOK v3, C4 and arc42
writes docs/specs/ - FR-014, NFR-003, BR-002
Stage S2 /harness-bootstrap
Purpose first, then the codebase, then the harness around the contract.
- Seats chosen from 18 agents by purpose and evidence, each with complete frontmatter: model, effort, tools, disallowed tools, turns, memory, isolation, preloaded skills, its own hooks
- 17 rules, 10 of them loaded only on the paths they govern
- 27 hooks and 23 commands, the stricter hooks opt-in
writes .claude/ - agents, rules, hooks, commands, scripts, settings
Stage S3 the delivery loop
Plan, build, verify, merge - inside what the harness allows.
- Process is sized to the change: the main session does the work, and the tier sets how much checking it gets
- Verification is planned from the diff, not repeated out of habit
- A hook that exits 2 stops the tool call before it happens
writes code or documents, and a task board you can resume from
Stage S4 harness-view
Reads the harness off disk and renders it, with no model in the loop.
- Flow and graph views of every wire; every node is a file you can open
- A deterministic score with each finding named
writes a score, and a named finding for each problem
Process sized to the change
Before anything is dispatched, the change is put in one of four tiers, and the tier decides how much checking it gets. The main session does the work at every tier; the orchestrator is opt-in.
Routing tier N4 the tier is decided before dispatch
Tier Inline
A question, a lookup, or a small edit you can see whole in one or two files.
- The main session does it, with no subagent and no task file
- One check of the thing that changed
result done in the session, and the branch still lands through a reviewed MR
Tier Direct
One module, reversible, touching no contract, schema, auth, payment or infrastructure.
- The main session does it, with no subagent
- It proves each acceptance criterion itself, and says how
result no dispatch, no task file, one reviewed MR
Tier Standard
One domain, several files, or a functional requirement behind it.
- Still the main session, in one domain
- A task file when the work must survive a compacted session
- Tests over what changed, not the whole suite
result a task on the board, and a reviewed MR
Tier Guarded
It touches schema, auth, money, a public contract, a migration, a deploy or personal data.
- The main session does the work, then the independent read-only reviewer reads it - required, never skipped
- For a new FR,
spec-guardianlocks the scope before anything is built /implement-fr FR-NNis that flow, end to end- The orchestrator is opt-in: only when you ask, for a mission across several domains or repositories
result tests plus an independent review, and none of it is optional
-
Verification is planned from the diff
.claude/scripts/verify-plan.pyreads the paths a change touches and says which tests and reviews it needs, and why each skipped gate was skipped. The secret scan always runs. Security review runs for risky paths only. End-to-end runs only for a named flow whose paths changed. A docs-only change gets no reviewer seat. A review or test that already passed on the same content is refused by the spawn hook; only a human can ask for it again. -
Spawns are capped
Only the orchestrator delegates, and how deep and how wide it may fan out is set in
settings.jsonthroughCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHandCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, not left to a prompt. -
Task state is one command
.claude/scripts/task.pymoves the file, its folder and its board row together, then reads the row back; a hook refuses hand edits to the board. Each task keeps a short checkpoint - next step, last green commit, open questions - so resuming reads three lines, not the whole log. Old log rows fold into an archive.
The roster is sized to the purpose
Code, research, strategy, docs, or a mix. The purpose sets the base; the contract and the modules that exist decide the rest. Pick a repo and watch it resolve.
Tailor N2 evidence in, roster out
- orchestrator
- checker
- writer
- researcher
- strategist
- spec-guardian
- ba-analyst
- code-reviewer
- security-reviewer
- debugger
- devops
- qa-test
- data-modeler
- db-engineer
- db-seeder
- history-tracker
- merge-manager
- reviewer
3 of the 18 seats installed 15 left empty
because a docs purpose fields a writer and a read-only checker - no code, so no dev, test or code-review seat
4 of the 18 seats installed 14 left empty
because strategy gets the planning pair and a checker that red-teams the recommendation
7 of the 18 seats installed 11 left empty
because nothing in the contract or the tree justifies a database or a test seat, plus one dev agent per real module
9 of the 18 seats installed 9 left empty
because a database pulls in the data modeler, and choosing tests fields qa-test
15 of the 18 seats installed 3 left empty
because long-running work earns the planning pair and a history tracker, and parallel PRs earn a merge manager
-
A kit installs everything
Every seat before it has read a line of your repo. You pay context for all of them, and the ones nobody owns turn into generic advice.
-
A run installs 3 to 17 of the 18 seats
Rules are scoped to paths that exist, so 75% of rule content stays out of the default session.
derived by
scripts/check_numbers.pyandbenchmark/benchmark.py --json
Watch a request get stopped
Five layers sit between an agent and your repository. Send a request down the route and see which layer refuses it.
Control route N3 coral is a refusal
Stopped at layer 1 deny list
git push --force origin main
result permission denied - the call never reaches the shell
Stopped at layer 2 blocking hook, exit 2
cat .env
result exit 2 - the hook refuses, and the reason goes back to the model
Stopped at layer 3 spawn boundary
A sub-agent tries to spawn another sub-agent.
result refused - only the orchestrator delegates, within the caps
Through all five held for review
edit src/payments/charge.ts
result the payments rule loads because the path exists, and the gate plans a security review
Through all five allowed
npm test
result the call runs - the floor stays out of the way of ordinary work
-
1 - deny list
Declared in
settings.json. The client refuses the call before any agent reasoning is involved. -
2 - hooks
A hook that exits 2 stops the call and returns its reason, so the model learns what it may not do. Opt-in sets cover more ground: irreversible shell commands, unknown network hosts, large files in history, unreviewed dependency changes, edits to a migration already on the default branch, and a "done" with no evidence behind it.
-
3 - spawn boundary
Who may spawn whom is fixed by the topology and capped by settings, not by a prompt.
-
4 - path-scoped rules
A rule loads only on the paths it governs, so it never becomes background noise.
-
5 - review gates
Review is a step in the flow, sized to the diff, held by seats that cannot edit what they review.
No model is consulted: the guardrails are shell scripts and exit codes, so the result cannot depend on the model. What a cheaper model changes is the quality of the work and the depth of the review - the ceiling, which this eval does not measure.
314/314 per hook flavour, on a harness scaffolded with the strict, long-session and database
hooks on - re-run it with py -3.13 eval/guardrail_eval.py
harness-view reads it back
A small Rust binary that reads the harness off disk and shows how it is actually wired. It calls no model and no network, and makes no judgment calls.
Viewer route N5 read off disk, written back the same way
Nothing here is a model's opinion. scan writes a byte-stable graph -
sorted, no timestamps - and the three commands below it are three readings of that one file.
The Assess tab and harness-view assess in CI run the same engine.
Every change the page makes goes back through one narrow door: the server binds to
127.0.0.1, and every mutating request must be same-origin.
-
Not only code repos
A research or writing harness with no tests and no code graph scans and scores on the same terms, and an orchestrator-kit install - its board, guard hooks and spawn allowlist - is read as well.
-
Every field, every event
Every documented subagent frontmatter field, hooks on any event from
settings.jsonor a seat's ownhooks:, andskills:preloads andAgent(a, b)grants drawn as edges. -
Board drift, named
A task whose folder, status and board row disagree is marked
DRIFTin the graph and counted against board health.
The commands
harness-view # serve the current folder, open a browser
harness-view scan [path] # write .claude/state/harness-graph.json
harness-view serve [path] [--port 7420] # the local UI
harness-view watch [path] # rebuild on .claude/, docs/ or .agent-base/ changes
harness-view assess [path] [--json] # score it; exit 1 on a high findingDetail, including the safety model and every endpoint: tools/harness-view/README.md.
What the score is not: it does not judge whether a rule says anything useful, or whether a hook blocks what it claims to. A clean report means every rule in the engine passed, not that the harness is good.
Install it
The plugin route has working updates, so it comes first. The release zip is the offline, pinned alternative.
Claude Code
Plugin route
/plugin marketplace add nguyenhx2/agent-harness-bootstrap
/plugin install harness-bootstrap@agent-harness-bootstrap
/plugin install spec-builder@agent-harness-bootstrapInstall either plugin on its own, or both; neither needs further configuration.
Codex
Plugin route
codex plugin marketplace add nguyenhx2/agent-harness-bootstrapThen open /plugins in the Codex CLI and install either skill, or both.
Cursor, and every Agent Plugins client
Plugin route
git clone https://github.com/nguyenhx2/agent-harness-bootstrap
cp -r agent-harness-bootstrap/plugins/harness-bootstrap ~/.cursor/plugins/local/Reload the window. VS Code, Copilot and Kiro read the same directories; what was verified against which client is in docs/PLUGIN.md.
Or the release zip
Offline, pinned
# both skills, pinned to whatever you downloaded
unzip agent-harness-bootstrap.zip -d ~/.claude/skills/Requires Python 3. Each release attaches SHA256SUMS to verify the archive.
The viewer
Optional
Each release attaches a standalone executable for Windows, macOS and Linux, with the web UI compiled in. On Windows, drop it into a repo and double-click it. Nothing in the harness requires it.
cargo install --path tools/harness-view # or build it yourselfRun it
Both skills interview you first, in the language you write to them in. Nothing is written until you approve a one-screen plan.
The first run
/spec-builder # write the contract first, if you are starting from an idea
/harness-bootstrap # build (or update) the .claude harness for this repoThe first question is what the repo is for. If it already has code, the analysis pre-fills the rest, so you correct findings rather than type from scratch. The one batch never guessed is governance: model sovereignty, residency, licences, gated actions. In a hurry, say so: you get only the questions with no safe default.
Day to day
/new-task "short title" # register a task through task.py
/implement-fr FR-014 # the Guarded flow, end to end
/review-changes # the branch gate, sized by verify-plan.py
/secret-scan # any hit blocks until it is rotated
/task-resume TASK-007 # read the checkpoint, not the whole logMove to a new version
Reconciled, never clobbered
/plugin update harness-bootstrap@agent-harness-bootstrap # the skill
/harness-bootstrap:harness-update # the harness in this repoThe update re-reads the code, re-runs the scaffolder against your recorded answers, and reports every file in one of three states:
- ADDED
- New in the newer skill version. Written in.
- KEPT
- Identical on both sides. Left alone.
- CONFLICT
- You edited it. It stays as you had it and joins a queue you resolve one file at a time.
A control you switched off stays off, and authored content such as agent scopes and
coding-standards.md is reached only through that queue.
Change the harness, narrowly
The bootstrap writes a first draft. Each of these shows you the diff, applies
only what you confirm, and records why in docs/context/tool-changelog.md.
-
/harness-tune
Reads what actually happened - the run archive, blocks, retry caps, verify-plan logs - and proposes at most four ranked changes to one dial each: deploy permission, force-push posture, spawn allowlist, caps, review depth. Each is proved after it lands.
-
/harness-toggle
Switch one rule, command, hook or seat off without deleting it. Protected controls need a typed confirmation; enabling is never gated.
-
/agent-permissions
Give one seat one more tool, or one fewer. Reviewers never gain write access; narrowing skips the check.
-
/new-skill
Decide whether a recurring workflow should be a skill at all. If it should: scaffold it from the template, write six kinds of trigger case, lint it with
skill-check.py. -
/skill-wire
Map an installed skill to the seat that needs it, through the seat's
skills:preload, after re-reading every file of the skill. -
/board-audit
Read-only sweep for tasks nobody drives, statuses that disagree, and branches no task references.
-
/code-graph
The committed module-boundary map: which module may import which, with an owner per module. A new cross-module import is named on the edit that adds it.
-
/docs-graph
Every requirement ID, where it is defined and who references it; the orphans it prints are work nobody scheduled or references to nothing.
None of them will give a reviewer write access, let a seat other than the orchestrator spawn, or remove the review gate.