tribunal-kit 5.8.2 → 5.8.4

package/.agent/skills/delight/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: delight
+description: Inject micro-moments of delight, subtle surprise interactions, personality, and tactile feedback into user interfaces. Use when building success celebrations, copy-to-clipboard feedback, empty states, or playful UI elements.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: Micro-Delight & Interactive Polish
+  tier: pro
+  co-requires: [whimsy-injector, micro-interaction, emil-design-eng]
+  trigger-signals:
+    strong: [delight, micro-delight, make it playful, add personality, surprise animation, tactile feedback]
+    weak: [sparkle, fun ui, success feedback]
+---
+
+# Delight — Micro-Moments of Tactile UI Polish
+
+Elevate everyday digital interactions with subtle, memorable details that make software a joy to use.
+
+---
+
+## 5 Micro-Delight Patterns
+
+### 1. The Morphing State Checkmark
+- When clicking "Copy Link" or "Save", morph the button icon or label smoothly into a checkmark icon with a quick spring bounce (`scale(1.15) -> scale(1)` over `180ms`), holding for 1.5 seconds before morphing back.
+
+### 2. Micro-Confetti & Particle Bursts
+- On completing a key milestone (e.g. completing onboarding, submitting a project), trigger a lightweight 12-particle CSS/canvas burst anchored directly to the submit button.
+
+### 3. Tactile Drag & Reorder Haptics
+- When dragging list items, elevate the item with a slight tilt ($2^\circ$), drop shadow increase, and scale (`scale(1.02)`), giving a physical card feeling.
+
+### 4. Playful Empty State Animations
+- Transform boring zero-data states with subtle floating illustrations, witty microcopy, and a prominent primary action button.
+
+### 5. Keyboard Shortcut Badges with Tooltips
+- Display subtle keyboard shortcut hints (e.g. `⌘K` or `Ctrl+K`) inside inputs or hover tooltips that respond with a subtle keypress press animation when pressed.
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Overdoing Delight on High-Frequency Actions**: Adding confetti bursts or long animations to actions users perform 50+ times a day. Keep high-frequency delight under 100ms and non-intrusive.
+2. **Ignoring Accessibility**: Failing to check `prefers-reduced-motion` for particle effects or canvas animations.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Active reviewers: `motion-reviewer` · `frontend-reviewer`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Is the delight moment brief (< 300ms for motion, 1.5s total hold)?
+✅ Does it respect `prefers-reduced-motion`?
+✅ Is it restricted to occasional milestones or state confirmations?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

package/.agent/skills/design-lab/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: design-lab
+description: Interactive design exploration workflow: conduct interviews, generate variants, and refine UI designs through user feedback loops.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: Design Exploration & UI Variants
+  tier: pro
+  co-requires: [brainstorming, shape, frontend-design]
+  trigger-signals:
+    strong: [design-lab, design exploration, generate variants, interactive design workflow, UI experiment]
+    weak: [explore designs, design options]
+---
+
+# Design Lab — Interactive Design Exploration & Variants
+
+Conduct rapid design experiments, explore multiple structural variants, and iteratively refine interfaces with feedback.
+
+---
+
+## 3 Design Lab Phases
+
+### Phase 1: Context & Constraint Gathering
+Ask 2 targeted questions to map out design direction:
+1. What aesthetic tone fits best? (e.g. Minimalist Editorial vs High-Impact Brutalist vs Clean Corporate SaaS)
+2. What component variants would you like to explore? (e.g. Card layout options A vs B)
+
+### Phase 2: Generating Distinct Structural Variants
+Generate 2 distinct visual variants (e.g. Option A: Centered Minimalist vs Option B: Asymmetrical Card Grid).
+
+### Phase 3: Interactive Refinement
+Synthesize feedback on preferred elements and build the polished final component.
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Generating Micro-Variations**: Creating 2 "variants" that differ by only a 1px border or hex color. Make variants structurally distinct.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Active reviewers: `frontend-reviewer` · `ui-ux-auditor`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Are the generated design variants visually and layout-wise distinct?
+✅ Is user feedback incorporated before committing to the final version?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

package/.agent/skills/diagnosing-bugs/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: diagnosing-bugs
+description: Systematic bug diagnosis methodology for hard bugs: Phase 1 (Build feedback loop), Phase 2 (Reproduce + minimise), Phase 3 (Hypothesise), Phase 4 (Instrument), Phase 5 (Fix + regression test), Phase 6 (Cleanup + post-mortem).
+version: 2.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: Systematic Debugging & Root Cause Isolation
+  tier: pro
+  co-requires: [systematic-debugging, test-result-analyzer]
+  trigger-signals:
+    strong: [diagnosing-bugs, systematic bug diagnosis, reproduce bug, root cause isolation, intermittent bug, debug protocol, hard bugs]
+    weak: [fix bug, investigate error]
+---
+
+# Diagnosing Bugs — A Discipline for Hard Bugs
+
+A systematic discipline for hard bugs. Skip phases only when explicitly justified.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
+
+---
+
+## Protocol Overview
+
+```
+Phase 1: Build a Feedback Loop ──► Phase 2: Reproduce + Minimise ──► Phase 3: Hypothesise
+                                                                               │
+Phase 6: Cleanup + Post-Mortem ◄── Phase 5: Fix + Regression Test ◄── Phase 4: Instrument
+```
+
+---
+
+## Phase 1 — Build a Feedback Loop
+
+This is the core skill. Everything else is mechanical. If you have a tight pass/fail signal for the bug — one that goes red on this bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.
+
+### 10 Strategies to Construct a Feedback Loop (in priority order)
+
+1. **Failing Test at Whatever Seam Reaches the Bug**: Unit, integration, or E2E test.
+2. **Curl / HTTP Script**: Send requests against a running dev server.
+3. **CLI Invocation with Fixture Input**: Diffing stdout/stderr against a known-good snapshot.
+4. **Headless Browser Script (Playwright / Puppeteer)**: Drives the UI, asserts on DOM/console/network.
+5. **Replay a Captured Trace**: Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway Harness**: Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / Fuzz Loop**: If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection Harness**: If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can run `git bisect`.
+9. **Differential Loop**: Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL Bash Script**: Last resort. If a human must click, drive them with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Tighten the Loop
+
+Treat the loop as a product. Once you have a loop, tighten it:
+- **Can I make it faster?** (Cache setup, skip unrelated init, narrow the test scope.)
+- **Can I make the signal sharper?** (Assert on the specific symptom, not "didn't crash".)
+- **Can I make it more deterministic?** (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+> ⚡ **Debugging Superpower**: A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is a debugging superpower.
+
+### Non-Deterministic Bugs
+
+The goal is not a clean repro but a higher reproduction rate. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When You Genuinely Cannot Build a Loop
+
+Stop and say so explicitly. List what you tried. Ask the user for:
+1. Access to whatever environment reproduces it.
+2. A captured artifact (HAR file, log dump, core dump, screen recording with timestamps).
+3. Permission to add temporary production instrumentation.
+
+*Do not proceed to hypothesise without a loop.*
+
+### Phase 1 Completion Criterion — A Tight Loop That Goes Red
+
+Phase 1 is done when the loop is tight and red-capable: you can name **one command** — a script path, a test invocation, a curl — that you have already run at least once (paste the invocation and its output), and that is:
+- ✅ **Red-capable**: Drives the actual bug code path and asserts the user's exact symptom, going red on this bug and green once fixed. Not "runs without erroring" — it must catch this specific bug.
+- ✅ **Deterministic**: Same verdict every run (or high, pinned reproduction rate).
+- ✅ **Fast**: Seconds, not minutes.
+- ✅ **Agent-runnable**: Runnable unattended (HITL only via `scripts/hitl-loop.template.sh`).
+
+*If you catch yourself reading code to build a theory before this command exists, stop. No red-capable command, no Phase 2.*
+
+---
+
+## Phase 2 — Reproduce + Minimise
+
+Run the loop. Watch it go red — the bug appears.
+
+### Confirm
+1. The loop produces the failure mode the user described — not a different failure nearby. (Wrong bug = wrong fix.)
+2. The failure is reproducible across multiple runs (or at a high enough reproduction rate).
+3. You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix addresses it.
+
+### Minimise
+Once it's red, shrink the repro to the smallest scenario that still goes red. Cut inputs, callers, config, data, and steps one at a time, re-running the loop after each cut — keep only what's load-bearing for the failure.
+
+> 🎯 **Why bother**: A minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+**Done when every remaining element is load-bearing — removing any single one makes the loop go green.**
+
+---
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+**Format**: `"If [X] is the cause, then [Y] will make the bug disappear / will make it worse."`
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+Show the ranked list to the user before testing. (Proceed with your ranking if the user is AFK.)
+
+---
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. Change one variable at a time.
+
+### Tool Preference
+1. **Debugger / REPL Inspection**: If the environment supports it. One breakpoint beats ten logs.
+2. **Targeted Logs**: Place logs at boundaries that distinguish hypotheses. Never "log everything and grep".
+3. **Tag Every Debug Log**: Prefix every debug log with a unique tag, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep.
+4. **Performance Profiling Branch**: For performance regressions, establish a baseline measurement (`timing harness`, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+---
+
+## Phase 5 — Fix + Regression Test
+
+Write the regression test before the fix — but only if there is a correct seam for it.
+
+A correct seam is one where the test exercises the real bug pattern as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+If no correct seam exists, note it. The codebase architecture is preventing the bug from being locked down. Flag this for Phase 6.
+
+### If a Correct Seam Exists:
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+---
+
+## Phase 6 — Cleanup + Post-Mortem
+
+### Required Before Declaring Done
+- [ ] Original repro no longer reproduces (re-run Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (grep the prefix)
+- [ ] Throwaway prototypes deleted (or moved to debug location)
+- [ ] Correct hypothesis stated in commit / PR message
+
+### Post-Mortem Handoff
+Ask: **What would have prevented this bug?** If the answer involves architectural debt (no good test seam, tangled callers, hidden coupling), hand off to `/improve-codebase-architecture` with specific findings.
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Shotgun Debugging**: Making random edits across multiple files hoping the error disappears.
+2. **Reading Code to Build Theories Before Having a Red Loop**: Jumping straight to hypotheses without a red-capable command.
+3. **Symptom Swallowing**: Wrapping a throwing call in silent `try/catch` or returning empty fallbacks instead of addressing root cause.
+4. **Testing Multiple Hypotheses at Once**: Changing multiple variables simultaneously, creating ambiguous results.
+
+---
+
+## 🏛️ Tribunal Integration & Pre-Flight Self-Audit
+
+**Active Reviewers: `debugger` · `logic-reviewer` · `resilience-reviewer`**
+
+```
+✅ Has a red-capable feedback loop command been executed and verified red?
+✅ Has the repro scenario been minimised to only load-bearing elements?
+✅ Were 3–5 falsifiable hypotheses formulated before testing?
+✅ Are all debug logs tagged with [DEBUG-...] and cleaned up before merge?
+✅ Has a regression test been added at a valid seam?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

package/.agent/skills/distill/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: distill
+description: Simplify noisy interfaces by removing non-essential visual and operational complexity. Use when a UI has too many options, crowded toolbars, redundant text, or unnecessary visual containers.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: UX Simplification & Reduction
+  tier: pro
+  co-requires: [quieter, clarify, baseline-ui]
+  trigger-signals:
+    strong: [distill, simplify ui, declutter, remove complexity, streamline interface, too crowded]
+    weak: [clean up, simplify options]
+---
+
+# Distill — UX Simplification & Decluttering
+
+Systematically strip away visual clutter, redundant controls, and cognitive friction to reveal the core user task.
+
+---
+
+## The 4 Distillation Steps
+
+### 1. Identify & Remove Visual Noise
+- **Container Reduction**: Eliminate unnecessary nested cards, boxes inside boxes, and decorative borders. Use whitespace instead of lines to separate content blocks.
+- **Icon Pruning**: Remove decorative icons that restate obvious text labels (e.g. an envelope icon next to a button that clearly says "Send Email").
+
+### 2. Collapse Secondary Actions
+- **Primary vs Overflow**: Keep only 1 primary action button and max 1 secondary button visible. Hide tertiary actions inside an overflow dropdown (`...` menu).
+- **Progressive Disclosure**: Hide advanced settings or non-essential controls behind an "Advanced Settings" accordion or popover.
+
+### 3. Trim Copy & Microcopy
+- **Cut Conversational Filler**: Strip verbose instructions. Change *"Please fill out the form below to register your account"* to *"Create account"*.
+- **Shorten Button Labels**: Change *"Click here to update your profile settings"* to *"Save profile"*.
+
+### 4. Group Related Fields
+- **Consolidate Form Inputs**: Merge separate "First Name" and "Last Name" fields into "Full Name" if separate values aren't strictly required. Merge city/state/zip into single address lookup where possible.
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Hiding Essential Actions**: Removing actions that users need frequently, forcing extra clicks.
+2. **Deleting Error Context**: Removing helpful inline validation messages while trimming copy.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Active reviewers: `frontend-reviewer` · `ui-ux-auditor`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Is the primary task front and center without distraction?
+✅ Have secondary/tertiary options been cleanly collapsed or progressively disclosed?
+✅ Is all microcopy concise, active, and direct?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

package/.agent/skills/domain-modeling/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: domain-modeling
+description: Builds and sharpens project domain models, ubiquitous language, entity relationships, and bounded contexts before writing code.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: Domain Driven Design & Business Modeling
+  tier: pro
+  co-requires: [architecture, codebase-design]
+  trigger-signals:
+    strong: [domain-modeling, ubiquitous language, bounded context, aggregate root, domain entity, business logic model]
+    weak: [model data, data entities]
+---
+
+# Domain Modeling — Ubiquitous Language & Bounded Contexts
+
+Model business domain concepts cleanly before committing to database schemas or API signatures.
+
+---
+
+## 4 Domain Modeling Rules
+
+### 1. Establish Ubiquitous Language
+- Agree on strict, unambiguous terms used identically across domain experts, code variable names, database tables, and UI copy.
+  - ❌ *User*, *Account*, *Member*, *Client* used interchangeably for the same concept.
+  - ✅ Define 1 clear term: **Customer** (for billing context) vs **User** (for authentication context).
+
+### 2. Define Bounded Contexts
+- Separate large systems into distinct bounded contexts. An entity named `Product` in the *Inventory Context* (stock level, warehouse bin) has different attributes than `Product` in the *Catalog Context* (hero image, pricing).
+
+### 3. Aggregates & Invariants
+- An **Aggregate Root** (e.g. `Order`) enforces internal business invariants across child entities (`OrderItem`).
+- Never mutate a child entity (`OrderItem`) directly without passing through the aggregate root method (`order.addItem(product, qty)`).
+
+### 4. Value Objects Over Primitives
+- Wrap primitives into type-safe Value Objects to enforce validation logic:
+```typescript
+// Value Object enforcing domain rule
+export class EmailAddress {
+  private readonly value: string;
+
+  constructor(email: string) {
+    if (!email.includes("@")) throw new Error("Invalid email domain");
+    this.value = email.toLowerCase().trim();
+  }
+
+  public toString(): string { return this.value; }
+}
+```
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Anemic Domain Models**: Creating plain data structures (`DTOs`) without domain methods, pushing business logic into scattered service files.
+2. **Mixing Contexts**: Creating 1 giant `User` table with 60 columns spanning auth, billing, shipping, and notification preferences.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Active reviewers: `logic-reviewer` · `type-safety`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Are entity names strictly consistent with the project's ubiquitous language?
+✅ Are domain invariants enforced inside Aggregate Roots?
+✅ Have complex primitives been converted into type-safe Value Objects?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.

package/.agent/skills/fixing-accessibility/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: fixing-accessibility
+description: Audit and fix HTML accessibility issues including ARIA labels, keyboard navigation, focus management, color contrast, and form errors. Use when adding interactive controls, forms, dialogs, or reviewing WCAG compliance.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: UI Craft & Accessibility
+  tier: pro
+  co-requires: [audit-and-fix, web-accessibility-auditor]
+  trigger-signals:
+    strong: [fixing-accessibility, accessibility audit, WCAG 2.2, aria-label, keyboard navigation, focus trap, color contrast]
+    weak: [a11y, focus ring, screen reader]
+---
+
+# Fixing Accessibility — WCAG 2.2 AA Audit & Remediation
+
+Guidelines for detecting, prioritizing, and fixing accessibility defects across web interfaces.
+
+---
+
+## 1. Priority Priority Matrix
+
+| Priority | Category | Critical Requirements |
+| --- | --- | --- |
+| **P1** | **Accessible Names** | Every icon button MUST have `aria-label` or `aria-labelledby`. Decorative icons MUST have `aria-hidden="true"`. |
+| **P2** | **Keyboard Access** | All interactive controls MUST be reachable and operable via `Tab` / `Shift+Tab`, `Space`, `Enter`. NEVER use `<div>` or `<span>` as clickable elements without `role="button"`, `tabIndex={0}`, and key handlers. |
+| **P3** | **Focus & Dialogs** | Modals/Dialogs MUST trap focus within the dialog container while open, return focus to trigger on close, and dismiss on `Escape`. |
+| **P4** | **Color Contrast** | Text MUST satisfy WCAG AA 4.5:1 ratio (3.0:1 for large text). Focus rings MUST have at least 3.0:1 contrast against adjacent background. |
+| **P5** | **Form Validation** | Inputs MUST have explicit `<label>` or `aria-labelledby`. Errors MUST use `aria-invalid="true"` and `aria-describedby` pointing to error text. |
+
+---
+
+## 2. Accessible Code Patterns
+
+### Icon-Only Button
+```tsx
+// ✅ SAFE & ACCESSIBLE
+<button
+  type="button"
+  onClick={onClose}
+  className="p-2 rounded-md hover:bg-neutral-100 dark:hover:bg-neutral-800"
+  aria-label="Close dialog"
+>
+  <XIcon className="w-5 h-5" aria-hidden="true" />
+</button>
+```
+
+### Accessible Modal Dialog Focus Trap
+```tsx
+// ✅ SAFE & ACCESSIBLE
+<div
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby="dialog-title"
+  aria-describedby="dialog-description"
+  className="fixed inset-0 z-50 flex items-center justify-center bg-black/50"
+>
+  <div className="bg-surface p-6 rounded-xl max-w-md w-full">
+    <h2 id="dialog-title" className="text-xl font-bold">Confirm Deletion</h2>
+    <p id="dialog-description" className="text-muted mt-2">This action cannot be undone.</p>
+    {/* Actions */}
+  </div>
+</div>
+```
+
+---
+
+## Anti-Slop Table
+
+| Violation | Accessible Fix | Impact |
+| --- | --- | --- |
+| `<div onClick={submit}>Submit</div>` | `<button type="button" onClick={submit}>Submit</button>` | Fixes screen reader announcement & keyboard trigger |
+| `<button><TrashIcon /></button>` | `<button aria-label="Delete item"><TrashIcon aria-hidden="true" /></button>` | Gives screen reader clear accessible name |
+| `outline: none` in CSS | `:focus-visible { outline: 2px solid var(--ring); outline-offset: 2px; }` | Restores visible keyboard focus indicator |
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Stripping Focus Outlines**: Setting `outline: none` without providing a visible `:focus-visible` replacement.
+2. **Duplicate ARIA Labels**: Putting `aria-label` on both a outer button and inner text/icon simultaneously.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Are all icon buttons properly labeled with aria-label?
+✅ Can all interactive elements be operated using keyboard only (Tab + Space/Enter)?
+✅ Do form fields have explicit aria-describedby associations for helper and error text?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+Test keyboard navigation (`Tab`, `Shift+Tab`, `Escape`) in browser preview before finalizing code.

package/.agent/skills/fixing-metadata/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: fixing-metadata
+description: Audit and fix page metadata including page titles, meta descriptions, Open Graph, Twitter cards, canonical URLs, and JSON-LD structured data.
+version: 1.0.0
+last-updated: 2026-07-22
+applies-to-model: gemini-3-6-flash, claude-3-7-sonnet
+routing:
+  domain: Technical SEO & Metadata Optimization
+  tier: pro
+  co-requires: [seo-fundamentals, web-quality-audit]
+  trigger-signals:
+    strong: [fixing-metadata, Open Graph tags, Twitter card metadata, canonical URL, JSON-LD structured data, meta description fix]
+    weak: [fix metadata, SEO tags]
+---
+
+# Fixing Metadata — Technical SEO & Open Graph Tags
+
+Audit, generate, and fix page metadata for rich social previews, search engine indexing, and structured data.
+
+---
+
+## 4 Metadata Standard Requirements
+
+### 1. Title & Meta Description Length & Formatting
+- **Title Tag**: 50–60 characters max (*"Product Title | Brand Name"*).
+- **Meta Description**: 140–155 characters max. Must contain active call to value without truncating on search result cards.
+
+### 2. Open Graph & Twitter Card Matrix
+```html
+<!-- Open Graph / Facebook / LinkedIn -->
+<meta property="og:type" content="website" />
+<meta property="og:title" content="UI Skills for Design Engineers" />
+<meta property="og:description" content="A curated collection of design-engineering skills for accessibility, motion, and frontend craft." />
+<meta property="og:image" content="https://example.com/og-image.jpg" />
+<meta property="og:image:width" content="1200" />
+<meta property="og:image:height" content="630" />
+
+<!-- Twitter / X -->
+<meta name="twitter:card" content="summary_large_image" />
+<meta name="twitter:title" content="UI Skills for Design Engineers" />
+<meta name="twitter:description" content="A curated collection of design-engineering skills for accessibility, motion, and frontend craft." />
+<meta name="twitter:image" content="https://example.com/twitter-image.jpg" />
+```
+
+### 3. Canonical Tag Verification
+```html
+<link rel="canonical" href="https://example.com/current-page-path" />
+```
+
+### 4. Next.js App Router Metadata Export Example
+```typescript
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "UI Skills for Design Engineers",
+  description: "Curated design-engineering skills for accessibility, motion, and frontend craft.",
+  openGraph: {
+    title: "UI Skills for Design Engineers",
+    description: "Curated design-engineering skills for accessibility, motion, and frontend craft.",
+    url: "https://example.com",
+    images: [{ url: "https://example.com/og.jpg", width: 1200, height: 630 }],
+  },
+  twitter: {
+    card: "summary_large_image",
+    title: "UI Skills for Design Engineers",
+    images: ["https://example.com/twitter.jpg"],
+  },
+};
+```
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Relative Image URLs in OG Metadata**: Using `<meta property="og:image" content="/og.jpg">` instead of full absolute HTTPS URLs (`https://domain.com/og.jpg`).
+2. **Missing `summary_large_image`**: Forgetting `twitter:card` type, causing Twitter/X to render a tiny square thumbnail instead of a prominent banner preview.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Active reviewers: `seo-specialist` · `frontend-reviewer`**
+
+### ✅ Pre-Flight Self-Audit
+
+```
+✅ Are OpenGraph and Twitter card image URLs absolute HTTPS links?
+✅ Is title length between 50 and 60 characters?
+✅ Is canonical URL explicitly defined?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.