builder

builder is a plugin for coding agents. Your agent ends each piece of work with a builder report. The report names who the work is for, each call the agent made alone, and the test run that proves the work. Nothing leaves this machine without a send rule or your yes.

builder is the soul behind that report. You decide. The agent proposes, builds inside the repository, and reports. Correct is not enough: the work must fit one person at one moment. So each piece of work starts from that person and the non-goals. Each call the agent makes alone carries its reason. The evidence is a test run from the session. The last line says what left the machine.

Example, invented for illustration:

For:       a customer who moved — at checkout. Now they can change their email in one step.
Non-goals: no change to the login flow.
Calls:
  - The old address gets a notice — because a stolen account changes the email first.
Evidence:  python3 -m unittest → 14 passed (example).
Outside:   nothing sent.

Install

builder installs on four harnesses. Pick yours. builder needs Python 3 and Bash, on macOS or Linux. Its session hook makes no network call and finishes in under one second.

Claude Code

/plugin marketplace add Lutherwaves/builder
/plugin install builder@builder

In Claude Code, call a skill as /builder:shape.

Codex CLI

codex plugin marketplace add Lutherwaves/builder
codex plugin add builder@builder

Codex runs a plugin's hooks only after you trust them. builder does not work around this step. Until you trust the hook, the builder skill still loads by name. Until Codex detection lands (issue #17), builder's session start on Codex uses the Claude Code step list and mapping. The marketplace add was proven with a local path. The Lutherwaves/builder form is the git form that Codex documents.

Cursor CLI

A Cursor CLI plugin install is not verified. This manual path works. In your project, create .cursor/hooks.json:

{"version":1,"hooks":{"sessionStart":[{"command":"<path to builder>/hooks/session-start --harness cursor"}]}}

<path to builder> must be an absolute path.

Keep only these keys. One invalid key disables every hook in the file. Then copy builder's skill folders into .agents/skills/ in the same project.

A Cursor plugin install (.cursor-plugin/plugin.json) also exists for the editor's plugin flow. This README does not claim that the CLI installs it.

As a fallback, add one line to your project's AGENTS.md. Cursor CLI reads that file. builder never writes AGENTS.md itself.

Use the builder skill for the soul of this work: for whom, what it is not, each call with its reason, proof, and what left the machine.

opencode

Add builder to the plugin list in opencode.json. Use opencode 1.19 or newer: version 1.1.x crashes on plugins with non-function exports. A local checkout works:

{"plugin": ["/path/to/builder"]}

opencode also takes a git form, as superpowers documents: "plugin": ["builder@git+https://github.com/Lutherwaves/builder.git"]. Only the local path was proven, with opencode debug skill: the skills load. No live opencode session has run builder yet.

Harness support

A harness is listed as supported only after every eval fixture passes on it.

Harness	Version	Eval date	Status
Claude Code	2.1.308 (Claude Code)	2026-10-22	experimental: canon 5/6; fleet 3/4; harness 4/6; reach 3/4; shape 2/6; 3 not graded

What happens in your first session

1. You ask for your work as usual. builder adds its thirteen tenets to the session, and the agent does your work first.
2. At the end of that reply, the agent introduces builder in at most three short lines. This happens even after a one-line request.
3. The agent offers one setup step and asks: yes, not now, or never.
4. Each later reply offers the next step, one at a time: superpowers, gstack, a signed-in gh, signed commits, and the channel where your team talks (for messages to teammates; notes to you go by notification). A step you already did is skipped.
5. "Not now" stays quiet for 7 days. "Never" stays quiet for good.
6. When you answer every step, onboarding ends.

After that, a session shows at most one recommendation, and only when a signal fires. Examples: you run three or more sessions, your weekly usage reaches 80%, or no code graph is set up. The first two signals need matchblox. builder keeps your answers in ~/.config/builder/ledger.json. Set BUILDER_HOME to move it.

The nine skills

Skill	What you get
builder	The soul: thirteen tenets, a routing table to superpowers and gstack, and the builder report at the end of each piece of work.
shape	A feature name becomes an issue: the person, the moment, anti-goals, and each open question with a recommendation.
canon	A repository rule carries its incident and a check that fails when someone breaks it.
reach	By default, a message to a teammate waits for your yes. Every send passes a duplicate check and a limit of 6 sends per hour.
fleet	Many sessions work side by side, one lane each. Work outside a lane goes to its owner as a brief.
intake	The day's captured tasks are reconciled against work in motion. Nothing becomes an issue without your marker or your yes.
budget	A forecast of the weekly usage limit, and one idle session to compact. Where the harness has no usage reading, it says so.
harness	A local code graph answers "what calls this?" in one query, and a watcher names stale graphs.
review	A review proves how a change hurts a person: what it ran, each harm with its evidence, fix and test, and a verdict. Nothing is posted without your yes.

Call a skill by name, for example the shape skill. The agent also loads a skill when its job comes up.

Works with

builder runs on its own. If a partner is missing, builder uses a fallback and says so once.

• superpowers: planning, test-driven development and review. builder routes to these skills.
• gstack: a real browser, QA, security checks and ship workflows.
• gh: intake checks open pull requests and issues through it.
• matchblox: budget reads the plan windows from it, and fleet reads the live sessions. Run matchblox setup to add its hooks (docs).
• Your channel's MCP server: reach sends through it. For Slack, use a Slack connector or Slack's official MCP server.
• codebase-memory-mcp: harness provisions it. It runs locally and needs no API key.

Compare with your own setup

tests/evals/parity.sh runs two fixtures twice: once with your setup, and once with builder and its recommendations only. The builder run accepts every recommendation. It prints both transcripts next to the expected behaviour, so you can compare them. It runs the agent four times, so it uses tokens from your plan. parity.sh works on Claude Code only. See tests/evals/README.md.

Standalone use of the budget forecast

skills/budget/burn-proj.py works without the plugin:

python3 burn-proj.py <used_pct> <resets_at_epoch> [now_epoch]
python3 burn-proj.py --from-matchblox [now_epoch]

python3 burn-proj.py 19 1783504800 1782990571
# elapsed=15.0%  naive=127%  profile_aware=100%  reset_in=5.95d

--from-matchblox needs matchblox on your PATH. Without it, read your agent's usage view and pass the numbers by hand.

• naive draws a straight line from the use so far. It is the worst case.
• profile_aware discounts the hours you do not work: 02:00 to 09:00, and the weekend. Tune them in mult().

Contributing

Every change lands through a pull request, and the validate check must pass. Run the same check before you push:

bash scripts/validate.sh

See CONTRIBUTING.md for the rules, and SECURITY.md to report a vulnerability.

License

MIT.

The harness skill derives its framing from Ryan Lopopolo's Harness Engineering, licensed CC BY 4.0. builder adapts the concepts and copies no source prose.