feat: a debug skill, a deslop pass, and the same flow on five harnesses

.claude-plugin/plugin.json

@@ -20,6 +20,7 @@
     "security-review",
     "codex",
     "cursor",
+    "grok",
     "opencode",
     "agent-skills"
   ]

.codex-plugin/plugin.json

@@ -18,13 +18,14 @@
     "rulings",
     "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

@@ -19,6 +19,7 @@
     "rulings",
     "codex",
     "cursor",
+    "grok",
     "opencode",
     "agent-skills"
   ],

AGENTS.md

@@ -1,6 +1,6 @@
 # builder — agent guide
 
-builder is a plugin for coding agents: seven 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,8 +12,11 @@ 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'` |

CHANGELOG.md

@@ -9,10 +9,16 @@
 - 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 now has seven skills: `builder`, `shape`, `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.
+- 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.
@@ -33,6 +39,8 @@
 
 ### 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.

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to builder
 
-Thanks for your interest. builder is a plugin for coding agents: seven skills, one session-start hook,
-and one Go binary, `builder`. It runs on Claude Code, Codex CLI, Cursor CLI and opencode. [AGENTS.md](AGENTS.md) tells you which file to change for each job.
+Thanks for your interest. builder is a plugin for coding agents: eight skills, one session-start hook,
+and one Go binary, `builder`. It runs on Claude Code, Codex CLI, Cursor CLI, Grok Build and opencode. [AGENTS.md](AGENTS.md) tells you which file to change for each job.
 
 ## Quick start
 

README.md

@@ -10,7 +10,7 @@ report: is it done, what you have to do, what isn't proven yet, what left your m
 and every call the agent made on its own, with the reason. Nothing leaves the machine
 (no push, no PR, no message) without your yes.
 
-It's a plugin for Claude Code, Codex CLI, Cursor CLI and opencode. It takes a request
+It's a plugin for Claude Code, Codex CLI, Cursor CLI, Grok Build and opencode. It takes a request
 through spec, plan, build, review and ship, with security in every stage. Skills and one
 session hook; no server, no account, no network call at session start.
 
@@ -55,6 +55,11 @@ sensitive surface the work touches. A task on such a surface writes its hostile-
 test first. The review runs a security pass by itself, and `ship` stops on an open check.
 `security` audits the whole repository and remembers what it covered.
 
+Two more things keep the work honest. When something fails and the cause is not known, `debug`
+finds the root cause and pins it with a test before any fix. Before the last test run, `build`
+removes what its own change did not need: a comment that restates the code, a guard for a case
+that cannot happen, a helper with one caller. `review` lists the same things under "Slop".
+
 | | builder | your own CLAUDE.md |
 |---|---|---|
 | Starts from the person and the non-goals | every piece of work | if you wrote it |
@@ -80,6 +85,8 @@ codex plugin marketplace add Lutherwaves/builder
 codex plugin add builder@builder
 ```
 
+**Grok Build.** Grok Build reads Claude Code plugins. Add this repository as a marketplace in its `/plugins` screen, and install `builder`.
+
 **Cursor CLI** and **opencode:** see [docs/install.md](docs/install.md).
 
 The first session asks to install the helper binary. It runs the session-start hook and
@@ -96,7 +103,7 @@ A harness counts as supported once every eval fixture passes on it.
 <!-- support:start -->
 | Harness | Version | Eval date | Status |
 | --- | --- | --- | --- |
-| Claude Code | 2.1.308 (Claude Code) | 2026-10-22 | experimental: spec 2/6; 10 not graded |
+| Claude Code | 2.1.308 (Claude Code) | 2026-10-22 | experimental: spec 2/6; 11 not graded |
 <!-- support:end -->
 
 ## Skills
@@ -105,11 +112,12 @@ A harness counts as supported once every eval fixture passes on it.
 | --- | --- |
 | `builder` | The thirteen tenets, the five stages and their gates, and the report. |
 | `spec` | A request becomes a spec. It reads the repository, asks one question at a time with its recommendation, shows two or three ways to build it, and waits for your approval. |
-| `plan` | An approved spec becomes tasks that each start with a failing test, reviewed as an engineer and as a designer. |
-| `build` | The plan runs one task at a time, test first, one commit per task. It stops when a step is wrong and proposes the change. It answers each review comment with one outcome and one reply. |
+| `plan` | An approved spec becomes tasks that each start with a failing test, reviewed as an engineer and as a designer. Work on an API, a service boundary, a data store or an agent tool also gets an architecture review. |
+| `build` | The plan runs one task at a time, test first, one commit per task. It stops when a step is wrong and proposes the change. It removes what its own change did not need. It answers each review comment with one outcome and one reply. |
 | `review` | A review that proves each harm with evidence, a fix and a test, with a security pass and the running product. Posts nothing without your yes. |
 | `ship` | Reviewed work becomes a checked release. It stops on an open finding and waits for your yes before each push, pull request, merge, tag and release. |
 | `security` | A whole-repository audit: every layer, standards-mapped findings with CVSS scores, and what changed since last time. |
+| `debug` | A failure becomes a root cause in one sentence, a test that pins it, and a fix at the cause. It stops after three fixes that did not hold. |
 
 Ask for a skill by name, or just describe the job. The agent loads the right one.
 

cmd/support-table/main.go

@@ -23,7 +23,7 @@ import (
 )
 
 var (
-	harnesses = []struct{ id, name string }{{"claude", "Claude Code"}, {"codex", "Codex CLI"}, {"cursor", "Cursor CLI"}, {"opencode", "opencode"}}
+	harnesses = []struct{ id, name string }{{"claude", "Claude Code"}, {"codex", "Codex CLI"}, {"cursor", "Cursor CLI"}, {"grok", "Grok Build"}, {"opencode", "opencode"}}
 	version   = regexp.MustCompile(`^[A-Za-z0-9._ +()-]{1,60}$`)
 	fixtureRe = regexp.MustCompile(`^[a-z0-9_-]+$`)
 	dateRe    = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}$`)

docs/install.md

@@ -21,8 +21,7 @@ codex plugin add builder@builder
 ```
 
 Codex runs a plugin's hooks only after you trust them, and builder doesn't work around
-that. Until you trust the hook, load the `builder` skill by name. Until Codex detection
-lands (issue #17), builder's session start on Codex prints the Claude Code action map.
+that. Until you trust the hook, load the `builder` skill by name.
 
 ## Cursor CLI
 
@@ -45,6 +44,14 @@ 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.
 ```
 
+## Grok Build
+
+Grok Build reads Claude Code marketplaces and plugins. Open `/plugins`, add `Lutherwaves/builder` as a
+marketplace, and install `builder`. For a local checkout, start it with `grok --plugin-dir <path to builder>`.
+
+When Grok Build asks you to trust the plugin's hook, trust it. Without the hook, load the `builder` skill by name.
+A builder skill has its plain name there: `/spec`, `/plan`, `/build`, `/review`, `/ship`.
+
 ## opencode
 
 Use opencode 1.19 or newer: 1.1.x crashes on plugins with non-function exports. Add