tribunal-kit 1.0.0 → 2.4.2

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

@@ -0,0 +1,123 @@
+---
+description: Mobile-specific Tribunal. Runs Logic + Security + Mobile reviewers. Use for React Native, Flutter, and responsive web code.
+---
+
+# /tribunal-mobile — Mobile Code Tribunal
+
+$ARGUMENTS
+
+---
+
+This command activates the **Mobile Tribunal** — a focused panel of reviewers covering the specific failure modes of mobile and responsive application code.
+
+Use this instead of `/tribunal-full` when your code is specifically mobile-domain. It gives faster, more precise feedback than running all 11 reviewers.
+
+---
+
+## When to Use This vs Other Tribunals
+
+| Code type | Right tribunal |
+|---|---|
+| React Native, Flutter, mobile UI | `/tribunal-mobile` ← you are here |
+| Pure React (web) components | `/tribunal-frontend` |
+| API routes, auth, middleware | `/tribunal-backend` |
+| Cross-domain or pre-merge audit | `/tribunal-full` |
+
+---
+
+## Active Reviewers
+
+| Reviewer | What It Catches |
+|---|---|
+| `logic-reviewer` | Hallucinated RN/Flutter APIs, impossible logic, undefined refs |
+| `security-auditor` | Hardcoded secrets, insecure storage, OWASP Mobile Top 10 |
+| `mobile-reviewer` | Touch targets, safe areas, keyboard avoidance, gesture handling, image optimization |
+
+---
+
+## What Gets Flagged — Real Examples
+
+| Reviewer | Example Finding | Severity |
+|---|---|---|
+| logic | Calling a non-existent `Animated.stagger()` method | ❌ HIGH |
+| security | `AsyncStorage.setItem('token', jwt)` — use `expo-secure-store` instead | ⚠️ MEDIUM |
+| security | Deeplink handler with no validation of `url` param | ❌ HIGH |
+| security | Missing certificate pinning on sensitive API endpoints | ⚠️ MEDIUM |
+| mobile | Button `height: 20` — minimum touch target is 44pt (iOS) / 48dp (Android) | ❌ HIGH |
+| mobile | Missing `<SafeAreaView>` on root screen component | ❌ HIGH |
+| mobile | No `KeyboardAvoidingView` on screen with text inputs | ❌ HIGH |
+| mobile | `<Image source={uri}>` with no width/height bounds — memory risk | ⚠️ MEDIUM |
+| mobile | No `Platform.OS` guard on platform-specific code | ⚠️ MEDIUM |
+
+---
+
+## Mobile-Specific Anti-Hallucination Rules
+
+```
+❌ Never reference RN APIs not listed in the installed react-native version
+❌ Never assume iOS and Android behave identically — always check Platform.OS when needed
+❌ Never use AsyncStorage for sensitive data (tokens, passwords, biometrics)
+❌ Never skip keyboard avoidance on screens with text inputs
+❌ Never use hardcoded pixel values — use pt (iOS) or dp (Android) logical units
+❌ Never claim an animation approach is "performant" without mentioning native driver usage
+```
+
+---
+
+## Output Format
+
+```
+━━━ Tribunal: Mobile ━━━━━━━━━━━━━━━━━━━━━
+
+Active reviewers: logic · security · mobile
+
+[Your code under review]
+
+━━━ Verdicts ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+logic-reviewer:    ✅ APPROVED
+security-auditor:  ⚠️  WARNING
+mobile-reviewer:   ❌ REJECTED
+
+━━━ Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+security-auditor:
+  ⚠️ MEDIUM — Line 8
+     AsyncStorage used for auth token storage
+     Fix: Use expo-secure-store or react-native-keychain for sensitive data
+
+mobile-reviewer:
+  ❌ HIGH — Line 12
+     Touch target: Button height is 20pt. Minimum is 44pt (iOS) / 48dp (Android)
+     Fix: style={{ minHeight: 44 }}
+
+  ❌ HIGH — Line 34
+     Missing SafeAreaView wrapping the root view
+     Fix: Wrap with <SafeAreaView style={{ flex: 1 }}>
+
+━━━ Verdict: REJECTED ━━━━━━━━━━━━━━━━━━━━
+
+Address rejections?  Y = fix and re-review | N = accept risk | R = revise manually
+```
+
+---
+
+## Cross-Workflow Navigation
+
+| Finding type | Next step |
+|---|---|
+| Insecure storage CRITICAL | Replace storage library via `/enhance` |
+| All touch target issues | `/enhance` to normalize touch targets in shared components |
+| Cross-platform behavior gap | `/refactor` to extract Platform.OS guards into a utility |
+| All approved | Human Gate to write to disk |
+
+---
+
+## Usage
+
+```
+/tribunal-mobile my React Native login screen component
+/tribunal-mobile the Flutter payment form widget
+/tribunal-mobile the responsive mobile nav component with touch gestures
+/tribunal-mobile the biometric authentication flow
+```

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

@@ -0,0 +1,152 @@
+---
+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
+```

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

@@ -1,153 +1,171 @@
 ---
-description: Plan and implement UI
+description: Plan and implement cutting-edge advanced UI/UX
 ---
 
-# /ui-ux-pro-max — Advanced UI/UX Design Mode
+# /ui-ux-pro-max — Advanced Cutting-Edge UI/UX Design Mode
 
 $ARGUMENTS
 
 ---
 
-This command activates the highest-fidelity UI/UX workflow. It combines deep design thinking, component architecture, and real-time feedback — not just "generate a pretty layout."
+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 not a shortcut. It's a full design session.
+> 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 features. `/ui-ux-pro-max` obsesses over the craft:
+`/create` builds standard features. `/ui-ux-pro-max` obsesses over extreme craft and futuristic patterns:
 
-- Color decisions backed by contrast ratios and optical principles — not "looks nice"
-- Typography choices based on reading distance, weight hierarchy, and scale
-- Layout that solves the actual user flow, not the common template
-- Interaction states for every element (hover, focus, active, loading, error, empty)
-- Accessibility by default — not retrofitted
+- **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).
 
 ---
 
-## Design Rules (Always Active in This Mode)
+## Extreme Design Rules (Always Active in This Mode)
 
-### Color
-- No purple/violet as primary color — most overused AI design choice
-- All text must pass WCAG AA contrast (4.5:1 minimum)
-- Color palette derived from a single base hue with rotational logic — not random picks
-- No pure black backgrounds (`#000`) — use `#090909` to `#121212` for perceived depth
+### 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.
 
-### Typography
-- Google Fonts only if you have the `<link>` to prove it exists — no invented font names
-- Minimum 16px body text on mobile
-- Line height between 1.4–1.6 for body, 1.1–1.2 for headings
-- No more than 3 font weights in one component
+### 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.
 
-### Layout
-- No standard hero (left text / right illustration) without a compelling reason
-- Section max-width: 1200px for content, 720px for text-heavy content
-- 8px spacing grid — all padding and margin values are multiples of 8
+### 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.
 
-### Interaction
-- Every interactive element has: default, hover, focus, active, and disabled states
-- Focus rings must be visible — never `outline: none` without a styled alternative
-- Loading states for anything async — no silent spinners
-- Error states with actionable copy — not just "Error occurred"
+### 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 Design Session Protocol
+## The Pro-Max Design Protocol
 
-### Step 1 — Problem Before Pixels
+### Step 1 — Perceptual & Contextual Mapping
 
-Answer these before designing anything:
+Before painting a pixel, determine:
 
 ```
-Who is the user?              (not "general users" — a specific persona)
-What is the one thing this UI must make easy?
-What is the emotional tone?   (serious, playful, professional, urgent)
-What does the user do after this screen?
+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 — Layout Skeleton (No Colors yet)
+### Step 2 — Spatial Layout Skeleton (No Colors yet)
 
-Define the structure:
-- What regions exist? (nav, hero, content, sidebar, footer)
-- What is the visual hierarchy? (#1 most important thing → #2 → #3)
-- What flows from top to bottom when the user scrolls?
+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 — Color + Typography System
+### Step 3 — Generative Color + Fluid Typography System
 
-Pick once, use consistently:
+Define the algorithmic base:
 
-```
-Base hue:         [HSL value]
-Primary:          [hue, full saturation]
-Background:       [hue, 2–5% saturation, 6–12% lightness for dark]
-Surface:          [background + 4–6% lightness]
-Text primary:     [96–98% lightness on dark]
-Text secondary:   [65–70% lightness on dark]
-Accent:           [complementary hue, high saturation]
+```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 — Interaction Layer
+### Step 5 — Physics & Interaction Layer
 
-Define CSS transitions for every state change:
+Define organic movement:
 ```css
-transition: all 0.15s ease;   /* for micro-interactions */
-transition: all 0.25s ease;   /* for layout transitions */
+/* 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 — Accessibility Audit
+### Step 6 — Extreme Accessibility Audit
 
 ```
-✅ All images have alt attributes
-✅ Focus order follows visual order
-✅ Color is not the only indicator of state (add icon or text)
-✅ Touch targets minimum 44px × 44px on mobile
-✅ ARIA roles on custom interactive elements
+✅ 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 Google Fonts** — verify every font name at fonts.google.com before using it
-- **No invented CSS properties** — `backdrop-filter` needs vendor prefix in some browsers; write `// VERIFY: check browser support`
-- **Contrast ratios must be real** — don't claim AA compliance without checking the actual ratio
-- **No placeholder images** — generate real images or use a placeholder service with documented URL format
+- **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:
+Each step produces a high-fidelity summary:
 
 ```
-📐 Layout skeleton: [description or ASCII diagram]
+📐 Spatial Layout: [description of grid, container queries, and z-axis layers]
 
-🎨 Color system:
-   Background:   #[hex]
-   Surface:      #[hex]
-   Primary text: #[hex]
-   Accent:       #[hex]
-   Contrast:     [ratio]:1 → AA [pass|fail]
+🎨 Generative Color:
+   [OKLCH base mapped variables]
+   APCA Contrast Check: [Pass/Fail for Text/Bg combinations]
 
-🧱 Component: [name]
-   Tribunal: [verdict]
+🧱 Component Schema:
+   [Name] + [State transitions: Hover, Focus, Active, Skeleton]
+   Tribunal: [Verdict]
 
-♿ Accessibility:
-   [checklist result]
+♿ 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 SaaS dashboard homepage
-/ui-ux-pro-max build a pricing page that converts
-/ui-ux-pro-max create a mobile-first landing page for a productivity app
-/ui-ux-pro-max redesign the login and registration flow
+/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
 ```