One-time setup · for Repeat and Automate
Install the workers
Custom subagents are small files Claude Code loads as named workers. Save each block below into your project's .claude/agents/ folder (for example .claude/agents/studies-generator.md). Once installed, the Repeat and Automate prompts call them by name, so the model, tools and rules are fixed and stop drifting. Install once per project, not per run.
studies-generator.md
--- name: studies-generator description: Generates one UI concept from an assigned aesthetic and interaction model. model: sonnet tools: Read, Write --- You are a senior product designer. Read brief.md and anti-patterns.md in the run folder. You will be given one AESTHETIC and one INTERACTION MODEL; both are non-negotiable, do not drift to safer choices. Use the frontend-design skill. Produce two files: designs/.html a self-contained single-file page that opens in any browser with no build step. The primary interaction must actually work. Output HTML, never .tsx or .jsx. designs/ .interaction.md the navigation model, each state, keyboard/focus/ARIA behaviour, mobile changes, and which anti-patterns you avoided. Satisfy the brief's key flows and handle its listed states, not just the happy path. Return only the two paths and one sentence on the central idea.
studies-judge.md
--- name: studies-judge description: Scores one candidate against the rubric. Read-only. model: sonnet tools: Read --- You are a design and UX auditor. Read rubric.md and anti-patterns.md and the candidate you are given plus its .interaction.md. Score every rubric dimension 1 to 5 with one concrete justification tied to what is actually in the files. Score interaction and state from the .interaction.md. Apply the AI-tell penalty; a justified, well-executed use of an otherwise-clichéd pattern is not penalised. Judge the design, not its verbosity; boldness that breaks the brief scores low on fit. Return only valid JSON: id, scores, ai_tell_penalty, ai_tells_found, weighted_total, strengths, weaknesses. You never edit files.
studies-verifier.md
--- name: studies-verifier description: Checks one candidate for a single anti-pattern. Read-only, skeptic. model: haiku tools: Read --- You check whether one specific anti-pattern (given to you) is present in one candidate. Be a skeptic to limit false positives: only flag a clear, unjustified instance of the unthinking default. Return JSON: anti_pattern, present (true/false), one-line evidence. You never edit files.
studies-refiner.md
--- name: studies-refiner description: Refines one shortlisted candidate against the human's feedback. Does not redesign. model: sonnet tools: Read, Write --- You refine a strong candidate, not redesign it. Read the original, its .interaction.md, its audit JSON, and this candidate's block in shortlist.md. The human's Keep and Change are AUTHORITATIVE over the audit. PRESERVE everything under Keep plus the central idea and interaction model. FIX everything under Change, then any flagged AI-tell. Do not swap the navigation pattern, change fonts wholesale, or touch anything unflagged. Keep accessibility intact. Output a self-contained .html and update its .interaction.md. Return a 2-line changelog of what you kept and what you changed.
studies-reviewer.md
--- name: studies-reviewer description: Re-scores a refined candidate and confirms whether weaknesses are resolved. Read-only. model: sonnet tools: Read --- You re-score a refined candidate against rubric.md and report whether each prior weakness from its audit is now resolved. Return JSON: id, scores, weighted_total, resolved (list), unresolved (list). If anything is unresolved, say so plainly so the loop can run again. You never edit files.
studies-previewer.md
--- name: studies-previewer description: Verifies every design renders and assembles the index.html record. model: haiku tools: Read, Write, Bash --- For each designs/*.html, headlessly load it in real Chrome, capture console errors, confirm the main content is populated. If one fails, fix the preview harness (CDN imports, Babel automatic JSX runtime), never the design. Build designs/index.html: embed studies_diverge_converge_node_graph.svg at the top with an amber ring on the current step node, then list every candidate with a single-click link and one-line description, ordered by audit score if audit/scores.json exists. After Step 2 include the plain-language rationale; after Step 4 include the changelogs and keep pre-refine versions with a compare link. Do not write "double-click". Do not init git or deploy.
Step 0 · you decide
Setup
You author three files: brief.md, rubric.md and anti-patterns.md. Then CC drafts matrix.md from your brief for you to approve. This is identical across all three tiers, because it is where your intent enters as rules the workers follow.
Help me write brief.md for a Studies run. Interview me one question at a time, wait for each answer, do not pad. Ask, in order: 1. What are you building? (the one surface, not the whole product) 2. Who is it for, how technical are they, how often do they use it? 3. What problem does it solve, and where does success or trust come from? 4. What are the key user flows, start to finish? 5. What states occur? (empty, loading, error, edge) 6. Desktop-first, mobile-first, or parity? 7. Does it render any system or process I should design around? When I have answered, draft brief.md, show a one-screen summary, let me correct it. Once the brief is approved, draft matrix.md from it using the matrix boilerplate: keep the eligible-patterns library, the aesthetic list, the coverage rule and the sanity check, and fill only the per-candidate aesthetic x interaction cells (default 8). Show me the matrix to approve. Do not generate any designs. End your reply by telling me to author rubric.md and anti-patterns.md from boilerplate, then run Step 1.
Below is my unstructured thinking about a surface I want to design. Read it, then draft brief.md from it. For anything missing or ambiguous (audience, problem, key flows, states, device priority, any system the UI must render), ask me targeted questions one at a time, only for the gaps. Do not invent answers. When the gaps are filled, show a one-screen summary and let me correct it. Once the brief is approved, draft matrix.md from it using the matrix boilerplate (fill only the per-candidate cells, default 8). Show me the matrix to approve. No designs yet. End your reply by telling me to run Step 1 next. MY THINKING: [ dump everything: what it is, who it is for, why it matters, half-formed flows, references, constraints ]
rubric.md boilerplate
| Dimension | Weight | 1 | 5 | |---|---|---|---| | Hierarchy and legibility | 0.18 | nowhere for the eye to land | instant scan path | | Brief fit | 0.20 | ignores the job | nails the job | | Interaction fit | 0.22 | wrong pattern for the task | obvious-in-hindsight pattern | | Flow and state coverage | 0.15 | happy path only | empty/loading/error/edge handled | | Distinctiveness and craft | 0.15 | generic, sloppy | memorable, meticulous | | Accessibility (incl. interaction) | 0.10 | fails AA, no keyboard/focus | clears AA, focus/escape/ARIA/kbd | | AI-tell penalty | minus up to 1.0 | | subtract per anti-pattern present | Optional surface-specific dimension: add one for what is uniquely hard about THIS surface, rebalance to 1.00.
anti-patterns.md boilerplate
## Surface-specific tells (fill per run) [ tells unique to this domain. Leave blank if none. ] ## Visual tells - Left-border accent stripe on cards or messages - Purple or violet gradients, especially on white - Inter / Roboto / system-font defaults - Sparkle iconography on generate or AI actions - Uniform three-card grid with icon-title-blurb ## Interaction tells - Floating circular chat bubble pinned bottom-right - Centered single-column chat with suggestion chips - Skeleton loaders on everything as the only loading state - Modal-for-everything where a drawer or inline fits better NOTE: avoidance is not contrarianism. If a pattern is the right tool, use it well.
matrix.md frame (CC fills it)
## Eligible interaction patterns (CC deletes the wrong ones) master-detail / progressive reveal / activity stream / split view / command palette / spatial node graph / document-centric / spotlight focus / drill-down inspector / timeline / wizard / bottom sheet ## Aesthetic directions (distinct; no two candidates the same feel) Swiss / Brutalist / Editorial / Glassmorphic / Industrial / Refined minimal / Data-dense / Calm focus / Terminal-mono / Maximalist ## Candidate assignments (CC fills from the brief; you approve) 01 [aesthetic] x [interaction model] ... to N, crossing distinct cells on BOTH axes ## Coverage rule No interaction pattern more than twice; no two candidates share both axes.
Step 1 · Claude Code runs it
Generate
CC spawns one worker per matrix row in parallel, each forced into its assigned look and interaction model, plus one baseline as the control. You paste the prompt; CC does the rest.
Orchestrate Step 1. Read brief.md, rubric.md, matrix.md and anti-patterns.md. For each row in matrix.md, spawn one generator sub-agent in parallel. Give each its assigned AESTHETIC and INTERACTION MODEL (non-negotiable), and have it use the frontend-design skill. Each produces designs/.html (self-contained, opens with no build step, primary interaction works, HTML never .tsx) and designs/ .interaction.md (navigation, states, keyboard/focus/ARIA, mobile, anti-patterns avoided). Each returns only the two paths and one sentence. Also generate one baseline (no cell) as designs/00-baseline.html. Then run prompts/preview-build.md to verify renders and build designs/index.html. Give me a one-line index. End your reply by telling me to run Step 2.
Orchestrate Step 1. Read brief.md, matrix.md, anti-patterns.md. For each row in matrix.md, invoke the studies-generator subagent in parallel, passing that row's aesthetic and interaction model. Invoke studies-generator once more with no assigned cell for designs/00-baseline (the control). Then invoke studies-previewer to verify renders and build designs/index.html. Give me a one-line index. End your reply by telling me to run Step 2.
Step 2 · Claude Code runs it
Audit
You paste the prompt, then CC judges on its own. A fresh judge scores each candidate against your rubric and reads its interaction spec. No candidate judges its own work.
Orchestrate Step 2. Read rubric.md and anti-patterns.md. For each candidate in designs/ including 00-baseline, spawn an independent judge sub-agent (not the generators). Each reads the candidate and its .interaction.md, scores every rubric dimension 1 to 5 with one concrete justification, applies the AI-tell penalty, and returns JSON: id, scores, ai_tell_penalty, ai_tells_found, weighted_total, strengths, weaknesses. Aggregate and rank into audit/scores.json and write the plain-language rationale for index.html. Show me the ranked board including the baseline. Then stop for the gate. End your reply by telling me to open the previews, then run Step 3.
Orchestrate Step 2. For each candidate in designs/ including 00-baseline, invoke the studies-judge subagent (it scores against rubric.md and returns JSON). Optionally invoke studies-verifier per anti-pattern entry. Aggregate and rank into audit/scores.json, then invoke studies-previewer to write the rationale into index.html. Show me the ranked board including the baseline. Then stop for the gate. End your reply by telling me to open the previews, then run Step 3.
Step 3 · you decide
Gate
The one decision point, and it is the same in every tier. CC presents the top five and stops. You open the previews, actually click them, then pick three with Keep and Change feedback. Your feedback overrides the judges where they disagree.
Run Step 3. Read audit/scores.json. Confirm the previews in designs/ open; a single click on a link in designs/index.html opens each one. Present the top 5 as a table: rank, id, aesthetic x interaction, score, AI-tells, the one watch-out, the path to open, and a one-line "what to try". Then STOP. I will reply with my picks. Use AskUserQuestion to collect them, and when a piece of my feedback could apply to other picks, ask whether to apply it to them too. Write my selection verbatim to audit/shortlist.md, then confirm. End your reply by telling me to run Step 4.
SHORTLIST (3 picks) PICK 1 : candidateWhy it advances: Keep (do not change): Change or fix: PICK 2 : candidate ... PICK 3 : candidate ... Overall direction (optional):
Step 4 · Claude Code runs it
Refine
CC refines all three picks against your feedback. A refiner applies your Keep and Change, a separate reviewer re-scores, looping until the rubric is met or two rounds pass. Originals are preserved.
Orchestrate Step 4. Read audit/shortlist.md. For each of the 3 picks, run a refiner then a separate reviewer, max 2 rounds, stopping when the reviewer confirms the rubric is met. Refiner: the human's Keep and Change are AUTHORITATIVE over the audit; preserve Keep plus the central idea and interaction model, fix Change then any flagged AI-tell, do not redesign. Output designs/refined/.html and update its .interaction.md. Keep originals. Rebuild index.html via prompts/preview-build.md. Show me the 3 changelogs. End your reply with: "Run the Step 5 prompt. Step 5 will ask which of the three to finalise, and you can add feedback when you reply."
Orchestrate Step 4. Read audit/shortlist.md. For each of the 3 picks, invoke studies-refiner then studies-reviewer, looping max 2 rounds, stopping when the reviewer confirms the rubric is met. Keep originals; do not overwrite. Invoke studies-previewer to rebuild index.html, keeping pre-refine versions with a compare link. Show me the 3 changelogs. End your reply with: "Run the Step 5 prompt. Step 5 will ask which of the three to finalise, and you can add feedback when you reply."
Step 5 · Claude Code runs it
Finalise
Where you choose the winner. CC asks which of the three refined picks to finalise and takes any last feedback, then writes a clean standalone HTML file plus a thorough interaction and README spec to final/, ready to hand to CC in another project.
Run Step 5. First, use AskUserQuestion to ask which of the three refined picks (A, B, C) I want to finalise, and invite optional last feedback to apply before finalising. Wait for my answer. Then, applying any feedback, produce in final/: a clean self-contained standalone .html (interactions working, real content where I provide it, any preview-only shortcut such as a Tailwind CDN resolved), and a thorough README + interaction spec (every state, every keyboard path, the interaction model, the anti-patterns honoured) as the contract a future project rebuilds against. Write only to final/. Do not init git, do not deploy, do not touch another repo. End your reply by telling me the run is complete and pointing me to final/.