@event4u/agent-config 5.10.0 → 6.0.0

package/dist/agent-src/skills/existing-ui-audit/SKILL.md

@@ -0,0 +1,217 @@
+---
+model_tier: high
+name: existing-ui-audit
+description: "Use BEFORE writing or editing any non-trivial UI — inventories components, design tokens, shadcn primitives, and reusable patterns into state.ui_audit. Hard gate for the ui directive set."
+personas:
+  - frontend-engineer
+domain: discovery
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# existing-ui-audit
+
+> **Interplay:** this audit answers *what exists* (components, tokens,
+> primitives → `state.ui_audit`);
+> [`design-intelligence`](../design-intelligence/SKILL.md) answers *what to
+> build* (corpus-grounded style/token/typography/pattern selection).
+> Audit runs first; its reuse findings outrank corpus suggestions — never
+> let a grounded recommendation introduce a component the inventory
+> already covers.
+
+## When to use
+
+Use this skill when:
+- The dispatcher has routed work to `directive_set="ui"` (intent `ui-build` or `ui-improve`)
+- A `mixed` flow is about to enter its UI phase
+- The user asks "what UI do we already have for X?"
+
+Do NOT use when:
+- `directive_set="ui-trivial"` — the trivial path bypasses audit by precondition (≤1 file, ≤5 lines, no new component, no new state, no new dep)
+- `directive_set="backend"` — no UI surface to inventory
+- The audit findings already exist in `state.ui_audit` for this state-file (cached) — re-run only if `package.json` or `composer.json` mtime changed
+
+## Procedure: Audit the existing UI surface
+
+### 0. Inspect stack and input
+
+1. Read `state.stack.frontend` — set by `scripts/work_engine/stack/detect.py` (one of `blade-livewire-flux`, `react-shadcn`, `vue`, `plain`).
+2. Read `state.input` — the request being processed. The audit must answer: "what already exists that is similar to this request?"
+
+### 1. Enumerate components and templates
+
+| Stack | Where to look |
+|---|---|
+| `blade-livewire-flux` | `resources/views/components/`, `resources/views/livewire/`, `resources/views/partials/`, `resources/views/layouts/`, `app/View/Components/`, `app/Livewire/` |
+| `react-shadcn` | `components/`, `app/components/`, `src/components/`, `src/app/(routes)/`, plus any `app/**/page.tsx` for Next.js |
+| `vue` | `resources/js/components/`, `src/components/`, `pages/` |
+| `plain` | `resources/views/`, plus any `*.html` under `public/` |
+
+Capture each component/template as: `{path, name, kind: page|partial|component|layout, exports?: [props]}`.
+
+### 2. Identify the design system
+
+Detect markers, in order. **Stop at the first match** — projects rarely run more than one design system.
+
+| Marker | Signal | Where |
+|---|---|---|
+| Flux | `livewire/flux` in `composer.json`, `<flux:*>` tags in views | `composer.json`, grep `resources/views` |
+| shadcn/ui | `components.json` exists at repo root | `components.json` |
+| Headless UI | `@headlessui/react` or `@headlessui/vue` in `package.json` | `package.json` |
+| Radix | `@radix-ui/*` in `package.json` (without shadcn marker) | `package.json` |
+| Material/Chakra/Mantine/Ant | their package names in `package.json` | `package.json` |
+| Custom / none | none of the above match | — |
+
+### 3. Detect design tokens
+
+Write into `state.ui_audit.design_tokens` (object, never null — empty object is fine):
+
+| Source | What to extract |
+|---|---|
+| `tailwind.config.{js,ts,cjs,mjs}` | `theme.colors`, `theme.spacing`, `theme.fontFamily`, `theme.extend.*` |
+| `:root { --... }` blocks in `resources/css/`, `app/globals.css`, `src/app/globals.css` | every `--token-name: value` pair |
+| `theme.json` / `tokens.json` (any depth) | flat or nested token tree |
+| `app/css/variables.css`, `assets/scss/_tokens.scss` | SCSS `$var: value` and CSS custom properties |
+
+Group output by category: `colors`, `spacing`, `radius`, `font`, `shadow`, `breakpoint`, `other`.
+
+### 4. Detect shadcn inventory (only when `state.stack.frontend == "react-shadcn"`)
+
+Read `components.json` for the registered style + base color, then read `package.json` for `@radix-ui/*` and any locally vendored `components/ui/*.tsx` files. Write into `state.ui_audit.shadcn_inventory`:
+
+```
+{
+  version: <from package.json shadcn registry CLI version, or null>,
+  style: "default" | "new-york" | <other>,
+  base_color: "slate" | "zinc" | ...,
+  primitives: ["Button", "Dialog", "Form", "Table", ...],   // names of files in components/ui/
+  installed_radix: ["@radix-ui/react-dialog", ...]          // raw radix list
+}
+```
+
+### 5. List reusable patterns
+
+Categorize what already exists. Empty arrays are valid, never omit the keys.
+
+```
+state.ui_audit.patterns = {
+  forms: [<component path:str>, ...],     // any component with <form>, useForm, <flux:input>, <Input> + <Button type=submit>
+  tables: [...],                          // <table>, <flux:table>, DataTable, headless table primitives
+  modals: [...],                          // <flux:modal>, <Dialog>, AlertDialog, Sheet
+  empty_states: [...],                    // components matching grep "no results"|"empty"|"keine"|"nothing yet"
+  navigation: [...],                      // sidebar, breadcrumb, tabs
+  data_display: [...]                     // cards, lists, stat tiles
+}
+```
+
+### 6. Match candidates for the current input
+
+For each item in `state.ui_audit.components`, score similarity to `state.input.data` (fuzzy on filename + props/slots + co-occurring terms). Keep top 5 with `score >= 0.3`. Write into `state.ui_audit.candidates`:
+
+```
+[{path, name, score, reason: "matches 'settings' + 'toggle' in props"}, ...]
+```
+
+If `candidates` is empty, the user is building net-new. That is normal — record the empty list, do not halt.
+
+### 7. Greenfield branch
+
+If **all** are true:
+- `state.ui_audit.components` is empty
+- `state.ui_audit.design_system == "custom-or-none"`
+- `state.ui_audit.design_tokens` is empty (no Tailwind config customizations, no `:root`)
+
+then set `state.ui_audit.greenfield = true` and emit a halt:
+
+```
+> No existing UI surface detected — this looks like greenfield.
+>
+> 1. Scaffold a minimal token set + a base component primitive folder
+>    before building (recommended for projects with >1 planned screen)
+> 2. Proceed bare with Tailwind defaults (recommended for one-off prototypes)
+> 3. Point me at an external design-system reference (URL or file)
+
+**Recommendation: 1 — Scaffold tokens + primitives** — even one extra screen
+benefits from a shared base; the scaffold cost is ~10 min and saves
+re-doing every primitive on screen 2. Caveat: flip to 2 if this is a
+demo or single-page prototype that will not grow.
+```
+
+Record the user's pick in `state.ui_audit.greenfield_decision` (`scaffold` | `bare` | `external_reference`). Re-running the skill on the same state-file with `greenfield_decision` set is a no-op for the halt (audit findings stay).
+
+### 8. (Optional) Capture an a11y baseline
+
+The R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline`
+when present; the review gate then filters incoming
+`state.ui_review.a11y.violations` against it so pre-existing
+violations stay informational and only NEW or CHANGED entries block
+the polish loop. Without a baseline the gate sees every violation as
+actionable — fine for greenfield, noisy for legacy surfaces.
+
+Capture the baseline when:
+
+- The audit covers components with known a11y debt the project does
+  not intend to fix in this run (legacy templates, third-party
+  embeds, vendor widgets).
+- The user says "don't block on existing a11y issues" or similar.
+
+Skip the baseline (omit the key, leave `state.ui_audit.a11y_baseline`
+unset) when:
+
+- The surface is greenfield — the review gate should treat every
+  violation as new.
+- The project's a11y posture is "zero known violations" and any
+  finding is by definition actionable.
+
+Shape (each entry must carry at least `rule` + `selector`; severity
+is optional but recommended so the review gate's severity-floor
+filter behaves the same on replay):
+
+```
+state.ui_audit.a11y_baseline = [
+  {rule: "color-contrast", selector: ".legacy-tab", severity: "moderate"},
+  {rule: "label",          selector: "form#search input[type=search]"},
+  ...
+]
+```
+
+Producer parity: the review skill that writes
+`state.ui_review.a11y.violations` MUST use the same `(rule, selector)`
+shape, otherwise the engine's de-dup will miss matches and pre-existing
+violations will surface as new findings on every run.
+
+### 9. Validate and write findings
+
+1. Verify every key in the **Output format** below is present in `state.ui_audit` (empty arrays/objects allowed; `null` only for `shadcn_inventory` outside the react-shadcn stack).
+2. Verify `state.ui_audit.greenfield == true` implies `state.ui_audit.greenfield_decision` is set.
+3. Write the full object back into the state-file. Audit completes with outcome `done` — the dispatcher's audit gate now passes.
+
+## Output format
+
+1. **`state.ui_audit.components`** — array of component/template descriptors (path, name, kind, exports)
+2. **`state.ui_audit.design_system`** — single string identifying the dominant system or `custom-or-none`
+3. **`state.ui_audit.design_tokens`** — object grouped by category (colors, spacing, radius, font, shadow, breakpoint, other)
+4. **`state.ui_audit.shadcn_inventory`** — object with version, style, base_color, primitives (only when stack is `react-shadcn`; `null` otherwise)
+5. **`state.ui_audit.patterns`** — object with forms, tables, modals, empty_states, navigation, data_display arrays
+6. **`state.ui_audit.candidates`** — top-5 similarity matches for the current input (may be empty)
+7. **`state.ui_audit.greenfield`** — boolean; when true, `greenfield_decision` MUST also be set before the dispatcher advances
+8. **`state.ui_audit.a11y_baseline`** *(optional)* — array of `{rule, selector, severity?}` entries documenting pre-existing a11y violations the review gate should treat as informational. Omit the key entirely when no baseline applies; do not write `[]` for "I checked and there are none" — that disables the gate's filter for every future run.
+
+## Gotcha
+
+- The model tends to skip the audit and start designing straight from the request — the dispatcher gate at `directives/ui/audit.py` enforces "no design without audit findings". Never treat this skill as optional for non-trivial UI.
+- The model tends to misidentify a single Tailwind utility as a "design token" — tokens come from the config or `:root`, not from class strings in templates.
+- Don't assume a Radix-only `package.json` means shadcn — shadcn requires `components.json` at repo root.
+- `state.ui_audit.shadcn_inventory.version` is often missing; the shadcn CLI does not always pin itself in `package.json`. Record `null` rather than guessing.
+- Greenfield is detected, not assumed — a project with one Blade layout and no components is still greenfield only if tokens AND design system markers AND components are all empty.
+- Re-running the skill on a stale state-file: cache by `(composer.json mtime, package.json mtime)`; if either changed, re-audit and overwrite.
+
+## Do NOT
+
+- Do NOT advance to `directives/ui/design.py` or `apply.py` if `state.ui_audit` is empty.
+- Do NOT advance to design or apply if `state.ui_audit.greenfield == true` and `state.ui_audit.greenfield_decision` is unset.
+- Do NOT silently skip the greenfield halt because "Tailwind has defaults" — the user picks the path explicitly.
+- Do NOT write paths outside the project root into the inventory.
+- Do NOT rewrite `state.ui_audit` once it is populated unless re-detection is triggered by mtime change — design and apply read from it.

package/dist/agent-src/skills/fe-design/SKILL.md

@@ -0,0 +1,265 @@
+---
+model_tier: medium
+name: fe-design
+description: "Reference for frontend-design heuristics — component architecture, layout patterns, form/table design, responsive strategy, a11y, UX principles. Stack-agnostic; cited by directives/ui/design.py."
+personas:
+  - frontend-engineer
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# Frontend Design Skill (Reference)
+
+## Positioning — reference, not executor
+
+`fe-design` is a **universal reference skill**, not an executor. It carries
+stack-agnostic heuristics that the UI directive set cites; it does **not**
+own the flow.
+
+| Concern | Owner |
+|---|---|
+| Layout / states / microcopy lock | [`directives/ui/design.py`](../../templates/scripts/work_engine/directives/ui/design.py) |
+| Stack-dispatched implementation | [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py) → `blade-ui` / `livewire` / `flux` / `react-shadcn-ui` |
+| Existing-component inventory + tokens | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) (mandatory pre-step) |
+| Grounded selection (style, color tokens, typography, pattern, anti-patterns) | [`design-intelligence`](../design-intelligence/SKILL.md) — corpus-grounded; this skill stays the heuristic layer and *invokes* it |
+| Design-review polish loop | [`directives/ui/review.py`](../../templates/scripts/work_engine/directives/ui/review.py) + [`directives/ui/polish.py`](../../templates/scripts/work_engine/directives/ui/polish.py) |
+
+## When to use
+
+Cite this skill when:
+
+- Planning a new page or feature UI before implementing
+- Choosing between component patterns (modal vs. inline, table vs. cards)
+- Designing forms with complex validation or multi-step flows
+- Making responsive design decisions
+- Reviewing UI for accessibility and usability
+
+Do NOT use this skill to:
+
+- Implement components — that is the apply-step's stack-dispatched skill
+- Audit an existing UI — that is `existing-ui-audit`
+- Drive the full UI flow — that is the `directives/ui/` orchestrator
+
+## How the directive set cites this skill
+
+`directives/ui/design.py` produces the design brief (layout, components,
+states, microcopy, a11y). Selection decisions (style, semantic color
+tokens, typography pairing, layout pattern, anti-patterns) come **grounded**
+from [`design-intelligence`](../design-intelligence/SKILL.md) — run its
+corpus query first; fall back to these heuristics only where the corpus
+reports an evidence gap or the audit already pins a project pattern.
+Stack-specific choices come from the dispatched impl skill.
+
+## Component Architecture
+
+### Page structure (universal shape)
+
+```
+Page layout
+├── Header (static)
+├── Navigation (interactive — active state)
+├── Content area
+│   ├── Page heading + actions (static)
+│   ├── Filters (interactive — reactive)
+│   ├── Data display (interactive — table / cards)
+│   └── Pagination (interactive)
+└── Footer (static)
+```
+
+The stack-specific mapping (Blade partial vs. Livewire component vs.
+React island vs. Vue SFC) is the apply-step's concern, not this skill's.
+
+### When to use what (kind, not framework)
+
+| Kind | When | Example |
+|---|---|---|
+| **Static partial** | No interactivity, server-rendered only | Header, footer, static info |
+| **Reusable UI component** | Props-only, no state | Button, badge, card shell |
+| **Stateful component** | Needs server interaction or local state | Forms, tables, filters |
+| **Library primitive** | Standard UI from a design system | Modal, dropdown, input, toast |
+| **Client-only micro-interaction** | No server roundtrip needed | Toggle, accordion, clipboard |
+
+### Component granularity
+
+- **One stateful component per concern** — don't build mega-components.
+- **Compose with reusable UI components** for shared shells, headers, fields.
+- **Use the project's library primitives first** — never rebuild what the design system already provides (audit findings tell you which).
+- **Extract when used 3+ times** — DRY applies to UI too.
+
+## Form Design
+
+### Principles
+
+1. **Labels always visible** — no placeholder-only inputs
+2. **Validation on blur + submit** — immediate feedback, not on every keystroke
+3. **Error messages below the field** — red text, specific message
+4. **Required fields marked** — asterisk (*) or "(required)" label
+5. **Logical grouping** — related fields in sections with headings
+6. **Primary action prominent** — submit button stands out, cancel is secondary
+
+### Layout patterns
+
+| Fields | Layout | When |
+|---|---|---|
+| 1–3 fields | Single column | Simple forms (login, search) |
+| 4–8 fields | Two columns on desktop, single on mobile | Standard CRUD forms |
+| 8+ fields | Sections with headings or tabs/steps | Complex entity forms |
+| Related pairs | Side by side (first/last name, city/zip) | Logically paired fields |
+
+### Multi-step forms
+
+```
+Step indicator (1 — 2 — 3)
+├── Step 1: Basic info     → Next
+├── Step 2: Details        → Back / Next
+└── Step 3: Review + Submit → Back / Submit
+```
+
+- Show progress indicator (step numbers or progress bar)
+- Allow going back without losing data
+- Validate each step before allowing next
+- Show summary on final step
+
+## Table Design
+
+### Principles
+
+1. **Right-align numbers** — easier to compare
+2. **Left-align text** — natural reading direction
+3. **Sortable columns** — click header to sort
+4. **Sticky header** — visible when scrolling long tables
+5. **Row actions** — edit/delete as icon buttons or dropdown menu
+6. **Empty state** — helpful message when no data, not just blank
+
+### Responsive tables
+
+| Screen | Strategy |
+|---|---|
+| Desktop (≥1024px) | Full table with all columns |
+| Tablet (768–1023px) | Hide less important columns |
+| Mobile (<768px) | Card layout or horizontal scroll |
+
+### Pagination
+
+- Default: 25 rows per page
+- Show total count: "Showing 1–25 of 142"
+- Allow page size change (10, 25, 50, 100)
+- Prefer server-side pagination — avoid loading the full set client-side
+
+## Responsive Strategy
+
+### Breakpoints (Tailwind reference scale)
+
+| Prefix | Min width | Target |
+|---|---|---|
+| `sm:` | 640px | Large phones |
+| `md:` | 768px | Tablets |
+| `lg:` | 1024px | Small laptops |
+| `xl:` | 1280px | Desktops |
+| `2xl:` | 1536px | Large screens |
+
+### Mobile-first approach
+
+1. Design for mobile first (default styles)
+2. Add complexity at larger breakpoints
+3. Test at each breakpoint, not just desktop
+
+### Common patterns
+
+| Element | Mobile | Desktop |
+|---|---|---|
+| Navigation | Hamburger menu | Sidebar or top nav |
+| Forms | Single column | Two columns |
+| Tables | Cards or scroll | Full table |
+| Actions | Bottom sheet / FAB | Inline buttons |
+| Filters | Collapsible panel | Sidebar or inline |
+
+## Accessibility (a11y)
+
+### Minimum requirements
+
+- **Color contrast:** 4.5:1 for text, 3:1 for large text (WCAG AA)
+- **Keyboard navigation:** All interactive elements reachable via Tab
+- **Focus indicators:** Visible focus ring on all focusable elements
+- **Alt text:** All meaningful images have descriptive alt text
+- **ARIA labels:** Interactive elements without visible text need `aria-label`
+- **Semantic HTML:** Use `<button>`, `<nav>`, `<main>`, `<form>` — not `<div>` for everything
+
+### Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| `<div onclick>` | Use `<button>` |
+| Color-only status | Add icon or text alongside color |
+| Missing form labels | Add `<label for="...">` |
+| Auto-playing content | Provide pause/stop control |
+| Tiny click targets | Min 44×44px touch target |
+
+## UX Principles
+
+1. **Feedback** — Every action gets a response (toast, loading state, success message)
+2. **Forgiveness** — Undo for destructive actions, confirmation for irreversible ones
+3. **Consistency** — Same patterns for same interactions across the app
+4. **Progressive disclosure** — Show basics first, details on demand
+5. **Loading states** — Skeleton screens or spinners, never blank screens
+6. **Error recovery** — Clear error messages with suggested actions
+
+## Aesthetic direction
+
+Audit-pinned tokens and components always take precedence (see `existing-ui-audit`). When the audit pins an aesthetic, honor it without deviation. When the audit shows **no pinned aesthetic** — greenfield surface, marketing landing page, brand-new feature without design-system precedent — the design brief is allowed (and expected) to commit to a deliberate direction instead of defaulting to safe centered hero + 3-column features + CTA.
+
+Typography pairings (73 curated heading/body combos, Google Fonts URLs +
+Tailwind config) and icon-system guidance (104 Phosphor entries with
+import code) come grounded from
+[`design-intelligence`](../design-intelligence/SKILL.md)
+(`--domain typography`, `--domain icons`) — query before picking from memory.
+
+Pick one direction up front and let composition, typography, and color follow from it. Avoid the "neutral AI default": uniform grid, system fonts as the visible body face, purple-to-blue gradients on white, predictable spacing. A direction that fits the brand intent (editorial / brutalist / refined / playful / retro / maximal / minimal / etc.) and is consistent across the page beats hedging.
+
+Surface the chosen direction in the design brief as a one-line statement (e.g. `aesthetic: editorial-magazine — asymmetric grid, serif display + sans body, generous gutters`). The apply step (`react-shadcn-ui` / `blade-ui` / `livewire` / `flux`) reads this line and matches typography, spacing, and motion to it; if no line is present, the apply step uses project defaults.
+
+## Procedure
+
+When `directives/ui/design.py` (or any caller) cites this skill:
+
+1. **Inspect `state.ui_audit` first** — review the audit produced by [`existing-ui-audit`](../existing-ui-audit/SKILL.md); it is mandatory. Stop and request the audit if missing.
+2. **Pick the smallest matching section** — Component Architecture, Form Design, Table Design, Responsive Strategy, Accessibility, or UX Principles. Cite by H2/H3 heading, never paste the whole skill.
+3. **Defer to audit findings** — when the audit pins a project pattern (token, primitive, layout convention), use it. The heuristics here are fallbacks for gaps, not overrides.
+4. **Defer to the stack apply skill** — Blade vs. Livewire vs. Flux vs. React-shadcn choices come from the dispatched impl skill, never from this reference.
+5. **Surface conflicts** — if a heuristic here contradicts an audit finding or stack convention, name both and let the caller decide; do not silently pick.
+
+## Output format
+
+When this skill's content is folded into a design brief or review:
+
+1. Quote the cited heuristic verbatim, with the H2/H3 heading and a one-line "why this applies" tie-back to the request.
+2. Map each heuristic to a concrete artifact in the brief (component, form section, table column, breakpoint rule, a11y check, UX state).
+3. Keep stack-agnostic — never name Blade/Livewire/Flux/React primitives in the cited prose; the apply step adds those.
+4. Mark anything overridden by audit findings as `[audit override]` and link to the audit entry.
+
+## Related
+
+- **Orchestrator:** [`directives/ui/`](../../templates/scripts/work_engine/directives/ui/) — owns the UI flow
+- **Pre-step (mandatory):** [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — inventory before design
+- **Stack apply skills (dispatched, not standalone):**
+  - [`blade-ui`](../blade-ui/SKILL.md) — Blade template impl
+  - [`livewire`](../livewire/SKILL.md) — Livewire component impl
+  - [`flux`](../flux/SKILL.md) — Flux component library usage
+  - [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) — React + shadcn primitives
+- **Adjacent reference:** [`dashboard-design`](../dashboard-design/SKILL.md) — monitoring dashboard design (different domain)
+
+## Gotcha
+
+- Don't design components without running `existing-ui-audit` first — the audit's component/token inventory is the canonical source for "what already exists in this project". Reinventing is the #1 failure mode.
+- Heuristics in this reference apply across stacks; do not promote them to project rules without checking the audit.
+- Mobile-first is not optional — every layout must work on 320px width.
+
+## Do NOT
+
+- Do NOT skip mobile viewport testing.
+- Do NOT use fixed pixel widths for responsive layouts.
+- Do NOT ignore accessibility requirements.
+- Do NOT use this skill as an executor — it is a reference cited by `directives/ui/design.py`.