tribunal-kit 2.4.6 → 3.0.0

package/.agent/workflows/tribunal-performance.md

@@ -1,152 +1,133 @@
----
-description: Performance-specific Tribunal. Runs Logic + Performance reviewers. Use for optimization, profiling, and bottleneck analysis.
----
-
-# /tribunal-performance — Performance Code Tribunal
-
-$ARGUMENTS
-
----
-
-This command activates the **Performance Tribunal** — a focused panel targeting algorithmic complexity, memory bloat, blocking I/O, and throughput bottlenecks before they hit production.
-
-Use this instead of `/tribunal-full` when you specifically need a performance lens. It avoids noise from unrelated reviewers.
-
----
-
-## When to Use This vs Other Tribunals
-
-| Code type | Right tribunal |
-|---|---|
-| Performance-critical loops, async patterns | `/tribunal-performance` ← you are here |
-| Security vulnerabilities | `/tribunal-backend` or `/tribunal-full` |
-| Mobile-specific performance | `/tribunal-mobile` (includes mobile perf issues) |
-| SQL N+1 or unbounded queries | `/tribunal-database` |
-| Cross-domain or pre-merge | `/tribunal-full` |
-
----
-
-## Active Reviewers
-
-| Reviewer | What It Catches |
-|---|---|
-| `logic-reviewer` | Hallucinated methods, impossible logic, undefined refs |
-| `performance-reviewer` | O(n²) complexity, blocking I/O, memory floods, missing pagination, no streaming |
-
----
-
-## What Gets Flagged — Real Examples
-
-| Pattern | Example | Severity |
-|---|---|---|
-| O(n²) complexity | `Array.includes()` inside a `for` loop | ❌ REJECTED |
-| Blocking I/O in async context | `fs.readFileSync()` inside an `async` handler | ❌ REJECTED |
-| Uncontrolled concurrency | `Promise.all(items.map(item => fetchItem(item)))` where `items.length` is unbounded | ❌ REJECTED |
-| Memory flood | Loading entire table into memory: `const all = await db.findMany()` | ❌ REJECTED |
-| Expensive re-renders | Derived value recomputed on every render without `useMemo` | ⚠️ WARNING |
-| No streaming on large responses | Returning full LLM response, not streaming | ⚠️ WARNING |
-| Sort on every render | `items.sort(fn)` inside JSX (mutates original array) | ❌ REJECTED |
-| Regex in hot path | Complex regex compiled on every call (not pre-compiled) | ⚠️ WARNING |
-
----
-
-## Pipeline
-
-```
-Your code
-    │
-    ▼
-logic-reviewer       → Hallucinated methods, undefined refs
-    │
-    ▼
-performance-reviewer → O(n²) complexity, Array.includes() in loops,
-                       blocking fs.readFileSync() in async contexts,
-                       unbounded SELECT *, uncontrolled Promise.all floods,
-                       missing useMemo() on expensive derivations,
-                       no streaming on LLM responses,
-                       missing pagination on large datasets
-    │
-    ▼
-Verdict Summary
-```
-
----
-
-## Output Format
-
-```
-━━━ Tribunal: Performance ━━━━━━━━━━━━━━━━━
-
-Active reviewers: logic · performance
-
-[Your code under review]
-
-━━━ Verdicts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-logic-reviewer:       ✅ APPROVED
-performance-reviewer: ❌ REJECTED
-
-━━━ Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-performance-reviewer:
-  ❌ HIGH — Line 18
-     O(n²): Array.includes() inside for loop — O(n) lookup inside O(n) loop
-     Fix: Convert `otherList` to a Set before the loop for O(1) lookup
-
-  ❌ HIGH — Line 34
-     Blocking I/O: fs.readFileSync() inside async handler blocks the event loop
-     Fix: await fs.promises.readFile(path, 'utf-8')
-
-  ⚠️ MEDIUM — Line 52
-     No streaming: LLM response buffered before returning to client
-     Fix: Pipe the stream directly: res.pipe(openaiStream)
-
-━━━ Verdict: REJECTED ━━━━━━━━━━━━━━━━━━━━
-```
-
----
-
-## Severity Levels
-
-| Level | Meaning |
-|---|---|
-| `❌ REJECTED (HIGH)` | Will cause visible performance degradation under load — fix before merge |
-| `❌ REJECTED (MEDIUM)` | Will become a bottleneck at scale — address before deploy |
-| `⚠️ WARNING` | Acceptable now, will degrade at 10x scale — flag for upcoming sprint |
-| `✅ APPROVED` | No performance concerns detected at this code level |
-
----
-
-## Performance-Specific Anti-Hallucination Rules
-
-```
-❌ Never claim a fix is "faster" without citing the algorithmic reason (O-notation or benchmark)
-❌ Never recommend Promise.all for unbounded arrays — always suggest chunking with p-limit or similar
-❌ Never mark O(n²) as acceptable without explicit justification tied to data size constraints
-❌ Never suggest caching without identifying the invalidation strategy
-❌ Never recommend premature micro-optimizations over algorithmic improvements
-❌ No invented profiling tools — only documented options for the target runtime
-```
-
----
-
-## Cross-Workflow Navigation
-
-| Finding type | Next step |
-|---|---|
-| O(n²) pattern found | `/refactor` to extract and fix the algorithm |
-| Memory bloat in data loading | `/enhance` to add pagination or streaming |
-| Promise.all flood | `/enhance` to add concurrency control with `p-limit` |
-| Regex in hot path | `/enhance` to pre-compile and cache |
-| All approved | Human Gate to write to disk |
-
----
-
-## Usage
-
-```
-/tribunal-performance the data processing loop in userService.ts
-/tribunal-performance the search filter function that runs on every keystroke
-/tribunal-performance the batch API handler that fetches user data
-/tribunal-performance the LLM response handler
-```
+---
+description: Performance-specific Tribunal. Runs Logic + Performance reviewers. Use when code is slow, for optimization tasks, bundle analysis, Core Web Vitals improvement, memory leak investigation, and before deploying performance-critical features.
+---
+
+# /tribunal-performance — Performance Audit
+
+$ARGUMENTS
+
+---
+
+## When to Use /tribunal-performance
+
+| Use `/tribunal-performance` when... | Use something else when... |
+|:---|:---|
+| LCP, INP, or CLS is above threshold | General code review → `/tribunal-full` |
+| Bundle size is too large | Backend perf only → `/tribunal-backend` |
+| Memory usage grows unbounded | Database perf → `/tribunal-database` |
+| Node.js event loop is saturated | |
+| Optimizing rendering performance | |
+
+---
+
+## 2 Active Reviewers (Both Run Simultaneously)
+
+### logic-reviewer
+- Expensive computation in render function (runs every render)
+- Missing memoization where React.memo/useMemo would help
+- Infinite re-render loop (effect updates a value that triggers the effect)
+
+### performance-reviewer
+- INP: expensive synchronous work on user interaction (> 50ms blocking)
+- LCP: hero image without priority={true} or preload hint
+- CLS: missing width/height on images causing layout shift
+- Bundle: large library imported without tree-shaking or dynamic import
+- Memory: event listeners added without cleanup in useEffect
+- N+1: database queries in loop should be batched
+- Cache: expensive DB query without Redis/memory cache
+
+---
+
+## 2026 CWV Targets (Verdict Reference)
+
+| Metric | Good | Needs Work | Poor (REJECTED) |
+|:---|:---|:---|:---|
+| INP | < 200ms | 200–500ms | > 500ms |
+| LCP | < 2.5s | 2.5–4.0s | > 4.0s |
+| CLS | < 0.1 | 0.1–0.25 | > 0.25 |
+
+---
+
+## Verdict System
+
+```
+If code contains patterns causing POOR rating → ❌ REJECTED
+If code contains patterns causing NEEDS WORK → ⚠️ WARNING
+If all patterns cause GOOD rating → ✅ APPROVED
+```
+
+---
+
+## Output Format
+
+```
+━━━ Tribunal Performance ━━━━━━━━━━━━━━━━━━
+
+logic-reviewer:       ✅ APPROVED
+performance-reviewer: ❌ REJECTED
+
+━━━ VERDICT: ❌ REJECTED ━━━━━━━━━━━━━━━━━
+
+Blockers:
+- performance-reviewer: [HIGH — INP] Synchronous filterMillion() called in onClick handler
+  Impact: Blocks main thread 200ms+ on each click — INP will be POOR
+  Fix: Wrap in startTransition(() => setResults(filterMillion(items, q)))
+
+- performance-reviewer: [HIGH — LCP] Hero image missing priority
+  Impact: Browser discovers image late — LCP will be POOR (> 4s)
+  Fix: <Image src="/hero.webp" priority={true} ... />
+
+Warnings:
+- performance-reviewer: [MEDIUM — Bundle] lodash imported directly (+67kb unminified)
+  Fix: Replace with native Array methods or specific lodash-es import
+```
+
+---
+
+## Performance-Specific Hallucination Traps
+
+```typescript
+// ❌ React.memo doesn't help when parent re-renders with new objects every time
+const MemoCard = React.memo(Card);
+<MemoCard style={{ margin: 8 }} /> // New object {} every render → memo has no effect
+
+// ✅ Memoize the object itself
+const cardStyle = useMemo(() => ({ margin: 8 }), []);
+<MemoCard style={cardStyle} />
+
+// ❌ useMemo with no deps array — runs every render (same as no memo)
+const sorted = useMemo(() => items.sort(...)); // Missing deps array!
+
+// ✅ Correct deps array
+const sorted = useMemo(() => [...items].sort(compareFn), [items]);
+
+// ❌ Non-measurement claim
+// "This is fast" — never write this without a Lighthouse score to back it
+```
+
+---
+
+## Measurement Protocol
+
+Performance optimization without measurement is guessing:
+
+```
+Before optimizing:
+□ Run Lighthouse: record LCP, INP, CLS, bundle size
+□ Profile with Chrome DevTools: identify actual bottleneck
+
+After optimizing:
+□ Run Lighthouse again: confirm improvement
+□ Show before/after scores in audit output
+```
+
+---
+
+## Usage Examples
+
+```
+/tribunal-performance the product listing page with image grid
+/tribunal-performance the search component with real-time filtering
+/tribunal-performance the checkout flow for CWV compliance
+/tribunal-performance the API route with expensive DB query for caching
+```

package/.agent/workflows/ui-ux-pro-max.md

@@ -1,171 +1,143 @@
----
-description: Plan and implement cutting-edge advanced UI/UX
----
-
-# /ui-ux-pro-max — Advanced Cutting-Edge UI/UX Design Mode
-
-$ARGUMENTS
-
----
-
-This command activates the absolute highest-fidelity UI/UX workflow, meant for 2026+ web and mobile standards. It combines deep neuro-inclusive design thinking, spatial UI concepts, advanced component architecture, and generative styling. This is not just "generate a pretty layout" — it is the creation of a responsive, living, and hyper-optimized interface.
-
-> This is a full state-of-the-art design session. We are pushing pixels, physics, and perceptual psychology.
-
----
-
-## When to Use This vs Other Commands
-
-| Use `/ui-ux-pro-max` when... | Use something else when... |
-|---|---|
-| You need pixel-perfect, award-worthy UI craft | Standard UI is acceptable → `/create` |
-| Design system, color system, typography all need definition | Just one component → `/generate` |
-| You want accessibility, motion, and spatial design all considered | Quick functional prototype → `/create` |
-| Neuro-inclusive + APCA contrast standards are required | Speed matters over design quality → `/create` |
-
----
-
-## What Makes This Different From `/create`
-
-`/create` builds standard features. `/ui-ux-pro-max` obsesses over extreme craft and futuristic patterns:
-
-- **Generative & Algorithmic Color**: Using OKLCH/LCH for perceptual uniformity, not just picking hex codes that "look nice."
-- **Fluid & Variable Typography**: Designing with `clamp()`, `ch` units, and Variable Fonts for infinite scaling, not fixed breakpoints.
-- **Adaptive Psychology & Neuro-Inclusivity**: Respecting `prefers-reduced-motion`, varying cognitive load based on context, and utilizing OLED battery-saving true black themes.
-- **Advanced Micro-Interactions**: Spring-physics based animations and scroll-driven interactions instead of static, linear CSS transitions.
-- **Spatial & Contextual UI**: Considering z-axis depth (glass, blurs, multi-layered shadows) and contextual adaptation (UI conforming to user behavior).
-
----
-
-## Extreme Design Rules (Always Active in This Mode)
-
-### Generative Color & Light
-- **No purple/violet as primary color** — the most overused "AI design" cliché is banned.
-- Color palettes must be derived using algorithmic relationships (e.g., OKLCH lightness/chroma stepping).
-- **True Black & OLED Optimization**: Use `#000000` or `#010101` for deep backgrounds on mobile/PWA to save battery, utilizing high-contrast borders for separation instead of gray backgrounds.
-- Contrast must pass **WCAG 3.0 APCA** (Advanced Perceptual Contrast Algorithm) standards for readability, not just older WCAG 2.1 math.
-
-### Fluid & Variable Typography
-- Use system variable fonts or explicitly loaded modern Variable Fonts to reduce network requests.
-- Body text uses **fluid typography** `clamp(1rem, 0.8rem + 1vw, 1.25rem)` to scale linearly between screen sizes.
-- strict adherence to max line lengths (`max-w-[65ch]`) to prevent cognitive fatigue.
-
-### Spatial & Layout Architecture
-- Standard hero layouts (left text / right image) are prohibited unless explicitly justified. Use asymmetric, dynamic, or scroll-locked interactive hero sections.
-- The Z-axis matters: build depth using multi-layer shadows or contextual background blurs (`backdrop-filter`) carefully applied for performance.
-- Use **Logical Properties** (`margin-inline`, `padding-block`) exclusively to enforce automatic RTL (Right-to-Left) and LTR compatibility.
-
-### Advanced Interaction & Physics
-- Linear easing (`ease`, `linear`) is banned for layout shifts. You must use **spring physics** or custom `cubic-bezier` curves for natural, organic motion.
-- **Scroll-Driven Animations**: UI elements should react to scroll position natively using modern CSS `@scroll-timeline` or performant JS Observers.
-- **Zero-Wait UI**: Streaming UI components (like React Server Components or Optimistic UI updates) must be designed so the user never sees a raw loading spinner for action responses.
-
----
-
-## The Pro-Max Design Protocol
-
-### Step 1 — Perceptual & Contextual Mapping
-
-Before painting a pixel, determine:
-
-```
-Who is the specific user persona?
-What is the cognitive load capacity here? (e.g., dashboard = high data density, landing page = low friction)
-What is the desired emotional & visceral impact?
-How will the UI adapt to user input?
-```
-
-### Step 2 — Spatial Layout Skeleton (No Colors yet)
-
-Define the structural architecture with depth in mind:
-- What is the structural grid? (Subgrid, Container Queries)
-- What exists on the Z-axis? (What floats, what is grounded?)
-- How does the layout mutate on scroll?
-
-### Step 3 — Generative Color + Fluid Typography System
-
-Define the algorithmic base:
-
-```css
-/* Example OKLCH System */
-Base hue:         [OKLCH Hue Value]
-Surface (Dark):   oklch(15% 0.02 [Hue])
-Surface (OLED):   oklch(0% 0 0)
-Text Primary:     oklch(96% 0.01 [Hue])
-Accent:           oklch(70% 0.25 [Complementary Hue])
-```
-
-### Step 4 — Component Build (Tribunal: logic + frontend)
-
-Every component built goes through `/tribunal-frontend` before being shown.
-Focus on **Container Queries** (`@container`) so components contextualize themselves based on where they map, not window width.
-
-### Step 5 — Physics & Interaction Layer
-
-Define organic movement:
-```css
-/* Spring-like organic transition */
-transition-timing-function: cubic-bezier(0.34, 1.56, 0.64, 1);
-```
-Ensure all interactions check for `@media (prefers-reduced-motion: reduce)`.
-
-### Step 6 — Extreme Accessibility Audit
-
-```
-✅ APCA Contrast verified.
-✅ Logical properties used for full i18n support.
-✅ Touch targets mathematically enforce Fitts' Law (>48px minimum).
-✅ Cognitive boundaries respected (No sudden layout shifts, CLS = 0).
-✅ Screen reader flows tested via semantic HTML5.
-```
-
----
-
-## 🏛️ Anti-Hallucination Rules for UI
-
-- **No invented CSS properties** — Do not guess syntax for scroll timelines or `@property` declarations; write `// VERIFY: check browser compatibility` if using bleach-edge CSS.
-- **No placeholder images** — generate real structural visualizations or use SVG abstractions.
-- **Do not invent React/Next.js features** that don't exist in the current stable or canary builds.
-
----
-
-## Output Format
-
-Each step produces a high-fidelity summary:
-
-```
-📐 Spatial Layout: [description of grid, container queries, and z-axis layers]
-
-🎨 Generative Color:
-   [OKLCH base mapped variables]
-   APCA Contrast Check: [Pass/Fail for Text/Bg combinations]
-
-🧱 Component Schema:
-   [Name] + [State transitions: Hover, Focus, Active, Skeleton]
-   Tribunal: [Verdict]
-
-♿ Neuro-Inclusive Audit:
-   [Compliance with cognitive safety, motion reduction, and touch targets]
-```
-
----
-
-## Cross-Workflow Navigation
-
-| After /ui-ux-pro-max produces output... | Do this |
-|---|---|
-| Component code is ready for merge | `/tribunal-frontend` for React/hooks audit |
-| Performance-critical animations written | `/tribunal-performance` to check for jank |
-| Color + contrast system defined | Document in the design system, then `/create` components |
-| Accessibility audit is required | Additional review with `accessibility-reviewer` via `/review [component]` |
-
----
-
-## Usage
-
-```
-/ui-ux-pro-max design a generative AI prompt dashboard
-/ui-ux-pro-max build an e-commerce checkout with extreme conversion optimization
-/ui-ux-pro-max create a spatial WebXR-inspired landing page
-/ui-ux-pro-max redesign a high-frequency trading interface for minimum cognitive load
-```
+---
+description: Plan and implement cutting-edge advanced UI/UX. Creates distinctive, production-grade frontend interfaces with high design quality that avoid generic AI aesthetics — no purple gradients, no bento grids, no mesh backgrounds.
+---
+
+# /ui-ux-pro-max — Advanced UI/UX Design
+
+$ARGUMENTS
+
+---
+
+## When to Use /ui-ux-pro-max
+
+| Use `/ui-ux-pro-max` when... | Use instead when... |
+|:---|:---|
+| Building a visually distinctive interface | Functional-only component → `/generate` |
+| Design quality is the primary goal | Fast page needed → `/enhance` |
+| Creating from a design brief | Bug fix in UI → `/debug` |
+| Mobile + web parity required | |
+
+---
+
+## Phase 1 — Design Intent (Mandatory)
+
+Answer these before any design work:
+
+```
+1. Who is the user? (developer tools feel different from consumer apps)
+2. What emotion should the interface evoke? (calm focus, urgent speed, playful delight)
+3. What is the ONE thing users do most? (hero interaction gets maximum design attention)
+4. What existing interfaces does the user love? (don't copy — understand the WHY)
+5. What makes this interface DIFFERENT from every competitor?
+```
+
+---
+
+## Phase 2 — Design Identity
+
+Every interface built by /ui-ux-pro-max has a distinct visual identity:
+
+```
+Forbidden defaults (generic AI aesthetics):
+❌ Purple/violet as primary color
+❌ Left text / right image hero section
+❌ Mesh gradient backgrounds
+❌ Bento grid as the only layout
+❌ Emoji as icons
+❌ shadcn without explicit user request
+
+Distinctive alternatives:
+✅ Signal orange, acid green, warm slate, deep red — intentional palettes
+✅ Typographic-first hero sections
+✅ Grain textures, solid contrast, radial depth
+✅ Asymmetric or broken-grid layouts
+✅ SVG icons (lucide-react or custom)
+✅ Motion that communicates meaning (not decoration)
+```
+
+---
+
+## Phase 3 — Interaction Craft
+
+Every interactive element has 4 states designed:
+
+```
+1. Default:  The base state
+2. Hover:    Indicates interactability (cursor change, subtle lift, color shift)
+3. Active:   Confirms click/press (scale down, darker, haptic feedback on mobile)
+4. Disabled: Communicates unavailability (reduced opacity, cursor change, tooltip why)
+```
+
+Micro-animations are required, not optional:
+
+```
+Entry animations:  elements fade/slide in on mount
+State transitions: smooth color + scale changes (150–200ms)
+Loading states:    skeleton screens, not spinners (skeleton shows shape)
+Error shake:       invalid form input shakes (4px left-right)
+Success pulse:     confirmed actions pulse green briefly
+```
+
+---
+
+## Phase 4 — Implementation (Tribunal-Reviewed)
+
+All generated code runs through `/tribunal-frontend` including `accessibility-reviewer`:
+
+```
+WCAG 2.2 AA — Non-negotiable:
+□ Keyboard navigation complete and visible
+□ Screen reader semantics verified (role, label, live region)
+□ Color contrast 4.5:1 minimum on all text
+□ Focus indicator visible (outline: 2px solid, offset: 2px)
+□ Motion respects prefers-reduced-motion
+```
+
+---
+
+## Phase 5 — Design Verification
+
+Before finalizing:
+
+```
+□ Open in mobile viewport (375px) — does it work?
+□ Open in dark mode — does it look intentional?
+□ Keyboard-navigate through the critical path — is it complete?
+□ Screenshot and ask: "Would I scroll past this on Dribbble?"
+□ Screen reader test with VoiceOver or NVDA
+```
+
+---
+
+## Output Format
+
+```
+━━━ UI/UX Design ━━━━━━━━━━━━━━━━━━━━━━━━
+
+Design Identity: [1 sentence describing the visual intent]
+Primary action:  [what the user does most prominently]
+Color palette:   [specific hex values — not color names]
+Motion profile:  [subtle / moderate / expressive]
+
+━━━ Tribunal: Frontend + Accessibility ━━━━━━
+
+frontend-reviewer:    ✅ APPROVED
+accessibility-reviewer: [verdict]
+
+[Generated components]
+
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━
+Approve?  Y = write | N = discard | R = revise design direction
+```
+
+---
+
+## Usage Examples
+
+```
+/ui-ux-pro-max design a SaaS dashboard for an analytics platform
+/ui-ux-pro-max redesign the checkout flow with better conversion UX
+/ui-ux-pro-max create an onboarding flow for a developer tool
+/ui-ux-pro-max design the landing page hero section with distinctive layout
+/ui-ux-pro-max create a data visualization dashboard with real-time updates
+```