Builder

Spec-driven build. Reads the explorer memory as ground truth, plans a change from .claude/specs/, gates it (clarity 9+/10, technical plan 9+/10), implements only what the spec says, runs hybrid QA, then syncs the durable memory. Usage: /builder:start [optional note]

Show the current builder state cheaply — reads .claude/builder/ artifacts (PLAN.md, CHANGELOG.md, QA.md, settings.json) and explorer freshness, without spawning any sub-agents. Use to resume or inspect.

Read-only context loader for the builder flow. Recalls the explorer codebase memory (.claude/explorer/*) and produces a compact build-ready brief. Invoked first by /builder:start. Never scans the codebase from scratch and never edits anything.

Critical-tier bug diagnostician for the builder flow (Opus 4.8, effort xhigh). Invoked by /builder:start in BUG-FIX MODE to run symptom intake → reproduce-first → root-cause → characterization (Phases B0–B3): writes the Bug Brief to .claude/builder/BUG.md, a FAILING reproduction test, characterization tests that pin the blast radius, and the fix PLAN.md. Diagnosis quality comes from this deep tier; correctness comes from the verification net + regression gate, not from effort.

Implements an APPROVED plan for the builder flow (Sonnet). Invoked by /builder:start only after the plan is rated 9+/10 and validate-plan.sh passes. Edits ONLY the files in the plan's Scope, follows MEMORY.md conventions, keeps diffs minimal, and writes a change report. The PreToolUse scope guard blocks any out-of-scope edit.

Final builder step (Sonnet): updates the durable memory so the next session is accurate — refreshes the affected explorer artifacts (MEMORY.md, index.json, TRACK.md, map/*.md) and the builder log. Invoked by /builder:start after QA passes. Resolves every index.json path on disk via find/glob (never infers), fixing the known explorer path defect.

Opus escalation planner for the builder flow. Invoked ONLY when the Sonnet planner has failed to produce a 9+/10 plan within the configured loop limit (default 2). Same job as builder-planner — recall context, read specs, rate clarity, write .claude/builder/PLAN.md — but with deeper reasoning. Token-heavy; last resort, gated by settings.opus_escalation.

Implement an APPROVED plan (.claude/builder/PLAN.md) exactly as written — edit only the files listed in the plan's Scope, follow the conventions recorded in MEMORY.md, keep diffs minimal, and produce a change report. Use only after the orchestrator has rated the plan 9+/10 and validate-plan.sh has passed. The PreToolUse scope guard will block any edit outside the plan.

BUG-FIX MODE: turn a vague, repro-less bug report (e.g. 'the search field is not working', empty repro steps) into a verified, regression-safe fix via a deterministic symptom→reproduce→root-cause→characterize→fix→regression-gate workflow. Use when a spec is a bug report (auto-detected by a 'Bug:'/symptom shape, or marked by the user). The fix's accuracy comes from a VERIFICATION NET — a failing reproduction + characterization tests + a regression gate — NOT from thinking budget; effort only improves diagnosis quality. Builds on explorer recall, micro-decompose, the per-edit feedback loop, and the scope guard.

Decompose a requirement into the smallest INDEPENDENTLY-VERIFIABLE units, then harden each with an explicit edge-case enumeration drawn from a fixed taxonomy plus the codebase-specific risks in MEMORY.md. Use during planning (to write the PLAN.md '## Tasks' breakdown) and during implementation/QA (to drive and verify the edge-case coverage map). Proportional by design: a one-line change is ONE task — never explode a trivial spec into dozens of tasks.

Turn a spec (.claude/specs/specN.md) plus the explorer memory into (a) a clarity rating out of 10 and (b) a technical implementation plan that the orchestrator can rate. Use after recall-memory, before any code is written. Enforces evidence-first planning: every claim cites path:line, scope is an explicit file list, and the plan must respect the invariants and risks recorded in MEMORY.md. Used by both the Sonnet planner and the Opus escalation planner.

Verify a freshly built feature with a hybrid strategy: auto-detect a real test/build harness and (with confirmation) run it for feature-level edge cases AND app-level regression; if no harness exists, fall back to rigorous static analysis and edge-case enumeration. Use after apply-change, before reporting to the user. Produces a QA report and a score the orchestrator rates. Used by both the Sonnet QA agent and the Opus QA escalation.

8 hooks across 5 events