tribunal-kit 3.0.0 → 3.1.0

package/.agent/workflows/fix.md

@@ -1,135 +1,114 @@
----
-description: Auto-fix known issues with lint, formatting, imports, and TypeScript errors. Runs lint_runner.py and auto-fixers. Human approval required before applying any changes. Shows a diff of what will change before writing to disk.
----
-
-# /fix — Automated Error Resolution
-
-$ARGUMENTS
-
----
-
-## When to Use /fix
-
-| Use `/fix` when... | Use something else when... |
-|:---|:---|
-| Lint errors blocking CI | Logic bugs → `/debug` |
-| TypeScript type errors | Feature changes needed → `/enhance` |
-| Formatting inconsistencies | Security vulnerabilities → `/tribunal-backend` |
-| Missing imports auto-detectable | Structural changes → `/refactor` |
-| After a dependency version upgrade breaks types | |
-
----
-
-## What /fix Handles (Auto-Fixable)
-
-```
-✅ AUTO-FIXABLE:
-│ ESLint  → eslint --fix (formatting, unused imports, style)
-│ Prettier → prettier --write (spacing, quotes, semicolons)
-│ TypeScript → add missing required imports visible from types
-│ Tailwind → class ordering (prettier-plugin-tailwindcss)
-│ npm audit → npm audit fix (non-breaking dependency patches)
-
-⚠️ REQUIRES HUMAN DECISION:
-│ TypeScript strict mode errors (may require type narrowing by developer)
-│ Breaking API changes after major version bump
-│ Logic errors flagged by ESLint (not just style)
-│ Security vulnerabilities (audit fix --force changes major versions)
-```
-
----
-
-## Execution Sequence
-
-```bash
-# 1. Run lint with auto-fix
-python .agent/scripts/lint_runner.py . --fix
-
-# 2. Fix remaining TypeScript errors (auto-detectable only)
-npx tsc --noEmit 2>&1 | grep "error TS"
-
-# 3. Format all files
-npx prettier --write "src/**/*.{ts,tsx,js,json,css}"
-
-# 4. Check npm audit (report, don't auto-fix without approval)
-npm audit --audit-level=high
-```
-
----
-
-## Human Gate — Review Diff Before Applying
-
-After running fixers:
-
-```
-━━━ Fix Preview ━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Files that will change:
-  src/components/Button.tsx        (lint: 3 unused imports removed)
-  src/lib/auth.ts                  (lint: missing semicolons, trailing whitespace)
-  src/app/api/users/route.ts       (prettier: formatting)
-
-Diff preview:
-  --- src/components/Button.tsx
-  +++ src/components/Button.tsx
-  - import { useState, useEffect, useCallback } from 'react'; // useEffect unused
-  + import { useState, useCallback } from 'react';
-
-━━━ Remaining Errors (Need Human Review) ━━━
-
-  src/lib/payment.ts:34 — TS2345: Argument of type 'string | null' not assignable to 'string'
-  → This requires deliberate type narrowing — cannot auto-fix safely
-
-━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Apply auto-fixes?  Y = write to disk | N = discard | S = select specific files
-```
-
-**No files are written without explicit "Y" approval.**
-
----
-
-## Fix Guard
-
-```
-❌ Never run --force on npm audit fix without human approval (can break major APIs)
-❌ Never auto-fix TypeScript errors that require business logic decisions
-❌ Never apply lint fixes to generated test files without human review
-❌ Never "fix" ESLint disable comments — they may be intentional suppressions
-❌ Never mix fix + refactoring in the same run
-```
-
----
-
-## After /fix — Verify
-
-```bash
-# Verify fixes didn't introduce new errors
-npx tsc --noEmit    # Must be clean
-npm test            # Must still all pass
-npm run lint        # Must be zero errors
-```
-
-If any verification step fails after fixes → report and revert auto-fixes for that file.
-
----
-
-## Cross-Workflow Navigation
-
-| After /fix shows... | Go to |
-|:---|:---|
-| Logic errors remaining after lint | `/debug` |
-| Security issues in audit output | `/tribunal-backend` |
-| Complex type errors needing refactoring | `/refactor` |
-| After all errors fixed | `/deploy` (if pre-deploy fix) or `/generate` (if pre-generation) |
-
----
-
-## Usage Examples
-
-```
-/fix all lint errors in src/components/
-/fix TypeScript errors after upgrading to Next.js 15
-/fix unused import warnings blocking CI
-/fix after running npm audit --audit-level=high
-/fix formatting inconsistencies across the entire src/ directory
-```
+---
+description: Auto-fix known issues with lint, formatting, imports, and TypeScript errors. Runs lint_runner.py and auto-fixers. Human approval required before applying any changes. Shows a diff of what will change before writing to disk.
+---
+
+# /fix — Automated Error Resolution
+
+$ARGUMENTS
+
+---
+
+## When to Use /fix
+
+|Use `/fix` when...|Use something else when...|
+|:---|:---|
+|Lint errors blocking CI|Logic bugs → `/debug`|
+|TypeScript type errors|Feature changes needed → `/enhance`|
+|Formatting inconsistencies|Security vulnerabilities → `/tribunal-backend`|
+|Missing imports auto-detectable|Structural changes → `/refactor`|
+|After a dependency version upgrade breaks types||
+
+---
+
+## What /fix Handles (Auto-Fixable)
+
+```
+✅ AUTO-FIXABLE:
+│ ESLint  → eslint --fix (formatting, unused imports, style)
+│ Prettier → prettier --write (spacing, quotes, semicolons)
+│ TypeScript → add missing required imports visible from types
+│ Tailwind → class ordering (prettier-plugin-tailwindcss)
+│ npm audit → npm audit fix (non-breaking dependency patches)
+
+⚠️ REQUIRES HUMAN DECISION:
+│ TypeScript strict mode errors (may require type narrowing by developer)
+│ Breaking API changes after major version bump
+│ Logic errors flagged by ESLint (not just style)
+│ Security vulnerabilities (audit fix --force changes major versions)
+```
+
+---
+
+## Execution Sequence
+
+```bash
+# 1. Run lint with auto-fix
+python .agent/scripts/lint_runner.py . --fix
+
+# 2. Fix remaining TypeScript errors (auto-detectable only)
+npx tsc --noEmit 2>&1 | grep "error TS"
+
+# 3. Format all files
+npx prettier --write "src/**/*.{ts,tsx,js,json,css}"
+
+# 4. Check npm audit (report, don't auto-fix without approval)
+npm audit --audit-level=high
+```
+
+---
+
+## Human Gate — Review Diff Before Applying
+
+After running fixers:
+
+```
+━━━ Fix Preview ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Files that will change:
+  src/components/Button.tsx        (lint: 3 unused imports removed)
+  src/lib/auth.ts                  (lint: missing semicolons, trailing whitespace)
+  src/app/api/users/route.ts       (prettier: formatting)
+
+Diff preview:
+  --- src/components/Button.tsx
+  +++ src/components/Button.tsx
+  - import { useState, useEffect, useCallback } from 'react'; // useEffect unused
+  + import { useState, useCallback } from 'react';
+
+━━━ Remaining Errors (Need Human Review) ━━━
+
+  src/lib/payment.ts:34 — TS2345: Argument of type 'string | null' not assignable to 'string'
+  → This requires deliberate type narrowing — cannot auto-fix safely
+
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Apply auto-fixes?  Y = write to disk | N = discard | S = select specific files
+```
+
+**No files are written without explicit "Y" approval.**
+
+---
+
+## Fix Guard
+
+```
+❌ Never run --force on npm audit fix without human approval (can break major APIs)
+❌ Never auto-fix TypeScript errors that require business logic decisions
+❌ Never apply lint fixes to generated test files without human review
+❌ Never "fix" ESLint disable comments — they may be intentional suppressions
+❌ Never mix fix + refactoring in the same run
+```
+
+---
+
+## After /fix — Verify
+
+```bash
+# Verify fixes didn't introduce new errors
+npx tsc --noEmit    # Must be clean
+npm test            # Must still all pass
+npm run lint        # Must be zero errors
+```
+
+If any verification step fails after fixes → report and revert auto-fixes for that file.
+
+---

package/.agent/workflows/generate.md

@@ -60,6 +60,9 @@ Y = write to disk | N = discard | R = revise with feedback
 ❌ Assume environment variables exist (read .env.example first)
 ❌ Use Next.js 14 patterns in a Next.js 15 project (check version!)
 ❌ Use React 18 hooks in a React 19 project (useFormState → useActionState)
+❌ Use framer-motion v6 API in a v12 project (exitBeforeEnter → mode="wait")
+❌ Use raw useEffect for GSAP — always useGSAP from @gsap/react
+❌ Hallucinate LLM model names — verify against provider's current model list
 ```
 
 When unsure: write `// VERIFY: [specific reason]` instead of hallucinating.
@@ -78,13 +81,14 @@ security-auditor   → OWASP vulnerabilities, hardcoded secrets, injection
 
 | Keyword in request | Additional Reviewers |
 |:---|:---|
-| `api`, `route`, `endpoint`, `handler` | `dependency-reviewer` + `type-safety-reviewer` |
-| `sql`, `query`, `database`, `prisma`, `drizzle` | `sql-reviewer` |
-| `component`, `hook`, `react`, `vue`, `jsx` | `frontend-reviewer` + `type-safety-reviewer` |
+| `api`, `route`, `endpoint`, `handler`, `server action` | `dependency-reviewer` + `type-safety-reviewer` |
+| `sql`, `query`, `database`, `prisma`, `drizzle`, `orm` | `sql-reviewer` |
+| `component`, `hook`, `react`, `vue`, `jsx`, `tsx` | `frontend-reviewer` + `type-safety-reviewer` |
+| `animation`, `gsap`, `framer`, `motion`, `scroll` | `frontend-reviewer` + `performance-reviewer` |
 | `test`, `spec`, `vitest`, `jest`, `playwright` | `test-coverage-reviewer` |
 | `slow`, `optimize`, `cache`, `performance`, `bundle` | `performance-reviewer` |
 | `mobile`, `react native`, `expo` | `mobile-reviewer` |
-| `llm`, `openai`, `anthropic`, `gemini`, `embedding` | `ai-code-reviewer` |
+| `llm`, `openai`, `anthropic`, `gemini`, `embedding`, `ai` | `ai-code-reviewer` |
 | `aria`, `wcag`, `a11y`, `accessibility` | `accessibility-reviewer` |
 | `import`, `package`, `npm`, `require` | `dependency-reviewer` |
 
@@ -139,6 +143,7 @@ Write to disk?  Y = approve | N = discard | R = revise with feedback
 | Security-critical code was generated | `/tribunal-full` for maximum coverage |
 | DB queries were generated | `/tribunal-database` |
 | New API routes were generated | `/tribunal-backend` |
+| Animation/motion code generated | `/tribunal-frontend` |
 | Tests need to be written next | `/test` |
 | Something was rejected 3 times | Escalate to human with failure report |
 
@@ -154,4 +159,7 @@ Write to disk?  Y = approve | N = discard | R = revise with feedback
 /generate a Zod schema for email + password + role login input
 /generate a Server Action for creating a product with image upload
 /generate a rate-limited fetch wrapper using @upstash/ratelimit
+/generate a Framer Motion page transition with shared element (layoutId)
+/generate a GSAP ScrollTrigger timeline with useGSAP React hook
+/generate an OpenAI structured output call with Zod schema validation
 ```

package/.agent/workflows/migrate.md

@@ -1,160 +1,160 @@
----
-description: Migration workflow for framework upgrades, dependency bumps, and database migrations. Impact analysis first, expand-and-contract for DB, dependency compatibility matrix before upgrading, rollback tested before deploy.
----
-
-# /migrate — Safe Migration Execution
-
-$ARGUMENTS
-
----
-
-## When to Use /migrate
-
-| Use `/migrate` when... | Use something else when... |
-|:---|:---|
-| Upgrading Next.js major version | Adding a feature → `/enhance` |
-| Upgrading React version | Schema change in existing rows → `/migrate` |
-| Database schema structural change | Simple column add → `/enhance` |
-| Changing auth libraries (next-auth v4 → v5) | Dependency patches → `/fix` |
-| Removing deprecated APIs at scale | |
-
----
-
-## Migration Types
-
-```
-Type A: Framework upgrade (Next.js 14 → 15, React 18 → 19)
-  → Audit breaking changes, update callsites, run Tribunal
-  
-Type B: Dependency major version (Prisma 5 → 6, next-auth 4 → 5)
-  → Check changelog for removed APIs, update all callsites
-  
-Type C: Database schema migration (expand-and-contract)
-  → Always in 3 phases, never destructive in one step
-
-Type D: Auth system migration
-  → Dual-write old + new, staged rollout, never big bang
-```
-
----
-
-## Phase 1 — Impact Analysis
-
-Before any migration:
-
-```bash
-# What uses the old API?
-grep -r "getServerSideProps\|getStaticProps" src/ --include="*.ts"  # Next.js pages/ to app/
-grep -r "getServerSession\|NextAuth" src/ --include="*.ts"          # next-auth v4 to v5
-grep -r "from 'next-auth'" src/ --include="*.ts"                    # Count callsites
-grep -r "prisma\.user\.findOne" src/ --include="*.ts"               # Removed Prisma APIs
-
-# How many files will change?
-# Low risk: < 5 files
-# Medium risk: 5-20 files → plan each file explicitly
-# High risk: > 20 files → automate with codemods, not manual
-```
-
----
-
-## Phase 2 — Breaking Change Inventory
-
-```
-Framework Migration Breaking Changes (Next.js 14 → 15 example):
-□ params and searchParams are now Promises — must await
-□ cookies(), headers(), draftMode() are async — must await
-□ fetch() caching defaults changed (now no-store by default)
-□ Turbopack becomes default dev server (may affect custom configs)
-
-Auth Library Breaking Changes (next-auth v4 → v5):
-□ import { getServerSession } from 'next-auth' → import { auth } from './auth'
-□ Configuration file: pages/api/auth/[...nextauth].ts → auth.ts
-□ SessionProvider import path changed
-□ Callbacks API may have changed
-```
-
----
-
-## Phase 3 — Database Migrate (Expand-and-Contract Pattern)
-
-**NEVER do destructive schema changes in a single step on live data.**
-
-```
-Step 1: EXPAND (add, never remove)
-  - Add new column (nullable)
-  - Add new table
-  - Add new foreign key
-
-Step 2: DUAL-WRITE (write to both old and new)
-  - Application writes to BOTH old_column and new_column
-  - Deploy this code before backfilling
-
-Step 3: BACKFILL (populate new structure)
-  - Fill new_column from old_column in background batches
-  - Verify: SELECT COUNT(*) WHERE new_column IS NULL should = 0
-
-Step 4: READ MIGRATION (switch reads to new)
-  - Application reads from new_column only
-  - Application still writes to both
-
-Step 5: CONTRACT (remove old)
-  - Remove writes to old_column
-  - After 1 deployment cycle → drop old_column
-```
-
----
-
-## Phase 4 — Migration Execution Order
-
-```
-□ Create git branch: git checkout -b migrate/[description]
-□ Run tests BEFORE migration: npm test (establish baseline)
-□ Apply changes in topological order (foundation files first)
-□ Run: npx tsc --noEmit (no type errors introduced)
-□ Run: npm test (all tests still pass)
-□ Run Tribunal on changed files: /tribunal-full
-□ PR review with explicit diff
-□ Deploy to staging before production
-□ Run tests in staging
-□ Human Gate: approve production deployment
-```
-
----
-
-## Phase 5 — Rollback Plan
-
-Before migrating production, document the rollback:
-
-```
-Rollback for code migration:
-  git revert [migration-commit]
-  git push origin main --force-with-lease
-
-Rollback for DB migration:
-  Maintain down.sql for every migration
-  Test rollback script on staging before production migration
-```
-
----
-
-## Migration Guard
-
-```
-❌ Never rename a DB column in a single migration (breaks live app)
-❌ Never DROP a column in the same migration that adds the replacement
-❌ Never migrate production database and application code simultaneously
-❌ Never run a migration without first testing on a restored production backup
-❌ Never skip the backward-compatibility window (keep old code during transition)
-```
-
----
-
-## Usage Examples
-
-```
-/migrate upgrade Next.js 14 to Next.js 15 App Router
-/migrate upgrade from next-auth v4 to v5 auth.js
-/migrate add a phoneNumber field to the users table
-/migrate remove the deprecated legacy_api_key column from users
-/migrate upgrade Prisma 5 to Prisma 6 and update all breaking API calls
-```
+---
+description: Migration workflow for framework upgrades, dependency bumps, and database migrations. Impact analysis first, expand-and-contract for DB, dependency compatibility matrix before upgrading, rollback tested before deploy.
+---
+
+# /migrate — Safe Migration Execution
+
+$ARGUMENTS
+
+---
+
+## When to Use /migrate
+
+|Use `/migrate` when...|Use something else when...|
+|:---|:---|
+|Upgrading Next.js major version|Adding a feature → `/enhance`|
+|Upgrading React version|Schema change in existing rows → `/migrate`|
+|Database schema structural change|Simple column add → `/enhance`|
+|Changing auth libraries (next-auth v4 → v5)|Dependency patches → `/fix`|
+|Removing deprecated APIs at scale||
+
+---
+
+## Migration Types
+
+```
+Type A: Framework upgrade (Next.js 14 → 15, React 18 → 19)
+  → Audit breaking changes, update callsites, run Tribunal
+  
+Type B: Dependency major version (Prisma 5 → 6, next-auth 4 → 5)
+  → Check changelog for removed APIs, update all callsites
+  
+Type C: Database schema migration (expand-and-contract)
+  → Always in 3 phases, never destructive in one step
+
+Type D: Auth system migration
+  → Dual-write old + new, staged rollout, never big bang
+```
+
+---
+
+## Phase 1 — Impact Analysis
+
+Before any migration:
+
+```bash
+# What uses the old API?
+grep -r "getServerSideProps\|getStaticProps" src/ --include="*.ts"  # Next.js pages/ to app/
+grep -r "getServerSession\|NextAuth" src/ --include="*.ts"          # next-auth v4 to v5
+grep -r "from 'next-auth'" src/ --include="*.ts"                    # Count callsites
+grep -r "prisma\.user\.findOne" src/ --include="*.ts"               # Removed Prisma APIs
+
+# How many files will change?
+# Low risk: < 5 files
+# Medium risk: 5-20 files → plan each file explicitly
+# High risk: > 20 files → automate with codemods, not manual
+```
+
+---
+
+## Phase 2 — Breaking Change Inventory
+
+```
+Framework Migration Breaking Changes (Next.js 14 → 15 example):
+□ params and searchParams are now Promises — must await
+□ cookies(), headers(), draftMode() are async — must await
+□ fetch() caching defaults changed (now no-store by default)
+□ Turbopack becomes default dev server (may affect custom configs)
+
+Auth Library Breaking Changes (next-auth v4 → v5):
+□ import { getServerSession } from 'next-auth' → import { auth } from './auth'
+□ Configuration file: pages/api/auth/[...nextauth].ts → auth.ts
+□ SessionProvider import path changed
+□ Callbacks API may have changed
+```
+
+---
+
+## Phase 3 — Database Migrate (Expand-and-Contract Pattern)
+
+**NEVER do destructive schema changes in a single step on live data.**
+
+```
+Step 1: EXPAND (add, never remove)
+  - Add new column (nullable)
+  - Add new table
+  - Add new foreign key
+
+Step 2: DUAL-WRITE (write to both old and new)
+  - Application writes to BOTH old_column and new_column
+  - Deploy this code before backfilling
+
+Step 3: BACKFILL (populate new structure)
+  - Fill new_column from old_column in background batches
+  - Verify: SELECT COUNT(*) WHERE new_column IS NULL should = 0
+
+Step 4: READ MIGRATION (switch reads to new)
+  - Application reads from new_column only
+  - Application still writes to both
+
+Step 5: CONTRACT (remove old)
+  - Remove writes to old_column
+  - After 1 deployment cycle → drop old_column
+```
+
+---
+
+## Phase 4 — Migration Execution Order
+
+```
+□ Create git branch: git checkout -b migrate/[description]
+□ Run tests BEFORE migration: npm test (establish baseline)
+□ Apply changes in topological order (foundation files first)
+□ Run: npx tsc --noEmit (no type errors introduced)
+□ Run: npm test (all tests still pass)
+□ Run Tribunal on changed files: /tribunal-full
+□ PR review with explicit diff
+□ Deploy to staging before production
+□ Run tests in staging
+□ Human Gate: approve production deployment
+```
+
+---
+
+## Phase 5 — Rollback Plan
+
+Before migrating production, document the rollback:
+
+```
+Rollback for code migration:
+  git revert [migration-commit]
+  git push origin main --force-with-lease
+
+Rollback for DB migration:
+  Maintain down.sql for every migration
+  Test rollback script on staging before production migration
+```
+
+---
+
+## Migration Guard
+
+```
+❌ Never rename a DB column in a single migration (breaks live app)
+❌ Never DROP a column in the same migration that adds the replacement
+❌ Never migrate production database and application code simultaneously
+❌ Never run a migration without first testing on a restored production backup
+❌ Never skip the backward-compatibility window (keep old code during transition)
+```
+
+---
+
+## Usage Examples
+
+```
+/migrate upgrade Next.js 14 to Next.js 15 App Router
+/migrate upgrade from next-auth v4 to v5 auth.js
+/migrate add a phoneNumber field to the users table
+/migrate remove the deprecated legacy_api_key column from users
+/migrate upgrade Prisma 5 to Prisma 6 and update all breaking API calls
+```