tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/react-specialist/SKILL.md

@@ -1,108 +1,227 @@
----
-name: react-specialist
-description: Senior React specialist (React 18+) focusing on advanced patterns, state management, performance optimization, and production architectures (Next.js/Remix).
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
----
-
-# React Specialist - Claude Code Sub-Agent
-
-You are a senior React specialist with expertise in React 18+ and the modern React ecosystem. Your focus spans advanced patterns, performance optimization, state management, and production architectures with emphasis on creating scalable applications that deliver exceptional user experiences.
-
-## Configuration & Context Assessment
-When invoked:
-1. Query context manager for React project requirements and architecture
-2. Review component structure, state management, and performance needs
-3. Analyze optimization opportunities, patterns, and best practices
-4. Implement modern React solutions with performance and maintainability focus
-
----
-
-## The React Excellence Checklist
-- React 18+ features utilized effectively
-- TypeScript strict mode enabled properly
-- Component reusability > 80% achieved
-- Performance score > 95 maintained
-- Test coverage > 90% implemented
-- Bundle size optimized thoroughly
-- Accessibility compliant consistently
-
----
-
-## Core Architecture Decision Framework
-
-### Advanced React Patterns & Hooks Mastery
-*   Compound components, Render props, Custom hooks design, Ref forwarding, Portals.
-*   `useState` patterns, `useEffect` optimization, `useMemo`/`useCallback` carefully applied, `useReducer` complex state, custom hooks library.
-*   Concurrent features (`useTransition`, `useDeferredValue`, Suspense for data/streaming HTML).
-
-### State Management & Components
-*   **State:** Server state (React Query/TanStack), Global state (Zustand, Redux Toolkit, Jotai), Local and URL state.
-*   **Structure:** Atomic design, Container/presentational separation, Error boundaries, Fragment usage.
-
-### extreme Performance Optimization
-*   `React.memo` usage, Code splitting, Virtual scrolling.
-*   Selective hydration, Bundle analysis, Tree shaking.
-*   Core Web Vitals driven implementation (LCP, FID, CLS).
-
-### Production Architectures (SSR)
-*   **Next.js/Remix:** Server components, Streaming SSR, Progressive enhancement, SEO optimization.
-*   **Ecosystem:** React Query, Tailwind CSS, Framer Motion, React Hook Form.
-
----
-
-## Output Format
-
-When this skill produces or reviews code, structure your output as follows:
-
-```
-━━━ React Specialist Report ━━━━━━━━━━━━━━━━━━━━━━━━
-Skill:       React Specialist
-Language:    [detected language / framework]
-Scope:       [N files · N functions]
-─────────────────────────────────────────────────
-✅ Passed:   [checks that passed, or "All clean"]
-⚠️  Warnings: [non-blocking issues, or "None"]
-❌ Blocked:  [blocking issues requiring fix, or "None"]
-─────────────────────────────────────────────────
-VBC status:  PENDING → VERIFIED
-Evidence:    [test output / lint pass / compile success]
-```
-
-**VBC (Verification-Before-Completion) is mandatory.**
-Do not mark status as VERIFIED until concrete terminal evidence is provided.
-
-
----
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/tribunal-frontend`**
-**Active reviewers: `logic` · `security` · `frontend` · `type-safety`**
-
-### ❌ Forbidden AI Tropes in React
-1. **Sloppy Layout Generation** — never build UI without explicit dimensional boundaries. You MUST apply strict numeric design tokens (e.g. 4px grid spacing) and explicit flex/grid layouts.
-2. **Unnecessary `useEffect` Data Fetching** — never fetch raw data inside a `useEffect` if a framework pattern (Server Components, SWR, React Query) is available.
-3. **Missing `key` in maps** — always provide a unique, stable key. No using iteration index as the key.
-4. **Prop Drilling Nightmare** — avoid passing props more than 3 levels deep; use Context or atomic stores (Zustand) instead.
-4. **Over-Memoization** — do not slap `useMemo`/`useCallback` on everything prematurely. Only use it when profiling proves a performance bottleneck.
-5. **Class Components** — never hallucinate class `extends React.Component` or lifecycle methods (`componentDidMount`) in a modern React 18+ app unless explicitly requested for legacy migration.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before generating React code:
-```text
-✅ Did I use strictly functional components with hooks?
-✅ Is my component free of side effects during the render phase?
-✅ Are array maps properly utilizing unique and stable `key` attributes?
-✅ Did I configure proper fallbacks using `<Suspense>` and Error Boundaries?
-✅ When handling state, did I ensure that mutated state is returned as a deeply cloned or immutable structure?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Assuming a React component "works" just because it compiles or because the bundler gives no immediate warnings.
-- ✅ **Required:** You are explicitly forbidden from completing your UI assignment without providing **concrete terminal/test evidence** (e.g., passing Jest/Vitest logs, successful build output, or specific CLI execution results) proving the build is error-free.
+---
+name: react-specialist
+description: React 19+ specialist. use(), useActionState, useOptimistic, React Compiler, Server/Client Components, Zustand/Jotai, React Query. Use when building components, managing state, optimizing renders.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 3.1.0
+last-updated: 2026-04-06
+---
+
+# React 19+ — Dense Reference
+
+## Hallucination Traps (Read First)
+- ❌ `useFormState` → ✅ `useActionState` (stable name)
+- ❌ `useContext()` in conditionals → ✅ `use(Context)` CAN be conditional
+- ❌ `useMemo/useCallback/React.memo` in React 19+ projects → ✅ React Compiler handles this
+- ❌ `exitBeforeEnter` (Framer) → ✅ `mode="wait"` on `<AnimatePresence>`
+- ❌ `next/router` → ✅ `next/navigation` in App Router
+- ❌ Server Components using `useState/useEffect` → must be `"use client"`
+
+---
+
+## React 19 Core APIs
+
+### `use()` — Replaces many useEffect patterns
+```tsx
+import { use } from "react";
+// Reads promises (suspends until resolved)
+function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
+  const user = use(userPromise); // suspends
+  return <h1>{user.name}</h1>;
+}
+// Reads context — CAN be called conditionally (unlike useContext)
+function Admin({ isAdmin }: { isAdmin: boolean }) {
+  if (isAdmin) return <Panel theme={use(ThemeContext)} />;
+  return <PublicPanel />;
+}
+```
+
+### `useActionState` — Form actions with state
+```tsx
+import { useActionState } from "react"; // NOT useFormState
+
+async function submitForm(prevState: FormState, formData: FormData) {
+  const email = formData.get("email") as string;
+  if (!email.includes("@")) return { error: "Invalid email" };
+  await saveToDatabase(email);
+  return { error: null, success: true };
+}
+
+function SignupForm() {
+  const [state, formAction, isPending] = useActionState(submitForm, { error: null });
+  return (
+    <form action={formAction}>
+      <input name="email" disabled={isPending} />
+      {state.error && <p>{state.error}</p>}
+      <button disabled={isPending}>{isPending ? "Saving..." : "Submit"}</button>
+    </form>
+  );
+}
+```
+
+### `useOptimistic` — Instant UI feedback
+```tsx
+import { useOptimistic } from "react";
+function TodoList({ todos }: { todos: Todo[] }) {
+  const [optimistic, addOptimistic] = useOptimistic(
+    todos,
+    (current, newTodo: Todo) => [...current, newTodo]
+  );
+  async function handleAdd(formData: FormData) {
+    addOptimistic({ id: crypto.randomUUID(), title: formData.get("title"), pending: true });
+    await saveTodo(formData.get("title") as string);
+  }
+  return (
+    <form action={handleAdd}>
+      {optimistic.map(t => <li key={t.id} style={{ opacity: t.pending ? 0.5 : 1 }}>{t.title}</li>)}
+    </form>
+  );
+}
+```
+
+### `useFormStatus` — Button pending state (must be INSIDE `<form>`)
+```tsx
+import { useFormStatus } from "react-dom";
+// ❌ TRAP: Cannot be called in the same component as <form>
+function SubmitButton() {
+  const { pending } = useFormStatus(); // reads nearest parent form
+  return <button disabled={pending}>{pending ? "Saving..." : "Save"}</button>;
+}
+```
+
+### `useTransition` — Non-blocking updates (React 19: supports async)
+```tsx
+const [isPending, startTransition] = useTransition();
+startTransition(async () => {
+  const data = await search(query); // async supported in React 19 only
+  setResults(data);
+});
+```
+
+### `useDeferredValue` — Stale-while-rerender
+```tsx
+const deferredQuery = useDeferredValue(query);
+const isStale = query !== deferredQuery;
+return <div style={{ opacity: isStale ? 0.6 : 1 }}><ExpensiveList query={deferredQuery} /></div>;
+// React 19: useDeferredValue(value, initialFallback) — 2-arg form
+```
+
+---
+
+## React Compiler (React 19)
+- Auto-memoizes components/values/callbacks. **Don't manually memoize in React 19 projects.**
+- ❌ `useMemo(() => calc(a), [a])` / `useCallback(fn, [id])` / `React.memo(Comp)` — legacy
+- ✅ Write plain functions/values. Compiler optimizes automatically.
+- Exception: still use manual memo if compiler is explicitly disabled in config.
+
+---
+
+## Component Patterns
+
+### Compound Components (shared state via context)
+```tsx
+const TabsContext = createContext<{ active: string; setActive: (id: string) => void } | null>(null);
+function Tabs({ children, defaultTab }: { children: ReactNode; defaultTab: string }) {
+  const [active, setActive] = useState(defaultTab);
+  return <TabsContext value={{ active, setActive }}><div>{children}</div></TabsContext>;
+}
+function Tab({ id, children }: { id: string; children: ReactNode }) {
+  const ctx = use(TabsContext)!;
+  return <button onClick={() => ctx.setActive(id)} aria-selected={ctx.active === id}>{children}</button>;
+}
+```
+
+### Render Props / Higher Order Hooks
+Prefer custom hooks over render props for modern React.
+
+### Context Performance Pattern
+```tsx
+// Split context — prevents all consumers from re-rendering on every change
+const CountStateCtx = createContext<number>(0);
+const CountDispatchCtx = createContext<Dispatch<Action>>(() => {});
+```
+
+---
+
+## State Management
+
+### Zustand (preferred for global state)
+```tsx
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+const useStore = create<Store>()(
+  persist(
+    (set, get) => ({
+      count: 0,
+      increment: () => set(s => ({ count: s.count + 1 })),
+      getDoubled: () => get().count * 2,
+    }),
+    { name: "my-store" }
+  )
+);
+// ❌ TRAP: Do NOT destructure the whole store — causes re-render on every change
+// ✅ const count = useStore(s => s.count); // selector
+```
+
+### Jotai (preferred for derived/atomic state)
+```tsx
+import { atom, useAtom, useAtomValue, useSetAtom } from "jotai";
+const countAtom = atom(0);
+const doubledAtom = atom(get => get(countAtom) * 2); // derived atom
+// ❌ TRAP: atomWithStorage is from jotai/utils — NOT from jotai
+import { atomWithStorage } from "jotai/utils";
+```
+
+### React Query / TanStack Query
+```tsx
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+const { data, isPending, error } = useQuery({
+  queryKey: ["user", userId],
+  queryFn: () => fetchUser(userId),
+  staleTime: 5 * 60 * 1000, // don't refetch for 5 minutes
+});
+// Optimistic update:
+const qc = useQueryClient();
+const mutation = useMutation({
+  mutationFn: updateUser,
+  onMutate: async (newUser) => {
+    await qc.cancelQueries({ queryKey: ["user", newUser.id] });
+    const prev = qc.getQueryData(["user", newUser.id]);
+    qc.setQueryData(["user", newUser.id], newUser);
+    return { prev };
+  },
+  onError: (_, __, ctx) => qc.setQueryData(["user"], ctx?.prev),
+  onSettled: () => qc.invalidateQueries({ queryKey: ["user"] }),
+});
+```
+
+---
+
+## Performance
+
+| Technique | When |
+|-----------|------|
+| `useDeferredValue` | Expensive derived render (charts, filters) |
+| `useTransition` | Page nav, tab switches, data load |
+| `lazy()` + `Suspense` | Code-split heavy components |
+| `<Virtuoso>` / `<WindowVirtualizer>` | Lists > 200 items |
+| Avoid `useEffect` for state transforms | Use `useMemo` or derived atoms |
+
+---
+
+## Refs & DOM
+
+```tsx
+// React 19: ref is now a prop (no forwardRef needed)
+function Input({ ref, ...props }: ComponentProps<"input"> & { ref?: Ref<HTMLInputElement> }) {
+  return <input ref={ref} {...props} />;
+}
+// ❌ TRAP: forwardRef is deprecated in React 19 — still works but not needed
+```
+
+---
+
+## Testing Checklist
+- ✅ Use React Testing Library — test behavior, not implementation
+- ✅ `userEvent` over `fireEvent` (async, closer to real interaction)
+- ✅ Mock server calls with MSW (Mock Service Worker)
+- ❌ Never test internal state, ref values, or component instances

package/.agent/skills/readme-builder/SKILL.md

@@ -9,8 +9,6 @@ applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 
 # README Builder Skill
 
-> A great README is a product pitch, a user manual, and a contributor's welcome — all in one document.
-
 ---
 
 ## Ground Rules
@@ -46,7 +44,7 @@ Before generating any README content, answer these questions by scanning the pro
 ```markdown
 # [Project Name]
 
-> [One-line tagline: what it does and for whom]
+[One-line tagline: what it does and for whom]
 
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Version](https://img.shields.io/npm/v/package-name)](https://www.npmjs.com/package/package-name)
@@ -106,10 +104,10 @@ package-name init --config ./config.json --output ./dist
 
 ## ⚙️ Configuration
 
-| Option | Type | Default | Description |
+|Option|Type|Default|Description|
 |--------|------|---------|-------------|
-| `option1` | `string` | `"default"` | What it controls |
-| `option2` | `boolean` | `false` | What it controls |
+|`option1`|`string`|`"default"`|What it controls|
+|`option2`|`boolean`|`false`|What it controls|
 
 ---
 
@@ -185,12 +183,12 @@ Add a dedicated `## Commands` section:
 ```markdown
 ## Commands
 
-| Command | Description |
+|Command|Description|
 |---------|-------------|
-| `tool init` | Initialize a new project |
-| `tool build` | Compile and bundle |
-| `tool deploy` | Deploy to production |
-| `tool --help` | Show all available options |
+|`tool init`|Initialize a new project|
+|`tool build`|Compile and bundle|
+|`tool deploy`|Deploy to production|
+|`tool --help`|Show all available options|
 ```
 
 ### Libraries / SDKs
@@ -203,10 +201,10 @@ Add a `## API Reference` section with function signatures:
 
 Returns: `ReturnType`
 
-| Parameter | Type | Description |
+|Parameter|Type|Description|
 |-----------|------|-------------|
-| `param1` | `string` | Description |
-| `param2` | `options` | Optional config |
+|`param1`|`string`|Description|
+|`param2`|`options`|Optional config|
 ```
 
 ### Monorepos
@@ -215,10 +213,10 @@ Add a `## Packages` table:
 ```markdown
 ## Packages
 
-| Package | Version | Description |
+|Package|Version|Description|
 |---------|---------|-------------|
-| [`@org/core`](packages/core) | [![npm](https://img.shields.io/npm/v/@org/core)](https://npm.im/@org/core) | Core engine |
-| [`@org/cli`](packages/cli) | [![npm](https://img.shields.io/npm/v/@org/cli)](https://npm.im/@org/cli) | CLI interface |
+|[`@org/core`](packages/core)|[![npm](https://img.shields.io/npm/v/@org/core)](https://npm.im/@org/core)|Core engine|
+|[`@org/cli`](packages/cli)|[![npm](https://img.shields.io/npm/v/@org/cli)](https://npm.im/@org/cli)|CLI interface|
 ```
 
 ---
@@ -242,71 +240,3 @@ Evidence:    [file written at path / content reviewed]
 ```
 
 ---
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/generate`**
-**Active reviewers: `logic` · `frontend` · `documentation`**
-
-### ❌ Forbidden AI Tropes in README Generation
-
-1. **Placeholder content** — "Add your description here", "TODO", "Coming soon" are never acceptable.
-2. **Fabricated badges** — never create badge URLs with invented package names or repo paths.
-3. **Untested code blocks** — never write installation or usage commands without verifying them against the actual `package.json` or project config.
-4. **Version number invention** — always read the actual version from `package.json`, `pyproject.toml`, or `Cargo.toml`.
-5. **Generic feature claims** — "fast", "powerful", "easy to use" without concrete evidence or metrics.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before generating README content:
-
-```
-✅ Did I read the actual project files first (package.json, source)?
-✅ Is the project name correct (not a guess)?
-✅ Are all code block commands runnable against this actual project?
-✅ Are badge URLs pointing to the real repo/package?
-✅ Is the version number read from actual project files, not guessed?
-✅ Does every feature bullet describe a concrete, provable capability?
-```
-
-
----
-
-## 🤖 LLM-Specific Traps
-
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
-
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
-
----
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before confirming output:
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
-```
-
-### 🛑 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.