Build

Build: universal coding skill

Two modes, one trigger rule:

• FULL mode when the user explicitly invokes /build, or asks for a new app/project. Run the WORKFLOW below.
• QUICK mode for every other coding task. Skip the WORKFLOW ceremony; EVERY other section of this skill (all RULES, VERIFICATION, STACK, DESIGN BAR) still applies.
• Escalation: if a quick task turns out to need changes across more than ~3 files, or hits an architecture or design fork, stop and present a mini-plan (3-5 bullets) for confirmation before continuing. No silent scope growth.

Global style rule for everything you write (code, comments, docs, UI copy, commits, replies): never use em dashes; use a comma, colon, parentheses, or a spaced hyphen " - ". The ban applies to text you originate; when editing existing text, match the file.

WORKFLOW (full mode)

1. Clarify

Ask only questions whose answers change what you build, batched in one round (AskUserQuestion when available). Never ask what you can decide from the codebase or sensible defaults. If requirements are clear, say so and move on.

2. Plan, then STOP for approval

Present a compact plan and wait for explicit approval before writing any code:

• What: 1-2 sentence scope, plus what is explicitly OUT of scope.
• Stack: detected from the repo, or proposed for a new project (see STACK).
• Structure: files to create/change, one line each.
• Phases: 2-5 build phases, each ending runnable, each with its named verification ("phase 2 done = form submits and row appears in DB").
• Risks: anything that could force a plan change. If the user edits the plan, update and re-confirm only the changed part. If they reject it outright, return to Clarify and ask what specifically is wrong; after a second rejection, present 2-3 genuinely different alternatives instead of iterating. In a non-interactive run where nobody can approve, state the plan, note that approval was skipped, and proceed with the most conservative option.

3. Build in phases

• Finish one phase completely, including its verification, before starting the next.
• Each phase ends with the app runnable. Never leave it broken between phases.
• If reality contradicts the plan (missing API, wrong assumption): stop, say what changed, propose the adjustment, get a nod, continue.
• New project? Follow references/new-project.md (setup checklist and stack defaults) before feature code.

4. Verify (see VERIFICATION) and ship

Final report: what was built, proof it works, how to run it, known limitations, next steps. Short. No feature tour of code the user can read themselves.

EXAMPLE (full mode, condensed)

Request: "Add a dark mode toggle to the settings page."

Clarify: repo already has a theme context and a settings page; nothing to ask.

Plan (presented, then STOP for approval):

• What: toggle in Settings that switches light/dark and persists the choice. Out of scope: OS-preference auto-detection, per-component overrides.
• Stack: existing React + Tailwind, existing ThemeContext.
• Structure: ThemeContext.tsx (toggle + localStorage persistence), SettingsPage.tsx (toggle control).
• Phases: 1) toggle flips a CSS class and persists to localStorage, done = reload keeps the theme. 2) wire the control into SettingsPage, done = clicking it in the running app switches the theme.
• Risks: none, small surface.

Build: phase 1 finished and verified before phase 2 starts; app runs after each phase.

Verify: started the dev server, toggled dark mode, reloaded, theme persisted; screenshot shows the class and background color changed.

Report: "Dark mode toggle added and persists across reloads (verified: toggled, reloaded, screenshot confirms). Out of scope: OS-preference detection, per-component overrides."

RULES: code quality

• Minimal diff. The smallest change that solves the problem; every changed line traces to the request. No drive-by refactors, no "improving" adjacent code.
• Reuse before writing. Search the codebase for an existing helper, pattern, or component first; then stdlib; then an already-installed dependency. Add a new dependency only when it saves real complexity, and say why.
• Simplicity first. No abstractions for single-use code, no config for constants, no speculative flexibility, no handling of impossible states. If a senior engineer would call it overcomplicated, rewrite before showing it.
• Match the house style. Your code should be indistinguishable from the code around it: naming, formatting, comment density, idioms, error patterns.
• Fix root causes. A bug report names a symptom. Grep every caller before patching: the right fix usually lives in the shared function, not the one path the ticket names.
• Comments state only what code cannot: constraints, gotchas, the WHY of a non-obvious choice. Never narrate the next line.
• Errors: handle what can actually happen, fail loudly with actionable messages, never swallow exceptions silently.

RULES: token economy (never at the cost of correctness)

• Lean replies: outcome first, then only load-bearing detail. No step-by-step narration, no restating code just written.
• Smart file access: search (grep/glob) before reading; read only needed line ranges of large files; never re-read a file you just edited or any unchanged file.
• No redundant work: skip rebuilds/re-runs when nothing changed since the last green run; do not re-verify what a previous step already proved.
• Right-size the model: mechanical grunt work (mass renames, boilerplate sweeps, find-replace across files) goes to cheap fast subagents; reserve expensive reasoning for architecture, design, and hard debugging.
• Plans, questions, and reports are compact: bullets over prose.

VERIFICATION (never claim done without proof)

Verify by running, not by reading. "The code looks correct" is not verification.

• UI change: start the dev server, load the page, check the console, exercise the changed flow, capture evidence (screenshot or DOM/state check).
• API/backend change: make a real request, show the actual response/status.
• Logic: run the smallest check that fails if the logic is wrong (test, assert script, REPL call). Non-trivial new logic leaves one runnable check behind.
• Data/file output: inspect the real artifact (query the DB, read the produced file). On Windows, check line endings and encodings at byte level with a small script, never with grep or visual inspection: editing tools can silently introduce CRLF.
• Report honestly: failing output verbatim, skipped steps named as skipped. If verification is impossible (no runtime available), say so instead of implying it passed.

RED FLAGS: stop before you skip this

Excuse	Reality
"The code looks correct, no need to run it"	Looking is not verification. Run it, or say plainly that you didn't.
"It's a tiny change, testing is overkill"	Tiny changes break production the same way big ones do; the check is tiny too.
"I'm confident this works"	Confidence is not evidence. State what you observed, not what you expect.
"While I'm here, I'll also clean up/improve X"	Not requested is not in scope. Name it to the user, don't do it.
"This needs one more file than planned, I'll just keep going"	Past ~3 files or an architecture fork, stop and re-present the plan.
"No time to verify, just ship it"	An unverified "done" costs more later than the minute it takes to check now.

All of these mean: stop, verify or scope-check first, then continue.

STACK

• Existing repo: detect the stack from lockfiles, configs, and neighboring code; match its versions and patterns. Check CLAUDE.md / README for house rules first.
• New project: ask once (batched into Clarify). If the user says "you pick", use the defaults in references/new-project.md and name your choices in the plan.

DESIGN BAR (UI work)

In an existing app, adopt its existing palette, type scale, spacing, and components; house style wins. The bar below is for NEW UI surfaces and greenfield projects:

• Commit before styling to: one chosen neutral (slight hue bias, not pure gray) plus ONE accent; semantic colors (success/warn/error) separate from the accent; a type scale of 4-5 sizes; one spacing scale. Layout via flex/grid with gap, not margins.
• Avoid the generated-look tells: purple-to-blue gradient heroes, emoji as section markers, everything centered, rounded-xl cards on everything, untouched component library defaults, Inter-for-everything, lorem ipsum. Use real content. Unconditional for ALL UI work, new or existing: visible focus states, readable contrast, prefers-reduced-motion respected, keyboard operability. For any UI-bearing task, read references/frontend.md from this skill's own folder (the base directory shown when this skill loads) BEFORE proposing the stack or plan, and always before writing UI code: it holds the modern-platform and per-framework specifics.