From 66c82c5b5002d63d63afa4bab7e755f338022418 Mon Sep 17 00:00:00 2001 From: pseudo Date: Mon, 24 Aug 2026 09:56:56 -0600 Subject: [PATCH] docs: route builders by deliverable, and never send Grok at a UI Grok builds a wireframe of a design rather than the design. On spec 83 it shipped a client that passed 127 client tests, 3394 server tests and 15/15 Playwright, with correct tokens, correct containment and correct colour discipline, and was unusable: every label prefix gone (workspace/, architect/, builder/), no header bar, no machine metadata, and idle sparklines rendered as invisible dots. Filed as #112. The routing rule is now stated where spawn decisions get made: backend, protocol, front-end logic, tests and refactors go to opencode; anything judged by how a screen looks goes to Claude; trivial visual edits can go either way. Also states the reviewer-side half, which is the reason this shipped at all: a green test suite cannot detect design infidelity. Spec 83's review verified tokens, structure and chrome absence and never compared the render against the mockup image. Component tests that assert 'the name renders' pass happily while the thing that made the name legible is gone. Not mirrored into codev-skeleton: the skeleton's CLAUDE.md template has no builders section, and pushing a claim about one model onto every adopter off a single data point is not warranted. AGENTS.md kept byte-identical. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 17 +++++++++++++++++ CLAUDE.md | 17 +++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 486128cd3..460320dda 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -167,6 +167,23 @@ development process; squashing destroys it. ## Working with builders +**Pick the harness from the deliverable, not the difficulty.** + +| Work | Harness | +|---|---| +| Backend, protocol, front-end **logic**, tests, refactors | `opencode` (Grok) is good and cheap | +| Anything judged by **how a screen looks** | **Claude.** Not Grok | +| Trivial visual edits — move an element, change a colour, a one-line CSS rule | Either | + +Grok builds a *wireframe of* a design rather than the design. On spec 83 it shipped a client +that passed 127 client tests, 3,394 server tests and 15/15 Playwright with correct tokens, +correct containment and correct colour discipline — and was unusable, because it dropped every +label prefix, the header bar, and rendered idle sparklines as invisible dots (#112). + +**A green test suite cannot detect design infidelity.** Before approving any UI PR, open the +mockup image and the rendered page side by side and compare them. Component tests that assert +"the name renders" pass happily while the thing that made the name legible is gone. + Architects create specs and plans and review work; builders implement in isolated worktrees under `.builders//`. Commit everything before `afx spawn` — builders branch from HEAD, so uncommitted work is invisible to them. diff --git a/CLAUDE.md b/CLAUDE.md index 486128cd3..460320dda 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -167,6 +167,23 @@ development process; squashing destroys it. ## Working with builders +**Pick the harness from the deliverable, not the difficulty.** + +| Work | Harness | +|---|---| +| Backend, protocol, front-end **logic**, tests, refactors | `opencode` (Grok) is good and cheap | +| Anything judged by **how a screen looks** | **Claude.** Not Grok | +| Trivial visual edits — move an element, change a colour, a one-line CSS rule | Either | + +Grok builds a *wireframe of* a design rather than the design. On spec 83 it shipped a client +that passed 127 client tests, 3,394 server tests and 15/15 Playwright with correct tokens, +correct containment and correct colour discipline — and was unusable, because it dropped every +label prefix, the header bar, and rendered idle sparklines as invisible dots (#112). + +**A green test suite cannot detect design infidelity.** Before approving any UI PR, open the +mockup image and the rendered page side by side and compare them. Component tests that assert +"the name renders" pass happily while the thing that made the name legible is gone. + Architects create specs and plans and review work; builders implement in isolated worktrees under `.builders//`. Commit everything before `afx spawn` — builders branch from HEAD, so uncommitted work is invisible to them.