agent-harness-bootstrap

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

by nguyenhx2 · English · 日本語

📊 Slide presentation · 🎥 Video gallery · 📦 Latest release · 📚 Docs map

🎬 What it does

Two skills for Claude Code that fix four specific, recognizable failure modes of an unmanaged AI coding agent:

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

• spec-builder creates the thing you and the AI both understand - one shared voice, built from an idea, a transcript, meeting notes, or a pile of legacy docs, into a 13-section contract with stable requirement IDs and acceptance criteria. It never invents a requirement; anything unstated becomes a flagged open issue instead of a guess. What that contract actually looks like: see below.
• harness-bootstrap creates the frame that lets AI operate autonomously AND safely - the .claude/ harness (a folder of agents, path-based rules, and enforcement scripts that shapes what an AI agent may do) it runs inside, tailored to your repo rather than copied from a template. It reads your code first, so what it generates fits your repo. What "tailored" means concretely: see What you get.
• The guardrails are shell scripts and exit codes, not the model's judgment. Swap every agent from Opus to Haiku and the safety floor is byte-identical - python eval/guardrail_eval.py proves it, 26/26.

📋 What spec-builder produces

Not prose retyped from scratch each time - a fixed structure, thirteen numbered sections under docs/specs/ (01-overview.md through 13-revision-history.md), installed from real template files so the shape never drifts between projects:

• Stable requirement IDs, each with one defining home - FR- (functional requirements, section 05), NFR- (non-functional, 07), BR- (business rules, 05), US-/UC- (user stories and use cases, 05), and more. Every other document links back to the defining section instead of restating the requirement.
• The blank-cell-with-question rule - an unknown never becomes an invented fact. It becomes either an assumption (AS-nn, with what breaks if it's wrong) or an open issue (OI-nn, with a named owner) in 11-assumptions-constraints.md - never a guessed default standing in for a real answer.
• A verifiable quality gate - every FR must appear in the feasibility table (12), carry an acceptance criterion with at least one negative case, and trace back to something a stakeholder actually said. Each check in the gate is a grep command against the files, not a vibe check.
• The specs graph - docs/context/specs-graph.html, a self-contained interactive export (open in any browser, no server needed) of how sections, requirements, ADRs, and tasks reference each other, with orphan IDs called out.

Full depth, and the standards it draws on (ISO/IEC/IEEE 29148, ISO/IEC 25010, BABOK v3, MoSCoW, Cockburn use cases): spec-builder/SKILL.md · ba-standards.md.

🚀 Quickstart

Requires Python 3. Install both skills in one line.

macOS / Linux (bash):

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

Windows (PowerShell):

irm https://github.com/nguyenhx2/agent-harness-bootstrap/releases/latest/download/agent-harness-bootstrap.zip -OutFile "$env:TEMP\skills.zip"
Expand-Archive "$env:TEMP\skills.zip" "$env:USERPROFILE\.claude\skills" -Force
Remove-Item "$env:TEMP\skills.zip"

Or let the agent install it - paste this into any Claude Code session:

Install the two skills from the latest release of
https://github.com/nguyenhx2/agent-harness-bootstrap into ~/.claude/skills/:
download agent-harness-bootstrap.zip from the latest release, verify it against the
SHA256SUMS asset from the same release, extract it so that each skill directory
(harness-bootstrap/, spec-builder/) sits directly under ~/.claude/skills/, confirm both
SKILL.md files exist, and tell me the installed version from their VERSION files.

Then, inside Claude Code:

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

If the repo already has code, run /harness-bootstrap on its own - it reads the code first and pre-fills the intake with what it found. Existing files are reconciled, not overwritten: anything that conflicts is reported and left for you to merge. Nothing is written until you approve the plan.

One skill at a time, a pinned version, checksums, from source, or running the harness in Cursor and Codex instead of Claude Code: see docs/tools/ - Claude Code · Cursor · Codex.

📦 What you get

Not a fixed bundle - a .claude/ harness tailored to this repo. The roster, which rules load, the hook flavor, the deny-list, and the delivery discipline are all derived from intake and from what the code graph finds in your source, not copied from a template:

• Agent roster - one dev seat per module or bounded context the code graph maps in your repo, not a fixed head count; add or retire a seat later with /harness-update.
• Rules that load - matched to the stack your manifests actually show; a rule for a language, framework, or concern you don't have (no DB, no UI) never loads at all.
• Hooks - matched to the dev OS intake detects (Windows vs. POSIX), so the guardrails fire instead of silently no-opping on the wrong shell.
• Deny-list - matched to the real destructive commands for this stack (the DB reset command, the deploy command, any infra-teardown command) - confirmed from your config, never guessed.
• Methodology - chosen in intake: DDD by default (bounded-context scopes, tests ship with the implementation), TDD opt-in (tests strictly first - stronger proof, slower delivery, and the two can pull against each other if combined) - see intake.md.
• Effort profile - Default / Economy / Thorough, tuning cost vs. depth per seat without touching a review or safety gate.
• Control level - deploy rights and destructive-command posture; deployment defaults to human-only (deploy sits in permissions.deny until intake, or /harness-tune later, moves it to ask), adjustable after bootstrap without re-running intake.

.claude/
  agents/     one seat per module the code graph finds - model, effort, tool grant, turn limit
  rules/      always-loaded core plus stack-matched rules that load only on a matching file touched
  commands/   the tuning commands (below) plus the stack-specific ones intake wires in
  hooks/      the guardrails matched to your OS, blocking a dangerous action before it happens
  settings.json
docs/
  tasks/      the board: one row per task, a session log the agent writes AS IT WORKS
  context/    code-graph.md (dependency map) and docs-graph.md (traceability map), each also exported
              as self-contained interactive HTML - docs/context/harness-graph.html (agents, hooks,
              rules, commands, settings, and modules) and docs/context/specs-graph.html (document
              traceability)
  specs/ requirements/ architecture/ templates/
AGENTS.md + CLAUDE.md

The spawn boundary itself - only a roster seat may run, and only at its pinned model - is enforced by the guard-agent-spawn hook, not by a rule an agent could drift from.

Shipped toolbox this tailoring draws from - the asset superset, not a per-project guarantee: 15 agents, 15 rules, 21 slash commands, 9 hooks. What actually lands in your .claude/ depends on the dimensions above; see roster.md for the full seat list.

Full guarantees, the memory model, and the cost breakdown: docs/ASSESSMENT.md, docs/CONTEXT-MANAGEMENT.md, cost-model.md.

🎛️ Post-bootstrap tuning

The harness's starting posture is not permanent. Seven commands ship into every bootstrapped repo to adjust it after the fact - full guidance, worked examples, and the invariants each one enforces live in docs/TUNING.md.

Three things none of the seven will ever do, no matter what you confirm: reviewers never gain write access, only the orchestrator spawns, and the code-review gate cannot be removed - only rescoped.

🗺️ Docs map

Numbers, measured against the predecessor skill this replaces - reproduce with python benchmark/benchmark.py:

👤 Who made this

Built by nguyenhx2. Contributions welcome - start with CONTRIBUTING.md.

📄 License

MIT - see LICENSE.