tribunal-kit 3.0.0 → 4.0.0

package/.agent/workflows/orchestrate.md

@@ -1,168 +1,168 @@
----
-description: Coordinate multiple agents for complex tasks. Use for multi-perspective analysis, comprehensive reviews requiring different domain expertise, or tasks where a single agent would miss domain-specific failures. Fan-Out dispatch → parallel execution → Fan-In synthesis → Human Gate.
----
-
-# /orchestrate — Multi-Agent Coordination
-
-$ARGUMENTS
-
----
-
-## When to Use /orchestrate
-
-| Use `/orchestrate` when... | Use something else when... |
-|:---|:---|
-| Task spans 2+ technical domains | Single domain → use specialist directly |
-| Multi-perspective review is needed | Simple code generation → `/generate` |
-| Fan-out parallelism would save time | Debugging → `/debug` (sequential by nature) |
-| One agent would miss domain failures | Planning only → `/plan` |
-
----
-
-## Phase 1 — Scope Classification
-
-Before dispatching workers:
-
-```
-1. Is this actually multi-domain? (2+ distinct technical areas)
-   → YES → proceed to Phase 2
-   → NO  → route to the single correct specialist agent
-
-2. Can tasks be parallelized (no dependencies between them)?
-   → YES → Fan-Out dispatch (all workers simultaneous)
-   → NO  → Sequential wave dispatch
-   
-3. Context budget check:
-   □ How many files does each worker need?
-   □ Total context across all workers manageable?
-   □ Can I pass context_summary instead of full file dumps?
-```
-
----
-
-## Phase 2 — Worker Decomposition
-
-Break the goal into atomic, non-overlapping worker tasks:
-
-```
-Goal: Review the full checkout feature before launch
-
-Decomposed Workers:
-├── Worker A [backend-specialist]: Review API routes for auth and validation
-├── Worker B [database-architect]: Review DB queries for N+1 and transactions
-├── Worker C [frontend-specialist]: Review UI components for RSC compliance
-└── Worker D [security-auditor]: Review the full checkout flow for OWASP issues
-```
-
-**Worker files cannot overlap.** If two workers both need to modify the same file → one worker owns it.
-
----
-
-## Fan-Out Pattern (Parallel Dispatch)
-
-When tasks are independent, dispatch all simultaneously:
-
-```
-━━━ Wave 1: Fan-Out ━━━━━━━━━━━━━━━━━━━━━━━
-Worker A (backend)    → RUNNING  (reading: src/app/api/checkout/)
-Worker B (database)   → RUNNING  (reading: prisma/schema.prisma, checkout queries)
-Worker C (frontend)   → RUNNING  (reading: src/app/checkout/page.tsx)
-Worker D (security)   → RUNNING  (reading: all of the above)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Wait for ALL workers (allSettled — single worker failure doesn't cancel siblings)
-
-━━━ Wave 1: Results ━━━━━━━━━━━━━━━━━━━━━━━
-Worker A: ✅ COMPLETE
-Worker B: ✅ COMPLETE
-Worker C: ⚠️ BLOCKED (missing: what state management pattern to assume)
-Worker D: ✅ COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Supervisor provides missing info to Worker C → redispatch
-```
-
----
-
-## BLOCKED Worker Protocol
-
-When a worker cannot proceed:
-
-```
-Status: BLOCKED
-Reason: Missing context — the auth middleware file is not in provided scope
-Unblocked by: Read src/middleware.ts first and pass auth pattern to worker
-
-Supervisor action:
-1. Provide the missing context if available
-2. Escalate to human if decision is needed
-3. Never guess — BLOCKED beats hallucinating
-```
-
----
-
-## Sequential Wave Execution
-
-When tasks depend on each other:
-
-```
-Wave 1 → Foundation (must complete first)
-Wave 2 → Depends on Wave 1 output (receives context_summary, not full output)
-Wave 3 → Synthesis (combines all wave outputs)
-```
-
-**Context discipline between waves:** Summarize Wave N output in 3-5 bullets before passing to Wave N+1.
-
----
-
-## Fan-In — Synthesis
-
-After all workers complete:
-
-```
-1. Merge findings by severity
-2. Identify conflicts (Worker A says X, Worker B says Y)
-3. Resolve conflicts with evidence (which worker has specific file evidence?)
-4. Produce unified output sorted by priority
-```
-
----
-
-## Human Gate
-
-```
-━━━ Orchestration Complete ━━━━━━━━━━━━━━━━━
-
-Workers: 4 dispatched / 4 complete / 0 blocked
-
-━━━ Synthesized Findings ━━━━━━━━━━━━━━━━━━
-[Critical issues first, then high, then medium]
-
-━━━ Required Changes ━━━━━━━━━━━━━━━━━━━━━
-Files to modify: [list]
-Files to create: [list]
-
-━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Approve?  Y = proceed | N = discard | R = revise
-```
-
----
-
-## Error Recovery
-
-```
-Worker failure (after 3 retries):
-  Report: agent=[name], task=[what], attempts=3, last_error=[error], suggestion=[what to check]
-  Action: continue remaining workers, include failure in final synthesis
-```
-
----
-
-## Usage Examples
-
-```
-/orchestrate review the entire authentication system for security and correctness
-/orchestrate analyze the payment feature: backend logic + DB queries + frontend UX
-/orchestrate comprehensive code review before launch: security + tests + performance
-/orchestrate compare three different caching strategies and recommend the best fit
-```
+---
+description: Coordinate multiple agents for complex tasks. Use for multi-perspective analysis, comprehensive reviews requiring different domain expertise, or tasks where a single agent would miss domain-specific failures. Fan-Out dispatch → parallel execution → Fan-In synthesis → Human Gate.
+---
+
+# /orchestrate — Multi-Agent Coordination
+
+$ARGUMENTS
+
+---
+
+## When to Use /orchestrate
+
+|Use `/orchestrate` when...|Use something else when...|
+|:---|:---|
+|Task spans 2+ technical domains|Single domain → use specialist directly|
+|Multi-perspective review is needed|Simple code generation → `/generate`|
+|Fan-out parallelism would save time|Debugging → `/debug` (sequential by nature)|
+|One agent would miss domain failures|Planning only → `/plan`|
+
+---
+
+## Phase 1 — Scope Classification
+
+Before dispatching workers:
+
+```
+1. Is this actually multi-domain? (2+ distinct technical areas)
+   → YES → proceed to Phase 2
+   → NO  → route to the single correct specialist agent
+
+2. Can tasks be parallelized (no dependencies between them)?
+   → YES → Fan-Out dispatch (all workers simultaneous)
+   → NO  → Sequential wave dispatch
+   
+3. Context budget check:
+   □ How many files does each worker need?
+   □ Total context across all workers manageable?
+   □ Can I pass context_summary instead of full file dumps?
+```
+
+---
+
+## Phase 2 — Worker Decomposition
+
+Break the goal into atomic, non-overlapping worker tasks:
+
+```
+Goal: Review the full checkout feature before launch
+
+Decomposed Workers:
+├── Worker A [backend-specialist]: Review API routes for auth and validation
+├── Worker B [database-architect]: Review DB queries for N+1 and transactions
+├── Worker C [frontend-specialist]: Review UI components for RSC compliance
+└── Worker D [security-auditor]: Review the full checkout flow for OWASP issues
+```
+
+**Worker files cannot overlap.** If two workers both need to modify the same file → one worker owns it.
+
+---
+
+## Fan-Out Pattern (Parallel Dispatch)
+
+When tasks are independent, dispatch all simultaneously:
+
+```
+━━━ Wave 1: Fan-Out ━━━━━━━━━━━━━━━━━━━━━━━
+Worker A (backend)    → RUNNING  (reading: src/app/api/checkout/)
+Worker B (database)   → RUNNING  (reading: prisma/schema.prisma, checkout queries)
+Worker C (frontend)   → RUNNING  (reading: src/app/checkout/page.tsx)
+Worker D (security)   → RUNNING  (reading: all of the above)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Wait for ALL workers (allSettled — single worker failure doesn't cancel siblings)
+
+━━━ Wave 1: Results ━━━━━━━━━━━━━━━━━━━━━━━
+Worker A: ✅ COMPLETE
+Worker B: ✅ COMPLETE
+Worker C: ⚠️ BLOCKED (missing: what state management pattern to assume)
+Worker D: ✅ COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Supervisor provides missing info to Worker C → redispatch
+```
+
+---
+
+## BLOCKED Worker Protocol
+
+When a worker cannot proceed:
+
+```
+Status: BLOCKED
+Reason: Missing context — the auth middleware file is not in provided scope
+Unblocked by: Read src/middleware.ts first and pass auth pattern to worker
+
+Supervisor action:
+1. Provide the missing context if available
+2. Escalate to human if decision is needed
+3. Never guess — BLOCKED beats hallucinating
+```
+
+---
+
+## Sequential Wave Execution
+
+When tasks depend on each other:
+
+```
+Wave 1 → Foundation (must complete first)
+Wave 2 → Depends on Wave 1 output (receives context_summary, not full output)
+Wave 3 → Synthesis (combines all wave outputs)
+```
+
+**Context discipline between waves:** Summarize Wave N output in 3-5 bullets before passing to Wave N+1.
+
+---
+
+## Fan-In — Synthesis
+
+After all workers complete:
+
+```
+1. Merge findings by severity
+2. Identify conflicts (Worker A says X, Worker B says Y)
+3. Resolve conflicts with evidence (which worker has specific file evidence?)
+4. Produce unified output sorted by priority
+```
+
+---
+
+## Human Gate
+
+```
+━━━ Orchestration Complete ━━━━━━━━━━━━━━━━━
+
+Workers: 4 dispatched / 4 complete / 0 blocked
+
+━━━ Synthesized Findings ━━━━━━━━━━━━━━━━━━
+[Critical issues first, then high, then medium]
+
+━━━ Required Changes ━━━━━━━━━━━━━━━━━━━━━
+Files to modify: [list]
+Files to create: [list]
+
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Approve?  Y = proceed | N = discard | R = revise
+```
+
+---
+
+## Error Recovery
+
+```
+Worker failure (after 3 retries):
+  Report: agent=[name], task=[what], attempts=3, last_error=[error], suggestion=[what to check]
+  Action: continue remaining workers, include failure in final synthesis
+```
+
+---
+
+## Usage Examples
+
+```
+/orchestrate review the entire authentication system for security and correctness
+/orchestrate analyze the payment feature: backend logic + DB queries + frontend UX
+/orchestrate comprehensive code review before launch: security + tests + performance
+/orchestrate compare three different caching strategies and recommend the best fit
+```

package/.agent/workflows/performance-benchmarker.md

@@ -1,123 +1,114 @@
----
-description: Run standardized performance benchmarks including Lighthouse CI, bundle analysis, and API latency checks. Records before/after metrics. No optimization claims without measured evidence.
----
-
-# /performance-benchmarker — Evidence-Based Performance Measurement
-
-$ARGUMENTS
-
----
-
-## When to Use /performance-benchmarker
-
-| Use `/performance-benchmarker` when... | Use something else when... |
-|:---|:---|
-| Establishing performance baseline | Code optimization decisions → `/tribunal-performance` |
-| After optimization — verify improvement | Memory leaks investigation → `/debug` |
-| Pre-release performance gate | Bundle analysis only → run ANALYZE=true npm run build |
-| Regular weekly benchmark | API review only → `/tribunal-backend` |
-
----
-
-## Benchmark Suite (Run in Order)
-
-```bash
-# 1. Lighthouse CI — Core Web Vitals
-npx lighthouse http://localhost:3000 \
-  --output=json \
-  --output-path=./reports/lighthouse-$(date +%Y%m%d).json \
-  --only-categories=performance,accessibility,best-practices,seo
-
-# 2. Bundle Analysis
-ANALYZE=true npm run build
-
-# 3. API latency (using autocannon for load test)
-npx autocannon -c 10 -d 20 http://localhost:3000/api/products
-# -c: 10 concurrent connections
-# -d: 20 second duration
-
-# 4. Database query analysis
-# (Prisma): Add to your test route temporarily
-const plan = await prisma.$queryRaw`EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = ${userId}`;
-console.log(plan);
-```
-
----
-
-## Benchmark Report Format
-
-```
-━━━ Performance Benchmark — [date] ━━━━━━━━━
-
-━━━ Core Web Vitals (Lighthouse) ━━━━━━━━━━
-LCP:  [time]   [✅ Good | ⚠️ Needs Work | ❌ Poor]
-INP:  [time]   [✅ Good | ⚠️ Needs Work | ❌ Poor]
-CLS:  [score]  [✅ Good | ⚠️ Needs Work | ❌ Poor]
-FCP:  [time]
-TTFB: [time]
-
-Performance Score: [N]/100
-
-━━━ Bundle Sizes ━━━━━━━━━━━━━━━━━━━━━━━━━
-First Load JS (shared): [size]
-Largest page:           [size] ([route])
-Largest 3 bundles:
-  [bundle]: [size]
-  [bundle]: [size]
-  [bundle]: [size]
-
-━━━ API Latency (10 concurrent, 20s) ━━━━━━
-GET /api/products: avg [ms] | p99 [ms] | [req/s] req/s
-POST /api/orders:  avg [ms] | p99 [ms]
-
-━━━ Comparison (vs last run) ━━━━━━━━━━━━━━
-LCP:    4.2s → 1.9s  ▼ IMPROVED ✅
-INP:    480ms → 140ms ▼ IMPROVED ✅
-Bundle: 890kb → 310kb ▼ IMPROVED ✅
-p99 latency: 230ms → 89ms ▼ IMPROVED ✅
-```
-
----
-
-## Performance Gates (Fail Criteria)
-
-```
-Failing these means optimization is blocking — not optional:
-
-LCP   > 4.0s     → ❌ Must fix — users see blank page
-INP   > 500ms    → ❌ Must fix — UI feels unresponsive
-CLS   > 0.25     → ❌ Must fix — layout jumps are jarring
-Bundle > 1mb     → ❌ Must fix — 3G users abandon
-p99 API > 2000ms → ❌ Must fix — timeout risk on slow connections
-
-Warning range (fix before major release):
-LCP   2.5–4.0s  → ⚠️
-INP   200–500ms → ⚠️
-Bundle 500kb–1mb → ⚠️
-```
-
----
-
-## Historical Tracking
-
-Save every benchmark run:
-
-```bash
-# Benchmarks should be saved with date stamps
-./reports/lighthouse-2026-04-02.json
-./reports/bundle-2026-04-02.txt
-./reports/latency-2026-04-02.txt
-```
-
-This enables trend analysis: is performance improving or degrading over time?
-
----
-
-## Cross-Workflow Navigation
-
-| Benchmark shows... | Go to |
-|:---|:---|
-| LCP or INP failing | `/tribunal-performance` for optimization |
-| Bundle too large | `/enhance` to add dynamic imports |
-| API latency high | `/tribunal-backend` + check `/tribunal-database` for N+1 |
-| After optimization | Re-run `/performance-benchmarker` to verify |
+---
+description: Run standardized performance benchmarks including Lighthouse CI, bundle analysis, and API latency checks. Records before/after metrics. No optimization claims without measured evidence.
+---
+
+# /performance-benchmarker — Evidence-Based Performance Measurement
+
+$ARGUMENTS
+
+---
+
+## When to Use /performance-benchmarker
+
+|Use `/performance-benchmarker` when...|Use something else when...|
+|:---|:---|
+|Establishing performance baseline|Code optimization decisions → `/tribunal-performance`|
+|After optimization — verify improvement|Memory leaks investigation → `/debug`|
+|Pre-release performance gate|Bundle analysis only → run ANALYZE=true npm run build|
+|Regular weekly benchmark|API review only → `/tribunal-backend`|
+
+---
+
+## Benchmark Suite (Run in Order)
+
+```bash
+# 1. Lighthouse CI — Core Web Vitals
+npx lighthouse http://localhost:3000 \
+  --output=json \
+  --output-path=./reports/lighthouse-$(date +%Y%m%d).json \
+  --only-categories=performance,accessibility,best-practices,seo
+
+# 2. Bundle Analysis
+ANALYZE=true npm run build
+
+# 3. API latency (using autocannon for load test)
+npx autocannon -c 10 -d 20 http://localhost:3000/api/products
+# -c: 10 concurrent connections
+# -d: 20 second duration
+
+# 4. Database query analysis
+# (Prisma): Add to your test route temporarily
+const plan = await prisma.$queryRaw`EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = ${userId}`;
+console.log(plan);
+```
+
+---
+
+## Benchmark Report Format
+
+```
+━━━ Performance Benchmark — [date] ━━━━━━━━━
+
+━━━ Core Web Vitals (Lighthouse) ━━━━━━━━━━
+LCP:  [time]   [✅ Good | ⚠️ Needs Work | ❌ Poor]
+INP:  [time]   [✅ Good | ⚠️ Needs Work | ❌ Poor]
+CLS:  [score]  [✅ Good | ⚠️ Needs Work | ❌ Poor]
+FCP:  [time]
+TTFB: [time]
+
+Performance Score: [N]/100
+
+━━━ Bundle Sizes ━━━━━━━━━━━━━━━━━━━━━━━━━
+First Load JS (shared): [size]
+Largest page:           [size] ([route])
+Largest 3 bundles:
+  [bundle]: [size]
+  [bundle]: [size]
+  [bundle]: [size]
+
+━━━ API Latency (10 concurrent, 20s) ━━━━━━
+GET /api/products: avg [ms] | p99 [ms] | [req/s] req/s
+POST /api/orders:  avg [ms] | p99 [ms]
+
+━━━ Comparison (vs last run) ━━━━━━━━━━━━━━
+LCP:    4.2s → 1.9s  ▼ IMPROVED ✅
+INP:    480ms → 140ms ▼ IMPROVED ✅
+Bundle: 890kb → 310kb ▼ IMPROVED ✅
+p99 latency: 230ms → 89ms ▼ IMPROVED ✅
+```
+
+---
+
+## Performance Gates (Fail Criteria)
+
+```
+Failing these means optimization is blocking — not optional:
+
+LCP   > 4.0s     → ❌ Must fix — users see blank page
+INP   > 500ms    → ❌ Must fix — UI feels unresponsive
+CLS   > 0.25     → ❌ Must fix — layout jumps are jarring
+Bundle > 1mb     → ❌ Must fix — 3G users abandon
+p99 API > 2000ms → ❌ Must fix — timeout risk on slow connections
+
+Warning range (fix before major release):
+LCP   2.5–4.0s  → ⚠️
+INP   200–500ms → ⚠️
+Bundle 500kb–1mb → ⚠️
+```
+
+---
+
+## Historical Tracking
+
+Save every benchmark run:
+
+```bash
+# Benchmarks should be saved with date stamps
+./reports/lighthouse-2026-04-02.json
+./reports/bundle-2026-04-02.txt
+./reports/latency-2026-04-02.txt
+```
+
+This enables trend analysis: is performance improving or degrading over time?
+
+---