tribunal-kit 3.0.0 → 4.0.0

package/.agent/skills/edge-computing/SKILL.md

@@ -1,157 +1,131 @@
----
-name: edge-computing
-description: Edge computing mastery. Cloudflare Workers, Vercel Edge Functions, Durable Objects, edge-compatible data patterns, cold start elimination, caching policies (Stale-While-Revalidate), and global data locality. Use when designing globally distributed, extreme low-latency applications architectures.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 2.0.0
-last-updated: 2026-04-02
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
----
-
-# Edge Computing — Global Latency Mastery
-
-> The Edge is not just a faster server. It fundamentally changes the computing model.
-> You cannot put compute on the Edge and leave the database in Virginia. V8 isolates enforce new rules.
-
----
-
-## 1. The Edge Model (V8 Isolates vs Node.js)
-
-Edge functions (Cloudflare Workers, Vercel Edge) run on V8 Isolates, NOT standard Node.js environments.
-
-**What This Means:**
-1. Extremely fast cold starts (< 5ms) because there is no underlying OS process bootup.
-2. Hard memory/time limits per request (e.g., 50ms CPU time max).
-3. **NO NATIVE NODE MODULES.** You cannot use `fs`, `child_process`, or heavy native C++ binaries (e.g., standard `bcrypt`, `sharp`).
-
-```typescript
-// ❌ BAD: Attempting to use Node native core modules
-import fs from "fs"; 
-import bcrypt from "bcrypt"; // Has C++ bindings, will instantly crash on V8 edge
-
-// ✅ GOOD: Utilizing standard Web APIs (Fetch, CryptoKey)
-const hashBuffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(password));
-```
-
----
-
-## 2. Advanced Route Caching (Stale-While-Revalidate)
-
-The highest value proposition of the edge is intercepting requests *before* they cross the ocean.
-
-```typescript
-// Standard Edge Proxy request handling
-export default {
-  async fetch(request, env, ctx) {
-    const url = new URL(request.url);
-
-    // 1. Cache API responses at the edge
-    const cache = caches.default;
-    let response = await cache.match(request);
-
-    if (!response) {
-      // 2. Fetch Origin (The real server in Virginia)
-      response = await fetch(request);
-
-      // 3. Mutate Headers for SWR (Stale-While-Revalidate)
-      // Instructs the Edge CDN: Serve the stale version instantly to the user,
-      // but fire an async request in the background to update the cache for the next user.
-      response = new Response(response.body, response);
-      response.headers.set('Cache-Control', 's-maxage=60, stale-while-revalidate=86400');
-
-      // 4. Store in Cache asynchronously (do not block the user response)
-      ctx.waitUntil(cache.put(request, response.clone()));
-    }
-
-    return response;
-  }
-};
-```
-
----
-
-## 3. Edge Data Locality (The Database Problem)
-
-Running logic globally while querying a monolithic database in `us-east-1` is counter-productive. The latency of establishing a connection across the Atlantic will negate any Edge benefits.
-
-### Solutions:
-1. **Edge KV Stores**: (Cloudflare KV, Vercel KV) Eventually consistent, highly localized read-latency configs suitable for configuration routing, user sessions, or feature flags.
-2. **Distributed SQLite**: (Cloudflare D1, Turso) Replicas distributed to edge nodes automatically.
-3. **Connection Pooling**: Use an HTTP/Connection Pool proxy strictly (e.g., Prisma Accelerate, Supabase Edge Pooler). You cannot establish TCP `pg://` connections directly from millions of spinning V8 isolates, you will OOM crash the database.
-
-```typescript
-// ✅ Turso / LibSQL (Distributed Edge DB) usage:
-import { createClient } from "@libsql/client/web";
-
-const client = createClient({
-  url: env.TURSO_DATABASE_URL,
-  authToken: env.TURSO_AUTH_TOKEN,
-});
-
-const result = await client.execute("SELECT * FROM users WHERE id = ?", [userId]);
-```
-
----
-
-## 4. WebSockets at the Edge (Durable Objects)
-
-Standard Edge functions are stateless. To hold persistent state (like a live multiplayer gaming room, or a chat room's WebSocket connections across multiple users), you must funnel those connections into a single point of state: a Durable Object.
-
-```typescript
-// A Durable Object serves as a single source of truth that users globally connect into
-export class ChatRoom {
-  constructor(state, env) {
-    this.state = state;
-    this.sessions = [];
-  }
-
-  async fetch(request) {
-    // Upgrade standard HTTP to WebSocket
-    const pair = new WebSocketPair();
-    
-    // Accept connection, store it globally
-    this.sessions.push(pair.server);
-    pair.server.accept();
-    
-    // Handle incoming Chat messages
-    pair.server.addEventListener("message", msg => {
-      // Broadcast to all other connected edge users
-      this.sessions.forEach(session => session.send(msg.data));
-    });
-
-    return new Response(null, { status: 101, webSocket: pair.client });
-  }
-}
-```
-
----
-
-## 🤖 LLM-Specific Traps (Edge Computing)
-
-1. **Node Core Assumption:** The AI imports `fs`, `path`, or `child_process` directly into Cloudflare Workers / Next.js Edge Middleware. V8 isolates lack file system access. Use native Web APIs (`ReadableStream`, `Blob`).
-2. **Heavy Dependency Usage:** The AI imports massive NPM libraries (like `lodash` or `moment`) which crush the 1MB Edge script-size limits. Code for the Edge must be micro-optimized.
-3. **TCP Database Connections:** Generating `const client = new Client({ connectionString: "postgres://..." })` inside an Edge runtime. The edge requires HTTP/WebSocket driven database architectures, or a managed connection pooler to prevent TCP exhaustion.
-4. **State Fallacy:** Designing a global variable `let activeUsers = 0` inside an edge script and assuming it will sync. V8 Isolates boot and die globally in milliseconds. They share no memory.
-5. **Ignoring `ctx.waitUntil`:** Mutating databases or logging metrics synchronously before returning the web response, slowing down the user. All side-effects on the Edge must be deferred via `ctx.waitUntil(promise)`.
-6. **Non-Web Crypto:** Trying to use Node's `crypto` module. Standardize on the universally browser-compatible `crypto.subtle` Web Crypto API.
-7. **Environment Variable Bleed:** Using `process.env.SECRET` instead of passing the standard `env` injection parameter into the V8 fetch handler.
-8. **Missing CORS Origins:** Forgetting to dynamically append heavy CORS allow headers on the outgoing Edge proxy response manipulation.
-9. **Synchronous Loops:** Designing a large `forEach` data map inside the worker request block, tripping the strict 50ms CPU execution limits resulting in generic 1102 Worker Errors.
-10. **WebSocket Orphanages:** Opening a WebSocket inside a standard Edge function without bridging it into a Durable Object, causing the WS connection to terminate immediately when the isolate tears down.
-
----
-
-## 🏛️ Tribunal Integration
-
-### ✅ Pre-Flight Self-Audit
-```
-✅ Have I completely avoided using native Node.js core modules (`fs`, `path`, `crypto`)?
-✅ Am I leveraging standard Web APIs (Fetch, Streams, Web Crypto)?
-✅ Have database interactions utilized HTTP clients (or connection poolers) instead of direct TCP?
-✅ Has `ctx.waitUntil()` been used for all background analytics/caching updates?
-✅ Are environment variables injected via `env.VAR` rather than `process.env`?
-✅ Is localized global state (chat rooms, live editing) explicitly deferred to Durable Objects?
-✅ Did I define strict `s-maxage` and `stale-while-revalidate` directives for caching performance?
-✅ Are third-party library imports audited for their V8 isolate compatibility footprint?
-✅ Is JSON parsing happening inside `try/catch` to avoid 500ing early isolates?
-✅ Did I avoid deploying massive >1MB bundle payloads to the Edge routing layer?
-```
+---
+name: edge-computing
+description: Edge computing mastery. Cloudflare Workers, Vercel Edge Functions, Durable Objects, edge-compatible data patterns, cold start elimination, caching policies (Stale-While-Revalidate), and global data locality. Use when designing globally distributed, extreme low-latency applications architectures.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-02
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+## Hallucination Traps (Read First)
+- ❌ Importing Node.js-only APIs (fs, net, child_process) in edge functions -> ✅ Edge runtime has NO Node.js APIs; use Web APIs only
+- ❌ Using `global` or module-level mutable state in edge -> ✅ Edge functions are stateless across requests; use KV/Durable Objects for state
+- ❌ Assuming edge functions have unlimited execution time -> ✅ Cloudflare Workers: 30s, Vercel Edge: 25s; design for millisecond responses
+
+---
+
+
+# Edge Computing — Global Latency Mastery
+
+---
+
+## 1. The Edge Model (V8 Isolates vs Node.js)
+
+Edge functions (Cloudflare Workers, Vercel Edge) run on V8 Isolates, NOT standard Node.js environments.
+
+**What This Means:**
+1. Extremely fast cold starts (< 5ms) because there is no underlying OS process bootup.
+2. Hard memory/time limits per request (e.g., 50ms CPU time max).
+3. **NO NATIVE NODE MODULES.** You cannot use `fs`, `child_process`, or heavy native C++ binaries (e.g., standard `bcrypt`, `sharp`).
+
+```typescript
+// ❌ BAD: Attempting to use Node native core modules
+import fs from "fs"; 
+import bcrypt from "bcrypt"; // Has C++ bindings, will instantly crash on V8 edge
+
+// ✅ GOOD: Utilizing standard Web APIs (Fetch, CryptoKey)
+const hashBuffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(password));
+```
+
+---
+
+## 2. Advanced Route Caching (Stale-While-Revalidate)
+
+The highest value proposition of the edge is intercepting requests *before* they cross the ocean.
+
+```typescript
+// Standard Edge Proxy request handling
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+
+    // 1. Cache API responses at the edge
+    const cache = caches.default;
+    let response = await cache.match(request);
+
+    if (!response) {
+      // 2. Fetch Origin (The real server in Virginia)
+      response = await fetch(request);
+
+      // 3. Mutate Headers for SWR (Stale-While-Revalidate)
+      // Instructs the Edge CDN: Serve the stale version instantly to the user,
+      // but fire an async request in the background to update the cache for the next user.
+      response = new Response(response.body, response);
+      response.headers.set('Cache-Control', 's-maxage=60, stale-while-revalidate=86400');
+
+      // 4. Store in Cache asynchronously (do not block the user response)
+      ctx.waitUntil(cache.put(request, response.clone()));
+    }
+
+    return response;
+  }
+};
+```
+
+---
+
+## 3. Edge Data Locality (The Database Problem)
+
+Running logic globally while querying a monolithic database in `us-east-1` is counter-productive. The latency of establishing a connection across the Atlantic will negate any Edge benefits.
+
+### Solutions:
+1. **Edge KV Stores**: (Cloudflare KV, Vercel KV) Eventually consistent, highly localized read-latency configs suitable for configuration routing, user sessions, or feature flags.
+2. **Distributed SQLite**: (Cloudflare D1, Turso) Replicas distributed to edge nodes automatically.
+3. **Connection Pooling**: Use an HTTP/Connection Pool proxy strictly (e.g., Prisma Accelerate, Supabase Edge Pooler). You cannot establish TCP `pg://` connections directly from millions of spinning V8 isolates, you will OOM crash the database.
+
+```typescript
+// ✅ Turso / LibSQL (Distributed Edge DB) usage:
+import { createClient } from "@libsql/client/web";
+
+const client = createClient({
+  url: env.TURSO_DATABASE_URL,
+  authToken: env.TURSO_AUTH_TOKEN,
+});
+
+const result = await client.execute("SELECT * FROM users WHERE id = ?", [userId]);
+```
+
+---
+
+## 4. WebSockets at the Edge (Durable Objects)
+
+Standard Edge functions are stateless. To hold persistent state (like a live multiplayer gaming room, or a chat room's WebSocket connections across multiple users), you must funnel those connections into a single point of state: a Durable Object.
+
+```typescript
+// A Durable Object serves as a single source of truth that users globally connect into
+export class ChatRoom {
+  constructor(state, env) {
+    this.state = state;
+    this.sessions = [];
+  }
+
+  async fetch(request) {
+    // Upgrade standard HTTP to WebSocket
+    const pair = new WebSocketPair();
+    
+    // Accept connection, store it globally
+    this.sessions.push(pair.server);
+    pair.server.accept();
+    
+    // Handle incoming Chat messages
+    pair.server.addEventListener("message", msg => {
+      // Broadcast to all other connected edge users
+      this.sessions.forEach(session => session.send(msg.data));
+    });
+
+    return new Response(null, { status: 101, webSocket: pair.client });
+  }
+}
+```
+
+---

package/.agent/skills/extract-design-system/SKILL.md

@@ -1,134 +1,108 @@
----
-name: extract-design-system
-description: Design system extraction and tokenization mastery. Identifying repeated HTML/CSS patterns, extracting CSS variables, generating design tokens (colors, spacing, typography), building reusable component schemas, and standardizing ad-hoc styles into cohesive global systems. Use when refactoring messy CSS into a unified design system.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 2.0.0
-last-updated: 2026-04-02
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
----
-
-# Extract Design System — Tokenization Mastery
-
-> Magic numbers in CSS (`padding: 13px`) are technical debt.
-> A Design System is not a component library. It is a mathematical relationship between visual tokens.
-
----
-
-## 1. The Token Extraction Protocol
-
-When reviewing a messy, legacy UI file (`<div style="background: #e23e2a; border-radius: 6px; padding: 12px">`), the agent must extract these hardcoded values into Global Tokens.
-
-### Tier 1: Core Design Tokens (The Foundation)
-Tokens should be semantic, not literal. `color-brand` > `color-red`.
-
-```css
-:root {
-  /* Colors (HSL is preferred for programmatic manipulation) */
-  --brand-primary: 360, 76%, 53%; /* The specific red */
-  --surface-default: 0, 0%, 100%;
-  --surface-muted: 210, 40%, 96%;
-
-  /* Typography */
-  --font-sans: 'Inter', system-ui, sans-serif;
-  
-  /* Space / Geometry (8px grid scale) */
-  --space-1: 0.25rem;  /* 4px */
-  --space-2: 0.5rem;   /* 8px */
-  --space-3: 0.75rem;  /* 12px */
-  --space-4: 1rem;     /* 16px */
-  
-  /* Radaii */
-  --radius-sm: 4px;
-  --radius-md: 6px;    /* Extracted from the 6px legacy element */
-}
-```
-
-### Tier 2: The Refactor 
-(Using Tailwind v4 CSS-First as the standard delivery mechanism)
-
-```css
-@theme {
-    --color-primary: hsl(var(--brand-primary));
-    --spacing-3: var(--space-3);
-    --radius-md: var(--radius-md);
-}
-```
-
----
-
-## 2. Standardizing the 3 "C" Configurations 
-
-If building a design system inside React/Next.js, standardize the system through 3 primary mechanisms.
-
-1. **Colors (Dark Mode First):** Every single color extracted must have an inverse defined for `[data-theme='dark']`.
-2. **Container Queries:** Media queries (`@media (min-width)`) define the *device*. Container queries (`@container (min-width)`) define the *component context*. Always extract component sizing to rely on container-driven layouts for ultimate reusability.
-3. **Compound Variants (CVA):** Group extracted CSS classes into logical component states rather than passing 10 boolean props.
-
-```typescript
-// ✅ Efficient Extracted Component Architecture
-import { cva } from "class-variance-authority";
-
-const buttonStyles = cva(
-  "inline-flex items-center justify-center rounded-md font-medium transition-colors", // Base
-  {
-    variants: {
-      intent: {
-        primary: "bg-primary text-white hover:bg-primary/90",
-        destructive: "bg-red-500 text-white hover:bg-red-600",
-        outline: "border border-input hover:bg-accent",
-      },
-      size: {
-        sm: "h-9 px-3 text-sm",
-        default: "h-10 px-4 py-2",     // Extracted standard size
-        lg: "h-11 px-8",
-      },
-    },
-    defaultVariants: {
-      intent: "primary",
-      size: "default",
-    },
-  }
-);
-```
-
----
-
-## 3. Auditing the Accessibility Baseline
-
-A Design System must mandate accessibility at the token level, preventing developers from manually breaking contrast ratios later.
-
-1. Extracted primary text colors must hit a **4.5:1 contrast ratio** against the extracted background surfaces.
-2. Focus rings must be decoupled and standardized globally (`ring-2 ring-primary ring-offset-2`).
-
----
-
-## 🤖 LLM-Specific Traps (Design System Extraction)
-
-1. **Literal Naming:** Naming variables `--color-light-red` instead of `--color-danger` or `--color-primary`. Literal names break instantly when the dark mode theme flips the palette.
-2. **Ignoring the Spacing Geometry:** Leaving `margin-top: 17px` and `padding-left: 11px` unaddressed instead of mathematically rounding them into a strict 4px/8px geometric scale (`mt-4`, `pl-3`).
-3. **Re-inventing Tailwind:** Extracting 400 CSS utility classes manually into a custom CSS file instead of properly mapping the design tokens into the existing Tailwind `@theme` engine.
-4. **Prop Drilling Hell:** Converting a button to a component, but exposing 15 individual CSS class props (`textColor`, `paddingSize`, `borderR`) instead of grouping them logically into a `Variant` CVA scale.
-5. **Dark Mode Blindness:** Extracting a beautiful Light Mode system and failing to invert the HSL lightness scale for the dark mode `:root` selector, resulting in invisible text.
-6. **Rgb Hex Hardcoding:** Extracting hex codes (`#FFFFFF`) directly instead of defining them as `H S L` variable channels, destroying the ability to inject dynamic `opacity` (e.g., `bg-primary/50`).
-7. **One-Off Snowflake Classes:** Creating a unique component explicitly for one page (e.g., `<CheckoutSubmitButton>`) instead of designing a generic `<Button intent="checkout">`.
-8. **Font Sizing vs Line Height:** Extracting `font-size` tokens, but ignoring the paired `line-height` standardizations, causing typography block rendering to collapse vertically.
-9. **Hover-State Void:** Extracting the static appearance of elements perfectly but entirely ignoring the `hover:`, `focus:`, and `active:` micro-interaction states that defined the original UX.
-10. **The Component Dump:** Scanning a 2,000 line page and trying to extract 15 components simultaneously inside a single LLM response. The extraction must be phased iteratively Component by Component.
-
----
-
-## 🏛️ Tribunal Integration
-
-### ✅ Pre-Flight Self-Audit
-```
-✅ Are magic numbers strictly eradicated and mapped to a geometric mathematical scale (e.g., 4px grids)?
-✅ Are color tokens named semantically (`--primary`, `--danger`) rather than literally (`--blue`)?
-✅ Have hex codes been transformed to HSL structures to support dynamic opacity modification?
-✅ Is the `[data-theme='dark']` inversion matrix properly established alongside the root tokens?
-✅ Has `class-variance-authority` (cva) been used to cleanly manage component intent states?
-✅ Did I mathematically normalize inconsistent padding (e.g., fixing 11px and 13px both into 12px)?
-✅ Are global focus rings standardized to ensure accessibility consistency across interactive points?
-✅ Did I define the paired line-height geometries alongside the core typography font sizing tokens?
-✅ Have hover and transition states been deeply captured and centralized?
-✅ Did I phase the extraction process component-by-component to avoid hallucinating massive context blocks?
-```
+---
+name: extract-design-system
+description: Design system extraction and tokenization mastery. Identifying repeated HTML/CSS patterns, extracting CSS variables, generating design tokens (colors, spacing, typography), building reusable component schemas, and standardizing ad-hoc styles into cohesive global systems. Use when refactoring messy CSS into a unified design system.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-02
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+---
+
+## Hallucination Traps (Read First)
+- ❌ Creating CSS variables for every possible value -> ✅ Only tokenize values that appear 3+ times across components
+- ❌ Extracting a design system before the UI is stable -> ✅ Wait until patterns are proven by real usage before standardizing
+- ❌ Naming tokens by appearance (`--blue-500`) instead of purpose (`--color-primary`) -> ✅ Semantic names survive theme changes
+
+---
+
+
+# Extract Design System — Tokenization Mastery
+
+---
+
+## 1. The Token Extraction Protocol
+
+When reviewing a messy, legacy UI file (`<div style="background: #e23e2a; border-radius: 6px; padding: 12px">`), the agent must extract these hardcoded values into Global Tokens.
+
+### Tier 1: Core Design Tokens (The Foundation)
+Tokens should be semantic, not literal. `color-brand` > `color-red`.
+
+```css
+:root {
+  /* Colors (HSL is preferred for programmatic manipulation) */
+  --brand-primary: 360, 76%, 53%; /* The specific red */
+  --surface-default: 0, 0%, 100%;
+  --surface-muted: 210, 40%, 96%;
+
+  /* Typography */
+  --font-sans: 'Inter', system-ui, sans-serif;
+  
+  /* Space / Geometry (8px grid scale) */
+  --space-1: 0.25rem;  /* 4px */
+  --space-2: 0.5rem;   /* 8px */
+  --space-3: 0.75rem;  /* 12px */
+  --space-4: 1rem;     /* 16px */
+  
+  /* Radaii */
+  --radius-sm: 4px;
+  --radius-md: 6px;    /* Extracted from the 6px legacy element */
+}
+```
+
+### Tier 2: The Refactor 
+(Using Tailwind v4 CSS-First as the standard delivery mechanism)
+
+```css
+@theme {
+    --color-primary: hsl(var(--brand-primary));
+    --spacing-3: var(--space-3);
+    --radius-md: var(--radius-md);
+}
+```
+
+---
+
+## 2. Standardizing the 3 "C" Configurations 
+
+If building a design system inside React/Next.js, standardize the system through 3 primary mechanisms.
+
+1. **Colors (Dark Mode First):** Every single color extracted must have an inverse defined for `[data-theme='dark']`.
+2. **Container Queries:** Media queries (`@media (min-width)`) define the *device*. Container queries (`@container (min-width)`) define the *component context*. Always extract component sizing to rely on container-driven layouts for ultimate reusability.
+3. **Compound Variants (CVA):** Group extracted CSS classes into logical component states rather than passing 10 boolean props.
+
+```typescript
+// ✅ Efficient Extracted Component Architecture
+import { cva } from "class-variance-authority";
+
+const buttonStyles = cva(
+  "inline-flex items-center justify-center rounded-md font-medium transition-colors", // Base
+  {
+    variants: {
+      intent: {
+        primary: "bg-primary text-white hover:bg-primary/90",
+        destructive: "bg-red-500 text-white hover:bg-red-600",
+        outline: "border border-input hover:bg-accent",
+      },
+      size: {
+        sm: "h-9 px-3 text-sm",
+        default: "h-10 px-4 py-2",     // Extracted standard size
+        lg: "h-11 px-8",
+      },
+    },
+    defaultVariants: {
+      intent: "primary",
+      size: "default",
+    },
+  }
+);
+```
+
+---
+
+## 3. Auditing the Accessibility Baseline
+
+A Design System must mandate accessibility at the token level, preventing developers from manually breaking contrast ratios later.
+
+1. Extracted primary text colors must hit a **4.5:1 contrast ratio** against the extracted background surfaces.
+2. Focus rings must be decoupled and standardized globally (`ring-2 ring-primary ring-offset-2`).
+
+---