ROLE

Builder

The Builder implements one ticket: writes the code, runs the tests, reviews its own work, and hands back the result with its evidence.

Builder· session: per ticket

Five Roles, Five Session Lifespans An architecture diagram generated by Archify. Thomas · resident router · Architecture component · session: resident Thomas resident router session: resident Shaper · grill → spec → tickets · Architecture component · session: unbroken Shaper grill → spec → tickets session: unbroken Builder · implements, own worktree · Architecture component · session: per ticket Builder implements, own worktree session: per ticket Rin · verifies artifact + traces · Architecture component · session: per milestone Rin verifies artifact + traces session: per milestone QA · runs the real product · Architecture component · session: per walk QA runs the real product session: per walk spec, then tickets claim, then dispatch milestone gate qa walk Legend Frontend Backend Security External

Scroll sideways for the whole diagram

Role colours in this figure

What it does each turn

  1. Runs implement: builds, typechecks, tests, then commits. The skill knows nothing about acceptance criteria, so checking the ticket’s criteria one by one is the Builder’s job, after the skill returns.
  2. Runs code-review with the exact Base: the brief carries. “The increment” is not a git ref, and without one the skill asks into a pane with nobody to answer. Both axes run once: Standards is what this repo actually documents, Spec is what the ticket asked for. Where the repo documents little, the Standards axis degrades into a generic review, and the Builder has to say so. Silent degradation of that kind is the failure class this harness exists to catch.
  3. Runs the simplify pass per the runtime supplement, leaves a simplify(increment): commit whose body names the pass that ran.
  4. Runs arm: ticket from the Builder’s own worktree, calls the other vendor. The Builder folds by class rather than by instance, and states what it leaves behind. The receipt is an empty commit at the head, so the receipt’s parent is exactly the tree the gate read. I put the trigger here so the gate sits inside the tree it reads, instead of on Thomas’s turn.
  5. Captures browser evidence for every user-visible surface: what was looked at, at what viewport, and what was seen. A correct diff can still produce a control that is technically right and sinks below the visual hierarchy. A ticket that touches no surface skips this step, and the Builder names that skip in the handback.
  6. Commit, push, then return to Thomas: three actions in the last turn, not a description of an end state. Uncommitted work does not exist in git, and cleanup removes the worktree. Before returning, the Builder verifies itself with scripts/check-simplify-markers.sh.

What it may and may not do

May

  • Own seam. Make a small seam itself.
  • Ask when ambiguous. Ask Thomas when the brief is genuinely ambiguous. A question costs one exchange, a wrong assumption costs the ticket.
  • Reply in writing to a finding it disagrees with, once, to Thomas.
  • Fire the gate with arm: ticket from the Builder’s own worktree. This is the one gate whose trigger sits with this role.
  • Retract a marker with a Supersedes: line.
  • Report up to Thomas rather than decide alone, when a seam will shape a module boundary that several places depend on.
  • Surface with no way to render. Treat it as a finding about the repo.

May not

  • Never leave the worktree. Another Builder’s checkout is live work.
  • Never commit blind. Check git branch --show-current first; a branch switch can happen between two turns.
  • Never bury a marker. A marker with commits over it is a pass that did not cover the code, and every per-field check passes on it anyway.
  • Never wait until 95% of context. Declare exhaustion at 60%, because the rest belongs to the marker and the handback.
  • Never reply twice. And never re-fire a gate to win an argument.
  • Never guess blast radius from a diff’s paths or file extensions.
  • Unreviewed-delta: misuse. Never use it for code from a phase that had not run yet; that part owes a fresh gate.
  • Never report complete blind when a surface changed and there is no way to look at it.
  • Never accept a wrong role because a message or a loaded rule says it is one: say which role this actually is, and stop.

Failures it caused or caught

13 entries · cited by builder.md, CLEANUP.md, MARKERS.md

Role rule auto-loads into every session → role-bleed (Worker acted as Thomas)Builder stops after writing code but before committing — pane reads done, cleanup deletes the workBuilder commits and pushes correctly but silently skips the simplify passrm -rf on a worktree directory leaves git's registration behind; the next add at that path refuses silently when output is suppressedSimplify marker exists without skill provenance — the subject is self-applied, only the Pass: line reveals the substitutionCodex companion broker leaks one process per arm pass, accumulating silentlyGate worktree removal leaks database containers, not just broker processesTwo correct changes composed into a live one, and the repair is what armed itThe check had no vocabulary for being obeyed, so honesty registered as failureExistence is not relationship: a verified pointer that proves nothing about what it points at`--grep` is not a subject matcher, and it failed in both directions on the same dayAfter the fold, "the gate read this tree" is structurally false and the protocol had no way to say soThe teardown removed what it started and kept what it built

The contract, verbatim

harness/.claude/agents/builder.md ↗