{
"markdown": "# harness-boot\n\n> [English](README.md) Β· [νκ΅μ΄](README.ko.md)\n\n> **Your AI has speed. We give it direction.**\n\nharness-boot is a multi-agent development harness for Claude Code. Where most AI tools add *capability*, we add *focus*.\n\n[](.claude-plugin/plugin.json)\n[](tests/parity)\n[](LICENSE)\n\n---\n\n## π Why a *harness*?\n\nA loose horse runs fast in every direction. A harnessed horse runs fast toward something.\n\n```\nYou βββΆ β Convert βββΆ β‘ Evolve βββΆ β’ Focus βββΆ β£ Collaborate βββΆ β€ Unify βββΆ Result\n (the context) (the docs) (the rules) (the experts) (two commands)\n```\n\n---\n\n## Five strengths\n\n| # | Strength | How it works | What you get |\n|---|---|---|---|\n| 1 | **Convert** | Plain-language ideas convert into an intermediate language β structured specs that every AI agent can act on directly | Same context for every agent β less guessing, sharper output |\n| 2 | **Evolve** | Edit one place, the rest stays in sync; mismatches surface automatically; your manual tweaks survive | Design docs are always current β no manual upkeep |\n| 3 | **Focus** | Each agent works inside its lane; completion criteria are enforced by the system, not by trust | AIs stay on the work that's theirs |\n| 4 | **Collaborate** | Role-specialized agents follow set procedures; every decision and disagreement is recorded | Blind spots get covered, every step is traceable |\n| 5 | **Unify** | Two slash commands. Talk to it in plain English; see the plan before anything runs | Almost nothing to memorize |\n\n---\n\n## Architecture\n\n```\n Plain language / plan.md / existing code\n β\n βΌ\n ββββββββββββββββββββββββββββββββββββββββββββ\n β spec.yaml (single source of truth) β\n β ββ Ideas β vision Β· users β\n β ββ Rules β features Β· decisions β\n ββββββββββββ¬ββββββββββββββββββ¬ββββββββββββββ\n β β\n Auto-derived Expert collaboration\n β β\n βΌ βΌ\n ββββββββββββββββββ ββββββββββββββββββββββββ\n β domain.md β β orchestrator β\n β architecture β β ββ Planning β\n β events.log β β ββ Design β\n β chapters/ β β ββ Implementation β\n β drift detector β β ββ QA Β· Integration β\n ββββββββββββββββββ β ββ Audit (read-only)β\n β + ceremonies β\n ββββββββββββββββββββββββ\n β\n βΌ\n /harness-boot:work\n (no args = dashboard Β· words = intent)\n```\n\n---\n\n## Quick start\n\nIn Claude Code:\n\n```bash\n/plugin marketplace add qwerfunch/harness-boot\n/plugin install harness-boot@harness-boot\n\ncd my-new-project\n```\n\nPick the entry point that fits β both feed into the same harness:\n\n```bash\n# A. From a one-line idea\n/harness-boot:init \"a simple to-do app\"\n\n# B. From an existing planning doc (plan.md, design notes, a sketch)\n/harness-boot:init plan.md\n```\n\nThen drive every feature through the lifecycle:\n\n```bash\n/harness-boot:work\n```\n\nIf it takes more than 5 minutes, [open an issue](https://github.com/qwerfunch/harness-boot/issues). We'll fix it.\n\n---\n\n## Manual install\n\nUse this when you want to run from a local clone β for contributors, forks, or offline setups. The repo's `.claude-plugin/marketplace.json` makes any clone act as a self-hosted marketplace.\n\n> Note: harness-boot is not listed in the official Claude Code marketplace yet β the `qwerfunch/harness-boot` form above resolves to this GitHub repo directly.\n\n```bash\ngit clone https://github.com/qwerfunch/harness-boot.git\ncd harness-boot\n```\n\nThen in Claude Code (use the absolute path of the clone):\n\n```bash\n/plugin marketplace add /absolute/path/to/harness-boot\n/plugin install harness-boot@harness-boot\n```\n\nTo update later, `git pull` in the clone and run `/plugin marketplace update harness-boot`.\n\n---\n\n## How to use it\n\n### Talk to it in plain English\n\nAppend whatever you'd normally say after `/harness-boot:work`. Short keywords and full sentences both work.\n\n| Intent | What you can say |\n|---|---|\n| Dashboard / what's next | (no args) Β· \"what's on my plate?\" Β· \"where am I?\" Β· \"what should I do next?\" |\n| Run checks | \"test it\" Β· \"run the gates\" Β· \"check what's there\" Β· \"make sure nothing's missing\" |\n| Mark as done | \"it's done\" Β· \"ready to ship\" Β· \"I think we're good\" Β· \"let's wrap up the login feature\" |\n| Block / pause | \"I'm stuck\" Β· \"pausing this\" Β· \"the upstream API isn't ready\" Β· \"calling it for the day\" |\n| Start / switch | \"login feature\" Β· \"let's do signup next\" Β· \"F-3\" Β· \"tackle billing first\" |\n| Resume | \"keep going\" Β· \"back to yesterday's work\" Β· \"do the recommended one\" |\n| Add evidence | \"I checked\" Β· \"got reviewed\" Β· \"a friend tried it\" Β· \"QA passed\" |\n| Drop a feature | \"skip this one\" Β· \"cancel\" Β· \"F-9 β never mind\" |\n| Look back | \"what did I do last week?\" Β· \"history of F-3\" Β· \"why did we go with OAuth?\" |\n\nThese are just samples β Claude reads context and handles other phrasings too. When it isn't sure, it shows you the plan and asks Y/n before running anything.\n\n### A short conversation\n\nA typical happy path β start a feature, run the gates, mark it done.\n\n```\nYou> let's start the login feature\n\nClaude> Starting Login (F-3).\n To finish: smoke run (gate_5) PASS + at least 1 evidence.\n Next: run the gates.\n\nYou> run them\n\nClaude> tests (gate_0) PASS β 19 unit tests\n smoke run (gate_5) PASS β evidence auto-saved\n type/lint/coverage (gate_1/2/3) SKIPPED β no tool detected\n Iron Law satisfied (smoke run + evidence). Mark Login (F-3) done? [Y/n]\n\nYou> Y\n\nClaude> Done. Retro saved: .harness/_workspace/retro/F-3.md\n Up next: Signup (F-4). Say \"switch\" or \"show what's left\".\n```\n\n### Dashboard output\n\n```\nharness-boot\n\nActive: \"Login feature\"\n Progress: 3/6 gates passed Β· 2 evidence\n Blockers: accessibility Β· Space-key behavior unclear\nPending: \"Signup\" Β· \"Forgot password\"\nNext: (1) run the next gate (recommended)\n```\n\n---\n\n## Built with harness-boot\n\n| Project | Preview | Demo | Source | Description |\n|---|---|---|---|---|\n| **cosmic-suika** | ![\"cosmic-suika](\"docs/assets/cosmic-suika.png\")
| [Play](https://qwerfunch.github.io/cosmic-suika-pages/) | [GitHub](https://github.com/qwerfunch/cosmic-suika-pages) | Space-themed merge game |\n| *Yours next* | β | β | β | Add your harness-boot project here |\n\n**Built something?** Open a [PR](https://github.com/qwerfunch/harness-boot/pulls) adding your project to the table β copy an existing row as a template. Or open an [issue](https://github.com/qwerfunch/harness-boot/issues) with the image and a one-liner if a PR is overkill.\n\nSend any image, GIF, or screenshot that shows the project β plus a one-liner and a link. We'll optimize and place it on merge. Full guide: [`docs/assets/README.md`](docs/assets/README.md).\n\n---\n\n## Benchmarks\n\nDoes harness-boot actually produce better output than vanilla Claude Code β fewer tokens, more issues resolved? The framework for an apples-to-apples comparison is public, with the methodology, task list, and reproduction scripts open for inspection.\n\n- **Suite**: SWE-bench Verified (20-task subset across 9 popular Python repos: django, sympy, scikit-learn, matplotlib, sphinx, pytest, requests, flask, pylint, astropy, pandas, xarray)\n- **Measures**: resolve rate Β· token consumption Β· wall time Β· code quality signals (LOC, tests added, drift catches)\n- **Status**: framework public, measurement in progress\n- **Read**: [`docs/benchmark/swe-bench-verified/REPORT.md`](docs/benchmark/swe-bench-verified/REPORT.md) β results table fills in row-by-row as runs complete\n- **Methodology**: [`docs/benchmark/swe-bench-verified/README.md`](docs/benchmark/swe-bench-verified/README.md) β why SWE-bench Verified, why 20 tasks, what's measured\n- **Reproduce**: [`docs/benchmark/swe-bench-verified/scripts/setup.md`](docs/benchmark/swe-bench-verified/scripts/setup.md) β end-to-end external setup\n- **Validity caveats**: [`docs/benchmark/swe-bench-verified/analysis/threats-to-validity.md`](docs/benchmark/swe-bench-verified/analysis/threats-to-validity.md)\n- **Privacy**: the auto token capture (Stop hook Β· F-174) reads only the local transcript file Claude Code already wrote and appends token counts + the model id to your local `events.log`. No network access. Set `HARNESS_DISABLE_TOKEN_HOOK=1` to opt out entirely.\n\n---\n\n## Repository layout\n\n```\nharness-boot/\nβββ .claude-plugin/ plugin.json Β· marketplace.json\nβββ agents/ specialist agent definitions\nβββ commands/ slash commands (init Β· work)\nβββ hooks/ session-bootstrap Β· prompt-log\nβββ src/ TypeScript implementation\nβββ dist/cli/ esbuild single-file bundle (committed; no node_modules at install site)\nβββ bin/harness Node shim that loads the bundle β `harness `\nβββ self_check.sh 5-step self-dogfood verification\nβββ skills/spec-conversion/ plan.md β spec.yaml conversion\nβββ docs/ schema Β· templates Β· samples Β· portfolio assets\nβββ tests/parity/ TS parity test suite\n```\n\n---\n\n## Status\n\n**v0.15.0** β Adaptive drive + structural archive separation + plugin-level writing rules (F-129 β F-140). Iron Law gains paired `perf_regression` / `perf_resolved` evidence kinds so silently-regressing perf cycles can no longer ship. `complete()` now relocates done feature bodies into a sibling `spec.archive.yaml` and `harness sync` migrates pre-existing bodies in one pass β `spec.yaml` stays slim by construction. `harness drive` becomes adaptive: deterministic replan after each completion, periodic real-test injection (`harness.yaml drive.real_test.command`), and transient-retry on flaky e2e. Plugin-level `docs/communication-rules.md` standardises answer-first format and native-tone replies for any user language.\n\nPreviously: **v0.14.3** β Stability + cleanup batch (F-122 β F-128). `tests/parity/driveLoopAndPlan.test.ts` time-bomb fixed (F-122) so CI on every downstream fork stays green; CLAUDE.md brought back in sync (F-123) and refactored into stable / semi-static sigil / volatile-pointer layers so future drift is structurally prevented (F-124); the pre-cutover Python footprint (`legacy/scripts/`, `tests/unit`, `tests/integration`, `tests/scale` β ~28 k lines combined) evicted from git tracking, working trees preserved locally (F-125 + F-126); `hooks/pre-commit-phase2.sh` now short-circuits during git's own merge / cherry-pick / revert / rebase finalizers so conflict-resolution commits no longer require `HARNESS_BYPASS_PRE_COMMIT=1` (F-127). Zero capability addition, zero behaviour change; v0.14.2 installs are functionally identical.\n\n**v0.14.0** β `drive` ships (F-118 + F-119). New autonomous-loop slash command `/harness-boot:drive \"\"` that scaffolds a *Goal* (a container that groups N features) via researcher β product-planner β feature-author and then runs every feature's gate cycle to completion. **Bounded by design**: BR-015 forbids self-issued `--hotfix-reason`, `git commit/push/tag`, and any shared-state mutation; the loop *halts* on 9 enumerated conditions (commit boundary, retry threshold, drift error, blocked feature, wall-clock, iteration cap, network failure, STOP file, plan-phase approval) and yields back to the user. Read-only `harness drive --status [G-N] [--all] [--json] [--watch]` is mtime-invariant (CQS, BR-012).\n\nPreviously: **v0.13.2** β Repo root cleanup (F-117): dead Python config (`pytest.ini`, `requirements-dev.txt`) removed after the v0.13 TS-only cutover. No behavior change.\n\n**v0.13.1** added the `feature-author` skill β auto-triggers on Korean (\"X κΈ°λ₯ ꡬνν΄μ€\", \"X λ§λ€μ΄μ€\") or English (\"draft a feature\", \"spec out X\") prompts to scaffold a complete `features[]` entry with shape detection, project-mode-aware AC count, and lockstep paste instructions.\n\n- Changelog β [CHANGELOG.md](CHANGELOG.md)\n- Developer guide β [CLAUDE.md](CLAUDE.md)\n- Issues β [GitHub Issues](https://github.com/qwerfunch/harness-boot/issues)\n\n```bash\n# For contributors building from source (devDependencies only β\n# end users install via /plugin install and need no npm step):\nnpm install\nnpm test # vitest suite (parity tests)\nbash self_check.sh # 5-step structural verification\n```\n\n---\n\n## License\n\n[MIT](LICENSE) β Free to use, free to fork.\n",
"bytes": 12793,
"sha": "d24d0d57a2e1e6d19bc067dfbaf633d3e208b7b7e2e67443f1eafff54c384387",
"repo_slug": "qwerfunch/harness-boot",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_qwerfunch_harness_boot_harness_boot_bbb1b8cb/readme"
}