
web-builder-harness
A Claude Code plugin that turns a one-sentence idea into a small, verified web app
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up web-builder-harness (claude-plugin project) into my current project. Found on https://claudeers.com/web-builder-harness Repo: https://github.com/coldingcode/web-builder-harness Homepage/docs: — Detected install method: claude-plugin → /plugin install web-builder-harness@coldingcode/web-builder-harness Category: plugins. Platforms: cli, web, mobile. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
/plugin marketplace add coldingcode/web-builder-harness /plugin install web-builder-harness@coldingcode/web-builder-harness
git clone https://github.com/coldingcode/web-builder-harness
// compatibility
| Platforms | cli, web, mobile |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | AGPL-3.0 |
| Pricing | open-source |
| Language | Python |
Web Builder Harness
中文 · English
A Claude Code plugin that turns a one-sentence idea into a small, verified web app. It plans the product, builds it in sprints, and checks every sprint with independent agents, enforced by hooks so the builder cannot grade its own work.
What it does
- Plan. A planner asks a few focused questions, writes a product spec with a design direction, and produces a feature list. Each feature has concrete user scenarios, including at least one tagged
[错误]/[error]or[边界]/[edge]case. - Confirm once. You approve the feature list. From then on the scope is frozen and recorded with a hash.
- Build in sprints. Each sprint goes through generate → evaluate → product acceptance. A sprint passes only when both graders pass it. A sprint gets up to 3 cycles; after that the orchestrator asks you what to do.
The roles never overlap:
| Role | Writes | Does not |
|---|---|---|
| Planner | CLAUDE.md, .web-builder/spec.md, feature_list.json (once) | write product code |
| Generator | product code, tests/ | touch .web-builder/, change pass status |
| Evaluator | .web-builder/evidence/, its verdict | edit code, score visual taste |
| Product acceptance (PA) | its verdict only | run the app, edit any file |
Install
Requires Python 3 on your PATH (python3). The scripts use only the standard library.
In Claude Code:
/plugin marketplace add coldingcode/web-builder-harness
/plugin install web-builder@web-builder-harness
Then, in an empty folder (or an existing repo), start a run:
/web-builder a pomodoro timer web app with a task list
Check progress at any time with /web-builder status, and resume an interrupted run with /web-builder resume.
Gates
Hooks in web-builder/hooks/hooks.json run web-builder/scripts/hooks.py. Blocking uses exit code 2, as the Claude Code hook protocol requires.
- State is script-owned.
state.json,plan_confirmed.jsonandfeature_list.jsoncannot be written with Write, Edit or shell redirection. Onlyharness.pychanges them. - Confirmation freezes scope. After
confirm-plan, the feature list cannot be rewritten. The scope hash ignores pass status, so marking a sprint does not invalidate it. - Verdicts come only from graders. The evaluator and PA are the only agents that can write verdict files, and the file must match the current sprint and cycle.
- Sprints pass only on evidence.
mark-sprintrequires an evaluatorPASS, a PA score of at least 80 with no P0 issues, and an evidence bundle for that cycle containingreport.mdplus at least one result file or screenshot. - Planning comes before code. Product code cannot be written until the feature list is confirmed.
- Commits follow Conventional Commits, for example
feat(F-001): add todo persistence. - Stop gate. While a sprint is unfinished, the orchestrator cannot end its turn. If a block produces no change at all (no new commit, no working-tree edit, no verdict), the gate releases so the run cannot loop forever. When the cycle budget is spent, the turn may end so you can be asked.
- Test data stays in tests. Files named like
*_mock.*,*.seed.*or*.fake.*are refused outsidetests/. - The orchestrator writes no project files during a run. Product code comes from the generator and planning files from the planner.
- Config is locked.
.claude/settings*.jsonand.claude/hooks/cannot be changed by Write, Edit or shell redirection.
The hooks do nothing outside a Web Builder project (a folder with .web-builder/state.json), so installing the plugin does not affect your other repositories.
Project layout
After a run, your project contains:
.web-builder/
state.json run state (harness.py)
spec.md product spec and design direction (planner)
feature_list.json features and sprints (planner, frozen after confirmation)
plan_confirmed.json confirmation record with scope hash
verdicts/ sprint-N-evaluator.json, sprint-N-pa.json
evidence/sprint-N/cycle-C/ report.md, results, screenshots
CLAUDE.md conventions and commands for the chosen stack (planner)
.claude/rules/web-builder.md project rules loaded by Claude Code
tests/e2e/ persisted Playwright tests, one folder per sprint
Repository layout
.claude-plugin/marketplace.json marketplace manifest
web-builder/
.claude-plugin/plugin.json
agents/ planner, generator, evaluator, pa
commands/web-builder.md the /web-builder orchestration
hooks/hooks.json
scripts/harness.py state machine and control CLI
scripts/hooks.py hook dispatcher
skills/ shared reference and PA checklists
project-template/ copied into each project on init
tests/test_harness.py unit and integration tests
docs/history/ archived v8 design and self-review
Development
The test suite uses only the standard library:
python3 -m unittest discover -s tests -v
It covers the state machine, the cycle budget and extensions, the commit-message and write gates, verdict validation, the Stop gate's release rule, the prompt check, and repository hygiene (manifest versions, hook script paths, no placeholder names).
Limitations
- The README is in English and Chinese. The generated app's language follows your request.
- Scope is frozen after confirmation. To change scope, start a new run in a new folder.
- The evaluator and PA run in the same local environment as the generator, so they are independent by context, not by machine.
- The plugin ships no permission allowlist, so Claude Code asks you to confirm file writes and shell commands. The hooks only block operations; they never pre-approve one.
License
Community
// faq
What is web-builder-harness?
A Claude Code plugin that turns a one-sentence idea into a small, verified web app. It is open-source on GitHub.
Is web-builder-harness free to use?
web-builder-harness is open-source under the AGPL-3.0 license, so it is free to use.
What category does web-builder-harness belong to?
web-builder-harness is listed under plugins in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/web-builder-harness)
// retro hit counter
[](https://claudeers.com/web-builder-harness)
// reviews
// guestbook
// related in Claude Plugins
A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explainin…
"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
financial-services — a Claude ecosystem project on GitHub.