builder

Prototype-mode step of the /builder:* pipeline, between design and audit — trace every field the in-scope design contracts persist through the producer's model, validation, wire shape and write path, and onward to the property each consumer reads it from, then record what the app lacks as SC# rows in SPEC §Schema & API changes and T# rows in §Findings, tagged by owning app. Runs only when the manifest carries a design ref. Never edits app code and never edits the design source — a naming disagreement leaves as a row or an OPEN decision. Use when the user asks whether the backend can store what a design collects, to align design naming with the app, or invokes /builder:align.

Verify a feature spec against the codebase before any code is written — per-app layer and house-pattern compliance against the project config's house rules, schema-change and lifecycle check, the CROSS-APP CONTRACT audit (producer/consumer parity, breaking changes for released artifacts, wrong "not affected" claims, silent consumer divergence), component coverage per consumer, replaced-surface and adjacency check, and an adversarial gap hunt — writing findings into SPEC's §Findings & risks and open questions into §Decisions. First code-facing step of the /builder:* pipeline; capped at ONE pass (a second, scoped pass only when pass 1 changed a contract), with anything still uncertain carried into the build as a build-time risk. Use when the user asks to audit, verify, or gap-check a feature spec.

The stateless pre-flight for a design ref — run it repeatedly while a design settles, before it enters /builder:brainstorm. Resolves the ref, reads every in-scope contract, checks it against the project config's design conventions, disposes the open questions, diffs a built item against its frozen design snapshot, lists coverage owed and dead-end affordances, and runs the surface check (which live surfaces the ref replaces and what each side can do that the other can't), returned as one punch list ending READY or NOT READY. Never touches app code, never writes the design; writes nothing but the punch list. Use when the user asks whether a design is ready to build from, what the app does that the design doesn't, or "am I missing anything" before starting a build.

Help card for the /builder:* pipeline — explains how work is sized (xs/sm designed and built in chat, md/lg as a SPEC plus a manifest, xl as a program of children), what each /builder:* command does and which one to run for a given situation, how a finished design can be read as the requirements, how one-app-per-phase and the contract freeze keep a multi-app repo safe, where the artifacts live, how resuming after a context clear works, how a folder from an earlier pipeline is converted, and how a signed-off feature condenses to its SPEC. Also explains the .claude/builder.md project config the whole family reads. Use when the user asks how the build pipeline works, what the builder commands are, which build skill to use, or for help getting started with speccing or building a feature.

Sets up a repo for the /builder:* pipeline by writing its one project config, .claude/builder.md — copies PROJECT.template.md out of the installed plugin, fills the frontmatter and body from what the repo actually contains (project name, base branch, apps and their paths, the real gate commands, house-rule sources), asks only what the repo cannot answer (app roles, commit mode, optional ticket and design blocks), then proves the result parses. Refuses to overwrite an existing config unless asked; with --update it fills gaps and placeholders in one instead. Use when the user asks to set up, configure, initialise or install builder in a project, when any /builder:* step reports that .claude/builder.md is missing, or when the config still holds template placeholders.

Turn an audited feature spec into a committed implementation plan at the feature folder's PLAN.md — dependency-ordered phases, ONE APP PER PHASE with the producer before its consumers (contract + migrations → producer → consumers in parallel → tools → the cross-app E2E walk last), each task naming its app, its phase, the recipe skill to read first, its files and interfaces, and bite-sized steps carrying the actual code and tests. SPEC §Plan becomes a one-line-per-task index pointing at PLAN.md. Runs only after /builder:audit, with no OPEN decisions and no blocked findings. Ends by taking the build go-ahead and recording it on the manifest. Use when the user asks to plan a spec's implementation.

Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation

Apply ONE change to a feature that is already audited, planned or part-built — a new requirement, a reversed ruling, a conflict found mid-build. Post-build the default is a code fix plus at most one line of docs; the SPEC write-back is reserved for contract changes that un-built work depends on. It is also the ONLY way a FROZEN contract re-opens, and it names which consumers must be re-checked. Records human rulings as implementable statements in SPEC §Decisions and never re-audits. Use when a spec needs to change after /builder:brainstorm has run — revising, correcting, extending or reversing part of a feature spec.

Collapse a feature's folder to its write-once SPEC matching the implementation — at sign-off, and flip the header to SHIPPED when the PR merges. Run by /builder:signoff on PASS; standalone for a merged PR, a legacy shipped folder, or a signed-off feature that was never condensed.

Record the human's own hands-on verdict on a built feature — the durable spend of the /builder:* PR lock. Typed by the human ONLY; an agent can never grant, infer, or simulate it. On "it works" it writes a dated, sha-bound sign-off into the feature's MANIFEST.md and SPEC header, condenses the folder, and unlocks the verify+PR steps; on "found problems" it records each finding as a §Fixes task and the lock stays closed; on "works, but not yet" it records the sign-off AND a hold, so nothing pushes until the human says go. In a multi-app feature it captures WHICH apps were exercised, so a half-walked feature is recorded as PARTIAL rather than passing.

The dashboard of in-progress /builder:* work in this repo — one table of every open feature and program, most recently touched first, each with what it is, the step last completed, the step to do next, when it last moved, and the exact command to copy and paste to pick it up; plus which branch to switch to and any feature that can't be resumed as it stands. Read-only and fast — it reads manifests, never specs, and writes nothing. Use when the user asks where their work stands, what's in progress, what they were working on, what to pick up next, or for a status/overview of builder features.

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Use when implementing any feature or bugfix, before writing implementation code

Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always