Guardrails that block, not advise.

Does any of this sound familiar?

If you have put an AI agent on a real repository, you have probably hit at least three of these. Each one is answered by something in this repo, not by advice.

• I asked for one feature. It touched 14 files across 3 modules and force-pushed to main.

  What answers itScoped agents, 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 itThe task board and its session log live on disk, so a fresh session resumes where the last one stopped.

• It opened .env while just fixing a bug.

  What answers itThose paths are denied before the read happens. It cannot leak what it was never allowed to open.

• 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.

• The kit installed forty agents and a hundred skills my project never needed.

  What answers itThe roster is derived from your contract and your real modules: 7 to 15 of the 16 seats, never all of them by default.

• It wrote tests that pass no matter what the code does.

  What answers itA test's expected value must come from the acceptance criterion, not from running the code.

• It read my scanned PDF and wrote a spec from the three words it got.

  What answers itEvery source routes to a reader that can actually read it. A page holding under 80 characters is treated as a scan and goes to a vision pass; a file nothing can read becomes a named open issue, never a guess.

• 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

Two Claude Code skills and a viewer. You can use any one of them alone.

• spec-builder

  Turns an idea, a transcript, a pile of legacy docs, or a bare repo into one contract written to international standards, with stable requirement IDs. It never invents a requirement: anything unstated becomes a flagged open issue.

• harness-bootstrap

  Reads your code first, then builds the .claude/ harness that fits it: agents with a named scope, rules scoped to paths that exist, and hooks that block rather than advise.

• harness-view

  Reads the result and renders it. Scores it. Lets you switch any part off. No model in the loop, so a browser and a CI run cannot disagree.

The floor does not depend on the model. The guardrails are shell scripts and exit codes, so swapping every agent from Opus to Haiku leaves the safety result byte-identical. python eval/guardrail_eval.py proves it: 112/112 per hook flavour, 224/224 across both.

See the whole thing in one clip

Seven explainer clips, captioned, playing here in the page. No download, and no sound required.

• The complete solution ~63s

  The whole product in one clip: the four pain points, then spec-builder writing the contract, harness-bootstrap building the harness, the delivery loop running inside it, and the payoff. Each pain visibly flips from red to green as its fix lands. Closes with harness-view answering the question it exists for: how do you know it is actually wired right.

  Open the HTML animation Open the MP4

Install it

The plugin route comes first: it is the path with working updates, so it leads. The release zip stays fully supported as the offline, pinned alternative. Either way, the skills are available in the next session.

/plugin marketplace add nguyenhx2/agent-harness-bootstrap
/plugin install harness-bootstrap@agent-harness-bootstrap
/plugin install spec-builder@agent-harness-bootstrap

codex plugin marketplace add nguyenhx2/agent-harness-bootstrap

git clone https://github.com/nguyenhx2/agent-harness-bootstrap
cp -r agent-harness-bootstrap/plugins/harness-bootstrap ~/.cursor/plugins/local/

# both skills, pinned to whatever you downloaded
unzip agent-harness-bootstrap.zip -d ~/.claude/skills/

cargo install --path tools/harness-view   # or build it yourself

Move to a new version

Two things update independently: the skills on your machine, and the harness already scaffolded into a repository. Neither one overwrites work you did.

/plugin update harness-bootstrap@agent-harness-bootstrap
/plugin update spec-builder@agent-harness-bootstrap

/harness-bootstrap:harness-update

Run it

Both skills interview you before they write anything, in the language you write to them in. Nothing is generated until you approve a one-screen plan.

/spec-builder           # write the specs first, if you are starting from an idea
/harness-bootstrap      # build (or update) the .claude harness for this repo

/new-task "short title"    # register a task on the master plan
/implement-fr FR-014       # plan and implement one requirement end to end
/review-changes            # the review gate, on the whole branch diff
/secret-scan               # any hit blocks until it is rotated
/task-resume TASK-007      # after a compaction or a crash, trusting files over memory

Tuning it after the bootstrap

The bootstrap writes a first draft, not a verdict. Eight commands change the harness after it exists, and every one of them is deliberately narrow: it shows you the diff, asks, applies exactly what you chose, and records why in docs/context/tool-changelog.md. Each also refuses something, and the refusals are the half worth reading before you need them.

• /harness-tune

  Reach for it whenthe floor is tighter or looser than your team can work with, and you want to move a dial rather than remove a control.

  Turns one dial per confirmation: who may run the deploy command, the posture on force-push, rm -rf and a database reset, the spawn allowlist, per-seat turn caps and the attempt cap, how deep the review pass goes, and how much agent history lands on disk. Lowering a cap is free; raising one comes with the cost it will add. Removing the code-review gate is refused outright - that is a different repository, not a tuning - and switching a whole control off is not a tune either, it is the next command.

• /harness-toggle

  Reach for it whenone named rule, command, hook or seat is in the way and you want it off without deleting it.

  A script is the only thing that moves: it parks the file under .claude/disabled/, strips its registration out of settings.json, writes your one-line reason into .claude/disabled.json - committed, so the team shares it and a re-scaffold respects it - and regenerates the graph so the item renders greyed out. The protected controls (the secret guard, the spawn guard, the review seats) need a confirmation phrase typed literally, byte for byte. Enabling is never gated: restoring a control is not the risk the tiers exist for.

• /harness-update

  Reach for it whenyou moved to a newer skill version, or the codebase moved under a harness that was fitted to its old shape.

  Re-reads the code first, because a dev agent scoped to a path that no longer exists is a seat pointing at nothing. Then it re-runs the scaffolder against your recorded answers and reports every file as ADDED, KEPT or CONFLICT, and the conflicts are yours to resolve one at a time. Afterwards it re-applies your toggle state, so an update cannot resurrect something you deliberately switched off, and re-ports only to the Cursor or Codex targets intake recorded rather than re-detecting them.

• /agent-permissions

  Reach for it whenone seat needs one more tool - or, more often, one fewer.

  Edits a single seat's tools: line, after checking the change against the invariants that make a roster safe. Reviewers never gain Edit or Write, because a gate that edits is a dev agent that lost its independence. Only the orchestrator holds the spawn tool. There are no wildcard grants. And model: and effort: are not permissions, so they are refused here and sent to the roster and the cost model instead. A revocation skips the whole check: narrowing is always safe.

• /board-audit

  Reach for it whenyou are about to trust a status - or when work seems to be happening somewhere the board does not know about.

  Validates the board's own frontmatter and its dependency chains first, because every sweep after that assumes well-formed task files. Then it looks for Active tasks nobody is driving, finished agent runs nobody collected, a task whose status disagrees with the master plan, attempts past the cap still marked Active, worktrees and branches no task references, Blocked tasks naming no owner or condition that would unblock them, and a code graph that has gone stale. It is read-only on purpose: it reports, and you or the orchestrator reconcile.

• /code-graph

  Reach for it whena change crosses a module boundary, or the moment the staleness log stops being empty.

  Answers the question an agent cannot answer by reading one file: what breaks if I change this module. Modules, files, import edges with reference counts, and an owner per module matched from the roster's scopes. The orchestrator checks a target's fan-in before dispatch, and a high fan-in means the brief has to name the dependents. Honest about its limits: the built-in extractor is static, so a missing edge is absence of evidence, not evidence of isolation.

• /docs-graph

  Reach for it whenthe specs changed, or you suspect something is being built that no requirement ever asked for.

  The traceability twin of the code graph, and neither substitutes for the other. Every ID - FR, NFR, BR, ADR, TASK - the document that defines it, every document that references it, and a self-contained interactive graph that opens in any browser with no network. spec-guardian checks a diff's claimed IDs against it: an implementation naming a requirement the graph does not know is implementing an invented one. An orphan ID is either unstarted work or a dead reference, and the report says which.

• /skill-wire

  Reach for it whenyou installed a skill and nothing is using it. A skill serves nobody until a seat is told to reach for it.

  Re-reads every file of the skill at wire time rather than trusting the install-time review, because an update can have rewritten the text since - and if it arrived inside a plugin, the whole bundle, since a plugin's hooks and MCP servers run whichever of its skills you wired. It refuses a skill whose instructions edit .claude/, settings.json or hooks; it keeps reviewers on read-only skills, because write-shaped instructions get followed whatever the tool grants say. Unwiring is always allowed, and both directions are recorded.

All eight are written into your repository by the bootstrap and ship with the plugin as well, as /harness-bootstrap:harness-tune and so on, so they work in a project somebody else set up. Three things none of them will do, whatever you confirm: reviewers never gain write access, only the orchestrator spawns, and the code-review gate cannot be removed - only rescoped.

The roster is decided, not installed

The contract and the modules that actually exist decide who gets a seat. Pick a shape of project and watch the roster resolve.

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, and what the agent is told.

• 1 - deny list

  Declared in settings.json. The client itself refuses the call, before any agent reasoning is involved.

• 2 - blocking hooks

  11 blocking hooks. A hook that exits 2 stops the tool call and returns its reason, so the model learns what it may not do instead of being told to be careful.

• 3 - spawn boundary

  Who may spawn whom is fixed by the topology, not by a prompt. One orchestrator delegates; a sub-agent cannot start a second wave.

• 4 - path-scoped rules

  A rule loads only on the paths it governs, which keeps 62% of rule content out of the default session and stops rules from becoming background noise.

• 5 - review gates

  Review, security review and merge management are seats with their own budgets, and the branch gate is a step in the flow rather than a suggestion in a prompt.

Swap Opus for Haiku and the eval result is byte-identical. That is the point: the floor is enforced by shell scripts and exit codes, so it does not depend on which model is driving. What a cheaper model does change is the quality of the code written and the depth of the review, which is the ceiling, and this eval does not measure it.

112/112 per hook flavour - 44 must-block, 68 must-allow - re-run it yourself with py -3.13 eval/guardrail_eval.py

harness-view, the native viewer

A small Rust binary that reads the same .claude/state/harness-graph.json contract the skill writes, and shows how everything is actually wired. It only reads files and reports relationships: no model, no network, no judgment calls. A browser and a CI job cannot disagree about the same repo.

What is new in this release

• A roster editor

  Selecting an agent adds Edit roster: change a seat's model, effort, tools and description from pickers rather than by hand-editing frontmatter. The write touches only the keys that changed - an untouched key keeps its position, its comments and its blank lines, and CRLF stays CRLF. Renaming a seat is refused rather than ignored, because that is a routing-table change, not a field edit.

• A reference you can edit

  The catalogue behind those pickers: four vendors - Claude Code, OpenAI Codex, Gemini CLI and Z.AI GLM - with their models and tools, each carrying a verified flag and a note on what it does. Anything that could not be confirmed against a first-party source is marked unverified wherever it appears, including inside the picker. The catalogue is yours to change: edits are stored per repository in .claude/state/references.json and merged over the shipped seed, so upgrading the skill keeps them. An override can correct a label; it cannot promote an unverified model to verified.

• Editable command steps

  A command's numbered steps render as a chain of cards you can reorder by dragging, insert into, switch off in place, and retitle, with one Save for the batch and a Revert that discards it all. A save rewrites only the line spans the steps occupy: frontmatter, headings and the prose between groups pass through byte for byte. An unedited step is written back as the bytes it arrived as, and that is a test, not a claim.

• Mentions, and rendered markdown

  Typing in a step suggests the names it is reaching for: agent seats, rule files, hook names and real paths in the repository. A step whose text is a table, a list or a fenced block renders as one, so a routing table in step 4 reads as a table; opening it to edit shows the markdown source again. Repository text reaches the page through createElement and textContent only, and links are limited to http(s).

• Custom dialogs

  The confirmations and editors are the viewer's own dialogs rather than browser prompts, so they can be sized to what they hold, and resized when they are not.

• Runtime toggles, in two tiers

  Rules, commands, hooks and roster seats switch off from the details panel, on the same contract as /harness-toggle. A HARD-protected control needs a confirmation phrase typed literally, byte for byte - nothing is trimmed or case-folded. SOFT-protected ones, and every agent seat, need an explicit acknowledgement. Enabling is never gated: restoring a control is not the risk the tiers exist for. The record is .claude/disabled.json, committed, sorted, and with no dates in it.

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 the graph as .claude/ or docs/ change
harness-view assess [path] [--json]       # score it; exit 1 on a high finding

What the score is not: it does not measure whether the rules say anything useful for your codebase, whether an agent's scope matches how the code is really organised, or whether a hook that exists actually blocks what it claims to. A clean report means every rule in the engine passed, not that the harness is good.