docs: route builders by deliverable, never send Grok at a UI - #114
Merged
Conversation
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) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem. Nothing in the repo said which harness to use for which kind of work, so spec 83's UI unit went to Grok and came back unusable.
Root cause. Grok builds a wireframe of a design rather than the design. On #104 it produced 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 dropped every label prefix (
workspace/,architect/,builder/), the header bar, machine metadata, and rendered idle sparklines as invisible dots. Filed as #112.The reviewer-side half matters as much: 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.
Fix. A routing table in
CLAUDE.mdunder Working with builders, stated where spawn decisions actually get made:opencode(Grok)Plus the instruction to open the mockup and the render side by side before approving any UI PR.
Not mirrored into
codev-skeleton/. The skeleton'sCLAUDE.mdtemplate has no builders section and no harness guidance, and pushing a claim about one model onto every adopter off a single data point isn't warranted. This is our-instance guidance backed by our-instance evidence.Testing.
CLAUDE.mdandAGENTS.mdverified byte-identical withcmp. Docs only.🤖 Generated with Claude Code