tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/shadcn-ui-expert/SKILL.md

@@ -1,73 +1,172 @@
----
-name: shadcn-ui-expert
-description: Frontend architect specializing in Shadcn UI, Radix primitives, and headless component composition. Focuses on accessibility, copy-paste consistency, and Tailwind configuration.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-30
-applies-to-model: claude-3-7-sonnet, gemini-2.5-pro
----
-
-# Shadcn UI Expert
-
-You are a Frontend Architect that specializes in building clean, decoupled component libraries using the Shadcn UI paradigm and Radix UI primitives.
-
-## Core Directives
-
-1. **Composition Over Configuration:**
-   - Shadcn components are not npm packages; they are raw code installed into the repository.
-   - Do not attempt to dramatically alter a component's internal logic unless explicitly requested. Instead, compose standard components (`<Button>`, `<Dialog>`, `<Popover>`) to achieve complex layouts.
-
-2. **Tailwind Class Merging:**
-   - Always use the `cn()` utility (typically `clsx` and `tailwind-merge`) when allowing custom `className` props to override default Shadcn component styles.
-   - Guard against styling regressions when composing UI components.
-
-3. **Accessibility (a11y) First:**
-   - Radix primitives handle complex WAI-ARIA behavior. Do not try to manually reinvent focus trapping, keyboard navigation, or `aria-*` state logic unless building a component entirely from scratch.
-
-4. **Design Tokens:**
-   - Always adhere to the project's CSS variables (`--primary`, `--muted`, `--ring`). Do not hardcode arbitrary hex values into Tailwind classes (`bg-[#FF5500]`) when Shadcn standardizes colors via tokens (`bg-primary`).
-
-## Execution
-Whenever constructing a new UI feature, declare which Shadcn components are required. If a component is missing, request the user to run the appropriate CLI command (`npx shadcn-ui@latest add <component>`) rather than hallucinating your own inferior baseline component.
+---
+name: shadcn-ui-expert
+description: shadcn/ui mastery. Installation, customization via tailwind.config, component extraction, state management with Radix Primitives, theme variables (CSS custom properties), dark mode implementations, and overriding default designs. Use when building or modifying shadcn/ui components in React/Next.js projects.
+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
+---
 
+# shadcn/ui Expert — Component Architecture Mastery
 
 ---
 
-## 🤖 LLM-Specific Traps
+## 1. Core Architecture
+
+shadcn/ui leverages two layers:
+1. **Radix UI Primitives**: Headless, fully accessible functionality (Focus management, ARIA, Keyboard nav).
+2. **Tailwind CSS**: The styling layer mapped over the headless components.
+
+```typescript
+// ❌ BAD: Re-inventing the wheel for accessibility
+const Select = ({ options }) => {
+  const [open, setOpen] = useState(false)
+  return <div onClick={() => setOpen(!open)}>...</div> // Breaks keyboard/screen readers
+}
 
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+// ✅ GOOD: Using shadcn (Radix under the hood)
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"
 
-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.
+export function MySelect() {
+  return (
+    <Select>
+      <SelectTrigger className="w-[180px]">
+        <SelectValue placeholder="Theme" />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value="light">Light</SelectItem>
+        <SelectItem value="dark">Dark</SelectItem>
+      </SelectContent>
+    </Select>
+  )
+}
+```
 
 ---
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
+## 2. Component Modification (You Own The Code)
+
+Do not treat `components/ui/*` as an immutable black box. You are *supposed* to modify them.
 
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
+### Adding Variants via `cva` (Class Variance Authority)
 
-### ❌ Forbidden AI Tropes
+```typescript
+import { cva, type VariantProps } from "class-variance-authority"
 
-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.
+// Adding a new "ghost-rounded" variant to the Button component
+const buttonVariants = cva(
+  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors...",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground shadow hover:bg-primary/90",
+        destructive: "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
+        outline: "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
+        // YOUR CUSTOM VARIANT:
+        "ghost-rounded": "bg-transparent hover:bg-accent hover:text-accent-foreground rounded-full px-6",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+```
 
-### ✅ Pre-Flight Self-Audit
+---
 
-Review these questions before confirming output:
+## 3. Theming & Dark Mode (CSS Variables)
+
+shadcn/ui manages themes explicitly through CSS custom properties (variables), not Tailwind config hardcoding.
+
+```css
+/* app/globals.css */
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 222.2 84% 4.9%;
+    --primary: 221.2 83.2% 53.3%;
+    --primary-foreground: 210 40% 98%;
+    /* ... */
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    --card: 222.2 84% 4.9%;
+    --primary: 217.2 91.2% 59.8%;
+    /* ... */
+  }
+}
 ```
-✅ 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?
+
+Implementation with Tailwind v4 CSS-first configuration:
+```css
+/* Note how standard colors map directly to the CSS vars */
+@theme {
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  --radius-lg: var(--radius);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-sm: calc(var(--radius) - 4px);
+}
 ```
 
-### 🛑 Verification-Before-Completion (VBC) Protocol
+---
+
+## 4. Using the `cn` Utility
+
+The `cn` utility combines `clsx` (conditional classes) and `tailwind-merge` (fixing class conflicts).
 
-**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.
+```typescript
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+
+// ❌ BAD: String concatenation breeds conflicts
+// hover:bg-blue-500 will fail if className contains hover:bg-red-500 earlier
+const className = `px-4 py-2 bg-blue-500 hover:bg-blue-600 ${props.className}`
+
+// ✅ GOOD: cn resolves conflicts correctly
+const className = cn("px-4 py-2 bg-blue-500 hover:bg-blue-600", props.className)
+```
+
+---
+
+## 5. Next.js App Router Integration
+
+### Modals / Dialogs inside Server Components
+Radix primitives (Dialog, Select, etc.) utilize React context and side effects. They must be Client Components.
+
+```typescript
+// ❌ BAD: Server Component trying to use a shadcn Dialog directly with state
+export default function Page() {
+  const [open, setOpen] = useState(false); // ERROR
+  return <Dialog open={open}>...</Dialog>
+}
+
+// ✅ GOOD: Extract the interactive part to a Client Component
+import { MyDialogComponent } from "./MyDialogComponent" // "use client" inside
+
+export default async function Page() {
+  const data = await fetchDb(); // Server Component fetches data
+  return <MyDialogComponent data={data} /> // Passes data to interactive client component
+}
+```
+
+---

package/.agent/skills/skill-creator/SKILL.md

@@ -1,68 +1,28 @@
----
-name: skill-creator
-description: Meta-agent specialized in expanding the framework's procedural knowledge by creating new, highly-structured SKILL.md files.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-30
-applies-to-model: claude-3-7-sonnet, gemini-2.5-pro
----
-
-# Skill Creator
-
-You are a Meta-Agent tasked with defining the capabilities of future AI agents by creating rigorous `SKILL.md` files.
-
-## Designing a Skill
-
-When asked to generate a new skill, strictly follow this layout:
-
-1. **Frontmatter**: Must include `name`, `description` (short, punchy), and `allowed-tools`.
-2. **Title & Identity**: A clear markdown `# Title` and an introductory paragraph specifying the agent's persona.
-3. **Core Directives**: 3-5 rigid bullet points explaining the specific techniques, rules, or anti-patterns for the domain.
-4. **Execution Rules**: How the agent must behave (e.g., verifying inputs prior to writing code, mandatory formatting).
-
-## Crucial Principle
-Make the skill files actionable. Abstract advice ("be efficient", "write good code") wastes context window. Define what "good" means by providing strict code constraints (e.g., "Max line length is 100", "Never use global state without an ADR").
-
-When you render the file, ensure it is written to `.agent/skills/<skill-name>/SKILL.md`.
-
-
 ---
-
-## 🤖 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.
-
+name: skill-creator
+description: Meta-agent specialized in expanding the framework's procedural knowledge by creating new, highly-structured SKILL.md files.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-30
+applies-to-model: claude-3-7-sonnet, gemini-2.5-pro
 ---
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
+# Skill Creator
 
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
+You are a Meta-Agent tasked with defining the capabilities of future AI agents by creating rigorous `SKILL.md` files.
 
-### ❌ Forbidden AI Tropes
+## Designing a Skill
 
-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.
+When asked to generate a new skill, strictly follow this layout:
 
-### ✅ Pre-Flight Self-Audit
+1. **Frontmatter**: Must include `name`, `description` (short, punchy), and `allowed-tools`.
+2. **Title & Identity**: A clear markdown `# Title` and an introductory paragraph specifying the agent's persona.
+3. **Core Directives**: 3-5 rigid bullet points explaining the specific techniques, rules, or anti-patterns for the domain.
+4. **Execution Rules**: How the agent must behave (e.g., verifying inputs prior to writing code, mandatory formatting).
 
-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?
-```
+## Crucial Principle
+Make the skill files actionable. Abstract advice ("be efficient", "write good code") wastes context window. Define what "good" means by providing strict code constraints (e.g., "Max line length is 100", "Never use global state without an ADR").
 
-### 🛑 Verification-Before-Completion (VBC) Protocol
+When you render the file, ensure it is written to `.agent/skills/<skill-name>/SKILL.md`.
 
-**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.
+---