feat!: the first stage is spec, and the five stages chain by themselves

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "builder",
-  "description": "A framework for coding agents: shape, plan, build, review and ship, with security in every stage and nothing sent without your yes.",
+  "description": "A framework for coding agents: spec, plan, build, review and ship, with security in every stage and nothing sent without your yes.",
   "version": "3.0.0",
   "author": {
     "name": "Lutherwaves"
@@ -11,21 +11,16 @@
   "keywords": [
     "claude-code",
     "soul",
-    "onboarding",
-    "shaping",
+    "specs",
     "planning",
     "tdd",
     "shipping",
     "rulings",
-    "peer-messaging",
-    "fleet",
-    "usage-budget",
-    "harness",
-    "code-graph",
     "code-review",
     "security-review",
     "codex",
     "cursor",
+    "grok",
     "opencode",
     "agent-skills"
   ]

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "builder",
   "version": "3.0.0",
-  "description": "A framework for coding agents: shape, plan, build, review and ship, with security in every stage and nothing sent without your yes.",
+  "description": "A framework for coding agents: spec, plan, build, review and ship, with security in every stage and nothing sent without your yes.",
   "author": {
     "name": "Lutherwaves"
   },
@@ -11,26 +11,21 @@
   "keywords": [
     "claude-code",
     "soul",
-    "onboarding",
-    "shaping",
+    "specs",
     "planning",
     "tdd",
     "shipping",
     "rulings",
-    "peer-messaging",
-    "fleet",
-    "usage-budget",
-    "harness",
-    "code-graph",
     "codex",
     "cursor",
+    "grok",
     "opencode",
     "agent-skills"
   ],
   "skills": "./skills/",
   "interface": {
     "displayName": "builder",
-    "shortDescription": "Shape, plan, build, review and ship, with security in every stage",
+    "shortDescription": "Spec, plan, build, review and ship, with security in every stage",
     "developerName": "Lutherwaves",
     "category": "Developer Tools",
     "capabilities": [

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "builder",
   "displayName": "builder",
   "version": "3.0.0",
-  "description": "A framework for coding agents: shape, plan, build, review and ship, with security in every stage and nothing sent without your yes.",
+  "description": "A framework for coding agents: spec, plan, build, review and ship, with security in every stage and nothing sent without your yes.",
   "author": {
     "name": "Lutherwaves"
   },
@@ -12,19 +12,14 @@
   "keywords": [
     "claude-code",
     "soul",
-    "onboarding",
-    "shaping",
+    "specs",
     "planning",
     "tdd",
     "shipping",
     "rulings",
-    "peer-messaging",
-    "fleet",
-    "usage-budget",
-    "harness",
-    "code-graph",
     "codex",
     "cursor",
+    "grok",
     "opencode",
     "agent-skills"
   ],

.github/ISSUE_TEMPLATE/bug_report.md

@@ -19,5 +19,4 @@ labels: bug
 
 - OS:
 - Claude Code version:
-- `matchblox` present? (`command -v matchblox`)
 - `bash scripts/validate.sh` result:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -11,7 +11,7 @@ labels: enhancement
 
 ## Proposed solution
 
-<!-- New skill? New watcher section? A tweak to the projection? -->
+<!-- New skill? A change to a stage? -->
 
 ## Alternatives considered
 

AGENTS.md

@@ -1,6 +1,6 @@
 # builder — agent guide
 
-builder is a plugin for coding agents: thirteen skills, one session-start hook, and one Go binary, `builder`. The skills and the hook run it through `bin/builder`. builder has adapters for Claude Code, Codex CLI, Cursor CLI and opencode.
+builder is a plugin for coding agents: eight skills, one session-start hook, and one Go binary, `builder`. The skills and the hook run it through `bin/builder`. builder has adapters for Claude Code, Codex CLI, Cursor CLI, Grok Build and opencode.
 This guide routes an agent that works on builder itself.
 
 ## Where each change goes
@@ -12,19 +12,20 @@ This guide routes an agent that works on builder itself.
 | The build stage | `skills/build/SKILL.md` and its eval fixture `tests/evals/build/` | `bash tests/evals/run.sh --check`, then `bash tests/evals/run.sh build` |
 | The ship stage | `skills/ship/SKILL.md` and its eval fixture `tests/evals/ship/` | `bash tests/evals/run.sh --check`, then `bash tests/evals/run.sh ship` |
 | The engineering and design lenses of a plan review | `skills/plan/lenses.md` | `bash tests/evals/run.sh plan` |
+| The architecture lens of a plan review (API contract, boundaries, more than one customer, tools for agents) | `skills/plan/architecture.md` | `go test ./tests/ -run Architecture` |
+| The bar a review finding must pass, and the last sweep | `skills/review/bar.md` | `bash tests/evals/run.sh review-noise` |
+| How build answers review comments | `skills/build/comments.md` | `bash tests/evals/run.sh review-comments` |
+| What build removes from its own diff, and what review lists as slop | `skills/build/deslop.md` | `go test ./tests/ -run Slop` |
+| How a failure with no known cause is found and fixed | `skills/debug/SKILL.md` and its eval fixture `tests/evals/debug/` | `bash tests/evals/run.sh --check`, then `bash tests/evals/run.sh debug` |
 | The security pass of a review | `skills/review/security-pass.md` | `bash tests/evals/run.sh review-security` |
 | A domain checklist of an audit (AI, cloud, client, desktop and mobile, protocol) | `skills/security/domains.md` | `bash tests/evals/run.sh security-audit` |
+| How the stages chain (who loads whom, the plan header, the review path) | the handoff lines of each `skills/<stage>/SKILL.md` and `skills/builder/soul-compact.md` | `go test ./tests/ -run 'Stage|Soul|Handoff'` |
 | The soul the hook injects | `skills/builder/soul-compact.md` (keep it in step with `skills/builder/SKILL.md`) | `bash tests/test_hook.sh` |
 | The SessionStart hook | `hooks/session-start`, `internal/hook` | `bash tests/test_hook.sh`, `go test ./internal/hook/` |
-| A recommendation or its signal | `lib/recommendations.json`, `internal/signals`, `internal/ledger` | `go test ./internal/signals/ ./internal/ledger/` |
 | The security score, CWE checks and audit baseline | `internal/security`, `skills/security/standards.md` | `go test ./internal/security/` |
-| A send rule for `reach` | `internal/reach`, `skills/reach/rules.default.json` | `go test ./internal/reach/` |
-| The budget forecast | `internal/budget` | `go test ./internal/budget/` |
-| The graph drift check | `skills/harness/drift.sh` | `bash tests/test_drift.sh` |
-| An issue or rule template | `skills/shape/issue-template.md`, `skills/canon/rule-template.md` | `go test ./tests/` |
-| The parity eval | `tests/evals/parity.sh`, `tests/evals/lib.sh`, `cmd/parity-config` | `bash tests/evals/parity.sh --dry-run`, `go test ./cmd/parity-config/` |
-| Which harness runs builder, and where it keeps its files | `internal/harness` | `go test ./internal/harness/` |
-| What an action means on one harness (ask, schedule, usage, compact) | `skills/builder/harnesses/<harness>.md` | `bash scripts/validate.sh` |
+| The issue template | `skills/spec/issue-template.md` | `go test ./tests/` |
+| Which harness runs builder, and where builder keeps its files | `internal/harness` | `go test ./internal/harness/` |
+| What an action means on one harness (ask, subagent, browser, compact) | `skills/builder/harnesses/<harness>.md` | `bash scripts/validate.sh` |
 | The manifests | `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `.cursor-plugin/plugin.json`, `package.json` (description and keywords only; `version` stays equal in all four) | `bash scripts/validate.sh` |
 | The opencode adapter | `.opencode/plugins/builder.js` | `node --test tests/test_opencode.mjs` |
 | The support table in the README | `cmd/support-table` (never edit the block by hand) | `go test ./cmd/support-table/` |
@@ -41,22 +42,19 @@ Before every commit, run `bash scripts/validate.sh`. It runs all of the checks a
 - Write in ASD-STE100: active voice, present tense, one idea per sentence, short sentences.
 - A skill change starts with an eval: run the fixture without the skill, watch it fail, then write the skill.
 - The hook uses Bash and the `builder` binary only. It makes no network call and finishes in under one second.
-- Nothing writes outside the local machine without a send rule or the person's yes.
+- Nothing writes outside the local machine without the person's yes.
 - The repository is public. Keep employer, client, product and private repository names out of files, commits and pull requests.
 - Never commit an eval transcript. Transcripts live outside the repository.
 - Commits follow Conventional Commits and are signed. See [CONTRIBUTING.md](CONTRIBUTING.md).
 - Write your change under `## [Unreleased]` in `CHANGELOG.md`. Never edit a released section or a manifest `version`: the release bot owns both.
 
 ## Attribution
 
-The `harness` skill derives its framing from Ryan Lopopolo's **Harness Engineering** corpus
-(<https://github.com/lopopolo/harness-engineering>), licensed CC BY 4.0.
-builder adapts its vocabulary and applies its improve-harness loop. It copies no prose.
+builder takes ideas, and no text, from four MIT-licensed projects:
 
-builder takes ideas, and no text, from three MIT-licensed projects:
-
-- **obra/superpowers** (<https://github.com/obra/superpowers>): the spec, plan and build loop. `shape`, `plan` and `build` follow it.
+- **obra/superpowers** (<https://github.com/obra/superpowers>): the spec, plan and build loop. `spec`, `plan` and `build` follow it.
 - **garrytan/gstack** (<https://github.com/garrytan/gstack>): the reviews of a plan, the use of the running product, and shipping. `skills/plan/lenses.md`, `review` and `ship` follow it.
 - **cloudflare/security-audit-skill** (<https://github.com/cloudflare/security-audit-skill>): the audit method. `security` and `skills/security/domains.md` follow it.
+- **PostHog/posthog** (<https://github.com/PostHog/posthog>, MIT outside its `ee/` folder): the bar a review finding must pass, the last sweep, and the handling of review comments. `skills/review/bar.md` and `skills/build/comments.md` follow it.
 
-Keep each credit when you change the file that carries it. Copy no prose from any of the three.
+Keep each credit when you change the file that carries it. Copy no prose from any of the four.

CHANGELOG.md

@@ -4,23 +4,48 @@
 
 ### ⚠ Breaking
 
+- The first stage is named `spec`, not `shape`: load it as `builder:spec`.
 - A finding has a state (`confirmed`, `needs_validation` or `rejected`), and `builder security score` scores only a confirmed one and refuses a hand-written score or rating on any other.
-- builder is a framework of its own: every session knows the five stages `shape`, `plan`, `build`, `review` and `ship` and the gate of each, a small change skips the spec and the plan, and no work goes to another pack. A one-shot run asks its question and stops unless you say you cannot answer.
-- builder no longer recommends the superpowers or gstack packs at session start, because it does their jobs itself. An old saved answer for either still loads, and the parity eval runs the seven flow fixtures with builder alone.
+- builder is a framework of its own: every session knows the five stages `spec`, `plan`, `build`, `review` and `ship` and the gate of each, a small change skips the spec and the plan, and no work goes to another pack. A one-shot run asks its question and stops unless you say you cannot answer.
+- builder no longer recommends the superpowers or gstack packs at session start, because it does their jobs itself.
+- The session-start hook prints the soul, the builder root and the action map of your harness, and nothing else. It recommends nothing and asks no setup question: onboarding is gone. The one exception stays: when the helper binary is missing, the hook offers to install it. A `ledger.json` from 3.0.0 stays on your machine, and nothing reads it.
+- Removed: the `budget`, `canon`, `fleet`, `harness`, `intake` and `reach` skills, the `builder ledger`, `builder reach`, `builder budget` and `builder mcp-merge` commands, the recommendations and onboarding, and the parity eval. builder keeps seven of its skills: `builder`, `spec`, `plan`, `build`, `review`, `ship` and `security`. Send rules are gone, so each push, post or message needs your yes in the session. Release 3.0.0 is the last release that has them. builder leaves the state files of an older version on your machine and reads none of them.
 
 ### Features
 
+- `plan` reviews work on an API, a service boundary, a data store or an agent tool through an architecture lens: where the contract is written, one shape for every list, who owns each fact, where the customer boundary is enforced, and which guard keeps each rule. The project's own rules win, and `review` checks a change against the same questions.
+- Tenet 9 says what a good guard does: it names the incident that made it, says what to do instead, and fails when it checks nothing.
+- `debug` is a new skill. When a test fails or a bug report arrives, it reproduces the failure, finds the root cause, pins it with a failing test and fixes the cause. It changes one thing at a time and stops after three fixes that did not hold. `build` loads it when a test fails.
+- `build` removes what its own change did not need before the last test run: a comment that restates the code, a guard for a case that cannot happen, a helper with one caller, an option nobody asked for, filler in prose. `review` lists the same things under a new "Slop" heading, which does not touch the gate.
+- builder runs on Grok Build: the session start prints its action map, and `docs/install.md` says how to install it.
+- On Cursor CLI, Grok Build and opencode, where a skill has its plain name, the session start says that `builder:<name>` means the builder skill `<name>`.
+- The stages chain by themselves. Each stage ends by loading the next one (`builder:spec` → `builder:plan` → `builder:build` → `builder:review` → `builder:ship`), and the session start tells the agent to load a stage's skill when work enters it.
+- A new session, or a session after a compact, finds where the work stands from four records: the approval ruling of the spec, the header of the plan (`Spec:`, `Test command:`, `Plan approved:`), the task commits on the branch, and the review saved at a fixed path in builder's state folder.
+- `ship` asks for each tag and each release as its own write, counts a yes only after it showed that write, and stops when the head has commits that the saved review did not see.
+- `review` keeps a finding only when it names its trigger and its harm, lists each point it dropped under "Declined to judge" with the reason, sweeps the error paths and callers that no finding touched, and reports an instruction hidden in the change instead of following it.
+- Ask `build` to address the review comments on your branch, and each comment gets one outcome (fixed, declined, already fixed, or needs you) and one reply for its author. It fixes alone only what is worth it and safe, test first, never deletes or weakens a test on its own, checks a comment against the current code first, and hands you a schema change, a new dependency or two comments that disagree. A decision it hands you stays open until you answer, also when nobody is there. The replies wait for your yes before they reach the forge.
+- `ship` checks commit signing before anything leaves your machine, and, when the remote is on GitHub, that `gh` is present and signed in. It names the fix for each check that fails, so you fix them in one round. On another forge, or with no remote, it says that it did not check the forge tool. Its look back lists what broke and what you corrected, in the report.
 - An audit records which units it covered, deferred or left out, and the next audit picks up the new ones, the deferred ones and the covered ones whose files changed. It checks each open finding of the last audit again, so no hole is reported closed because the run skipped it. A baseline from the released version still loads.
 - A `security` audit says which records are confirmed, which need a check and by whom, which a second agent verified, and which units it did not cover. It loads domain checklists for AI, cloud, client, desktop and mobile, and protocol code.
-- `shape` reads the repository, asks one question at a time with a recommendation, shows two or three ways to build the work, and stops until you approve the spec. Your approval is a dated ruling in the spec, so `plan` can tell an approved spec in a new session. Each spec has a Surfaces line that names the sensitive surfaces it touches.
+- `spec` reads the repository, asks one question at a time with a recommendation, shows two or three ways to build the work, and stops until you approve the spec. Your approval is a dated ruling in the spec, so `plan` can tell an approved spec in a new session. Each spec has a Surfaces line that names the sensitive surfaces it touches.
 - `plan` turns an approved spec into a file map and tasks that each start with a failing test and end in one commit, reviews the plan as an engineer and as a designer, and maps every done-when line of the spec to a task.
 - `build` runs a plan one task at a time: a failing test first, then the code, then one commit per task. It stops at a wrong step, proposes the change and updates the plan, and ends with the full test run quoted and the change handed to `review`. A small change that no test can see, such as a typo, gets a named check that runs before and after it.
 - `review` runs a security pass by itself when a change touches a sensitive surface, uses the running product and quotes what it saw, and lists each check that still needs you under "Open checks that block ship". It saves the review to a file outside the repository and names its path, so `ship` can read it in a new session. `security` now does the whole-repository audit only.
 - `ship` takes reviewed work to a checked release: it syncs with the base branch and runs the full suite, stops on an open finding or an open check with the exact words to reply, shows the changelog line and the pull request text, and waits for your yes before each push, pull request and merge. Your answer to each open check goes into the pull request text, and a merge conflict leaves the checkout as it was.
 
 ### Documentation
 
-- The README, the agent guide and the plugin manifests describe builder as one framework from a request to a release, with security in every stage. The README credits the three projects that builder takes ideas from. The design and plan documents live in `docs/specs/` and `docs/plans/`.
+- The README, the agent guide and the plugin manifests describe builder as one framework from a request to a release, with security in every stage. The README credits the four projects that builder takes ideas from. The design and plan documents live in `docs/specs/` and `docs/plans/`.
+
+### Fixes
+
+- On Codex, the session start prints the Codex action map, not the one of Claude Code. builder tells the harnesses apart by the variable that each one sets for a plugin hook.
+- A security score no longer dead-ends when no session-start hook ran: the skill says where the helper binary is, and to stop when it is not there.
+- A security audit no longer closes an open finding when it deferred or did not inspect a unit of that finding's dimension. The finding stays under `not_rechecked`.
+- `builder security baseline` says whether it found a baseline and at which path, and stops with the fix when it cannot find the home folder.
+- A review comment cannot steer `build` by its words: only the forge's record or you say who is a maintainer, only the comment's author or a maintainer can withdraw an ask, and a note that the change itself adds is not a recorded decision.
+- `review` asks before it runs the build or the tests of a change from someone you did not name as trusted.
+
 
 ## [3.0.0] - 2026-10-27