Web Studio

web-studio

Orchestration only — this skill does not itself design or write code. It asks the questions in order, dispatches each stage to the right tool, and enforces the gates. The creative judgment lives in the the-designer agent; the build lives in Claude; validation lives in a second model.

Setup check (once per environment — confirm, don't assume)

1. The Designer: confirm the-designer is a registered subagent (new files in ~/.claude/agents/ register at session start, not mid-session).
2. Second model (stages 4/6 — optional): if the OpenAI Codex CLI is installed, verify with codex exec --skip-git-repo-check "reply OK" < /dev/null. Any other model CLI works if it can take a prompt and return text synchronously. If none is available: run those checks yourself, mechanically, and say so in the receipt — don't skip them, don't pretend a second model ran.
3. Image generation (stage 3 — optional): any CLI/MCP that can generate an image from a text prompt. If it offers a cost-estimate command, always estimate before creating. If none is available, the site ships with CSS/SVG art direction instead of generated media — note it in the receipt.
4. Fonts: check the project's font choices against your font guide's license notes before shipping. Never ship a personal-use-only font on a commercial site.
5. Studio Memory (see docs/MEMORY.md): ensure ~/.web-studio/ exists with TASTE.md, PATTERNS.md, FAILURES.md, JOB-LOG.md; create empty files on first run and note the cold start in the run log. Never block on memory — but never skip the read/write contract either.
6. The Library: ensure ~/.web-studio/library/<project-slug>/ exists for this project (brand/, images/, video/, source/, MANIFEST.md) — the canonical home for every asset this run makes or receives. Supplied assets (logos, fonts, references) are copied into brand//source/ with a MANIFEST.md provenance line before anything else uses them.

The questionnaire (ask one at a time, in order — do not batch)

1. Mode — best-quality (frontier model everywhere, no cost ceiling — the default) or tiered? Tiered means: the frontier model keeps the director and judge seats (stages 1, 2, 7), a cheaper model does the mechanical build (stage 5) with DESIGN.md + the signed direction as its complete brief, and the second model gates/reviews (stages 4, 6). Community benchmarks of this split report ~96% of all-frontier quality at roughly half the cost — the catch is discipline: the build model makes zero design decisions not already written in DESIGN.md.
2. Site type — product launch, brand/portfolio, dashboard, editorial/story-scroll, other?
3. The one-line success test — "When someone leaves this page, what's the single most important thing they should feel or do?" This is the pass/fail bar stage 7 scores against — not decoration.
4. Design direction — open-ended ("bold and vibrant") or "let the Designer pick."
5. Brand input mode — one of three: (a) pure imagination — no assets; the Designer invents the system. (b) extract from a live reference — the user names a live site whose standard they want matched: open it in a browser and measure it (computed palette, real font stacks, spacing rhythm) rather than describing it from memory; the extraction feeds stage 2's DESIGN.md. Match the standard, don't clone the site. (c) reference contract — the user has screenshots/URLs/taste notes: before any direction is committed, sort every reference into Keep / Change / Do-not-copy and record the sorting as a short contract in the project. References contribute structure and standards; identity stays original. In every mode, supplied fonts get a license check before use.
6. The product description — free text, the actual brief.
7. Concepts — 1 (recommended: get the first prompt right rather than paying for parallel iterations) or up to 3 for comparison.
8. Media/audio — generated media defaults to no audio (the single biggest render-cost lever). Confirm.
9. Receipt destination — on the site, in chat, or both (default both).

The 9-stage run

Log every stage transition to runs/<run_id>.jsonl (schema in runs/README.md). A run with no log file didn't happen.

1. Spar — first, initialize the project-scoped gate: node ~/.claude/hooks/direction-gate.js --init <project_dir> — from this moment, all Write/Edit into the project directory is machine-blocked. Then invoke the-designer with the questionnaire answers as the brief. It commits a one-sentence Direction Declaration and signs: node ~/.claude/hooks/direction-gate.js --sign <project_dir> "<direction>" (project-scoped — no session ids involved, so subagents can sign). Halt if unsigned — nothing downstream runs on an uncommitted direction. Persist the output as DIRECTION-BRIEF.md in the project.
2. Brand shot — same agent writes the project's DESIGN.md (templates/DESIGN-md-template.md — the official Google design.md spec shape: YAML token front matter + prose rationale) plus a complete art-direction brief for each media asset: subject, material, light, mood, crop, color story (hex-anchored), explicitly text-free. A bare noun prompt is never dispatched. Because the template is spec-shaped, any conforming community design.md drops in as an alternative input (see the template header) — but The Designer still signs a direction against it; a borrowed system never bypasses the gate. Input modes (b) and (c) from question 5 feed this stage.
3. Render — estimate cost first if the tool supports it; then generate. Audio off unless the questionnaire said otherwise. Log actual spend. Save canonical-first: the full-quality output lands in ~/.web-studio/library/<project>/images/ (or video/) with a MANIFEST.md line (prompt, model, credits, date) — the site folder gets a web-optimized derivative, never the only copy. Check the shelf before spending: if the library already holds a usable asset for this brief (earlier run, earlier concept), reuse it — never re-generate what exists. If render succeeds and a later stage fails, never silently re-render — report spend and ask before spending more.
4. Gate — second model audits the render plan + running spend. Prompt it to reply in exactly: FLAGS: <none|list> | BUDGET_OK: <yes|no> | NOTE: <one line>. Zero design opinions — discard any aesthetic suggestion.
5. Build — the site is built per DESIGN.md: its palette verbatim, its type pairing, its signature moves, its taste rules. Self-hosted fonts, semantic HTML, responsive by default, prefers-reduced-motion respected. In tiered mode (question 1), the cheaper model builds here from DESIGN.md alone — if it needs a design decision the file doesn't answer, that's a stage-2 gap: route the question to The Designer, don't let the build model improvise. Commit a checkpoint.
6. Review — three passes, in order — measure before you judge: (a) programmatic checks — serve the site over HTTP (never file:// — stale-snapshot risk) and run scripts/visual-checks.js in the page console at mobile (375px) and desktop (1280px) widths: viewport overflow, whole-page horizontal scroll, broken images, sub-40px tap targets. Collect console errors via your tool. Findings feed the review; they don't replace it. (b) second model checks links, receipt math, brief consistency — plus the programmatic findings — same no-design-opinions rule; (c) actually look at the rendered page at desktop AND mobile widths. Fix what's broken, re-check from (a), commit a checkpoint.
7. Verify — mechanical pre-flight first, judgment second. The Designer loads the Studio Memory at stage 1 and writes back here: on PASS ≥7.5, pattern → ~/.web-studio/PATTERNS.md, case study → ~/.web-studio/JOB-LOG.md (plus the project's own job log) — paths stated in the output or the write-back didn't happen. Mechanics: run a checkable sweep before invoking The Designer — default-palette tells (the stock purple/indigo-gradient family on dark, unmodified template blues), centered-stack layouts where the direction called for asymmetry, CTA contrast below WCAG AA, more than one competing CTA intent per viewport, motion breaking the DESIGN.md motion policy (non-transform/opacity animation, entries over 300ms, missing reduced-motion fallback). Checkable failures never spend judgment time. Then the-designer in QA mode: craft rubric, its named anti-patterns, a polish pass, PASS/FLAG with a numeric score. On PASS ≥7.5/10, append the case study to the project's job log and state the file path in the output — a verify step with no named log path didn't happen. Below 7.5 or hard FLAG: report the specific flags, don't silently patch and re-ship.
8. Deploy — ship it (any host; if your image tool has its own site hosting, that works too). Localhost is not done. Custom domain is a question, not an assumption.
9. Receipt — write COST-RECEIPT.md (templates/COST-RECEIPT-template.md): models used, actual credits/tokens spent per the run log (never an estimate), audio decision + why, deploy URL, total. Deliver per the questionnaire's answer.

Iteration rule

If the user rejects the output ("bland", "not it"), that's a stage 5–7 loop, not a restart: the Direction Declaration and DESIGN.md survive unless the user rejects the direction itself. Ask which it is if unclear. Log the rejection to ~/.web-studio/TASTE.md immediately — one calibration line (what was rejected, in what register, what to start with next time), plus a FAILURES.md entry when the rejected move is specific. Rejections are the highest-value taste data the studio ever receives; a rejection without a taste line will be repeated on the next build.

Non-goals

• Small edits to an existing site — invoke the-designer directly, skip the 9-question intake.
• This skill never makes a design decision itself. Every aesthetic call routes to the Designer.
• Never ship a font whose license you haven't checked.