Bootstrap Harness

bootstrap-harness

Create a production-quality harness (docs system for AI agents) in any repo. 3 progressive stages — produce only what the project needs at its current maturity.

File templates live in [templates.md](templates.md) — read it when you reach Step 3, not before.

When to use

• Fresh repo / no CLAUDE.md — just cloned or scaffolded, wants AI-agent workflow
• Repo with no harness — team adopting structured AI coding
• Major rebuild — current docs bloated / stale / drifted

When NOT to use

• Minor tweaks / drift → /review-harness (incremental, no rebuild)
• Single-file script / experiment → overkill
• Harness exists and mostly accurate → /review-harness first to confirm

---

Core principles (2025-2026 research)

1. Commands go first — agents query build/test/run most often (GitHub 2,500-repo study).
2. ✅ / ⚠️ / 🚫 three-tier Boundaries — Always / Ask first / Never (AGENTS.md spec).
3. CORRECT / INCORRECT code pairs — concrete examples beat prose; pull from real repo code.
4. **CLAUDE.md hard limit .md (dynamic). **Delivered plans → completed/. Rendered byproducts (HTML reports, teaching explainers, design variants) → docs/exec-plans/archive/ (gitignored).** The index docs/exec-plans/README.md connects them. No README inside active/ completed/ archive/` — the index lives one level up.
5. Bullet + ID for evolving rules → enables delta edits, not full rewrites (ACE paper). Rewriting a whole doc to add one rule causes context collapse (detail erodes) and brevity bias (specifics get summarized away). Add/edit small structured items instead.
6. Prose rots; code / tests / ADRs are truth. Never let a prose doc become a second source of truth for something the code, tests, or an ADR already encodes (capability lists, phase status, schema, counts). It WILL drift, and agents adopt the rotten copy as fact. State it once in the authoritative place; everywhere else links, not copies. And for code-derivable facts (counts, capability lists, enums), even a hand-maintained "single source" doc rots — derive it from code (a gen-docs step) or pin it with a CI assert (assert len(REGISTRY) == N); let prose only link. (Real case: a SPEC doc claimed "21 capabilities" while the registry had 11 — the "single source" was itself a stale literal.)
7. Periodic self-improvement, not a runtime loop. /review-harness audits on a cadence and proposes; a human approves. (A deterministic pre-commit/CI hygiene gate is a stronger opt-in for teams that want per-commit enforcement — mention it, don't scaffold it by default.)
8. Every file earns its place — if you can't name a concrete agent task that needs it, skip it.

---

Workflow — 4 steps

Use TodoWrite to track: Scan → Ask → Generate → Verify.

Step 1 — Scan repo silently

ls -la && git log --oneline -10 2>/dev/null
find . -maxdepth 2 -type f -name '*.md' | head -20
ls package.json pom.xml Cargo.toml pyproject.toml go.mod requirements.txt Gemfile 2>/dev/null   # stack
ls next.config.* vite.config.* nuxt.config.* 2>/dev/null                                         # framework
ls CLAUDE.md AGENTS.md GLOSSARY.md README.md docs/ .claude/ 2>/dev/null                           # existing harness
ls .github/workflows/ tests/ test/ __tests__/ 2>/dev/null                                         # maturity

Record internally: language/framework · existing docs worth keeping vs replacing · recent git activity (what's the team actually doing?) · maturity (PoC / MVP / prod?).

Step 2 — Ask the user (only if uncertain)

AskUserQuestion for: one-sentence project description (if README is generic) · target stage (Seed/Standard/Full) · business-domain-heavy? (Y → GLOSSARY) · multi-agent tools? (Cursor+Codex+Claude → AGENTS.md naming; Claude-only → CLAUDE.md). Skip anything obvious from the scan; don't bombard.

Step 3 — Pick stage, generate files

Read [templates.md](templates.md) now. Track each file in_progress → completed with TodoWrite.

Stage 1 — Seed (any project):

• CLAUDE.md (or AGENTS.md) — intro + Commands + Structure + Boundaries + pointer + index. **`.
• ❌ Copying from a previous project — scan the target first; a payments GLOSSARY is useless in a CMS.
• ❌ Weights / percentages / SLO numbers without measurement — false precision.
• ❌ Promoting a lesson to a hard rule on first sighting — require ≥2 references.
• ❌ Prose duplicating code-truth — a capability list / phase status / schema copied into prose becomes a second source that rots. Link to the one authoritative place.
• ❌ Keeping ✅-delivered plans in active/ "for reference" — active/ is in-progress only. Delivered → completed/ in the same commit you mark it done. "Move later" = never.
• ❌ Letting rendered HTML / reports pile up in active/ — they're byproducts, not plans → archive/ (gitignored).
• ❌ AGENTS.md as a symlink to CLAUDE.md — Windows checks the symlink out as a plain text file containing the path, not the content. If you want both names: make AGENTS.md the canonical file and CLAUDE.md a one-line @AGENTS.md import — Claude Code resolves it natively, other tools read AGENTS.md directly, Mac+Win safe, zero-dep. For large multi-tool fan-out, ruler also works.
• ❌ A four-file set in every directory (AGENTS.md+DESIGN.md+PROGRESS.md+BUGS.md per package) — no real backing, and PROGRESS/BUGS/DESIGN just duplicate exec-plans/ / lessons.md / ADRs (which rot independently). Use one AGENTS.md per directory that has genuinely local rules; everything else links to the single source.
• ❌ Creating a project-level copy of /review-harness — it's a user-level skill; reference it, never write .claude/skills/review-harness/ into the target.
• ❌ Framing the owner as "intern" / "junior" in any artifact — harness language treats them as the owner.

---

Closing report

## Harness Bootstrap Done — Stage 
### Generated
- CLAUDE.md ( lines, 
### Skipped (with reason)
- ARCHITECTURE.md — single-module · RELIABILITY.md — not prod-bound
### Key conventions encoded
- Commands/Testing/Structure/Boundaries · ✅/⚠️/🚫 tiers ·  CORRECT/INCORRECT pairs from real code · active→completed lifecycle + archive/ for byproducts
### Next steps
1. After your next milestone, run `/review-harness`
2. Append to docs/lessons.md as you hit pitfalls
3. If the project grows (UI / prod / multi-module), re-run for Stage 3

---

Sources

• AGENTS.md spec · GitHub 2,500-repo study
• ACE paper (2510.04618) — structured bullets, delta edits, context-collapse / brevity-bias
• Harness Engineering Best Practices 2026 — mechanisms-not-prompts, feedback-speed hierarchy, "docs rot, tests don't"
• Writing a good CLAUDE.md (HumanLayer) — < 60 lines, pointer-not-description
• openai/codex AGENTS.md · vercel-labs/ralph-loop-agent — CORRECT/INCORRECT reference

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TIANTIAN-ZHAN
• Source: TIANTIAN-ZHAN/claude-harness
• License: MIT

Install and usage instructions live in the source repository linked above.