Agent Harness Bootstrap

Give an AI agent a repo it can actually understand, and a harness it cannot escape.

English · 日本語

Two skills for Claude Code. spec-builder writes the spec an AI can build from. harness-bootstrap
builds the .claude/ harness it runs inside - agents, rules, guardrails and a task board, fitted to
your repo. The result also ports to Cursor and Codex, guardrails included.

Start here:

curl -fsSL https://github.com/nguyenhx2/agent-harness-bootstrap/releases/latest/download/agent-harness-bootstrap.zip -o skills.zip \
  && unzip -o skills.zip -d ~/.claude/skills/ \
  && rm skills.zip

/spec-builder           # write the contract first
/harness-bootstrap      # build or update the .claude harness for this repo

Requires Python 3. Full install (including Cursor and Codex) and usage below.

Watch it in 60 seconds

The whole product in one clip. Watch the full set with sound-free captions in the gallery - six clips, no download.

The problem, and what this does about it

Dropping an AI agent into a real repository raises the same hard questions every team hits:

Two skills

They cover the two ends of the same gap: the AI does not know what you want, and nothing constrains
what it does.

Green is deterministic and free. Purple costs tokens. The loop on the right runs the same on any model
tier, because the gates around it are shell scripts rather than judgment.

The rest of the clips

Every clip plays in your browser - watch the gallery,
no download. Sources in video/. There is also a
slide presentation (EN / VI / JP).

Install

The two skills run inside Claude Code - that is where you invoke /harness-bootstrap and
/spec-builder. Cursor and Codex do not run the skills; they run the harness the skills
produce, so their setup is one command against an already-scaffolded repo.

Claude Code

Download the latest release,
or install both skills in one line:

curl -fsSL https://github.com/nguyenhx2/agent-harness-bootstrap/releases/latest/download/agent-harness-bootstrap.zip -o skills.zip \
  && unzip -o skills.zip -d ~/.claude/skills/ \
  && rm skills.zip

Requires Python 3. Confirm what you installed:

cat ~/.claude/skills/harness-bootstrap/VERSION

Cursor

Scaffold the harness once from Claude Code (or copy an existing .claude/ in), then port it. From the
repo root:

python ~/.claude/skills/harness-bootstrap/scripts/port.py --target . --tool cursor

This writes .cursor/rules/*.mdc and .cursor/hooks.json plus its adapter. Cursor reads AGENTS.md
and the rules on its own; the hooks enforce through the adapter. No release to install - the porter
ships with the skill.

Codex

Same starting point, one command:

python ~/.claude/skills/harness-bootstrap/scripts/port.py --target . --tool codex

Codex reads AGENTS.md natively and its hook payload matches Claude Code's, so this only writes
.codex/hooks.json pointing at the existing hooks. Use --tool all to set up Cursor and Codex at
once.

# one skill at a time (stable URLs, always the newest release)
curl -fsSL https://github.com/nguyenhx2/agent-harness-bootstrap/releases/latest/download/harness-bootstrap.zip -o hb.zip
unzip -o hb.zip -d ~/.claude/skills/ && rm hb.zip

curl -fsSL https://github.com/nguyenhx2/agent-harness-bootstrap/releases/latest/download/spec-builder.zip -o sb.zip
unzip -o sb.zip -d ~/.claude/skills/ && rm sb.zip

# a pinned version
V=1.3.0
curl -fsSL "https://github.com/nguyenhx2/agent-harness-bootstrap/releases/download/v${V}/harness-bootstrap-v${V}.zip" -o hb.zip
unzip -o hb.zip -d ~/.claude/skills/ && rm hb.zip

# verify the download
curl -fsSLO https://github.com/nguyenhx2/agent-harness-bootstrap/releases/latest/download/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

# from source
git clone https://github.com/nguyenhx2/agent-harness-bootstrap.git
cp -r agent-harness-bootstrap/harness-bootstrap ~/.claude/skills/
cp -r agent-harness-bootstrap/spec-builder      ~/.claude/skills/

Use it

Invoke each skill by its exact name, with a leading slash. The names are unambiguous, so they never
collide with a natural-language phrase that could match some other skill you have installed:

/harness-bootstrap      # build or update the .claude harness for this repo
/spec-builder           # write the specs first

If the repo already has code, run /harness-bootstrap on its own. It reads the code before
writing anything - stack, modules, conventions, risky operations - and shows you that inventory first.
Most of the intake is pre-filled from what it found, so you are only asked what the code cannot tell
it. Existing files are reconciled, not overwritten: anything you wrote, or another tool created, is
reported as a CONFLICT and left in place for you to merge - never replaced.

If you are starting from an idea and an empty repo, run /spec-builder first, then
/harness-bootstrap. The specs come first because the agent roster comes out of them: cluster the
requirements into domains, one dev agent per domain, each scoped to the module path it will own.

Either way you see the plan - what will be created, kept and modified, plus every agent's model and
effort budget - and nothing is written until you approve it. The scaffold itself takes about a fifth
of a second.

Nothing here becomes global state. Both skills write only into the target repository, under .claude/
and docs/; they never touch your ~/.claude/skills/ directory, and the whole harness is a set of
files you can delete. Remove .claude/ and the repo is exactly as it was.

What lands in your repo

.claude/
  agents/           15 agents, each with an explicit model, effort, tool grant and turn limit
  rules/            14 rules - 6 always loaded, 8 that load only when you touch a matching file
  commands/         /new-task /task-resume /implement-fr /review-changes /secret-scan /deploy ...
  hooks/            6 hooks that block bad actions before they happen
  settings.json     permission allow/deny + hook registration
docs/
  tasks/
    master-plan.md      the board: one row per task
    active/TASK-NNN.md  goal, acceptance criteria, and a session log the agent writes AS IT WORKS
  specs/ requirements/ architecture/ context/ templates/
AGENTS.md + CLAUDE.md

What the harness guarantees

It cannot do the dangerous thing

Not "is told not to". Cannot. The guardrails are shell scripts and glob rules:

python eval/guardrail_eval.py   # 15 known-bad payloads at a real generated harness -> 15/15

Swap every agent from Opus to Haiku and re-run. Identical result: no model is in the loop.

Rules in .claude/rules/ are advice, and a model can drift from them after a compaction. Hooks,
permissions.deny, tools: and maxTurns are enforcement. A control moves from soft to hard the
moment it can be written as a file check.

The IDE can die and you lose nothing

State lives in committed markdown, written as the agent works, not in a context window that compaction
will summarise away. After a crash, an agent with an empty context scans docs/tasks/active/, reads
the session log, reconciles branches against the board, verifies against git rather than memory, and
continues from the last recorded row. /task-resume does it for you.

The rule that makes it work: a gate counts as passed only when the session log records it. An
agent's "done" is a claim you verify, never a fact.

Details: docs/CONTEXT-MANAGEMENT.md.

You stop paying for tokens you did not choose to spend

Opus is 1.67x Sonnet, not 5x, so tier is a smaller dial than most advice assumes and effort: is a
bigger one. The default roster is deliberately not the cheapest: it spends the difference on Opus review
gates. Take the other side of that bet by editing one table in
roster.md. These figures are modelled from published prices,
not measured - run python benchmark/model_cost.py.

How the harness is built, and how it holds itself

Nothing in your .claude/ folder is invented. Each agent, rule, hook and deny entry traces back to
something real: your code, your specs, or an answer you gave at intake, and scaffold.py copies the
rest from files on disk. Once it runs, the pieces hold each other: the orchestrator dispatches every
agent but cannot write product code, the reviewers gate the dev agents but cannot edit anything, the
board records what actually happened, and the hooks stop all of them without asking.

The whole thing, in one picture

The model sits in a slot near the top. Every layer beneath it - the deny list, the hooks, the tool
grants, the board - is deterministic and unchanged when the model changes.

Model tier is swappable today: opus, sonnet, haiku, fable. Model vendor is not.
Re-pointing the roster at a self-hosted or third-party model is a port rather than a config change, and
no adapter ships here. See docs/ASSESSMENT.md, Gap 2.

Also runs in Cursor and Codex

Cursor and Codex both have hook systems close enough to Claude Code's that the guardrails port, not
just the rules. The one-command setup for each is in Install above; here is what actually
crosses over and where it stops:

Codex reads AGENTS.md at the repo root with no setup, and its hook payload is identical to
Claude Code's, so the porter registers the existing hooks directly in .codex/hooks.json.

Cursor reads AGENTS.md and .cursor/rules/*.mdc. Its hook events and output differ, so the
porter writes a small adapter that translates Cursor's payload to the harness hooks and back. The
adapter is unit-tested in CI: it correctly denies a .env read and a commit to main, and allows
npm test.

Two honest limits, both printed by the porter and enforced nowhere else:

• Codex routes file edits through apply_patch with the path inside the command, so protect-adr
  (which reads a file path) is best-effort there. The Bash guards are exact.
• Cursor's afterFileEdit is observational, so an edit to an Accepted ADR is flagged after the
  fact rather than blocked before. Everything reachable through a shell command or a file read blocks
  the same as in Claude Code.

The three tools share one source of truth. AGENTS.md is the contract; .claude/, .cursor/, and
.codex/ are three renderings of it, generated from the same assets. Each tool has a page with the
exact files, the enforce-vs-advice table, and how to verify it:

• Claude Code - the reference: how the harness is generated and enforced.
• Cursor - the .mdc rules and the hook adapter.
• Codex - native AGENTS.md and the directly registered hooks.

Governance

Three rules ship into every repo you bootstrap. You supply the answers at intake; the skill never
invents a policy for your company.

• model-policy.md - classify your data
  (Public / Internal / Confidential / Restricted) and say which models may process each class.
  Restricted paths are denied at the read boundary, so an agent cannot leak what it cannot open.
• ip-compliance.md - dependency licence
  allow/deny, the AGPL-on-SaaS trigger, and a diff check the reviewers can run.
• ai-governance.md - which actions need
  a human who saw the specific action, not a config flag.

Reference

Numbers

Measured against the predecessor skill this replaces. Reproduce with python benchmark/benchmark.py.

Byte figures are exact. Token figures are estimated unless ANTHROPIC_API_KEY is set, in which case
the script counts them against the real endpoint.

Contributing

• No invented numbers. A script in benchmark/ or eval/ must print any figure you cite.
• Assets stay byte-stable. No timestamps or run IDs under assets/ - they land in a system prompt
  and cold-miss the prompt cache forever.
• No em-dashes. Plain hyphens.

Releases follow docs/RELEASING.md.

MIT - see LICENSE.