tribunal-kit 4.5.0 → 4.6.0

package/.agent/workflows/orchestrate.md

@@ -1,168 +1,192 @@
----
-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.
+required-skills: agent-organizer, parallel-agents
+---
+
+# /orchestrate — Multi-Agent Coordination
+
+$ARGUMENTS
+
+---
+
+## $CONTEXT_REQUIRED
+
+```
+Read BEFORE orchestrating:
+□ Target scope                → Identify the boundaries of the review/task
+□ Agent list                  → Determine which specialist agents are needed
+□ Context budget              → Determine how to split files among agents
+```
+
+---
+
+## 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
+```
+
+---
+
+## After /orchestrate — Next Steps
+
+| Outcome                         | Next Command                                |
+| :------------------------------ | :------------------------------------------ |
+| Review reveals multiple issues  | → Route to specific `/tribunal-*` or `/fix` |
+| Analysis points to architecture | → `/plan` to formalize the changes          |
+| Analysis needs more data        | → `/performance-benchmarker` or `/debug`    |
+
+---

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

@@ -1,114 +1,135 @@
----
-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?
-
----
+---
+description: Run standardized performance benchmarks including Lighthouse CI, bundle analysis, and API latency checks. Records before/after metrics. No optimization claims without measured evidence.
+required-skills: performance-profiling, vitals-reviewer
+---
+
+# /performance-benchmarker — Evidence-Based Performance Measurement
+
+$ARGUMENTS
+
+---
+
+## $CONTEXT_REQUIRED
+
+```
+Read BEFORE benchmarking:
+□ package.json                → Identify build/start scripts and profiling tools
+□ Application URL             → Verify the local URL and port
+□ Database connection          → Verify if DB profiling is supported
+```
+
+---
+
+## 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?
+
+---
+
+## After /performance-benchmarker — Next Steps
+
+| Outcome                          | Next Command                                            |
+| :------------------------------- | :------------------------------------------------------ |
+| Performance passes all gates     | → `/deploy` or return to development                    |
+| Performance degrades/fails gates | → `/tribunal-speed` to optimize the specific bottleneck |
+
+---