@event4u/agent-config 9.17.0 → 9.18.1

package/dist/agent-src/skills/design-intelligence/references/integration-mapping.md

@@ -0,0 +1,91 @@
+# design-intelligence — integration mapping
+
+> Section-level entry point of the `design-intelligence` skill (progressive
+> disclosure, 2026-08-04). Content moved VERBATIM from SKILL.md —
+> load this file when the section index in SKILL.md routes here.
+
+## `MASTER.md` + page overrides ↔ `state.ui_design` (mapping)
+
+The upstream cross-session memory pattern maps onto our delivery state:
+
+| Upstream artifact | Our state | Notes |
+|---|---|---|
+| `design-system/<project>/MASTER.md` | `state.ui_design` (project-level brief: style, tokens, typography, anti-patterns) | The state is the source of truth during a run. |
+| `design-system/<project>/pages/<page>.md` | per-page override entries inside `state.ui_design` (e.g. `pages.<page>` dict) | Page rules override project rules for that page only. |
+
+File persistence stays **opt-in** (`ground … --persist <dir>`) and writes
+under the consumer's project as a durable artifact for multi-session
+consistency; on a fresh session, re-hydrate `state.ui_design` from
+`MASTER.md` + the page file before re-running `design`.
+
+## Grounding the review/polish a11y gate (charts + contrast)
+
+The `review`/`polish` steps gate on `state.ui_review.a11y`. Ground two
+finding classes instead of ad-hoc judgment:
+
+- **Chart-type findings** — the grounding CLI (`ground` via
+  ./scripts-run) — `…/ground search --manifest … --domain
+  chart "<data shape>"` → `Accessibility Grade`, `A11y Fallback`,
+  `Color Guidance` columns justify "wrong chart type / missing colorblind
+  fallback" findings with a citable row.
+- **Contrast findings** — `--domain color "<product>"` returns the
+  WCAG-adjusted token set; a finding that a hex pair deviates from the
+  adopted set cites the row instead of eyeballing ratios. Auditing
+  *method* stays with [`accessibility-auditor`](../accessibility-auditor/SKILL.md).
+
+## Stack guidance (`--stack` axis)
+
+Per-framework Do/Don't corpora (16 stacks) ride the same manifest:
+
+```bash
+./scripts-run <skills-root>/corpus-grounding/scripts/ground search \
+  --manifest <skills-root>/design-intelligence/data/manifest.json \
+  --stack react "list rerender memo" [--filter "Severity=HIGH"]
+```
+
+Stack executors ([`blade-ui`](../blade-ui/SKILL.md),
+[`livewire`](../livewire/SKILL.md), [`flux`](../flux/SKILL.md),
+[`react-shadcn-ui`](../react-shadcn-ui/SKILL.md),
+[`tailwind-engineer`](../tailwind-engineer/SKILL.md)) pull idiomatic
+guidance + docs URLs from here instead of memory.
+
+## Diagram-type routing — route on the verb
+
+Choose a visualization by the *intent verb*, not the noun. Count the nouns
+before you draw (input-complexity triage): 1–2 → inline prose or a single
+shape; 3–7 → one diagram; 8+ → split or summarize, never one dense picture.
+
+| The user asks… | Intent | Draw |
+|---|---|---|
+| "how does X **work** / flow" | illustrative (intuition) | flowchart / sequence — illustrative default |
+| "what is X's **architecture** / structure" | reference (structural) | structural diagram (boxes + typed edges) |
+| a **cycle** / loop / lifecycle | — | a **stepper widget**, never a hand-drawn ring |
+| a **DB schema / ERD** / entity relations | — | **mermaid**, never hand-placed SVG |
+
+### Geometric pre-checks (run BEFORE finalizing an SVG/diagram)
+
+Ranked by failure rate — procedures, not constants:
+
+1. **viewBox safety** — compute the lowest + rightmost element (plus a buffer)
+   and set the viewBox from that; never assume the default fits.
+2. **arrow-through-box trace** — trace every arrow's path and confirm it does
+   not cross through an unrelated box before drawing it.
+3. **box-width-from-longest-label** — size each box from its longest label
+   before placing it, so text never overflows.
+
+(Reference-only: any color/easing/frame values come from the consumer's tokens
+or a maintained upstream — this skill vendors no drawn-asset corpus.)
+
+## Interplay (who owns what)
+
+| Concern | Owner |
+|---|---|
+| What already exists (components, tokens) | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — mandatory pre-step; audit findings outrank corpus suggestions |
+| What to build (grounded selection) | **this skill** |
+| Stack-agnostic heuristics + flow | [`fe-design`](../fe-design/SKILL.md) — invokes this skill for grounding |
+| Orchestration gates + locks | `directives/ui/{design,review,polish}.ts` — never import the engine |
+| WCAG audit method | [`accessibility-auditor`](../accessibility-auditor/SKILL.md) |
+| Token authoring | [`design-tokens`](../design-tokens/SKILL.md) |
+| Lo-fi structure exploration (pre-selection) | [`wireframe`](../wireframe/SKILL.md) — disposable greyscale variants |
+| Multiple hi-fi options (post-selection) | [`design-variations`](../design-variations/SKILL.md) — grounds each variation via this skill |
+| Fixed-canvas slide decks | [`html-deck`](../html-deck/SKILL.md) — own medium, still corpus-grounded |

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

@@ -160,127 +160,12 @@ When a finding warrants a remediation recommendation, prefer in this order:
 suggesting a different easing curve.* The same applies to decorative elements,
 excessive copy, and redundant UI chrome.
 
-## Before / After / Why output format
+## Section index — load on demand
 
-When reporting a finding with a specific remediation, use this table format:
+Load the reference file whose sections the review needs — never all of them by default:
 
-| Field | Content |
-|---|---|
-| **Before** | The current state (quote the code, value, or describe the pattern) |
-| **After** | The corrected state (specific value or alternative) |
-| **Why** | The mechanism: why is Before wrong and After better? (one sentence, states the principle) |
-
-**Wrong format** (do not use):
-```
-Before:
-  button { transition: all 0.3s ease; }
-After:
-  button { transition: transform 0.2s ease-out, opacity 0.2s ease-out; }
-```
-
-**Right format:**
-
-| | |
-|---|---|
-| **Before** | `transition: all 0.3s ease` |
-| **After** | `transition: transform 0.2s ease-out, opacity 0.2s ease-out` |
-| **Why** | `transition: all` animates layout properties on every state change, causing browser reflow; enumerate only the properties that move. |
-
-The Why column carries the reasoning — it's the part that teaches the developer
-and prevents the same finding from recurring.
-
-## Communication principles
-
-### Problems over prescriptions
-
-Describe **what's wrong and why it matters**, not how to fix it.
-
-```
-❌ "Change margin to 16px"
-✅ "Spacing feels inconsistent with adjacent elements, creating visual clutter near the CTA."
-```
-
-### Triage matrix
-
-Every issue gets a severity:
-
-| Severity | Meaning | Action |
-|---|---|---|
-| **Blocker** | Must fix before merge | Blocks PR |
-| **High** | Should fix before merge | Strong recommendation |
-| **Medium** | Consider for follow-up | Suggestion |
-| **Nitpick** | Optional polish | Prefix with "Nit:" |
-
-### Evidence-based
-
-Screenshots required for all visual issues. Reference specific viewport and state.
-
-### Start positive
-
-Acknowledge what works well before listing issues.
-
-## Report structure
-
-```markdown
-## Design Review Summary
-[Positive opening + overall assessment]
-
-### 🚫 Blockers
-[Critical issues — must fix]
-
-### ⚠️ High Priority
-[Significant issues — should fix]
-
-### 💡 Suggestions
-[Improvements for follow-up]
-
-### ✨ Nitpicks
-[Minor aesthetic details]
-
-### Testing Evidence
-[Screenshots: Desktop, Tablet, Mobile]
-
-### Next Steps
-1. [Fix blockers]
-2. [Address high-priority]
-
-**Overall: [Ready to merge | Needs revisions]**
-```
-
-
-## Visual QA with browser automation
-
-When Playwright MCP or browser tools are available, use them for automated visual verification:
-
-### Before/After comparison
-
-1. **Capture baseline** — screenshot before changes at all 3 viewports.
-2. **Apply changes** — deploy or hot-reload.
-3. **Capture after** — screenshot at the same viewports and states.
-4. **Compare** — visually diff the screenshots, flag regressions.
-
-### State-based verification
-
-Don't just screenshot the default state. Capture:
-
-| State | How to trigger |
-|---|---|
-| Empty | Remove data, check empty state UI |
-| Loading | Throttle network, capture skeleton/spinner |
-| Error | Force an error response, check error UI |
-| Overflow | Add very long text, many items |
-| Interactive | Hover, focus, open dropdowns |
-
-### Mockup-to-code verification
-
-When implementing from a design mockup or screenshot:
-
-1. **Open the mockup** — use the provided image/screenshot.
-2. **Implement** — build the UI component.
-3. **Side-by-side** — compare mockup vs. implementation at the same viewport.
-4. **Flag deviations** — spacing, colors, typography, alignment differences.
-
-This is especially useful when the user provides a screenshot or Figma export as a reference.
+- [`references/review-communication.md`](references/review-communication.md) — Before / After / Why output format · Communication principles · Report structure · Design Review Summary
+- [`references/verification-automation.md`](references/verification-automation.md) — Visual QA with browser automation · Async-verifier pattern (keep the main context clean)
 
 ## Output format
 
@@ -297,28 +182,6 @@ This is especially useful when the user provides a screenshot or Figma export as
 - WCAG
 - responsive
 
-## Async-verifier pattern (keep the main context clean)
-
-For a review that needs browser probing, use an **async background verifier**
-rather than self-screenshotting inline: fork a verifier subagent with its own
-view — it takes the screenshots, probes viewports, and checks states, then
-**stays silent on pass and surfaces only real, actionable problems** (never
-nitpicks). The main agent does not self-screenshot, so its context stays clean
-for the actual review reasoning. This is an orchestration pattern —
-dispatch it via [`subagent-orchestration`](../subagent-orchestration/SKILL.md)
-and position it against [`verify-repair-loop`](../verify-repair-loop/SKILL.md)
-(the existing verify skill); it complements them, it does not duplicate them.
-
-**Why the audit passes stay serial (not a parallel-4 fan-out).** A fan-out of
-a11y + slop + hierarchy + states across four subagents was evaluated and
-deferred: the passes share one live browser/navigation session and later phases
-build on state established by earlier ones, so they are not cleanly independent;
-and the expensive part — browser probing / screenshots — is already offloaded by
-the async verifier above, which captures the fan-out's main win without spinning
-up four separate views. Reconsider only when `design-review` runs as a standalone
-heavy batch over many *independent* surfaces, where per-surface
-`do-in-parallel` genuinely pays.
-
 ## Gotcha
 
 - Don't review design without understanding the user's constraints (time, resources, scope).

package/dist/agent-src/skills/design-review/references/review-communication.md

@@ -0,0 +1,92 @@
+# design-review — review communication
+
+> Section-level entry point of the `design-review` skill (progressive
+> disclosure, 2026-08-04). Content moved VERBATIM from SKILL.md —
+> load this file when the section index in SKILL.md routes here.
+
+## Before / After / Why output format
+
+When reporting a finding with a specific remediation, use this table format:
+
+| Field | Content |
+|---|---|
+| **Before** | The current state (quote the code, value, or describe the pattern) |
+| **After** | The corrected state (specific value or alternative) |
+| **Why** | The mechanism: why is Before wrong and After better? (one sentence, states the principle) |
+
+**Wrong format** (do not use):
+```
+Before:
+  button { transition: all 0.3s ease; }
+After:
+  button { transition: transform 0.2s ease-out, opacity 0.2s ease-out; }
+```
+
+**Right format:**
+
+| | |
+|---|---|
+| **Before** | `transition: all 0.3s ease` |
+| **After** | `transition: transform 0.2s ease-out, opacity 0.2s ease-out` |
+| **Why** | `transition: all` animates layout properties on every state change, causing browser reflow; enumerate only the properties that move. |
+
+The Why column carries the reasoning — it's the part that teaches the developer
+and prevents the same finding from recurring.
+
+## Communication principles
+
+### Problems over prescriptions
+
+Describe **what's wrong and why it matters**, not how to fix it.
+
+```
+❌ "Change margin to 16px"
+✅ "Spacing feels inconsistent with adjacent elements, creating visual clutter near the CTA."
+```
+
+### Triage matrix
+
+Every issue gets a severity:
+
+| Severity | Meaning | Action |
+|---|---|---|
+| **Blocker** | Must fix before merge | Blocks PR |
+| **High** | Should fix before merge | Strong recommendation |
+| **Medium** | Consider for follow-up | Suggestion |
+| **Nitpick** | Optional polish | Prefix with "Nit:" |
+
+### Evidence-based
+
+Screenshots required for all visual issues. Reference specific viewport and state.
+
+### Start positive
+
+Acknowledge what works well before listing issues.
+
+## Report structure
+
+```markdown
+## Design Review Summary
+[Positive opening + overall assessment]
+
+### 🚫 Blockers
+[Critical issues — must fix]
+
+### ⚠️ High Priority
+[Significant issues — should fix]
+
+### 💡 Suggestions
+[Improvements for follow-up]
+
+### ✨ Nitpicks
+[Minor aesthetic details]
+
+### Testing Evidence
+[Screenshots: Desktop, Tablet, Mobile]
+
+### Next Steps
+1. [Fix blockers]
+2. [Address high-priority]
+
+**Overall: [Ready to merge | Needs revisions]**
+```

package/dist/agent-src/skills/design-review/references/verification-automation.md

@@ -0,0 +1,61 @@
+# design-review — verification automation
+
+> Section-level entry point of the `design-review` skill (progressive
+> disclosure, 2026-08-04). Content moved VERBATIM from SKILL.md —
+> load this file when the section index in SKILL.md routes here.
+
+## Visual QA with browser automation
+
+When Playwright MCP or browser tools are available, use them for automated visual verification:
+
+### Before/After comparison
+
+1. **Capture baseline** — screenshot before changes at all 3 viewports.
+2. **Apply changes** — deploy or hot-reload.
+3. **Capture after** — screenshot at the same viewports and states.
+4. **Compare** — visually diff the screenshots, flag regressions.
+
+### State-based verification
+
+Don't just screenshot the default state. Capture:
+
+| State | How to trigger |
+|---|---|
+| Empty | Remove data, check empty state UI |
+| Loading | Throttle network, capture skeleton/spinner |
+| Error | Force an error response, check error UI |
+| Overflow | Add very long text, many items |
+| Interactive | Hover, focus, open dropdowns |
+
+### Mockup-to-code verification
+
+When implementing from a design mockup or screenshot:
+
+1. **Open the mockup** — use the provided image/screenshot.
+2. **Implement** — build the UI component.
+3. **Side-by-side** — compare mockup vs. implementation at the same viewport.
+4. **Flag deviations** — spacing, colors, typography, alignment differences.
+
+This is especially useful when the user provides a screenshot or Figma export as a reference.
+
+## Async-verifier pattern (keep the main context clean)
+
+For a review that needs browser probing, use an **async background verifier**
+rather than self-screenshotting inline: fork a verifier subagent with its own
+view — it takes the screenshots, probes viewports, and checks states, then
+**stays silent on pass and surfaces only real, actionable problems** (never
+nitpicks). The main agent does not self-screenshot, so its context stays clean
+for the actual review reasoning. This is an orchestration pattern —
+dispatch it via [`subagent-orchestration`](../subagent-orchestration/SKILL.md)
+and position it against [`verify-repair-loop`](../verify-repair-loop/SKILL.md)
+(the existing verify skill); it complements them, it does not duplicate them.
+
+**Why the audit passes stay serial (not a parallel-4 fan-out).** A fan-out of
+a11y + slop + hierarchy + states across four subagents was evaluated and
+deferred: the passes share one live browser/navigation session and later phases
+build on state established by earlier ones, so they are not cleanly independent;
+and the expensive part — browser probing / screenshots — is already offloaded by
+the async verifier above, which captures the fan-out's main win without spinning
+up four separate views. Reconsider only when `design-review` runs as a standalone
+heavy batch over many *independent* surfaces, where per-surface
+`do-in-parallel` genuinely pays.

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

@@ -234,6 +234,14 @@ violations will surface as new findings on every run.
 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.
 
+## Section index — load on demand
+
+Load on demand once the audit needs the pitfall catalog:
+
+- [`references/anti-slop-cross-reference.md`](references/anti-slop-cross-reference.md) — Anti-slop cross-reference
+
+- [`references/output-and-pitfalls.md`](references/output-and-pitfalls.md) — Output format · Gotcha · Anti-slop cross-reference
+
 ## Output format
 
 1. **`state.ui_audit.components`** — array of component/template descriptors (path, name, kind, exports)
@@ -273,33 +281,6 @@ tool produces, so the import path is uniform.
   that run are absent from the inventory the later ones are checked against.
   Adding a second component in the same run → re-read the component directories
   directly rather than trusting `state.ui_audit.components_found`.
-
-## Anti-slop cross-reference
-
-When the audit inventory reveals an existing aesthetic direction (dominant color
-scheme, border-radius convention, motion patterns), cross-check the findings
-against
-[`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md).
-If the existing UI already uses a listed anti-pattern, surface it as a design-debt
-finding (separate from the reuse inventory) — flag by entry ID and severity.
-
-**What the design step may then do depends on whose aesthetic it is.** These
-are two different situations and the sentence that used to cover both was
-wrong about one of them:
-
-| The anti-pattern lives in… | The design step may… |
-|---|---|
-| **The consumer's own legacy UI** (inventoried from the repo) | continue it for consistency, **or** propose a corrective direction change. Both are legitimate; it is their codebase and their debt. |
-| **A supplied spec** (a handed-over artifact, a `design-system.json`, a registered brand token) | **neither.** Build it as given. The finding is recorded as informational, marked `artifact_covered`, and no polish round acts on it. |
-
-A corrective direction change against a supplied spec is not a design
-improvement, it is overriding a decision the user already made — the failure
-[`design-fidelity`](../../rules/design-fidelity.md) exists to prevent, arriving
-through the audit's side door. Precedence and its exact scope:
-[`design-fidelity-mechanics`](../../../docs/guidelines/design-fidelity-mechanics.md)
-§ Provided-artifact precedence. Where the two sources disagree, surface the
-conflict rather than picking (fixture `daf-slop-vs-provided`).
-
 ## Do NOT
 
 - Do NOT advance to `directives/ui/design.ts` or `apply.ts` if `state.ui_audit` is empty.

package/dist/agent-src/skills/existing-ui-audit/references/anti-slop-cross-reference.md

@@ -0,0 +1,31 @@
+# existing-ui-audit — anti-slop cross-reference
+
+> Section-level entry point of the `existing-ui-audit` skill (progressive
+> disclosure, 2026-08-04). Content moved VERBATIM from SKILL.md —
+> load this file when the section index in SKILL.md routes here.
+
+## Anti-slop cross-reference
+
+When the audit inventory reveals an existing aesthetic direction (dominant color
+scheme, border-radius convention, motion patterns), cross-check the findings
+against
+[`docs/guidelines/design-antipatterns.md`](../../../../docs/guidelines/design-antipatterns.md).
+If the existing UI already uses a listed anti-pattern, surface it as a design-debt
+finding (separate from the reuse inventory) — flag by entry ID and severity.
+
+**What the design step may then do depends on whose aesthetic it is.** These
+are two different situations and the sentence that used to cover both was
+wrong about one of them:
+
+| The anti-pattern lives in… | The design step may… |
+|---|---|
+| **The consumer's own legacy UI** (inventoried from the repo) | continue it for consistency, **or** propose a corrective direction change. Both are legitimate; it is their codebase and their debt. |
+| **A supplied spec** (a handed-over artifact, a `design-system.json`, a registered brand token) | **neither.** Build it as given. The finding is recorded as informational, marked `artifact_covered`, and no polish round acts on it. |
+
+A corrective direction change against a supplied spec is not a design
+improvement, it is overriding a decision the user already made — the failure
+[`design-fidelity`](../../rules/design-fidelity.md) exists to prevent, arriving
+through the audit's side door. Precedence and its exact scope:
+[`design-fidelity-mechanics`](../../../../docs/guidelines/design-fidelity-mechanics.md)
+§ Provided-artifact precedence. Where the two sources disagree, surface the
+conflict rather than picking (fixture `daf-slop-vs-provided`).