[Lutherwaves]

What this is

builder 1.0 is one plugin that gives a coding agent the habits of a seasoned builder. It starts from the person, records each decision with its reason, proves the work, and writes nothing outside the machine without a send rule or the person's yes.

It runs on Claude Code, Codex CLI, Cursor CLI and opencode from one core. It sits on top of superpowers, gstack, gh and MCPs, and does not replace them.

What changes

• The soul at every session start. A shared hook prints the 13 tenets, the builder report and the commit rules. Each harness gets the output shape it reads: Claude Code and Codex get hookSpecificOutput, Cursor gets additional_context, and opencode gets plain text through its plugin.
• Agent-led setup. The person installs the plugin and the agent leads the rest: one recommendation at a time, answered yes, not now or never. One local ledger in ~/.config/builder serves every harness. Each step is offered only on a harness where it works, with that harness's own command.
• Eight skills: builder, shape, canon, reach, fleet, intake, budget, harness. Skill bodies name actions, not tools. One mapping file per harness (skills/builder/harnesses/<harness>.md) maps each action to that harness's tool, or says what to do where it has none.
• One adapter per harness: .claude-plugin, .codex-plugin plus .agents/plugins/marketplace.json, .cursor-plugin plus hooks/hooks-cursor.json, and package.json with .opencode/plugins/builder.js (no dependencies).
• lib/harness.py names the harness and its paths. No ~/.claude literal is left in the signals. builder state that sat under ~/.claude moves to $BUILDER_HOME; builder still reads the old place and never deletes it.
• Guards:
  • the deny-list scrub;
  • a Conventional Commits check on every commit subject and PR title;
  • skill shape checks;
  • a grep guard that keeps harness tool names and slash commands out of skill bodies;
  • manifests that must agree on name, version and description;
  • a Cursor hook file that must hold no unknown key.
• Evals per harness. tests/evals/run.sh --harness <h> runs each fixture through that harness's headless runner. The README support table is rendered from graded results, never by hand.

Verification

• 149 unit tests, 11 opencode adapter tests, and the hook, drift, state-path, eval-runner and validate shell suites pass. The scrub is clean.
• The hook runs in about 0.1 s on each harness, with no network call.
• All 67 commits are Conventional Commits and SSH-signed. The commit messages have no deny-list hits.
• Claude Code evals (2026-10-22): with builder, the runs met 32 of 41 bullets; without it, 7. Claude Code auto-updated during the batch, and the recorder keeps one version, so the README shows experimental on 2.1.308 with 2 fixtures not graded. The full table and the misses are in test: run builder's evals on Codex, Cursor and opencode, and fill the support table #17.
• Free load checks, no model call:
  • Codex installs builder from a local marketplace and lists its 8 skills as builder:<name>.
  • opencode 1.19.3 loads the 8 skills through the plugin.
  • Cursor 2026.10.19 fires sessionStart from a project .cursor/hooks.json (an earlier live check).
• Not run yet (test: run builder's evals on Codex, Cursor and opencode, and fill the support table #17): the Codex, Cursor and opencode evals, and parity.sh. Until test: run builder's evals on Codex, Cursor and opencode, and fill the support table #17 adds Codex detection, Codex gets the Claude Code step list and mapping. The README states both points.

Release

ef049ac carries Release-As: 1.0.0. When you squash-merge, keep the line Release-As: 1.0.0 in the commit body, or release-please cuts 0.2.0. release-please now bumps the version in every manifest and in package.json.

Design: builder on any harness

builder for any agent harness — design (2026-10-21)

Extends the builder 2 design (summarised at the top of this PR). Everything there still holds unless this document says otherwise. This work lands in the same PR (#16), so the first public release (1.0.0) is generic from day one (owner ruling, 2026-10-21).

Intent

matchblox runs Claude Code, Codex and opencode sessions side by side, and teammates use Cursor too. builder is the habits layer on top, so it cannot be tied to one harness. Its model is obra/superpowers: one source of skills, a thin adapter per harness, and installation through each harness's own mechanism. A colleague on Codex, Cursor CLI or opencode installs builder and gets the same soul, the same onboarding, the same skills and the same safety rules as a Claude Code user.

Owner's words: "this builder must be a generic plugin, like obra/superpowers is"; "can we tweak it so it works for cursor-cli (cursor-agent) and codex equally well". opencode is added because matchblox supports it.

Goals

1. Four harnesses, one core: Claude Code, OpenAI Codex CLI, Cursor CLI (cursor-agent / agent) and opencode. skills/, lib/ and the soul are shared and are not forked per harness.
2. Native install: each harness installs builder through its own plugin or extension mechanism. builder never edits a harness's config to install itself.
3. The soul at every session start: each harness gets the soul and onboarding at session start, either through its hook or, where it has no hook, through the closest substitute.
4. Same results: the same eval fixtures pass on each supported harness.
5. Honest support claims: the README lists a harness as supported only after its evals pass. Each row has the harness version and the eval date.
6. A neutral front door: the README, plugin descriptions and skill prose name no single harness, except in the per-harness install and adapter sections.

Non-goals

• Gemini CLI, Pi, Kimi, Copilot CLI, Hermes and others. The layout must make a later port cheap, but this release does not ship them.
• Features that exist only in one harness. They are not rebuilt for the others. A Claude-only feature stays Claude-only, and the skill says "where your harness has it".
• A builder-owned subagent or messaging system. Peer messaging stays with reach and matchblox.

Anti-goals (failure even if it "works")

• A skill body that names one harness's tool (PushNotification, SendMessage, AskUserQuestion) as the only way to do something.
• A support claim for a harness with no passing eval.
• builder writing into ~/.codex, ~/.cursor, ~/.config/opencode or ~/.claude config to install or enable itself.
• Four diverging copies of the hook logic.
• A Claude Code user who gets a worse result than today. The 1.0 behaviour on Claude Code must not regress: all current tests and evals stay green.

Constraints

• All global constraints of the builder-2 design and plan still bind. In short:
  • The repo is public and names no employer.
  • No design files go in the repo.
  • Bash and the Python 3 stdlib, on macOS and Linux.
  • The hook runs in under 1 s and makes no network calls.
  • Every commit is a signed Conventional Commit.
  • Writing is ASD-STE100.
  • Nothing goes outside the machine without a send rule or a yes.
• The opencode adapter is JavaScript, because opencode plugins are JS/TS modules. Keep it minimal, with no dependencies, and have it call the shared Python where it can.
• Each harness's headless runner, used for evals: claude -p, codex exec, agent -p and opencode run.

Facts the design rests on (research, 2026-10-21; see "Verify first")

	Skills found in	Plugin manifest	Session start	Headless	Config dir override	MCP config
Claude Code	plugin skills/	.claude-plugin/plugin.json + marketplace.json	SessionStart hook → hookSpecificOutput.additionalContext	claude -p	CLAUDE_CONFIG_DIR	.mcp.json, ~/.claude.json
Codex CLI 0.163	plugin skills/, .agents/skills, ~/.agents/skills	plugin.json / .codex-plugin/plugin.json + .agents/plugins/marketplace.json; codex plugin marketplace add owner/repo	SessionStart in plugin hooks/hooks.json, same JSON as Claude (sets CLAUDE_PLUGIN_ROOT for compatibility); plugin hooks run only after the user trusts them	codex exec	CODEX_HOME	config.toml [mcp_servers]
Cursor CLI 2026.10	plugin skills/, .agents/skills, .cursor/skills	.cursor-plugin/plugin.json (+ hooks path)	sessionStart → {"additional_context": …} (CLI support unverified: forum reports say the CLI fires only shell hooks)	agent -p (--force to write)	CURSOR_CONFIG_DIR	.cursor/mcp.json, ~/.cursor/mcp.json
opencode	.opencode/skills, .agents/skills, .claude/skills	JS module via plugin in opencode.json (git or npm)	no hook; the plugin injects context (superpowers uses a context or message transform)	opencode run	OPENCODE_CONFIG_DIR	opencode.json mcp

superpowers 7.0.0 does all four this way:

• one skills/;
• per-harness manifest dirs;
• one shared hooks/session-start that picks the JSON shape from an env var (CURSOR_PLUGIN_ROOT → additional_context; CLAUDE_PLUGIN_ROOT → hookSpecificOutput);
• .opencode/plugins/superpowers.js for opencode;
• tool mapping in references/<harness>-tools.md.

The how (decided)

1. Layout

skills/                      shared, unchanged structure
lib/                         shared; adds lib/harness.py
hooks/session_start.py       shared logic; output shape chosen per harness
hooks/session-start          shared shell entry
hooks/hooks.json             Claude Code + Codex (same schema)
hooks/hooks-cursor.json      Cursor (version 1, camelCase sessionStart)
.claude-plugin/              plugin.json, marketplace.json
.codex-plugin/plugin.json    skills + hooks paths
.agents/plugins/marketplace.json   Codex marketplace entry
.cursor-plugin/plugin.json   skills + hooks paths
.opencode/plugins/builder.js opencode adapter
package.json, index.js       opencode entry (main), no dependencies
skills/builder/harnesses/<harness>.md   action → tool mapping, one per harness

2. Harness detection: lib/harness.py

detect(env) -> "claude" | "codex" | "cursor" | "opencode" | "unknown":

• The env markers each harness sets, checked in a fixed order.
• An explicit BUILDER_HARNESS overrides detection.
• Codex sets CLAUDE_PLUGIN_ROOT too, so Codex is checked before Claude, on a Codex-only marker.
• The exact markers are fixed during implementation by reading each harness's real environment; see "Verify first".

paths(harness, env) -> dict gives:

• the config dir (honouring each harness's override variable);
• the user skills dirs;
• the MCP config files and the key where servers live;
• where installed plugins are recorded;
• the session process name.

lib/signals.py takes all paths from harness.paths. No ~/.claude literal remains outside harness.py.

3. Session start: one logic, four shapes

session_start.py builds the same text on every harness: the soul, the onboarding or one recommendation, and the mapping file for the detected harness, appended in at most 15 lines. It prints:

Harness	Output
claude, codex	{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":…}}
cursor	{"additional_context": …}
opencode	plain text on stdout (--format text), read by builder.js

builder.js runs python3 hooks/session_start.py --format text once per top-level session. It injects the result the way superpowers' opencode plugin does, and skips child (subagent) sessions. If python3 is missing, it injects soul-compact.md alone.

Cursor CLI fallback. The Cursor CLI may not fire sessionStart. In that case, builder tells the person in its README Cursor section to add one line to the project's AGENTS.md (Cursor CLI reads AGENTS.md). The line points at the builder skill. The builder skill's description also carries the trigger, so skill discovery can load it. builder does not write AGENTS.md itself. The canon skill may offer to write it, with a yes, as it already does for agent files.

4. Skills name actions, not tools

• Skill bodies say what to do: "send the person a notification", "start a subagent", "ask the person to choose", "schedule a check every 30 minutes".
• skills/builder/harnesses/<harness>.md maps each action to the harness's tool, or to "not available: do X instead".
• The current Claude-specific lines move into claude.md: PushNotification, /usage, the artifact page, /loop, the cron tools, and the claude.ai Slack connector.
• Skill invocation syntax is written neutrally: "the shape skill", not /builder:shape. Each mapping file gives the harness's own syntax.

5. Recommendations per harness

• In lib/recommendations.json, how may be a string (the same on every harness) or a map {claude, codex, cursor, opencode}.
• An item is offered only on a harness that has an entry for it, or a string how.
• An item can also carry harnesses: [...]. Examples:
  • superpowers: a per-harness install command; each comes from superpowers' own README.
  • gstack: offered only where gstack documents support. The supported harnesses are checked during implementation.
  • autocompact: Claude only.
  • matchblox-setup: claude, codex and opencode, which matchblox supports. Cursor is included only if matchblox setup covers it.
  • code-graph: on every harness, with the per-harness MCP config.
  • signing, gh, channel, fleet, canon: the same on all harnesses.

6. State outside any harness dir

• builder state that now sits under ~/.claude moves under $BUILDER_HOME (default ~/.config/builder). This covers the intake config, seen.txt, and the code-graph repos.txt.
• builder reads the old path once if the new one is missing, so it migrates by reading, never by deleting.
• The ledger is already in ~/.config/builder. One ledger serves all harnesses on a machine: a step answered in one harness is answered everywhere.

7. Notifications, usage and sessions

• Note to the person. The route is:
  1. matchblox notify, when present;
  2. the harness's own notification, per the mapping (Claude Code PushNotification; Codex and Cursor have no push tool, so skip);
  3. an OS notification (reach.py notify).
     The code does not change; only the skill wording does.
• budget.
  • The percentage of the weekly limit comes from matchblox usage, which covers each account matchblox knows.
  • Without matchblox, the manual path is per harness: Claude Code /usage, and Codex /status (to verify).
  • Where neither path exists, budget says so and stops. It never invents a number.
• Session count (the fleet trigger). It comes from matchblox sessions when present. Otherwise builder counts the session processes of all four harnesses.

8. Evals per harness

• tests/evals/run.sh --harness <h> runs the existing fixtures with that harness's headless runner, with builder installed from the working copy.
• Per-harness runner notes:
  • Claude Code: --plugin-dir, as today.
  • Codex: a local marketplace dir, or a dev plugin path. The exact method is fixed in implementation.
  • Cursor: --force, with the plugin dir.
  • opencode: a local plugin path in an isolated OPENCODE_CONFIG_DIR.
• The allow and deny rules translate per harness. Where a harness cannot deny a tool, the runner uses PATH shims, as it already does for matchblox and tmux, and the README says which guard is weaker.
• expect.md stays the same for all harnesses; the grading bar does not change.
• parity.sh stays Claude Code only. Ruling 4 was about the owner's current setup, which is Claude Code.
• The README support table is written from eval results, never by hand.

9. Release and validation

• scripts/validate.sh checks:
  • every manifest: it parses, and it has the same name, version and description;
  • hooks-cursor.json;
  • package.json;
  • that no skill body names a harness tool outside skills/builder/harnesses/. This is a grep guard, with a list of tool names.
• release-please bumps the version in every manifest (extra-files).
• One description is used everywhere (my call, pending the owner's taste): "Builder habits for coding agents: guided setup, decisions with reasons, proof before done, and nothing sent without your yes."
• Keywords add codex, cursor, opencode and agent-skills.

10. Docs

• README:
  • one soul paragraph;
  • install, with one short block per harness;
  • the support table;
  • "what happens in your first session", which is the same on every harness;
  • the skills.
• AGENTS.md and CONTRIBUTING.md: how to add a harness. This means a manifest, a mapping file, detection, an eval runner, and the support table.
• SECURITY.md: the scope covers every adapter and every harness state dir that builder reads.

Verify first (before building on them)

1. Cursor CLI sessionStart: does cursor-agent fire it from a plugin, from .cursor/hooks.json, or not at all? Test it on this machine.
2. Codex:
   • the plugin install path for a local working copy;
   • whether plugin hooks/hooks.json with SessionStart runs after trust;
   • the env markers for detection.
3. Cursor CLI:
   • does it load plugin skills and .agents/skills?
   • can a plugin be installed from the CLI, or only in the editor UI?
4. opencode: the current plugin API for context injection, V1 or V2. Copy superpowers' working approach. opencode is not installed here, so testing needs the owner's yes to install it.
5. The env vars each harness sets for hook processes, needed for detection.
6. gstack and superpowers: the install command each documents for each harness.

Each finding goes in the ledger, as a ruling if it changes this design.

Left to the builder

• Exact detection markers, runner flags and mapping-file wording.
• How to split work into tasks.
• Whether index.js re-exports .opencode/plugins/builder.js or the reverse.
• Test structure, as long as every new branch in harness.py, session_start.py and signals.py has a unit test, and each adapter has a smoke test that runs without the harness installed.

Verified on this machine (2026-10-21)

• Cursor CLI (2026.10.19) fires sessionStart from the project's .cursor/hooks.json ({"version":1,"hooks":{"sessionStart":[{"command":…}]}}), and it honours {"additional_context": …}. In a cursor-agent -p run the model repeated a word that only the hook had given it. The forum reports are out of date for this version.
• The hook environment inherits the parent's variables. A Cursor hook launched from a Claude Code session also sees CLAUDECODE, CLAUDE_PROJECT_DIR and other CLAUDE* variables. Cursor adds CURSOR_VERSION, CURSOR_PROJECT_DIR and CURSOR_INVOKED_AS.
  • Ruling: env vars alone cannot detect the harness. Each harness's hook config passes it explicitly (session-start --harness cursor, and so on). Env detection is only a fallback, and it checks the innermost harness marker first.
• Codex CLI 0.163 is not signed in on this machine. codex exec returns 401, so the hook test needs the owner to run codex login.

Calls made after the builder check (mine; the owner can overturn)

1. "Passes"
   • The eval runner also writes a machine-readable verdict per fixture.
   • An agent grader (the controller, in an SDD run) marks each expect.md bullet as met or not met, quoting the transcript.
   • tests/evals/results/<harness>.json holds these verdicts: harness, harness version, date, fixture, bullets met out of total. It holds no transcripts and no local paths.
   • A harness is "supported" when every fixture meets every bullet in the with-builder run.
   • The README table is built from these files by a script, and validate.sh checks that the table matches them.
2. Partial support
   • A harness whose session-start path works but whose install is not native can still ship. Its README block states the exact manual step.
   • A harness whose evals do not pass ships as "experimental" in the table, with the reason.
   • A harness whose adapter cannot load the soul at all is left out of 1.0. The PR does not wait on it.
3. Regression rule
   • Behaviour must hold on Claude Code. Tests may change only where a path moves (~/.claude/intake → $BUILDER_HOME/intake, with a fallback that reads the old path).
   • The Claude evals and parity stay green.
4. Detection on other harnesses
   • When a harness gives builder no way to see an install (a plugin, gstack or an MCP server), the signal is None (unknown), not false.
   • An onboarding item with an unknown signal is offered once. The ledger keeps the answer, so it never nags.
   • A just-in-time item with an unknown signal is not offered.
5. The grep guard
   • The guard lists harness tool names only: PushNotification, SendMessage, AskUserQuestion, TodoWrite, ScheduleWakeup, CronCreate, CronDelete, Monitor, Artifact, WebFetch, apply_patch and update_plan. The list grows as the mapping files grow.
   • External CLIs and products (gh, tmux, matchblox, git, Slack, Todoist) are allowed in skill bodies.
   • Slash commands such as /loop and /usage count as harness features. They move to the mapping files.
6. The Codex trust step
   • It is part of Codex's own security model, so builder documents it in the Codex install block and does not work around it.
   • The builder skill description keeps its trigger, so skill discovery still loads the soul before trust.
   • The soul is re-injected on start, clear and compact wherever the harness has those events.
7. Mapping in the hook
   • The hook injects a short form of the mapping file: at most 15 lines, enforced by a test.
   • The full file is a normal skill reference, read on demand.
8. Unverified support
   • When support for gstack or matchblox setup on a harness cannot be verified, that harness is left out of the item.
   • Each fact added later carries its source URL in a comment in the recommendations file, or in the ledger.

🤖 Generated with Claude Code