@event4u/agent-config 1.13.0 → 1.14.0

package/.agent-src/skills/flux/SKILL.md

@@ -1,18 +1,36 @@
 ---
 name: flux
-description: "Use when writing Laravel Flux UI components — the official Livewire component library by the Laravel team. Covers components, slots, and variants."
+description: "Stack-implementation skill for Laravel Flux — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project uses `livewire/flux`. Covers Flux components, slots, variants, and form primitives."
 source: package
 ---
 
 # flux
 
+## Positioning — dispatched, not standalone
+
+`flux` is the **primitive-library executor** for projects on the Livewire + Flux stack. Invoked by [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py) once the design brief is locked, and revisited by `review.py` / `polish.py` during the design-review loop. Does **not** own the flow, drive the audit, or lock the design.
+
+| Concern | Owner |
+|---|---|
+| Audit + token inventory (mandatory pre-step) | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) |
+| Design brief (layout / states / microcopy) | [`directives/ui/design.py`](../../templates/scripts/work_engine/directives/ui/design.py) |
+| Universal design heuristics | [`fe-design`](../fe-design/SKILL.md) |
+| Component logic / state / actions | [`livewire`](../livewire/SKILL.md) |
+| Static Blade partials | [`blade-ui`](../blade-ui/SKILL.md) |
+
 ## When to use
 
-Use when building UI with Flux components in a project that uses `livewire/flux`.
+Cite this skill when:
+
+- Project depends on `livewire/flux` and `directives/ui/apply.py` dispatches Flux primitives
+- Building forms, modals, dropdowns, toasts, or other standard UI elements Flux already provides
 
 Do NOT use when:
+
 - Raw Blade templates without Flux (use `blade-ui` skill)
-- Livewire component logic (use `livewire` skill)
+- Livewire component logic / state (use `livewire` skill)
+- React + shadcn (use `react-shadcn-ui` skill)
+- Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
 
 ## Procedure: Create a Flux view
 
@@ -44,9 +62,18 @@ Do NOT use when:
 1. Blade view using Flux components with correct props and slots
 2. Livewire component class if interactive behavior is needed
 
+### Review pass — a11y findings + preview envelope
+
+When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
+
+Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+
 ## Gotcha
 
-- The model tends to use old Flux API syntax — always check latest docs.
+- Model tends to use old Flux API syntax — always check latest docs.
 - Flux has built-in validation display — don't add manual error rendering alongside it.
 - Don't mix Flux with raw HTML form elements in the same form.
 

package/.agent-src/skills/guideline-writing/SKILL.md

@@ -4,6 +4,8 @@ description: "Use when creating or editing a guideline in .agent-src.uncompresse
 source: package
 ---
 
+<!-- cloud_safe: degrade -->
+
 # guideline-writing
 
 ## When to use
@@ -109,8 +111,8 @@ Above the split signal, break by sub-topic into sibling files in the same folder
   → 0 FAIL (guidelines have relaxed linting but must still parse).
 * Run `bash scripts/compress.sh --sync` → regenerates `.agent-src/guidelines/`.
 * Run `python3 scripts/check_references.py` → no broken links.
-* Run the full CI pipeline locally — each script directly — must exit 0
-  except for tolerated warnings.
+* Run the full CI pipeline locally (see `Taskfile.yml` in this repo for
+  the script list) — must exit 0 except for tolerated warnings.
 
 ## Output format
 
@@ -135,6 +137,26 @@ Above the split signal, break by sub-topic into sibling files in the same folder
 * Do NOT create an orphan guideline with no inbound links
 * Do NOT edit `.agent-src/guidelines/` or `.augment/guidelines/` — generated
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the package's
+`scripts/check_references.py`, `scripts/skill_linter.py`, and `task`
+runner are not reachable. The skill still applies — with prose-only
+validation:
+
+* Emit the full guideline file as a copyable Markdown block. Do not
+  attempt to write to disk.
+* Self-check the frontmatter: `description` only, no `type`, no
+  `alwaysApply`.
+* Self-check the body: reference material, no numbered procedures,
+  named in a topic folder.
+* Tell the user to save under
+  `.agent-src.uncompressed/guidelines/{topic}/{name}.md` and run
+  `task sync && task lint-skills && task check-refs` locally before
+  committing.
+* Do not call the linter, ref-checker, or compressor — they only
+  run on the user's machine.
+
 ## Examples
 
 Good guideline name + description:

package/.agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -68,7 +68,7 @@ Before proceeding, the learning MUST pass all gates:
 | Repetition | Occurred 2+ times OR clearly generalizable? |
 | Impact | Improves correctness, reliability, or consistency? |
 | Failure pattern | Prevents a real, observed failure? |
-| Non-duplication | No existing rule/skill/guideline covers this? |
+| Non-duplication | No existing rule/skill/guideline/command covers this? **Verify via § 4 search protocol — a negative grep alone is not proof.** |
 | Scope fit | Fits rule, skill, or guideline? |
 | Minimal | Update existing preferred over creation? |
 
@@ -115,11 +115,53 @@ Choose one:
 * Update existing guideline
 * **Nothing** (baseline knowledge, standard tool usage, one-off)
 
-### 4. Check for overlap
+### 4. Check for overlap — search protocol (mandatory)
 
-* Does a similar rule already exist?
-* Does a similar skill already exist?
-* Would a small update be better than a new file?
+A grep that returns zero hits is **not** proof of no overlap. Knowledge in
+this package is distributed across **four surfaces** — `skills/`, `rules/`,
+`guidelines/`, `commands/`. Skip any of them and recall drops to ~25 %.
+Run all four steps before declaring "no overlap":
+
+**Step 1 — list all four surfaces.** Directory taxonomy is free evidence:
+
+```bash
+ls .agent-src.uncompressed/skills/ \
+   .agent-src.uncompressed/rules/ \
+   .agent-src.uncompressed/guidelines/ \
+   .agent-src.uncompressed/commands/
+```
+
+Sub-directories matter — `guidelines/php/patterns/`, `guidelines/agent-infra/`,
+etc. carry topic taxonomies a flat file scan misses. Always descend one level.
+
+**Step 2 — grep with both vocabularies.** Search for **solution-words** *and*
+**problem-words**. Solution-only grep is confirmation bias — the existing
+artifact may name the *symptom*, not the cure.
+
+| Vocabulary | Example for "agents miss Strategy pattern, write switch chains" |
+|---|---|
+| Solution-words | `strategy`, `registry`, `polymorph`, `interface` |
+| Problem-words | `discriminator`, `enum.*match`, `switch.*on`, `if.*else.*chain` |
+
+```bash
+grep -rl -E "<solution-words>|<problem-words>" .agent-src.uncompressed/
+```
+
+**Step 3 — taxonomy scan.** For any topic with a likely sub-folder
+(`patterns/`, `php/`, `laravel/`, `agent-infra/`), `ls` that folder
+*before* reading any file. Filename alone often answers the overlap question.
+
+**Step 4 — sample, do not just list.** On *any* keyword overlap from
+steps 2–3, **open and skim the 3 nearest matches** — read § headings, the
+"When to use" / "Overview" block, and the examples list. Listing filenames
+is not enough; semantic overlap hides behind unrelated keywords.
+
+Only after all four steps return clean → declare "no overlap" and proceed.
+Citation in the proposal: *"Reviewed before drafting: <files skimmed>"* —
+this is the audit trail § 0's Non-duplication gate verifies against.
+
+→ When the parent task is "create a new artifact", `artifact-drafting-protocol`
+Phase B (Research) requires this same protocol — single source of truth.
 
 ### 5. Draft the content
 
@@ -169,9 +211,9 @@ Mandatory fields the draft MUST fill:
 * `Success signal` (§7) — one metric, one baseline, one target, one
   evaluation date
 
-Run `python3 scripts/check_proposal.py agents/proposals/<id>.md` before
-handing to `upstream-contribute`. The
-script is a hard gate: non-zero exit = the proposal does not move
+Run `./agent-config proposal:check agents/proposals/<id>.md`
+before handing to `upstream-contribute`. The
+gate is hard: non-zero exit = the proposal does not move
 to stage `gated`.
 
 ## Output format
@@ -183,7 +225,7 @@ For the **decision step** (what this skill prints to the user):
 3. Rationale in one to three lines
 4. If decision ≠ "no action": path of the written proposal
    (`agents/proposals/<proposal_id>.md`) and gate status
-   (`check_proposal.py` exit 0 = ready for review)
+   (`./agent-config proposal:check` exit 0 = ready for review)
 
 The **proposal file itself** follows
 `proposal.example.md` verbatim — all ten sections, YAML frontmatter

package/.agent-src/skills/livewire/SKILL.md

@@ -1,18 +1,35 @@
 ---
 name: livewire
-description: "Use when writing Livewire components — reactive state, events, lifecycle hooks, and clean separation between component logic and Blade templates."
+description: "Stack-implementation skill for Livewire — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Livewire. Covers reactive state, events, lifecycle hooks, and component/view separation."
 source: package
 ---
 
 # livewire
 
+## Positioning — dispatched, not standalone
+
+`livewire` is the **apply-step executor** for the Livewire stack. Invoked by [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py) once the design brief is locked, and revisited by `review.py` / `polish.py` during the design-review loop. Does **not** own the flow, drive the audit, or lock the design.
+
+| Concern | Owner |
+|---|---|
+| Audit + token inventory (mandatory pre-step) | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) |
+| Design brief (layout / states / microcopy) | [`directives/ui/design.py`](../../templates/scripts/work_engine/directives/ui/design.py) |
+| Universal design heuristics | [`fe-design`](../fe-design/SKILL.md) |
+| Static Blade partials inside the view | [`blade-ui`](../blade-ui/SKILL.md) |
+| Flux primitives inside the view | [`flux`](../flux/SKILL.md) |
+
 ## When to use
 
-Use when creating or editing Livewire components — reactive state, forms, tables, real-time updates.
+Cite this skill when:
+
+- `state.stack.frontend == "livewire"` and `directives/ui/apply.py` dispatches to this skill
+- Editing or creating Livewire components — reactive state, forms, tables, real-time updates
 
 Do NOT use when:
-- Static Blade views (use `blade-ui` skill)
-- Flux UI components (use `flux` skill)
+
+- Static Blade views with no interactivity (use `blade-ui` skill)
+- Flux UI primitives (use `flux` skill — `livewire` composes Flux internally)
+- Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
 
 ## Procedure: Create a Livewire component
 
@@ -58,6 +75,15 @@ Do NOT use when:
 1. Livewire component class with typed properties and actions
 2. Blade view with wire: bindings and Flux components
 
+### Review pass — a11y findings + preview envelope
+
+When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
+
+Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+
 ## Gotcha
 
 - Public properties serialize between requests — don't put large objects in state.

package/.agent-src/skills/md-language-check/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: md-language-check
+description: "Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone."
+source: package
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 30
+  allowed_tools: []
+  command:
+    - python3
+    - scripts/check_md_language.py
+---
+
+# md-language-check
+
+## When to use
+
+Fire **before** saving any `.md` file under:
+
+- `.agent-src.uncompressed/` (source of truth)
+- `.agent-src/` (compressed projection)
+- `.augment/` (local agent projection)
+- `agents/` (project roadmaps, contexts, sessions)
+
+Per [`language-and-tone`](../../rules/language-and-tone.md) § "`.md`
+files are ALWAYS English" + § Detection heuristic, every `.md` in
+those trees must be English. Bilingual content lives only in labeled
+`DE: … · EN: …` anchor blocks.
+
+Do NOT use when:
+
+- Editing project content outside the trees above
+- Reviewing non-`.md` files (checker rejects them)
+
+## Procedure
+
+### 1. Identify the file(s) about to be saved
+
+Collect every `.md` path the agent is about to create or modify this
+turn. Multiple files → one invocation.
+
+### 2. Run the checker
+
+```bash
+python3 scripts/check_md_language.py <path> [<path> …] [--format json]
+```
+
+Exit codes: `0` clean, `1` violations (save **blocked** until fixed
+or suppressed), `3` internal error.
+
+### 3. Resolve findings
+
+| Kind | Cause | Fix |
+|---|---|---|
+| `umlaut` | German prose in body | Translate to English |
+| `de_word` | German function word in unquoted prose | Translate; or move into `DE: … · EN: …` block |
+
+Meta-doc that **must** quote German tokens (e.g. the heuristic in
+`language-and-tone.md` itself) → append
+`<!-- md-language-check: ignore -->` to that single line. Never as a
+wholesale silencer.
+
+### 4. Re-run and confirm
+
+After every fix re-run on the same paths. Save proceeds only on `0`.
+
+## Allowed escape hatches
+
+- **Labeled anchor** — lines starting with `DE:` / `- DE:` / `* DE:`
+  (and the same for `EN:`) auto-skipped.
+- **Fenced code blocks** — exempt; shell snippets, JSON fixtures,
+  quoted user input pass through.
+- **Inline code** — backtick spans stripped before scanning.
+- **Per-line marker** — `<!-- md-language-check: ignore -->` on lines
+  that genuinely quote German tokens (rare).
+
+## Output format
+
+1. One-line summary: `clean` or `N violation(s) found`
+2. Per violation: `file:line — kind \`match\`` plus the offending line
+3. Next action: translate, move into a `DE:`/`EN:` block, add the
+   per-line ignore marker, or revert
+
+## Gotchas
+
+- `.md` files only; non-`.md` paths emit a warning and skip
+- Word list is short and conservative — clean run is **necessary
+  but not sufficient**; agent owns the final language judgement
+- Frontmatter (`--- … ---`) is exempt
+
+## Do NOT
+
+- Do NOT silence by deleting trigger words from
+  `scripts/check_md_language.py`; extend the allow-list instead
+- Do NOT use the ignore marker as a generic mute
+- Do NOT skip the gate "because the file is small"
+
+## Cloud Behavior
+
+Cloud surfaces (Claude.ai Web, Skills API) ship without the script,
+so this skill is **inert** there — apply the heuristic from
+[`language-and-tone`](../../rules/language-and-tone.md) manually.

package/.agent-src/skills/php-coder/SKILL.md

@@ -37,6 +37,30 @@ Do NOT use when:
 → See guideline `php/general.md` for detailed PHP conventions.
 → See guideline `php/controllers.md`, `php/eloquent.md`, etc. for domain-specific conventions.
 
+### Step 3: Stop-gate — branching on a discriminator?
+
+Before writing **a second** `match`/`switch` arm, **a second** `if/elseif`
+branch, or **a second** class hardcoded to one enum/string value (e.g.
+`Provider::FOO->value`, `'stripe'`, a `case Type::CSV`), STOP and run the
+Strategy sniff test.
+
+Trigger keywords in the task or surrounding code:
+
+- enum/string used as a type-tag: `Provider`, `Type`, `Channel`, `Format`,
+  `Driver`, `Kind`
+- repeated `match ($x)` / `switch ($x)` blocks on the same value
+- class names that bake a single enum case in: `StripeImportService`,
+  `CsvExporter`, `Ks21Job` next to `GeoCaptureJob` with the same shape
+- allowlist constants: `private const SUPPORTED_FOO = [Type::A, Type::B]`
+
+→ Run the sniff test in
+[`guidelines/php/patterns/strategy.md`](../../guidelines/php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
+Two "yes" answers → propose Strategy + Registry **before** adding the new
+branch. Three "yes" → it is already overdue and the refactor is the change.
+
+This gate fires **per task**, not per file — once you've passed the sniff
+test for a given discriminator, do not re-ask on the next branch.
+
 ### Core principles
 
 - **KISS** — simplest solution that works. No over-engineering.

package/.agent-src/skills/react-shadcn-ui/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: react-shadcn-ui
+description: "Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack."
+source: package
+---
+
+# react-shadcn-ui
+
+## Compatibility
+
+- **Tested against:** `shadcn@2.1`, Tailwind CSS `3.x`, React `18+`.
+- Audit step (`directives/ui/audit.py`) reads the line above and compares it with `state.ui_audit.shadcn_inventory.version`; major mismatch triggers a soft halt before this skill runs.
+
+## When to use
+
+Use when `state.stack.frontend == "react-shadcn"` and `directives/ui/apply.py`, `review.py`, or `polish.py` dispatches to this skill, or when a React project clearly uses shadcn/ui (presence of `components.json`, `@radix-ui/*` dependencies, a `components/ui/` folder of generated primitives).
+
+Do NOT use when:
+
+- Project is Blade + Livewire + Flux (use `flux` / `livewire` / `blade-ui`).
+- Project is Vue (use the Vue stack skills).
+- Plain React without shadcn/ui — fall back to manual composition; this skill assumes the primitive set exists.
+
+## Gotcha
+
+- shadcn/ui is **not** an npm package. Primitives are copied into `components/ui/` and edited in-place. Do not `npm install shadcn-ui`. Run `npx shadcn@latest add <primitive>` to scaffold; then edit.
+- Major-version drift between this skill's `## Compatibility` line and the project's installed primitives is a real risk. Audit step writes `state.ui_audit.shadcn_inventory` with the detected version — when it diverges by a major, audit emits a soft halt before this skill runs.
+- shadcn/ui composes Radix primitives. Accessibility built in via Radix but only when wrapper components used correctly (`asChild`, `<DialogTrigger>` instead of bare `<button>`).
+- Tailwind tokens come from `tailwind.config.{js,ts}` (`theme.extend.colors`) and CSS custom properties on `:root` and `.dark` (`--background`, `--foreground`, `--primary`, `--ring`, …). Audit writes them into `state.ui_audit.design_tokens`. Use those tokens; do not hardcode values.
+- Dark mode is class-based (`<html class="dark">`). Every color must come from `bg-background`, `text-foreground`, etc. — never raw `bg-white`.
+- Every interactive primitive must declare a focus-visible state via `focus-visible:ring-2 focus-visible:ring-ring`; comes free with generated primitives but easy to remove during a refactor.
+
+## Covered primitives
+
+Validated against the following shadcn primitives at the declared version:
+
+- **Form / inputs:** `Button`, `Input`, `Textarea`, `Checkbox`, `RadioGroup`, `Select`, `Switch`, `Label`, `Form` (react-hook-form wrapper + `zodResolver`).
+- **Overlay:** `Dialog`, `Sheet`, `Popover`, `Tooltip`, `DropdownMenu`, `AlertDialog`.
+- **Layout:** `Card`, `Separator`, `Tabs`, `Accordion`, `ScrollArea`.
+- **Data display:** `Table` (with `@tanstack/react-table`), `Badge`, `Avatar`, `Skeleton`, `Progress`.
+- **Feedback:** `Toast` (sonner), `Alert`.
+
+## Not covered — fall back to manual composition
+
+- Marketing-only components (Hero, Pricing, Features) — outside shadcn/ui.
+- `Calendar` / `DatePicker` — composition skill required, not generated.
+- `Combobox` — built from `Command` + `Popover`; case-by-case.
+- Streaming / partial-prerender boundaries — use the project's framework patterns (Next.js / Remix), not shadcn/ui.
+
+## Procedure: render a shadcn/ui component for the design brief
+
+### Step 0: Inspect
+
+1. Read `state.ui_audit.shadcn_inventory.version` and confirm it matches the version in `## Compatibility` within the same major. If audit flagged a mismatch, user already chose to proceed — note that in `state.changes`.
+2. Read `state.ui_audit.design_tokens` — every color, spacing, and radius in rendered output must reference a token from this map.
+3. Read `state.ui_design`:
+   - `components` → the primitive list to compose.
+   - `microcopy` → button labels, empty-state text, validation messages. **Lock — render verbatim.**
+   - `states` → empty / loading / error / success / disabled coverage.
+   - `a11y` → ARIA labels, keyboard nav, focus order.
+
+### Step 1: Compose primitives
+
+1. Import primitives from project's `components/ui/` path (`@/components/ui/button`, …) — never from `shadcn` or `radix-ui`.
+2. Compose Radix-style: `<Dialog>` → `<DialogTrigger asChild>` → `<DialogContent>` → `<DialogHeader>` → `<DialogTitle>`. Never wrap `DialogTrigger` around a pre-styled `<button>`; pass `asChild`.
+3. Use variant API of `Button` (`variant="default" | "destructive" | "outline" | "secondary" | "ghost" | "link"`); do not override with raw Tailwind for the variant set.
+4. Forms: `useForm` (react-hook-form) + `zodResolver(schema)` → `<Form>` → `<FormField>` → `<FormItem>` → `<FormLabel>` → `<FormControl>` → `<FormMessage>`. Validation messages come from the zod schema, mirrored to design-brief microcopy.
+
+### Step 2: Apply tokens, dark mode, a11y
+
+1. Colors via semantic classes: `bg-background`, `text-foreground`, `bg-primary text-primary-foreground`, `text-muted-foreground`. No `bg-white` / `text-black` / hardcoded `#fff`.
+2. Spacing / radius from theme tokens (`rounded-lg` mapped to `--radius` in `tailwind.config.{js,ts}`). Polish refactors hardcoded values when a token equivalent exists.
+3. Dark mode: never branch on a `dark` prop; rely on `.dark` class on root and semantic tokens.
+4. Every interactive primitive: keyboard trigger present (Enter/Space on buttons, Esc on dialogs — Radix free), visible focus ring, `aria-label` from `state.ui_design.a11y` when icon-only.
+
+### Step 3: State coverage
+
+1. Empty: render design-brief empty-state copy in a `Card` or inline placeholder; never `null`.
+2. Loading: `Skeleton` rows for tables; `Button` `disabled` + `Loader2` icon for submit-in-flight.
+3. Error: `Alert variant="destructive"` with design-brief message; `FormMessage` for field-level errors.
+4. Success: `toast.success(...)` from `sonner` with design-brief confirmation copy.
+5. Disabled: `disabled` prop on trigger plus design-brief reason as `aria-describedby` text.
+
+### Step 4: Validate
+
+1. No raw `<input>` / `<button>` / `<select>` outside the primitive set.
+2. No hardcoded colors / spacing — every value is a token.
+3. Microcopy matches `state.ui_design.microcopy` byte-for-byte.
+4. Dark mode: toggle `.dark` on `<html>`, render the component, every surface still legible (no `text-white on bg-white`).
+5. Keyboard: Tab through every focusable element; focus ring visible.
+
+## Output format
+
+1. React component file(s) under project's `components/` (or `app/`) tree, importing primitives from `@/components/ui/*`.
+2. Per file, one entry recorded in `state.changes` with `kind="ui"`, `stack="react-shadcn"`, and the design-brief summary.
+
+### Review pass — a11y findings + preview envelope
+
+When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Run a11y tool against rendered output (e.g. `axe-core` via Playwright, `@axe-core/react`, `jest-axe`) and translate hits into this shape. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
+
+Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+
+## Do NOT
+
+- Do NOT install `shadcn-ui` from npm — primitives are scaffolded.
+- Do NOT hardcode colors / spacing / radii — use the token map.
+- Do NOT branch on a `dark` prop — use semantic tokens + the `.dark` class.
+- Do NOT rewrite microcopy — it is locked by `state.ui_design`.
+- Do NOT skip `asChild` on `DialogTrigger` / `SheetTrigger` / similar Radix wrappers — breaks the accessibility contract.
+- Do NOT introduce a non-shadcn UI library (MUI, Chakra) into the same surface — pick one system per surface.
+
+## Auto-trigger keywords
+
+- shadcn / shadcn ui / shadcn/ui
+- React component (when project uses shadcn)
+- Radix primitive
+- Tailwind dark mode
+- React Hook Form + zod