@friedbotstudio/create-baseline 0.1.0

package/obj/template/.claude/skills/copywriting/references/natural-transitions.md

@@ -0,0 +1,272 @@
+# Natural Transitions
+
+Transitional phrases to guide readers through your content. Good signposting improves readability, user engagement, and helps search engines understand content structure.
+
+Adapted from: University of Manchester Academic Phrasebank (2023), Plain English Campaign, web content best practices
+
+---
+
+## Contents
+- Previewing Content Structure
+- Introducing a New Topic
+- Referring Back
+- Moving Between Sections
+- Indicating Addition
+- Indicating Contrast
+- Indicating Similarity
+- Indicating Cause and Effect
+- Giving Examples
+- Emphasising Key Points
+- Providing Evidence (neutral attribution, expert quotes, supporting claims)
+- Summarising Sections
+- Concluding Content
+- Question-Based Transitions
+- List Introductions
+- Hedging Language
+- Best Practice Guidelines
+- Transitions to Avoid (AI Tells)
+
+## Previewing Content Structure
+
+Use to orient readers and set expectations:
+
+- Here's what we'll cover...
+- This guide walks you through...
+- Below, you'll find...
+- We'll start with X, then move to Y...
+- First, let's look at...
+- Let's break this down step by step.
+- The sections below explain...
+
+---
+
+## Introducing a New Topic
+
+- When it comes to X,...
+- Regarding X,...
+- Speaking of X,...
+- Now let's talk about X.
+- Another key factor is...
+- X is worth exploring because...
+
+---
+
+## Referring Back
+
+Use to connect ideas and reinforce key points:
+
+- As mentioned earlier,...
+- As we covered above,...
+- Remember when we discussed X?
+- Building on that point,...
+- Going back to X,...
+- Earlier, we explained that...
+
+---
+
+## Moving Between Sections
+
+- Now let's look at...
+- Next up:...
+- Moving on to...
+- With that covered, let's turn to...
+- Now that you understand X, here's Y.
+- That brings us to...
+
+---
+
+## Indicating Addition
+
+- Also,...
+- Plus,...
+- On top of that,...
+- What's more,...
+- Another benefit is...
+- Beyond that,...
+- In addition,...
+- There's also...
+
+**Note:** Use "moreover" and "furthermore" sparingly. They can sound AI-generated when overused.
+
+---
+
+## Indicating Contrast
+
+- However,...
+- But,...
+- That said,...
+- On the flip side,...
+- In contrast,...
+- Unlike X, Y...
+- While X is true, Y...
+- Despite this,...
+
+---
+
+## Indicating Similarity
+
+- Similarly,...
+- Likewise,...
+- In the same way,...
+- Just like X, Y also...
+- This mirrors...
+- The same applies to...
+
+---
+
+## Indicating Cause and Effect
+
+- So,...
+- This means...
+- As a result,...
+- That's why...
+- Because of this,...
+- This leads to...
+- The outcome?...
+- Here's what happens:...
+
+---
+
+## Giving Examples
+
+- For example,...
+- For instance,...
+- Here's an example:...
+- Take X, for instance.
+- Consider this:...
+- A good example is...
+- To illustrate,...
+- Like when...
+- Say you want to...
+
+---
+
+## Emphasising Key Points
+
+- Here's the key takeaway:...
+- The important thing is...
+- What matters most is...
+- Don't miss this:...
+- Pay attention to...
+- This is critical:...
+- The bottom line?...
+
+---
+
+## Providing Evidence
+
+Use when citing sources, data, or expert opinions:
+
+### Neutral attribution
+- According to [Source],...
+- [Source] reports that...
+- Research shows that...
+- Data from [Source] indicates...
+- A study by [Source] found...
+
+### Expert quotes
+- As [Expert] puts it,...
+- [Expert] explains,...
+- In the words of [Expert],...
+- [Expert] notes that...
+
+### Supporting claims
+- This is backed by...
+- Evidence suggests...
+- The numbers confirm...
+- This aligns with findings from...
+
+---
+
+## Summarising Sections
+
+- To recap,...
+- Here's the short version:...
+- In short,...
+- The takeaway?...
+- So what does this mean?...
+- Let's pull this together:...
+- Quick summary:...
+
+---
+
+## Concluding Content
+
+- Wrapping up,...
+- The bottom line is...
+- Here's what to do next:...
+- To sum up,...
+- Final thoughts:...
+- Ready to get started?...
+- Now it's your turn.
+
+**Note:** Avoid "In conclusion" at the start of a paragraph. It's overused and signals AI writing.
+
+---
+
+## Question-Based Transitions
+
+Useful for conversational tone and featured snippet optimization:
+
+- So what does this mean for you?
+- But why does this matter?
+- How do you actually do this?
+- What's the catch?
+- Sound complicated? It's not.
+- Wondering where to start?
+- Still not sure? Here's the breakdown.
+
+---
+
+## List Introductions
+
+For numbered lists and step-by-step content:
+
+- Here's how to do it:
+- Follow these steps:
+- The process is straightforward:
+- Here's what you need to know:
+- Key things to consider:
+- The main factors are:
+
+---
+
+## Hedging Language
+
+For claims that need qualification or aren't absolute:
+
+- may, might, could
+- tends to, generally
+- often, usually, typically
+- in most cases
+- it appears that
+- evidence suggests
+- this can help
+- many experts believe
+
+---
+
+## Best Practice Guidelines
+
+1. **Match tone to audience**: B2B content can be slightly more formal; B2C often benefits from conversational transitions
+2. **Vary your transitions**: Repeating the same phrase gets noticed (and not in a good way)
+3. **Don't over-signpost**: Trust your reader; every sentence doesn't need a transition
+4. **Use for scannability**: Transitions at paragraph starts help skimmers navigate
+5. **Keep it natural**: Read aloud; if it sounds forced, simplify
+6. **Front-load key info**: Put the important word or phrase early in the transition
+
+---
+
+## Transitions to Avoid (AI Tells)
+
+These phrases are overused in AI-generated content:
+
+- "That being said,..."
+- "It's worth noting that..."
+- "At its core,..."
+- "In today's digital landscape,..."
+- "When it comes to the realm of..."
+- "This begs the question..."
+- "Let's delve into..."
+
+See the seo-audit skill's `references/ai-writing-detection.md` for a complete list of AI writing tells.

package/obj/template/.claude/skills/design-ui/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: design-ui
+owner: baseline
+description: Orchestrates `impeccable` for every design task inside a workflow phase. Captures intent in natural language, classifies it (design / development / copy), translates design intents into a sequence of impeccable subcommand invocations, runs them in main context with state persistence at `.claude/state/design/<slug>.json`, and returns a structured report. ALWAYS invokes `impeccable` under the hood for the underlying design move; never picks aesthetic direction itself; never writes product code directly. Per CLAUDE.md Article X.2, all design tasks in workflow phases route through this skill.
+---
+
+# design-ui — the impeccable orchestrator
+
+You are the routing layer between workflow phases and the vendored `impeccable` skill. Phase orchestrators (`/tdd` Step 6, `/chore`, `/document`) and direct user invocations hand you a `task_brief`; you classify it, translate it to an impeccable recipe, run the recipe step-by-step, persist state for resume, and return a structured `Report`. Every design move ultimately routes through `Skill(impeccable, "<cmd>", "<args>")` — you never originate a design artifact yourself.
+
+This skill is **first-party and freely editable**. The skill it orchestrates (`impeccable`) is **vendored Apache 2.0 and never edited**.
+
+## Architectural commitments
+
+These are not preferences. They are structural commitments locked by spec `docs/specs/design-ui-orchestrator.md` and constitutional commitment CLAUDE.md Article X.2:
+
+- **You ALWAYS invoke impeccable.** Every design move goes through `Skill(impeccable, …)`. No exceptions, no shortcuts.
+- **You NEVER pick aesthetic direction.** Register, palette, type scale, motion vocabulary — all decided inside impeccable's subcommands in main context. You decide *which* subcommand to invoke, not *what* design to produce.
+- **You NEVER write product code.** Files under `app/`, `site-src/`, `components/`, `src/` — all flow through impeccable's writing subcommands (`craft`, `polish`, refines, enhances, fixes). You write only thin glue: state JSON, brief snapshots, audit snapshots.
+- **You ALWAYS classify before acting.** A misrouted `task_brief` (development or copy concern) returns immediately with `final_state: "not_a_design_task"` and a pointer to the correct lane. Design tasks proceed; everything else stops at Stage 0.
+
+## Mandatory first step
+
+Invoke `Skill(code-structure)` before writing any file — even the thin-glue ones. The layer model applies: SKILL.md is orchestration, the `references/` files are domain, helper scripts (if any) are foundation.
+
+## Inputs the caller must provide (the `task_brief`)
+
+```jsonc
+{
+  "concern":           "design",                   // REQUIRED, fixed literal. Stage 0 asserts this.
+  "intent":            "<natural-language>",       // REQUIRED. The design ask in plain English.
+  "slug":              "<kebab-case>" | null,      // OPTIONAL. If null, derived from intent's first noun phrase.
+  "target_files":      ["<path>", ...] | "—",       // REQUIRED. Paths under design treatment. "—" for surface-less intents.
+  "write_set":         ["<glob>", ...],             // REQUIRED. The broader scope the design move may touch.
+  "register_override": "brand" | "product" | null, // OPTIONAL. Overrides PRODUCT.md for this call.
+  "references":        ["<url-or-path>", ...]      // OPTIONAL. Inspiration sources (URLs, image paths).
+}
+```
+
+If `concern` is missing or any of `intent` / `target_files` / `write_set` are missing for a non-surface-less recipe, **stop and ask** — do not infer. Stage 1 (capture) refuses incomplete briefs.
+
+## The four stages
+
+### Stage 0 — Classify
+
+Decide which lane this `task_brief` belongs to. The classification rule lives in [`references/design-vs-development.md`](references/design-vs-development.md): per-concern split between **design**, **development**, **copy** lanes.
+
+Stage 0 evaluates two signals: (1) the intent string against the [`references/intent-table.md`](references/intent-table.md) rows, and (2) the `target_files` extensions as a tie-breaker.
+
+If the classification is anything other than **design**, return immediately:
+
+```jsonc
+{
+  "final_state": "not_a_design_task",
+  "correct_lane": "/tdd" | "/document",
+  "reason": "<plain-language rationale>",
+  "state_file": ".claude/state/design/<slug>.json"
+}
+```
+
+design-ui still writes a checkpoint state file even on misroute — the orchestration history is traceable.
+
+### Stage 1 — Capture
+
+Once Stage 0 confirms `concern == "design"`:
+
+1. Verify `PRODUCT.md` exists at the project root. If missing or placeholder (< 200 chars, contains `[TODO]`), invoke `Skill(impeccable, "teach")` to populate it, then resume.
+2. Verify `DESIGN.md` exists. If missing, nudge once ("Run `$impeccable document` for more on-brand output") and proceed.
+3. Resolve the slug: use `task_brief.slug` if provided; otherwise derive kebab-case from the intent's first noun phrase (≤ 40 chars).
+4. Persist the initial state to `.claude/state/design/<slug>.json` per [`references/state-machine.md`](references/state-machine.md): `{slug, started_at, intent, register, state: "in_progress", step_index: 0}`.
+5. Verify `target_files` parents exist when applicable. If a parent directory is missing, persist `state: "blocked"` and return with `reason: "target_files parent directory missing"`.
+
+### Stage 2 — Translate
+
+Look up the intent in [`references/intent-table.md`](references/intent-table.md). The first matching row wins. Each row produces:
+
+- A **recipe**: an ordered list of impeccable subcommand names (from the vocabulary: `shape`, `craft`, `teach`, `document`, `extract`, `critique`, `audit`, `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize`, `live`).
+- A **mode**: `auto` (single-step or atomic; execute without prompting) or `ask` (multi-step; surface the plan and await `proceed`).
+
+For multi-step recipes (`mode == "ask"`), print the plan:
+
+> "Recipe: `[shape, craft, audit]`. Proceed? (or describe an override)"
+
+Wait for the user. On `proceed`, advance to Stage 3. On override, re-run Stage 2 with the adjusted intent. On refusal, persist `state: "blocked"` and return.
+
+For single-step / atomic recipes (`mode == "auto"`), advance to Stage 3 without prompting.
+
+If no row matches, the intent is ambiguous: surface to the user per the catch-all rule in `references/design-vs-development.md`.
+
+### Stage 3 — Orchestrate
+
+Execute the recipe step-by-step per [`references/orchestration.md`](references/orchestration.md):
+
+```
+for each step in recipe:
+  pre-checkpoint -> state JSON {step_index, next_cmd}
+  invoke         -> Skill(impeccable, "<cmd>", "<args>")
+  capture        -> read return value (output_path, files_written, score)
+  branch         -> apply gates (see orchestration.md)
+  post-checkpoint -> state JSON {step_index++, invocations[], verifications[]}
+```
+
+The orchestration gates:
+
+- **Gate 1 — P0 blocks.** If the previous `audit` returns `P0 ≥ 1`, do NOT auto-chain to `polish`. Block and surface.
+- **Gate 2 — P1 loops with cap 3.** If `P0 == 0` and `P1 ≥ 1`, run `polish` then re-audit. Loop up to 3 iterations. After iteration 3's final audit, if P1 > 0, terminate with `needs_human`. **No fourth iteration runs.**
+- **Gate 3 — Recipe mode.** Already handled at Stage 2; auto recipes pass through, ask recipes have already been approved.
+- **Gate 4 — Target-file existence.** Already verified at Stage 1; re-checked before any write step.
+- **Gate 5 — Register conflict.** If `task_brief.register_override` mismatches `PRODUCT.md`, surface the conflict to the user before proceeding.
+
+### Stage 4 — Report
+
+Return a structured `Report`:
+
+```jsonc
+{
+  "slug":              "<the slug>",
+  "intent":            "<the intent>",
+  "recipe_executed":   ["shape", "craft", "audit", "polish"],
+  "final_state":       "complete" | "needs_human" | "blocked" | "not_a_design_task",
+  "files_touched":     ["<path>", ...],
+  "verifications":     { "audit_score": "19/20", "p0": 0, "p1": 0 },
+  "next_actions":      ["<human-readable>"],
+  "state_file":        ".claude/state/design/<slug>.json",
+  "thin_glue_written": ["docs/design/<slug>.brief.md", "docs/design/<slug>.audit.md"]
+}
+```
+
+The caller (workflow phase or user) reads `final_state` and acts per the policy in [`references/orchestration.md`](references/orchestration.md) (the caller-policy table).
+
+## What you write (thin glue only)
+
+You write exactly these file kinds. Anything else is impeccable's territory.
+
+| File | Role |
+|---|---|
+| `.claude/state/design/<slug>.json` | The live state checkpoint. Written before AND after each impeccable invocation. Shape in [`references/state-machine.md`](references/state-machine.md). |
+| `docs/design/<slug>.brief.md` | Human-readable snapshot of impeccable `shape`'s output. Materialized after the `shape` step. |
+| `docs/design/<slug>.audit.md` | Human-readable snapshot of impeccable `audit`'s report. Materialized after each `audit` step (overwritten — latest audit only). |
+
+**Forbidden writes**:
+- Product code (`app/**`, `site-src/**`, `components/**`, `src/**`, `**/*.tsx`, `**/*.jsx`, `**/*.vue`, `**/*.svelte`, `**/*.css`, `**/*.njk`) — these flow through impeccable's writing subcommands.
+- `DESIGN.md` and `PRODUCT.md` — these flow through `impeccable teach` and `impeccable document`.
+- `.claude/skills/impeccable/**` — vendored, untouchable per Article IX.
+- `docs/specs/**` — `spec_approval_guard` blocks; specs are written by `Skill(spec)`.
+- Anywhere outside the thin-glue contract above.
+
+## Where you plug into the workflow
+
+- **`/tdd` Step 6** — Invokes `Skill(design-ui, task_brief)` once per declared row in the spec's `## Design calls` section, gated on the implement step's `write_set` intersecting `project.json → tdd.ui_globs`. Re-runs `verify` afterward.
+- **`/chore`** — When a chore touches files under `tdd.ui_globs` for design reasons, the chore routes through design-ui.
+- **`/document`** — When documentation includes UI surface renders (screenshots, component captures), `document` can drive design-ui for capture-time visual verification.
+- **Direct user** — `Skill(design-ui, task_brief)` from main context for ad-hoc design work outside a workflow phase.
+
+Per CLAUDE.md Article X.2, design tasks **inside a workflow phase** SHALL route through design-ui. Direct `/impeccable …` invocations for ad-hoc exploration outside a phase remain permitted.
+
+## Constraints (non-negotiable)
+
+- **Always invoke impeccable for design moves.** No file-content design decisions made inline in this skill.
+- **Always classify before acting.** Stage 0 runs first; misroutes return immediately.
+- **Always persist state.** Every step has a pre- and post-checkpoint. A killed orchestration must be resumable.
+- **Never edit the vendored `impeccable` skill.** Article IX vendoring discipline.
+- **Never write product code.** Only the thin-glue paths above.
+- **Never approve specs or write to `docs/specs/`.** Spec writing is `Skill(spec)`'s territory.
+- **Never run `git commit` or `git push`.** Commits happen in `/commit`.
+- **Honor the 3-iteration cap on `audit → polish` loops.** No fourth iteration runs. Terminate with `needs_human` per `references/orchestration.md`.
+- **Honor P0 blocking.** Never auto-loop past a P0 finding. Surface and block.
+- **Honor register overrides explicitly.** A `register_override` that conflicts with PRODUCT.md prompts the user; never silently accept.
+
+## References
+
+- [`references/design-vs-development.md`](references/design-vs-development.md) — Stage 0 classification rules: design vs development vs copy, per-concern.
+- [`references/intent-table.md`](references/intent-table.md) — Stage 2 translation table: ~21 intent patterns → impeccable recipes.
+- [`references/orchestration.md`](references/orchestration.md) — Stage 3 gates, loop logic, caller-policy matrix.
+- [`references/state-machine.md`](references/state-machine.md) — State file shape, terminal states, resume rule.

package/obj/template/.claude/skills/design-ui/references/design-vs-development.md

@@ -0,0 +1,89 @@
+# Design vs development vs copy
+
+Stage 0 of `design-ui` classifies an incoming `task_brief` into one of three lanes. Only the **design** lane proceeds through `design-ui`; the other two return early with `final_state: "not_a_design_task"` and a pointer to the correct lane.
+
+The split is **per-concern**, not per-file. A single source file (say `app/settings/page.tsx`) may carry behavior, surface, and prose all at once; each concern routes through its own lane, and the same file gets touched by all three over the lifetime of the feature.
+
+## The three lanes
+
+| Lane | Concerns | Routes through | Examples of intent phrasing |
+|---|---|---|---|
+| **Design** | Surface, motion, layout, typography, spacing, color, hierarchy, identity moments, register, visual accessibility (focus rings, contrast, motion-reduce) | `design-ui` → `impeccable` | "build a settings page that doesn't feel like a SaaS template" · "polish the FAQ" · "fix typography on `/cli/`" · "make the hero bolder" · "add motion to the buttons" · "adapt the docs for mobile" |
+| **Development** | Behavior, event handlers, data flow, state machines, validation logic, business rules, API integration, error-handling logic, performance optimizations behind the surface | `/tdd` → `scenario` → `implement` → `verify` | "add input validation to the settings form" · "implement the save handler" · "add error retry to the save endpoint" · "fix the off-by-one in the pagination" · "add tests for the auth flow" |
+| **Copy** | Body prose, marketing copy, README sections, documentation bodies, PR descriptions, microcopy when it's the prose itself (not the visual treatment) | `/document` → `prose` (which always invokes `humanizer`, conditionally invokes `copywriting` / `documentation` / `technical-tutorials`) | "rewrite the install instructions" · "improve the README" · "draft the launch announcement" · "polish the error messages' wording" |
+
+## Per-concern classification rule
+
+When a `task_brief` arrives, Stage 0 evaluates **two signals** in order:
+
+1. **Intent string match** — see `references/intent-table.md`. Each row names an intent pattern and the lane it belongs to. The first matching row decides.
+2. **`target_files` heuristic** — if the intent is ambiguous (no row matches OR a row matches but the intent could also fit another lane), inspect `target_files`:
+   - All paths match `tdd.ui_globs` AND no logic-file extensions → **design**.
+   - All paths are logic files (`.ts`, `.js`, `.go`, `.py`, `.rs`, etc., excluding `.tsx` / `.jsx` / `.vue` / `.svelte`) → **development**.
+   - All paths are `.md` / `.mdx` and the intent mentions "write", "rewrite", "improve", "draft" → **copy**.
+   - Mixed → return to step 1 with the user surfaced; ask which concern they mean.
+
+## Overlap is normal — same file, three lanes
+
+A single feature commonly cycles through all three lanes:
+
+| Sequence | Lane | What lands |
+|---|---|---|
+| 1. `/tdd` writes failing tests for behavior, then implements them | Development | `app/settings/page.tsx` gets the onSubmit handler, validation logic, data binding |
+| 2. `/tdd` Step 6 invokes `design-ui` per the spec's `## Design calls` | Design | Same file gets the type scale, spacing, motion, focus rings, hover states — via `impeccable craft` / `polish` |
+| 3. `/document` invokes `prose` for any user-facing text the spec marks | Copy | Same file's button labels, headings, error messages get rewritten through `prose` → `humanizer` |
+
+The lanes do not contend; they touch different parts of the same file. A button has:
+- behavior (the `onClick` handler) — development
+- surface (the size, padding, color, transition) — design
+- copy (the label text the user reads) — copy
+
+Each part routes to the lane that owns its concern.
+
+## Edge cases
+
+### Error states and loading states
+
+The **logic** that decides "we are in an error state" / "we are loading" belongs to **development**. The **visual treatment** of those states (skeleton shape, error illustration, retry button placement, micro-animation) belongs to **design**. The **wording** of the error message belongs to **copy**.
+
+### Forms
+
+Layout, label typography, focus rings, hover affordance, motion → **design**.
+Validation logic (which fields are required, regex constraints), submit handler, server integration → **development**.
+Field labels, helper text, validation error wording → **copy**.
+
+### A11y
+
+Per WCAG 2.1 AA: focus rings, color contrast, motion-reduce honoring → **design**. Keyboard event handlers, `aria-*` attribute logic when it depends on state → **development**. Alt text and screen-reader copy → **copy**.
+
+### Tokens (design-system level)
+
+"Extract reusable tokens from the brand" or "promote the code-window palette to tokens" — these are **design** intents (specifically the `extract` recipe via `impeccable extract`). They touch CSS variable declarations and the design system file; they are surface concerns, not behavior.
+
+### Performance
+
+Visual performance (image loading, animation jank, layout shift, paint cost) — **design** via `impeccable optimize`.
+Backend / data-fetching performance, query optimization, memoization for re-render avoidance — **development**.
+
+## Misroute handling
+
+If Stage 0 classifies the intent as **development** or **copy** (not design), `design-ui` immediately returns:
+
+```jsonc
+{
+  "final_state": "not_a_design_task",
+  "correct_lane": "/tdd" | "/document",
+  "reason": "<plain-language classification rationale>",
+  "state_file": ".claude/state/design/<slug>.json"  // checkpoint written even on misroute
+}
+```
+
+The caller (a workflow phase or the user) reads `correct_lane` and re-routes. `design-ui` never silently passes a non-design brief through to `impeccable` — that would muddy impeccable's contract.
+
+## When in doubt
+
+If the per-concern split is ambiguous *and* both signals (intent string + target_files) fail to resolve, surface to the user with a one-line question:
+
+> "This task seems to span design and development: <intent>. Which concern are you asking about? (a) design — surface, motion, visual a11y; (b) development — behavior, logic, data; (c) both, in sequence — start with `/tdd` for behavior, then this skill for design."
+
+Do not guess. The clean separation is what makes the lanes structural.

package/obj/template/.claude/skills/design-ui/references/intent-table.md

@@ -0,0 +1,64 @@
+# Intent table — natural-language intent → impeccable recipe
+
+Stage 2 of `design-ui` reads a `task_brief.intent` string and translates it to a sequence of `impeccable` subcommand invocations. This file is that translation table. Each row matches an intent pattern; the first match wins.
+
+`impeccable` ships ~21 subcommands organized in five categories: Build (`shape`, `craft`, `teach`, `document`, `extract`), Evaluate (`critique`, `audit`), Refine (`polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`), Enhance (`animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive`), Fix (`clarify`, `adapt`, `optimize`), Iterate (`live`). Each recipe row below names commands by their exact vocabulary so `design-ui` can mechanically dispatch `Skill(impeccable, "<cmd>", "<args>")`.
+
+## Reading the table
+
+Columns:
+- **Intent pattern** — the regex / keyword the intent string is matched against. Case-insensitive.
+- **Recipe** — the sequence of impeccable subcommands in order.
+- **Mode** — `auto` (single-step or "atom"; no user approval needed) or `ask` (multi-step; surface the plan and await `proceed`).
+- **Notes** — when this row earns vs. when a different row should match.
+
+The "polish atom" (`audit → polish → audit`) is treated as a **single** step from the orchestrator's point of view: design-ui's Stage 3 runs it as one unit and loops internally (cap 3 — see `orchestration.md`). It is `auto` because the user already said "polish" — they don't need to re-approve the audit they implicitly invoked.
+
+The "build atom" (`shape → craft → audit`) is multi-step and `ask`: `shape` produces a design brief that the user reviews before the destructive `craft` step writes code.
+
+## The table
+
+| Intent pattern | Recipe | Mode | Notes |
+|---|---|---|---|
+| `/^build\b\|^create\b\|^add a\b/i` | shape → craft → audit | ask | Net-new surface. Multi-step → user approves the plan after `shape` before `craft` writes files. |
+| `/^plan\b\|^sketch\b\|^explore\b/i` | shape | auto | Plan only; caller will implement themselves. Single step. |
+| `/^review\b\|^score\b/i` | critique ∥ audit | auto | Parallel evaluation: critique (UX scoring) AND audit (technical). Read-only. |
+| `/^polish\b\|^finish\b\|^ship\b/i` | audit → polish → audit | auto | Polish atom. Loops internally up to 3 iterations (orchestration.md). Single-step from the orchestrator's POV. |
+| `/^make .+ bolder\b\|^amplify\b\|^louder\b/i` | bolder → audit → polish | ask | Refinement with verification. Multi-step. |
+| `/^too aggressive\b\|^too loud\b\|^quieter\b\|^tone down\b/i` | quieter → audit → polish | ask | Opposite of bolder. |
+| `/^distill\b\|^strip\b\|^reduce\b/i` | distill → audit → polish | ask | Remove complexity. |
+| `/^harden\b\|^add error states\b\|^add loading states\b\|^add edge cases\b/i` | harden → audit | ask | Production-ready pass. |
+| `/^typography\b\|^fix typography\b\|^typeset\b/i` | typeset → audit | ask | Targeted type-system pass. |
+| `/^spacing\b\|^layout\b\|^fix spacing\b\|^rhythm\b/i` | layout → audit | ask | Targeted spacing / hierarchy pass. |
+| `/^color\b\|^colorize\b\|^palette\b/i` | colorize → audit | ask | Targeted color / palette pass. |
+| `/^add (motion\|animation)\b\|^animate\b/i` | animate → audit | ask | Motion pass with perf re-check. |
+| `/^add delight\b\|^add personality\b\|^make it delightful\b/i` | delight → audit | ask | Personality moments. |
+| `/^adapt\b\|^make .+ (mobile\|responsive)\b\|^responsive\b/i` | adapt → audit | ask | Multi-viewport pass. |
+| `/^clarify\b\|^improve copy\b\|^rewrite (labels\|errors\|microcopy)\b/i` | clarify → audit | ask | UX writing pass; pairs with `prose` skill for body copy. |
+| `/^optimize\b\|^perf\b\|^performance\b/i` | optimize → audit | ask | Visual perf pass (paint, layout shift, motion budget). |
+| `/^onboard\b\|^first[- ]run\b\|^empty state\b\|^activation\b/i` | onboard → polish | ask | Activation-flow design. |
+| `/^match (this )?reference\b\|^like the/i` | shape (with references) → craft → audit | ask | Inspiration-anchored build. `task_brief.references` populates the shape brief. |
+| `/^iterate\b\|^variants\b\|^live\b/i` | live | auto | Visual variant exploration in the browser. Single step. |
+| `/^extract\b\|^pull (out )?tokens\b\|^promote.+to tokens\b/i` | extract | auto | Token / component extraction. Single step. |
+| `/^overdrive\b\|^push (past )?conventional\b/i` | overdrive → audit → polish | ask | Maximalism mode. Three steps, ask before running. |
+| `(no match)` | — | — | Ambiguous intent; route to user clarification per `design-vs-development.md`. |
+
+## How a row is selected
+
+1. Lower-case the intent string, strip leading whitespace.
+2. Scan rows top-to-bottom. First regex that matches wins.
+3. If `target_files` is empty AND no row matches, the intent is surface-less; default recipe is `live` if the intent contains "browser" / "preview" / "iterate", else `extract` if "tokens" / "promote". Otherwise return `not_a_design_task` with a request for clarification.
+4. If a row matches but `target_files` is empty for an intent that normally needs a target (e.g., `polish`, `harden`), Stage 1 (capture) asks the user for `target_files` before Stage 2 (translate) commits.
+
+## Single-step vs multi-step (auto vs ask)
+
+- **auto**: design-ui runs the recipe without surfacing it. Used when the user's intent is unambiguous AND the recipe is one impeccable subcommand OR a self-contained atom (audit→polish→audit treated as one unit for orchestrator purposes).
+- **ask**: design-ui prints the plan ("Recipe: [shape, craft, audit]. Proceed? (or override)") and waits for the user to type `proceed` (or supply an override). Used for any recipe that's truly multi-step at the orchestrator level.
+
+The mode column above reflects this distinction. Stage 3 (orchestrate) reads the mode and gates accordingly.
+
+## Adding a new row
+
+If a future intent doesn't fit any row above, add a new one *here* before extending Stage 2 logic. The rule of thumb: the row must (a) name a known impeccable subcommand (no inventing new ones), (b) carry a recipe that ends in an evaluation step (`audit` or `critique`) for verification, and (c) classify cleanly as `auto` or `ask`.
+
+Do not add rows that map to `Skill(design-ui, …)` recursively — design-ui is the orchestrator, not a target.