@event4u/agent-config 1.12.0 → 1.14.0

package/.agent-src/skills/blade-ui/SKILL.md

@@ -1,19 +1,35 @@
 ---
 name: blade-ui
-description: "Use when creating or editing Blade views, components, partials, layouts, or view logic — even when the user says 'add a new page' or 'render this data' without naming Blade."
+description: "Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic."
 source: package
 ---
 
 # blade-ui
 
+## Positioning — dispatched, not standalone
+
+`blade-ui` is the **apply-step executor** for the Blade 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) |
+| Review + polish loop | [`directives/ui/review.py`](../../templates/scripts/work_engine/directives/ui/review.py) + [`polish.py`](../../templates/scripts/work_engine/directives/ui/polish.py) |
+
 ## When to use
 
-Use when creating or editing Blade views, components, partials, layouts, or forms.
+Cite this skill when:
+
+- `state.stack.frontend == "blade"` (or the project is clearly Blade-only without Livewire / Flux) and `directives/ui/apply.py` dispatches to this skill
+- Editing or creating Blade views, components, partials, layouts, or forms
 
 Do NOT use when:
+
 - API-only endpoints (use `api-endpoint` skill)
-- Livewire components (use `livewire` skill)
+- Livewire components (use `livewire` skill — composes Blade views internally)
 - Flux UI components (use `flux` skill)
+- Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
 
 ## Procedure: Create Blade view or component
 
@@ -23,11 +39,11 @@ Do NOT use when:
 2. Inspect existing UI patterns — layouts, partials, component naming, CSS conventions.
 3. Check form handling style — old input, validation errors, session flashes, reusable field partials.
 4. Inspect neighboring templates — match indentation, directives, slot usage, classes.
-5. Determine data flow — what belongs in controller/view model vs. template.
+5. Determine data flow — controller/view model vs. template.
 
 ### Step 1: Create the template
 
-1. Use the project's existing layout system.
+1. Use project's existing layout system.
 2. Keep template presentation-focused — no business logic, no DB queries.
 3. Extract repeated sections into partials or components.
 
@@ -54,6 +70,15 @@ Do NOT use when:
 1. Blade view or component file(s) following project conventions
 2. Component class (if applicable) with typed props
 
+### 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
 
 - `@include` shares parent scope — components don't. Know the difference.

package/.agent-src/skills/command-routing/SKILL.md

@@ -40,6 +40,38 @@ Only ask the user if inference fails and the command cannot proceed without the
 | `.augment/commands/` | Shared commands (work across projects) |
 | `agents/overrides/commands/` | Project-specific overrides (used instead of original) |
 
+## Commands that dispatch to a Python engine
+
+Most commands are pure markdown procedures — the agent reads the steps
+and executes them. Two commands delegate to the `work_engine` Python
+module via the `./agent-config` dispatcher; both share the same
+Option-A loop (read state → run engine → handle exit code → repeat),
+they only differ in the input envelope they build:
+
+| Command | Subcommand | Envelope | Use when |
+|---|---|---|---|
+| `/implement-ticket` | `./agent-config implement-ticket` | `input.kind="ticket"` | User points at a Jira/Linear ticket or supplies a structured ticket payload |
+| `/work` | `./agent-config work` | `input.kind="prompt"` | User supplies a free-form prompt — no ticket id, no acceptance criteria yet |
+
+Route prompt-shaped intents (`"add a CSV export endpoint…"`,
+`"fix the failing login test"`, `"refactor the audit-log controller"`)
+to `/work`. Route ticket-shaped intents
+(`"work on PROJ-123"`, `"start on the ticket on this branch"`) to
+`/implement-ticket`. If the user pastes both a ticket id **and** a
+free-form goal, prefer `/implement-ticket` and let it pull the AC from
+the ticket — `/work` is the fallback when no ticket exists.
+
+The actual step logic, halt formats, scoring breakdowns, and delivery
+report are emitted by the engine. Do not paraphrase or reorder engine
+output — surface it as-is. The two flows are mutually exclusive at the
+state-file level: one `.work-state.json` carries one envelope at a
+time, and the engine refuses to switch mid-flight.
+
+A sibling subcommand `./agent-config migrate-state` upgrades a legacy
+`.implement-ticket-state.json` file to the v1 `.work-state.json`
+schema. The wrapper invokes it automatically when the legacy file is
+detected; agents should not bypass the dispatcher.
+
 ## GitHub API: Replying to PR review comments
 
 When commands reply to PR review comments (e.g. `/fix-pr-bot-comments`):

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

@@ -4,6 +4,8 @@ description: "Use when creating or editing a slash command in .agent-src.uncompr
 source: package
 ---
 
+<!-- cloud_safe: degrade -->
+
 # command-writing
 
 ## When to use
@@ -58,9 +60,26 @@ name: {command-name}          # must match filename without .md
 description: "Short human-readable summary of what /{name} does"
 disable-model-invocation: true
 skills: [optional-skill-1]    # optional — skills this command delegates to
+suggestion:                   # required (road-to-context-aware-command-suggestion Phase 2)
+  eligible: true              # default; set false to opt out of auto-surfacing
+  trigger_description: "natural-language pattern, comma-separated examples"
+  trigger_context: "concrete signal — branch name, file pattern, recent tool output"
 ---
 ```
 
+Opt-out shape:
+
+```yaml
+suggestion:
+  eligible: false
+  rationale: "one-line reason this command must be invoked deliberately"
+```
+
+Linter enforces ≥10-char triggers when eligible; rationale required when
+ineligible. Optional `confidence_floor` (0.0–1.0) and `cooldown` (e.g. `10m`)
+override the global settings per command. Eligibility decisions live in
+[`agents/contexts/command-suggestion-eligibility.md`](../../../agents/contexts/command-suggestion-eligibility.md).
+
 When iterating on the description, delegate to the
 [`description-assist`](../description-assist/SKILL.md) skill — approval-gated,
 no silent edits, max two rounds.
@@ -105,8 +124,8 @@ multi-paragraph explanation, extract it into a skill and call it.
 * Run `bash scripts/compress.sh --sync` → regenerates `.agent-src/commands/{name}.md`.
 * Run `python3 scripts/compress.py --generate-tools` → creates the Claude symlink at
   `.claude/skills/{name}/SKILL.md`.
-* 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
 
@@ -133,6 +152,26 @@ multi-paragraph explanation, extract it into a skill and call it.
 * Do NOT edit `.agent-src/`, `.augment/`, or `.claude/` projections
 * Do NOT exceed the hard size limit without a waiver
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the package's
+`scripts/skill_linter.py`, `scripts/compress.py`, and the `task`
+runner are not available. This skill still applies — but with
+prose-only validation:
+
+* Emit the full command file as a copyable Markdown block. Do not
+  attempt to write it to disk.
+* Self-check the frontmatter against the rules below — `name`,
+  `description`, `disable-model-invocation: true` MUST all be
+  present.
+* Self-check the body shape: numbered steps, explicit safety gates,
+  no inline skill-level detail.
+* Tell the user to save the file under
+  `.agent-src.uncompressed/commands/{name}.md` and run
+  `task sync && task lint-skills` locally before committing.
+* Skip every reference to running the linter, compressor, or
+  generators yourself — they only run on the user's machine.
+
 ## Examples
 
 Good description (trigger-shaped, outcome-focused):

package/.agent-src/skills/description-assist/SKILL.md

@@ -4,6 +4,8 @@ description: "Use when polishing a skill/rule/command/guideline frontmatter desc
 source: package
 ---
 
+<!-- cloud_safe: degrade -->
+
 # description-assist
 
 ## When to use
@@ -155,6 +157,25 @@ and stop. Do not loop further.
 * Do NOT run `scripts/skill_trigger_eval.py` from inside this skill — eval
   execution spends API tokens and is a separate user action
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the package's
+`scripts/audit_skill_descriptions.py`, `scripts/skill_linter.py`,
+and `scripts/skill_trigger_eval.py` are not reachable. The skill
+still applies — with prose-only inspection:
+
+* Reason from the description text in the conversation. The agent
+  acts as the inspector; no separate audit pass runs.
+* Apply the same checklist used by the local audit: length budget,
+  trigger prefix ("Use when …"), domain class, symptom class,
+  undertrigger tail.
+* Emit verdict + up to 3 numbered variants. The user picks; the
+  agent emits the new frontmatter as a copyable block.
+* Skip every reference to running the audit or trigger-eval scripts.
+  Recommend the user run the package's local linter after applying.
+* Never claim a description has been "graded" or "scored" by an
+  external pass — there isn't one.
+
 ## Examples
 
 Inspection verdict (good — compact):

package/.agent-src/skills/estimate-ticket/SKILL.md

@@ -182,5 +182,4 @@ copy-paste instructions if missing.
 - [`refine-ticket`](../refine-ticket/SKILL.md) — sibling; refine first if the ticket is vague
 - [`jira-ticket`](../../commands/jira-ticket.md) — ticket loader
 - [`feature-plan`](../../commands/feature-plan.md) — downstream planning
-- [`road-to-ticket-refinement.md`](../../../agents/roadmaps/road-to-ticket-refinement.md) — governing roadmap
 - [`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) — drafting protocol

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

@@ -0,0 +1,187 @@
+---
+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."
+source: package
+---
+
+# existing-ui-audit
+
+## 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
+
+R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline` when present; review gate filters incoming `state.ui_review.a11y.violations` against it so pre-existing violations stay informational and only NEW or CHANGED entries block polish loop. Without baseline gate sees every violation as actionable — fine for greenfield, noisy for legacy surfaces.
+
+Capture baseline when:
+
+- Audit covers components with known a11y debt project does not intend to fix this run (legacy templates, third-party embeds, vendor widgets).
+- User says "don't block on existing a11y issues" or similar.
+
+Skip baseline (omit key, leave `state.ui_audit.a11y_baseline` unset) when:
+
+- Surface is greenfield — review gate should treat every violation as new.
+- 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 optional but recommended so review gate's severity-floor filter behaves 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: review skill that writes `state.ui_review.a11y.violations` MUST use same `(rule, selector)` shape, otherwise 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/.agent-src/skills/fe-design/SKILL.md

@@ -1,73 +1,76 @@
 ---
 name: fe-design
-description: "Use when designing frontend interfaces — component architecture, layout patterns, form design, table patterns, responsive strategies, and UX principles for Blade/Livewire/Flux/Tailwind."
+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."
 source: package
 ---
 
-# Frontend Design Skill
+# Frontend Design Skill (Reference)
+
+## Positioning — reference, not executor
+
+`fe-design` is a **universal reference skill**, not an executor. Stack-agnostic heuristics that the UI directive set cites; 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) |
+| 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
 
-Use this skill when:
+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
-- Deciding how to structure Livewire components
-
-## Procedure: Design a frontend interface
 
-1. **Understand requirements** — What data is shown? What actions are available? Who is the user?
-2. **Choose technology** — Pick from the project stack (see table below).
-3. **Design layout** — Mobile-first, component-based, consistent spacing.
-4. **Implement** — Build with Blade components, Livewire for interactivity, Flux for UI primitives.
-5. **Verify** — Check accessibility (labels, focus, contrast), responsive behavior, loading states.
+Do NOT use this skill to:
 
-This project uses a server-rendered stack:
+- 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
 
-| Layer | Technology | Skill |
-|---|---|---|
-| Templates | Laravel Blade | `blade-ui` |
-| Interactivity | Livewire 3 | `livewire` |
-| Component library | Flux (by Laravel) | `flux` |
-| Styling | Tailwind CSS | `tailwind` |
-| Icons | Heroicons / custom | — |
+## How the directive set cites this skill
 
-**Key principle:** Server-first. Use Livewire for interactivity. Avoid JavaScript unless Livewire can't handle it (e.g., drag-and-drop, complex animations).
+`directives/ui/design.py` produces the design brief (layout, components, states, microcopy, a11y). Brief picks heuristics from this reference when audit doesn't already pin a project pattern. Stack-specific choices come from the dispatched implementation skill.
 
 ## Component Architecture
 
-### Page structure
+### Page structure (universal shape)
 
 ```
-Page (Blade layout)
-├── Header (Blade partial)
-├── Navigation (Livewire — active state)
+Page layout
+├── Header (static)
+├── Navigation (interactive — active state)
 ├── Content area
-│   ├── Page heading + actions (Blade)
-│   ├── Filters (Livewire — reactive)
-│   ├── Data display (Livewire — table/cards)
-│   └── Pagination (Livewire)
-└── Footer (Blade partial)
+│   ├── Page heading + actions (static)
+│   ├── Filters (interactive — reactive)
+│   ├── Data display (interactive — table / cards)
+│   └── Pagination (interactive)
+└── Footer (static)
 ```
 
-### When to use what
+Stack-specific mapping (Blade partial vs. Livewire component vs. React island vs. Vue SFC) is the apply-step's concern.
 
-| Pattern | When | Example |
+### When to use what (kind, not framework)
+
+| Kind | When | Example |
 |---|---|---|
-| **Blade partial** | Static content, no interactivity | Header, footer, static info |
-| **Blade component** | Reusable UI element, props only | Button, badge, card shell |
-| **Livewire component** | Needs server interaction or state | Forms, tables, filters |
-| **Flux component** | Standard UI element from library | Modal, dropdown, input, toast |
-| **Alpine.js** | Client-only micro-interaction | Toggle, accordion, clipboard |
+| **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 Livewire component per concern** — don't build mega-components
-- **Compose with Blade components** inside Livewire for reusable UI pieces
-- **Use Flux for standard elements** — don't rebuild what Flux provides
-- **Extract when used 3+ times** — DRY applies to UI too
+- **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 provides (audit findings tell you which).
+- **Extract when used 3+ times** — DRY applies to UI too.
 
 ## Form Design
 
@@ -127,11 +130,11 @@ Step indicator (1 — 2 — 3)
 - Default: 25 rows per page
 - Show total count: "Showing 1–25 of 142"
 - Allow page size change (10, 25, 50, 100)
-- Use Livewire pagination (server-side)
+- Prefer server-side pagination — avoid loading the full set client-side
 
 ## Responsive Strategy
 
-### Breakpoints (Tailwind)
+### Breakpoints (Tailwind reference scale)
 
 | Prefix | Min width | Target |
 |---|---|---|
@@ -187,25 +190,40 @@ Step indicator (1 — 2 — 3)
 5. **Loading states** — Skeleton screens or spinners, never blank screens
 6. **Error recovery** — Clear error messages with suggested actions
 
-## Related
+## Procedure
 
-- **Skill:** `blade-ui` — Blade template implementation
-- **Skill:** `livewire` — Livewire component implementation
-- **Skill:** `flux` — Flux component library usage
-- **Skill:** `tailwind` — Tailwind CSS utility patterns
-- **Skill:** `dashboard-design` — Monitoring dashboard design (different domain)
+When `directives/ui/design.py` (or any caller) cites this skill:
 
+1. **Confirm audit ran first** — `state.ui_audit` from [`existing-ui-audit`](../existing-ui-audit/SKILL.md) is mandatory. Stop and request audit if missing.
+2. **Pick smallest matching section** — Component Architecture, Form Design, Table Design, Responsive Strategy, Accessibility, or UX Principles. Cite by H2/H3 heading, never paste whole skill.
+3. **Defer to audit findings** — when audit pins a project pattern (token, primitive, layout convention), use it. Heuristics here are fallbacks for gaps, not overrides.
+4. **Defer to stack apply skill** — Blade vs. Livewire vs. Flux vs. React-shadcn choices come from dispatched implementation skill, never from this reference.
+5. **Surface conflicts** — if heuristic here contradicts an audit finding or stack convention, name both and let caller decide; do not silently pick.
 
 ## Output format
 
-1. Component structure with layout, data flow, and interaction patterns
-2. Responsive behavior for mobile/tablet/desktop breakpoints
-3. Accessibility annotations (ARIA, keyboard navigation)
+When this skill's content is folded into a design brief or review:
+
+1. Quote cited heuristic verbatim, with H2/H3 heading and one-line "why this applies" tie-back to request.
+2. Map each heuristic to a concrete artifact in brief (component, form section, table column, breakpoint rule, a11y check, UX state).
+3. Keep stack-agnostic — never name Blade/Livewire/Flux/React primitives in cited prose; apply step adds those.
+4. Mark anything overridden by audit findings as `[audit override]` and link to 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 implementation
+  - [`livewire`](../livewire/SKILL.md) — Livewire component implementation
+  - [`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 checking existing Flux/Livewire components first — avoid reinventing.
-- The model tends to use raw HTML instead of project component library — always prefer existing components.
+- Don't design components without running `existing-ui-audit` first — audit's component/token inventory is canonical 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
@@ -213,11 +231,5 @@ Step indicator (1 — 2 — 3)
 - 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`.
 
-## Auto-trigger keywords
-
-- frontend design
-- component architecture
-- layout
-- form design
-- responsive

package/.agent-src/skills/finishing-a-development-branch/SKILL.md

@@ -31,6 +31,10 @@ become a PR. Never destroy work without explicit confirmation.
 NO MERGE, NO PR, NO DISCARD WITHOUT VERIFIED TESTS + EXPLICIT CHOICE.
 ```
 
+Skipping verification because "it worked a minute ago" is how broken
+`main` happens. Discarding because "I assumed the user meant it" is
+how work gets lost.
+
 ## Procedure
 
 ### 1. Inspect branch state