tribunal-kit 9.0.0 → 9.0.2

package/skills/nextjs-react-expert/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: nextjs-react-expert
+description: Use when Next.js 15+ App Router mastery. Server Components, Server Actions, PPR, caching, metadata, middleware, parallel/intercepting routes. Use when building Next.js apps or optimizing Next.js performance.
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - react-specialist
+  - react-doctor
+  - baseline-ui
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Next.js 15+ App Router — Dense Reference
+
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `nextjs-react-expert` domain, inspect these 5 critical parameters:
+
+1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
+2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
+3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
+4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
+5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
+
+## Activation Boundaries
+
+- **Activate when:** Use when Next.js 15+ App Router mastery. Server Components, Server Actions, PPR, caching, metadata, middleware, parallel/intercepting routes. Use when building Next.js apps or optimizing Next.js performance.
+- **DO NOT activate when:** The task falls outside the `nextjs-react-expert` domain or is managed by a different dedicated specialist.
+
+## 🔁 Multi-Pass Execution Protocol
+
+Execute all non-trivial tasks through this 7-pass cognitive loop:
+
+| Pass | Phase | Core Action |
+|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. |
+| **Pass 2** | **Plan** | Decompose the task into smallest logical steps; map dependencies and required tool calls. |
+| **Pass 3** | **Execute** | Implement the solution with production-grade craft, zero placeholders, and strict typing. |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. |
+| **Pass 5** | **Attack** | Perform an adversarial review searching for edge-case failures, race conditions, and traps. |
+| **Pass 6** | **Improve** | Eliminate discovered friction, optimize performance, and harden error boundaries. |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+
+## 2026 Next.js 15 Architecture & Performance Invariants
+
+1. **Async Route Params**: In Next.js 15, `params` and `searchParams` are Promises:
+   ```tsx
+   export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+     const { id } = await params;
+   }
+   ```
+2. **Async Headers & Cookies**: Always `await cookies()` and `await headers()`:
+   ```ts
+   import { cookies } from 'next/headers';
+   const cookieStore = await cookies();
+   ```
+3. **Partial Prerendering (PPR)**: Isolate dynamic data fetches within `<Suspense>` boundaries so the static shell renders instantly.
+4. **Server Action CSRF & Origin Verification**: Next.js 15 checks host header by default; ensure actions validate permissions before mutations.
+
+## Hallucination Traps (Read First)
+
+- ❌ Synchronous `const { id } = params` → ✅ Next.js 15: `const { id } = await params`
+- ❌ Synchronous `const c = cookies()` → ✅ Next.js 15: `const c = await cookies()`
+- ❌ Assuming `fetch()` is cached by default → ✅ Next.js 15 defaults to `{ cache: 'no-store' }`
+- ❌ `pages/api/` or `_app.tsx` → ✅ App Router only: `app/api/route.ts`, `app/layout.tsx`
+- ❌ `getServerSideProps` → ✅ Direct `async` Server Components
+- ❌ `next/router` → ✅ `next/navigation` (`useRouter`, `usePathname`)
+- ❌ Server Action without `"use server"` → ✅ Required at top of file or function
+- ❌ Passing functions as props Server → Client → ✅ Use Server Actions
+
+---
+
+## App Router Conventions
+
+```text
+app/
+├── layout.tsx         ← Root shell (HTML/BODY)
+├── page.tsx           ← Route UI
+├── loading.tsx        ← Auto-suspense fallback
+├── error.tsx          ← Error boundary (Must be "use client")
+├── not-found.tsx      ← 404 UI
+├── global-error.tsx   ← Root error boundary
+├── api/users/route.ts ← API Handler (GET, POST)
+├── @modal/login/page.tsx ← Parallel Route (renders in same layout)
+└── (auth)/login/page.tsx ← Route Group (doesn't affect URL)
+```
+
+---
+
+## Server vs Client Components
+
+- **Server Components (Default)**: Zero JS. Direct DB access. Secure env vars.
+- **Client Components (`"use client"`)**: Lifecycle (`useEffect`), State (`useState`), Browser APIs (`window`), Event listeners (`onClick`).
+
+```tsx
+// ✅ INTERLEAVING PATTERN: Pass Server Component as children to Client Component
+export default function Page() {
+  return (
+    <ClientSidebar>
+      {' '}
+      {/* "use client" */}
+      <ServerStats /> {/* Server: zero JS bundle, fetches DB */}
+    </ClientSidebar>
+  );
+}
+```
+
+---
+
+## Server Actions (Mutations)
+
+```tsx
+'use server';
+import { revalidatePath } from 'next/cache';
+import { z } from 'zod';
+
+const Schema = z.object({ name: z.string().min(2) });
+
+export async function createUser(prevState: any, formData: FormData) {
+  // ❌ TRAP: ALWAYS validate formData. Never trust client input.
+  const parsed = Schema.safeParse({ name: formData.get('name') });
+  if (!parsed.success) return { errors: parsed.error.flatten().fieldErrors };
+
+  await db.user.create({ data: parsed.data });
+  revalidatePath('/users'); // Clears cache so next render shows new user
+  return { success: true };
+}
+```
+
+Client usage (React 19):
+
+```tsx
+'use client';
+import { useActionState } from 'react';
+import { createUser } from './actions';
+
+export function UserForm() {
+  const [state, formAction, isPending] = useActionState(createUser, null);
+  return (
+    <form action={formAction}>
+      <input name="name" />
+      <button disabled={isPending}>Submit</button>
+      {state?.errors?.name && <p>{state.errors.name}</p>}
+    </form>
+  );
+}
+```
+
+---
+
+## Data Fetching & Caching (Next.js 15)
+
+```tsx
+// Next.js 15 caching defaults
+const dynamic = await fetch(url); // 15 default: NO CACHE
+const static = await fetch(url, { cache: 'force-cache' }); // Static
+const isr = await fetch(url, { next: { revalidate: 3600 } }); // Revalidate every hour
+const tagged = await fetch(url, { next: { tags: ['user-1'] } }); // On-demand via revalidateTag()
+
+// DB calls without fetch
+import { unstable_cache } from 'next/cache';
+const getCachedUser = unstable_cache(
+  async id => db.user.findUnique({ where: { id } }),
+  ['user-cache-key'],
+  { revalidate: 60, tags: ['users'] },
+);
+```
+
+### Waterfall Elimination
+
+```tsx
+// ✅ Parallel Fetching:
+const [user, posts] = await Promise.all([getUser(), getPosts()]);
+
+// ✅ Streaming (PPR-compatible):
+export default function Page() {
+  return (
+    <main>
+      <FastNav />
+      {/* Page shell loads instantly, SlowChart streams in when ready */}
+      <Suspense fallback={<Skeleton />}>
+        <SlowChart />
+      </Suspense>
+    </main>
+  );
+}
+```
+
+---
+
+## Partial Prerendering (PPR)
+
+PPR static-generates the route shell and streams dynamic parts.
+
+```tsx
+// next.config.ts
+export default { experimental: { ppr: true } };
+
+// Any component reading cookies/headers inside a Suspense boundary becomes a dynamic hole
+import { cookies } from 'next/headers';
+
+async function Cart() {
+  const c = await cookies(); // Next.js 15 cookies are async!
+  const cartId = c.get('cartId');
+}
+
+export default function Page() {
+  return (
+    <div>
+      <StaticHeader /> {/* Cached at build time on CDN */}
+      <Suspense fallback={<CartSkeleton />}>
+        <Cart /> {/* Dynamic, streamed at request time */}
+      </Suspense>
+    </div>
+  );
+}
+```
+
+---
+
+## Middleware
+
+```typescript
+// middleware.ts (Root of project)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(req: NextRequest) {
+  const token = req.cookies.get('auth-token');
+  if (!token && req.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', req.url));
+  }
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*'], // Strict matcher is critical for performance
+};
+```
+
+---
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Mitigation Strategy |
+|:---|:---|:---|
+| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
+| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
+| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
+| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
+| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
+
+---
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Uncontrolled Re-render Loop** | Mutating state inside render bodies or omitting hook dependencies | Wrap effects with explicit deps and isolate reactive derivations in useMemo |
+| **Accessibility Neglect** | Interactive <div> without role="button", tabIndex, or onKeyDown | Use semantic <button> or provide ARIA role, keyboard handlers, and focus ring |
+| **Layout Shift Flash** | Images/dynamic content without aspect-ratio or explicit dimensions | Enforce aspect-ratio or skeleton placeholders to guarantee zero CLS |
+
+---
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `frontend-reviewer` · `type-safety` · `ui-ux-auditor` · `complexity-reviewer`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### ✅ Pre-Flight Self-Audit Checklist
+
+```
+✅ Are all component props strictly typed with zero implicit "any"?
+✅ Are responsive breakpoints, fluid typography, and optical balance verified?
+✅ Is accessibility (ARIA labels, keyboard focus, contrast) validated?
+✅ Are re-renders minimized and state lifecycles cleanly separated?
+✅ Did I verify all imported UI components and icon sets actually exist?
+```
+
+### 🛑 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 test suites, compiler success, or equivalent operational proof) that your output works as intended.

package/skills/nextjs-react-expert/scripts/convert_rules.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Conversion Script: React Best Practices → .agent Format
+Merges 59 individual rules into 8 grouped section files
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+# Section metadata from _sections.md
+SECTIONS = {
+    'async': {
+        'number': 1,
+        'title': 'Eliminating Waterfalls',
+        'impact': 'CRITICAL',
+        'description': 'Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.'
+    },
+    'bundle': {
+        'number': 2,
+        'title': 'Bundle Size Optimization',
+        'impact': 'CRITICAL',
+        'description': 'Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.'
+    },
+    'server': {
+        'number': 3,
+        'title': 'Server-Side Performance',
+        'impact': 'HIGH',
+        'description': 'Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.'
+    },
+    'client': {
+        'number': 4,
+        'title': 'Client-Side Data Fetching',
+        'impact': 'MEDIUM-HIGH',
+        'description': 'Automatic deduplication and efficient data fetching patterns reduce redundant network requests.'
+    },
+    'rerender': {
+        'number': 5,
+        'title': 'Re-render Optimization',
+        'impact': 'MEDIUM',
+        'description': 'Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.'
+    },
+    'rendering': {
+        'number': 6,
+        'title': 'Rendering Performance',
+        'impact': 'MEDIUM',
+        'description': 'Optimizing the rendering process reduces the work the browser needs to do.'
+    },
+    'js': {
+        'number': 7,
+        'title': 'JavaScript Performance',
+        'impact': 'LOW-MEDIUM',
+        'description': 'Micro-optimizations for hot paths can add up to meaningful improvements.'
+    },
+    'advanced': {
+        'number': 8,
+        'title': 'Advanced Patterns',
+        'impact': 'VARIABLE',
+        'description': 'Advanced patterns for specific cases that require careful implementation.'
+    }
+}
+
+
+def parse_frontmatter(content: str) -> Tuple[Dict, str]:
+    """Parse markdown frontmatter and body"""
+    if not content.startswith('---'):
+        return {}, content
+
+    parts = content.split('---', 2)
+    if len(parts) < 3:
+        return {}, content
+
+    # Parse YAML frontmatter manually (simple key: value)
+    frontmatter = {}
+    for line in parts[1].strip().split('\n'):
+        if ':' in line:
+            key, value = line.split(':', 1)
+            frontmatter[key.strip()] = value.strip()
+
+    body = parts[2].strip()
+    return frontmatter, body
+
+
+def parse_rule_file(filepath: Path) -> Dict:
+    """Parse a single rule file"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    frontmatter, body = parse_frontmatter(content)
+
+    # Extract prefix from filename
+    filename = filepath.stem
+    prefix = filename.split('-')[0]
+
+    return {
+        'filename': filepath.name,
+        'prefix': prefix,
+        'title': frontmatter.get('title', filename),
+        'impact': frontmatter.get('impact', ''),
+        'impactDescription': frontmatter.get('impactDescription', ''),
+        'tags': frontmatter.get('tags', ''),
+        'body': body,
+        'frontmatter': frontmatter
+    }
+
+
+def group_rules_by_section(rules_dir: Path) -> Dict[str, List[Dict]]:
+    """Group all rules by their section prefix"""
+    grouped = {prefix: [] for prefix in SECTIONS.keys()}
+
+    for rule_file in sorted(rules_dir.glob('*.md')):
+        # Skip special files
+        if rule_file.name.startswith('_'):
+            continue
+
+        rule = parse_rule_file(rule_file)
+        prefix = rule['prefix']
+
+        if prefix in grouped:
+            grouped[prefix].append(rule)
+        else:
+            print(f"[WARNING] Unknown prefix '{prefix}' in file: {rule_file.name}")
+
+    return grouped
+
+
+def generate_section_file(section_prefix: str, rules: List[Dict], output_dir: Path):
+    """Generate a merged section file"""
+    if not rules:
+        print(f"[WARNING] No rules found for section: {section_prefix}")
+        return
+
+    section_meta = SECTIONS[section_prefix]
+    section_num = section_meta['number']
+    section_title = section_meta['title']
+    impact = section_meta['impact']
+    description = section_meta['description']
+
+    # Sort rules by title
+    rules.sort(key=lambda r: r['title'])
+
+    # Build content
+    content = f"""# {section_num}. {section_title}
+
+> **Impact:** {impact}
+> **Focus:** {description}
+
+---
+
+## Overview
+
+This section contains **{len(rules)} rules** focused on {section_title.lower()}.
+
+"""
+
+    # Add each rule
+    for i, rule in enumerate(rules, 1):
+        rule_id = f"{section_num}.{i}"
+        title = rule['title']
+        rule_impact = rule['impact']
+        tags = rule['tags']
+        body = rule['body']
+
+        content += f"""---
+
+## Rule {rule_id}: {title}
+
+"""
+
+        if rule_impact:
+            content += f"**Impact:** {rule_impact}  \n"
+
+        if tags:
+            content += f"**Tags:** {tags}  \n"
+
+        content += f"\n{body}\n\n"
+
+    # Write file
+    output_file = output_dir / f"{section_num}-{section_prefix}-{section_title.lower().replace(' ', '-')}.md"
+    output_file.write_text(content, encoding='utf-8')
+    print(f"[OK] Generated: {output_file.name} ({len(rules)} rules)")
+
+
+def main():
+    """Main conversion function"""
+    # Paths
+    base_dir = Path(__file__).parent.parent.parent.parent.parent
+    rules_dir = base_dir / "others/agent-skills/skills/react-best-practices/rules"
+    output_dir = base_dir / ".agent/skills/react-best-practices"
+
+    print(f"[*] Reading rules from: {rules_dir}")
+    print(f"[*] Output to: {output_dir}")
+    print()
+
+    # Check if rules directory exists
+    if not rules_dir.exists():
+        print(f"[ERROR] Rules directory not found: {rules_dir}")
+        return
+
+    # Group rules
+    print("[*] Grouping rules by section...")
+    grouped_rules = group_rules_by_section(rules_dir)
+
+    # Stats
+    total_rules = sum(len(rules) for rules in grouped_rules.values())
+    print(f"[*] Found {total_rules} total rules")
+    print()
+
+    # Generate section files
+    print("[*] Generating section files...")
+    for section_prefix in SECTIONS.keys():
+        rules = grouped_rules[section_prefix]
+        generate_section_file(section_prefix, rules, output_dir)
+
+    print()
+    print("[SUCCESS] Conversion complete!")
+    print(f"[*] Generated 8 section files from {total_rules} rules")
+
+
+if __name__ == '__main__':
+    main()