tribunal-kit 1.0.0 → 2.4.2

package/.agent/workflows/orchestrate.md

@@ -8,7 +8,18 @@ $ARGUMENTS
 
 ---
 
-This command coordinates multiple specialists to solve a problem that requires more than one domain. One agent is not orchestration.
+This command coordinates multiple specialists to solve a problem that requires more than one domain. **One agent is not orchestration.**
+
+---
+
+## When to Use /orchestrate vs Other Commands
+
+| Use `/orchestrate` when... | Use something else when... |
+|---|---|
+| Task requires 3+ domain specialists | Single domain → use the right `/tribunal-*` |
+| Sequential work with review gates between waves | Parallel, independent tasks → `/swarm` |
+| Existing codebase with complex dependencies | Greenfield project → `/create` |
+| Human gates required between every wave | Maximum parallel output → `/swarm` |
 
 ---
 
@@ -30,6 +41,7 @@ This command coordinates multiple specialists to solve a problem that requires m
 | Complete product | `project-planner` + `frontend-specialist` + `backend-specialist` + `devops-engineer` |
 | Security investigation | `security-auditor` + `penetration-tester` + `devops-engineer` |
 | Complex bug | `debugger` + `explorer-agent` + `test-engineer` |
+| New codebase or unknown repo | `explorer-agent` + relevant specialists |
 
 ---
 
@@ -41,7 +53,7 @@ Only two agents are allowed during planning:
 
 ```
 project-planner   → writes docs/PLAN-{slug}.md
-explorer-agent    → (if working in existing code) maps the codebase
+explorer-agent    → (if working in existing code) maps the codebase structure
 ```
 
 No other agent runs. No code is produced.
@@ -56,40 +68,76 @@ Approve to start implementation? (Y / N)
 
 **Phase B does NOT start without a Y.**
 
-### Phase B — Implementation (Parallel)
+### Phase B — Implementation (Manager & Micro-Workers)
 
-After approval, specialists activate:
+After approval, the Orchestrator acts as Manager and dispatches Micro-Workers using **isolated JSON payloads**.
 
 ```
-Foundation tier:  database-architect + security-auditor (run first)
-Core tier:        backend-specialist + frontend-specialist (after foundation)
-Quality tier:     test-engineer + qa-automation-engineer (after core)
+Wave 1:  database-architect + security-auditor (JSON dispatch #1)
+         ↓
+[Wait for completion & Tribunal review]
+         ↓
+Wave 2:  backend-specialist + frontend-specialist (JSON dispatch #2)
+         ↓
+[Wait for completion & Tribunal review]
+         ↓
+Wave 3:  test-engineer (JSON dispatch #3)
+         ↓
+[Wait for completion & Human Gate]
 ```
 
-Each tier's output goes through its Tribunal gate before the next tier begins.
+Workers execute in parallel **within** their wave, but waves execute **sequentially**. Each wave waits for the previous wave's Tribunal gate before proceeding.
 
 ---
 
-## Cross-Agent Context Handoff
+## Hierarchical Context Pruning
+
+When dispatching workers, the Orchestrator MUST use the `dispatch_micro_workers` JSON format.
+
+**Context discipline is strictly enforced:**
+
+```
+❌ Never pass full chat histories to workers
+❌ Never attach every file — attach only files the worker will actually read
+✅ The context_summary injected by the Orchestrator is the ONLY shared context
+✅ Files attached are strictly limited to what's needed for that specific task
+```
+
+**Per-worker context limit:** Excerpt only the relevant function or schema section — never the entire file.
 
-When one agent's output feeds the next:
+---
+
+## Retry Protocol
 
 ```
-The context passed to Agent B must include:
-  "Agent A produced: [result]
-   Build on this. Do not re-derive it."
+Attempt 1  → Worker runs with original parameters
+Attempt 2  → Worker runs with stricter constraints + failure feedback
+Attempt 3  → Worker runs with max constraints + full context dump
+Attempt 4  → HALT. Report to human with full failure history.
 ```
 
-Never let Agent B re-invent what Agent A already established.
+Hard limit: **3 retries per worker**. After 3 failures, escalate — do not silently proceed.
 
 ---
 
 ## Hallucination Guard
 
 - Every agent's output goes through Tribunal before it reaches the user
-- The Human Gate fires before any file is written — the user sees the diff and approves
-- Retry limit: 3 Maker revisions per agent. After 3 failures, stop and report to the user.
-- Per-agent scope is enforced — `frontend-specialist` never writes DB migrations
+- The Human Gate fires before any file is written — user sees the diff and approves
+- Per-agent scope is enforced — `frontend-specialist` **never** writes DB migrations
+- Retry limit: 3 Maker revisions per agent; after 3 failures → stop and report
+- `context_summary` is the only mechanism for sharing context across agents — no full dumps
+
+---
+
+## Cross-Workflow Navigation
+
+| When /orchestrate reveals... | Go to |
+|---|---|
+| Worker keeps failing after 3 retries | `/debug` the isolated worker task |
+| Plan needed before orchestrating | `/plan` first, then run `/orchestrate` against it |
+| Fully parallel independent sub-tasks | `/swarm` is more efficient |
+| Single domain needs specialist audit | Use the domain-specific `/tribunal-*` |
 
 ---
 
@@ -99,4 +147,5 @@ Never let Agent B re-invent what Agent A already established.
 /orchestrate build a complete auth system with JWT and refresh tokens
 /orchestrate review the entire API layer for security issues
 /orchestrate build a multi-tenant SaaS onboarding flow
+/orchestrate analyze this repo and implement all security findings
 ```

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

@@ -0,0 +1,305 @@
+---
+description: Run standardized performance benchmarks including Lighthouse, bundle analysis, and latency checks.
+---
+
+# /performance-benchmarker — Automated Performance Audit
+
+$ARGUMENTS
+
+---
+
+This command runs a comprehensive suite of performance benchmarks against your project and generates a structured report with numerical scores, regression detection, and prioritized actionable fixes.
+
+---
+
+## When to Use
+
+- Before any `/deploy` to catch performance regressions.
+- After adding new dependencies or large features.
+- When user reports "it feels slow" or asks to "check performance".
+- When triggered by `benchmark`, `lighthouse`, `bundle size`, or `latency` keywords.
+
+---
+
+## Pipeline Flow
+
+```
+Request (scope: full / web-vitals / bundle / api)
+    │
+    ▼
+Environment detection — framework, build tool, package manager
+    │
+    ▼
+Tool availability check — lighthouse? build script? dev server?
+    │
+    ▼
+Benchmark execution — run selected checks
+    │
+    ▼
+Score calculation — weighted composite
+    │
+    ▼
+Regression detection — compare against previous baselines (if available)
+    │
+    ▼
+Report — scores, pass/fail, recommendations, fix priority
+```
+
+---
+
+## Benchmark Suite
+
+### 1. Web Vitals (Frontend Performance)
+
+| Metric | Good | Needs Work | Poor | Measurement |
+|---|---|---|---|---|
+| LCP (Largest Contentful Paint) | < 2.5s | 2.5-4.0s | > 4.0s | Lighthouse or `web-vitals` library |
+| INP (Interaction to Next Paint) | < 200ms | 200-500ms | > 500ms | Lab approximation via TBT |
+| CLS (Cumulative Layout Shift) | < 0.1 | 0.1-0.25 | > 0.25 | Layout shift detection |
+| TTFB (Time to First Byte) | < 800ms | 800-1800ms | > 1800ms | Server response timing |
+| FCP (First Contentful Paint) | < 1.8s | 1.8-3.0s | > 3.0s | Lighthouse |
+| Speed Index | < 3.4s | 3.4-5.8s | > 5.8s | Lighthouse |
+
+**How to Run:**
+```bash
+# If lighthouse is available
+npx lighthouse http://localhost:3000 --output json --chrome-flags="--headless"
+
+# If web-vitals is installed, inject into page and measure
+# VERIFY: check if lighthouse-cli is available before running
+```
+
+**Common Fixes by Metric:**
+
+| Metric | Fix | Impact |
+|---|---|---|
+| LCP slow | Preload hero image, use `fetchpriority="high"` | High |
+| LCP slow | Eliminate render-blocking CSS/JS | High |
+| INP slow | Break long tasks > 50ms into smaller chunks | High |
+| INP slow | Use `requestIdleCallback` for non-critical work | Medium |
+| CLS high | Set explicit `width`/`height` on images/embeds | High |
+| CLS high | Use `font-display: swap` + font preload | Medium |
+| TTFB slow | Add caching headers, use CDN | High |
+| TTFB slow | Optimize database queries, add indexes | High |
+| FCP slow | Inline critical CSS, defer non-critical | High |
+
+### 2. Bundle Analysis (JavaScript/CSS)
+
+| Check | Target | Warning | Fail | Tool |
+|---|---|---|---|---|
+| Total JS (gzipped) | < 100KB | 100-200KB | > 200KB | Build output |
+| Largest chunk (gzipped) | < 50KB | 50-100KB | > 100KB | Build output |
+| CSS total | < 50KB | 50-100KB | > 100KB | Build output |
+| Unused CSS | < 5% | 5-15% | > 15% | PurgeCSS |
+| Duplicate packages | 0 | 1-2 | > 2 | Bundle analyzer |
+| Tree-shaking | No side-effect barrel exports | — | Side-effect imports found | Manual analysis |
+
+**How to Run:**
+```bash
+# Build and analyze
+npm run build -- --stats
+# VERIFY: check if the build script supports --stats flag
+
+# Alternative: analyze existing build output
+npx source-map-explorer dist/**/*.js
+# VERIFY: check if source-map-explorer is available
+```
+
+**Common Fixes:**
+
+| Issue | Fix | Savings |
+|---|---|---|
+| Large lodash import | `import debounce from 'lodash/debounce'` not `import { debounce } from 'lodash'` | 50-80KB |
+| Moment.js | Replace with `dayjs` or `date-fns` | 60-70KB |
+| Full icon library | Use tree-shakeable imports or individual icon files | 20-100KB |
+| Uncompressed images | Use WebP/AVIF, add `loading="lazy"` | 50-500KB |
+| CSS framework unused | PurgeCSS or `content` config in Tailwind | 30-90KB |
+
+### 3. API Latency (Backend Performance)
+
+| Check | Target | Warning | Fail | Method |
+|---|---|---|---|---|
+| Avg response (simple GET) | < 100ms | 100-300ms | > 300ms | 10 sequential requests |
+| Avg response (complex query) | < 300ms | 300-800ms | > 800ms | 10 sequential requests |
+| P95 response | < 500ms | 500-1000ms | > 1000ms | Sort, pick 95th percentile |
+| P99 response | < 1000ms | 1-3s | > 3s | Sort, pick 99th percentile |
+| Cold start | < 1s | 1-3s | > 3s | First request after 30s idle |
+| Concurrent handling | Linear scaling up to 10 req | — | Exponential degradation | 10 parallel requests |
+
+**How to Run:**
+```bash
+# Using curl timing
+curl -o /dev/null -s -w "time_total: %{time_total}s\n" http://localhost:3000/api/health
+
+# Loop for average
+for i in $(seq 1 10); do
+  curl -o /dev/null -s -w "%{time_total}\n" http://localhost:3000/api/endpoint
+done
+```
+
+**Common Fixes:**
+
+| Symptom | Likely Cause | Fix |
+|---|---|---|
+| Slow first request | Cold start, no connection pool | Pre-warm, use connection pooling |
+| Slow list endpoints | N+1 queries | Add eager loading / `include` |
+| Slow under load | No caching | Add Redis/in-memory cache for hot paths |
+| Inconsistent P95 | GC pauses | Optimize memory allocation, reduce object churn |
+
+### 4. Build Performance (DX)
+
+| Check | Target | Warning | Fail |
+|---|---|---|---|
+| Dev server cold start | < 3s | 3-8s | > 8s |
+| Hot reload (HMR) | < 200ms | 200-500ms | > 500ms |
+| Full production build | < 30s | 30-60s | > 60s |
+| TypeScript type-check | < 15s | 15-30s | > 30s |
+
+---
+
+## Composite Score
+
+```
+Performance Score = (
+  Web_Vitals_Score × 0.35 +
+  Bundle_Score     × 0.25 +
+  API_Score        × 0.25 +
+  Build_Score      × 0.15
+) × 100
+
+Grade:
+  90-100  →  A  (Ship with confidence)
+  75-89   →  B  (Minor optimizations available)
+  60-74   →  C  (Notable performance issues)
+  40-59   →  D  (Significant problems — fix before deploy)
+  < 40    →  F  (Critical — likely impacts user retention)
+```
+
+Each sub-score is calculated as: `(checks_passed / total_checks)` weighted by target (1.0), warning (0.6), fail (0.0).
+
+---
+
+## Output Format
+
+```
+━━━ Performance Benchmark Report ━━━━━━━━━
+
+Project:  [name]
+Date:     [timestamp]
+Score:    [0-100] / 100 → Grade [A-F]
+
+━━━ Web Vitals ━━━━━━━━━━━━━━━━━━━━━━━━━
+
+LCP:    1.8s  ✅ Good    (target: < 2.5s)
+INP:    95ms  ✅ Good    (target: < 200ms)
+CLS:    0.05  ✅ Good    (target: < 0.1)
+TTFB:   420ms ✅ Good    (target: < 800ms)
+FCP:    1.2s  ✅ Good    (target: < 1.8s)
+Score:  92/100
+
+━━━ Bundle ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Total JS:      156KB gzipped  🟡 Warning  (target: < 100KB)
+Largest chunk:  82KB gzipped  🟡 Warning  (target: < 50KB)
+CSS total:      28KB gzipped  ✅ Good
+Unused CSS:    4.2%           ✅ Good
+Duplicates:    0              ✅ Good
+Score: 72/100
+
+━━━ API Latency ━━━━━━━━━━━━━━━━━━━━━━━━
+
+GET /api/users:     avg 89ms  ✅  |  p95 142ms  ✅
+POST /api/auth:     avg 210ms 🟡  |  p95 480ms  🟡
+GET /api/dashboard: avg 340ms ❌  |  p95 820ms  ❌
+Cold start:         680ms     ✅
+Score: 58/100
+
+━━━ Build ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Dev cold start:   2.1s  ✅
+HMR:              89ms  ✅
+Production build: 18s   ✅
+Type-check:       12s   ✅
+Score: 100/100
+
+━━━ Fix Priority (by impact) ━━━━━━━━━━━
+
+1. 🔴 GET /api/dashboard avg 340ms
+   → Add database index on dashboard query joins
+   → Expected: < 100ms (70% improvement)
+
+2. 🟡 Total JS 156KB
+   → Lazy-load chart library (80KB)
+   → Expected: < 80KB initial (50% reduction)
+
+3. 🟡 POST /api/auth avg 210ms
+   → Cache user lookup in auth flow
+   → Expected: < 100ms (50% improvement)
+
+━━━ Trend (if baseline available) ━━━━━━
+
+LCP:    1.8s → 1.8s  → (no change)
+Bundle: 140KB → 156KB ↑ (+11%) ⚠️ Regression
+API p95: 400ms → 480ms ↑ (+20%) ⚠️ Regression
+```
+
+---
+
+## Regression Detection
+
+If a previous benchmark baseline exists (stored in `perf-baseline.json` or similar):
+
+| Metric | Change | Status |
+|---|---|---|
+| < 5% increase | No change | ✅ Stable |
+| 5-15% increase | Minor regression | 🟡 Flag |
+| > 15% increase | Significant regression | 🔴 Block deploy |
+| Any decrease | Improvement | 🎉 Celebrate |
+
+---
+
+## Baseline Management
+
+After a successful benchmark, save a baseline to detect future regressions:
+
+```bash
+# Save current benchmark as baseline
+python .agent/scripts/bundle_analyzer.py . --save-baseline
+```
+
+The baseline file is `perf-baseline.json` in the project root. Check it into version control so regressions are caught in CI.
+
+---
+
+## Cross-Workflow Navigation
+
+| After /performance-benchmarker shows... | Go to |
+|---|---|
+| Grade D or F | `/tribunal-performance` on the slowest code paths |
+| Bundle regression (+15%) | `/audit` for dependency analysis, then `/fix` |
+| API latency P95 > 500ms | `/debug` to identify the slow query or operation |
+| Web vitals LCP > 4s | `/enhance` to add image preloading and critical CSS |
+| Grade A or B, ready for deploy | `/deploy` following pre-flight checklist |
+
+---
+
+## Hallucination Guard
+
+- **Only run benchmarks with installed tools** — check with `which` or `npx --dry-run` first.
+- **Never fabricate benchmark numbers** — report "SKIPPED: [tool] not installed" if unavailable.
+- **Flag anomalies**: `// NOTE: unusually fast — may be cached` or `// NOTE: first run, cold start included`.
+- **Mark tool availability**: `// VERIFY: lighthouse-cli not detected, using fallback estimation`.
+- **Don't guess fixes** — only recommend fixes for issues that have measured evidence.
+
+---
+
+## Usage
+
+```
+/performance-benchmarker full audit
+/performance-benchmarker web vitals only
+/performance-benchmarker bundle analysis
+/performance-benchmarker api latency for /api/users /api/posts
+/performance-benchmarker build performance
+/performance-benchmarker compare with baseline
+```

package/.agent/workflows/plan.md

@@ -1,5 +1,5 @@
 ---
-description: Create project plan using project-planner agent. No code writing - only plan file generation.
+description: Create project plan using project-planner agent. No code writing — only plan file generation.
 ---
 
 # /plan — Write the Plan First
@@ -8,7 +8,18 @@ $ARGUMENTS
 
 ---
 
-This command produces one thing: a structured plan file. Nothing is implemented. No code is written. The plan is the output.
+This command produces one thing: **a structured plan file**. Nothing is implemented. No code is written. The plan is the output.
+
+---
+
+## When to Use /plan vs Other Commands
+
+| Use `/plan` when... | Use something else when... |
+|---|---|
+| Requirements are unclear or large | You already know what to build → `/create` |
+| Multi-agent work needs coordination | Single function needed → `/generate` |
+| You want written scope agreement before coding | Ready to build immediately → `/create` |
+| Stakeholder review is needed before work starts | Just a quick discussion → ask directly |
 
 ---
 
@@ -23,38 +34,34 @@ This command produces one thing: a structured plan file. Nothing is implemented.
 
 ### Gate: Clarify Before You Plan
 
-The `project-planner` agent asks:
+The `project-planner` agent asks — and gets answers to — these four questions before writing a single line of the plan:
 
 ```
-What outcome needs to exist that doesn't exist today?
-What are the hard constraints? (stack, existing code, deadline)
-What's explicitly not being built in this version?
-How will we confirm it's done?
+1. What outcome needs to exist that doesn't exist today?
+2. What are the hard constraints? (stack, existing code, deadline)
+3. What's explicitly not being built in this version?
+4. How will we confirm it's done? (observable done condition)
 ```
 
-If any answer is "I don't know" — those are clarified before the plan is written, not after.
-
-### Plan File Creation
+If any answer is "I don't know" — those are clarified **before** the plan is written, not after.
 
-```
-Location: docs/PLAN-{task-slug}.md
+> ⚠️ An unclear "done condition" is the most common cause of scope creep. It must be specific and observable.
 
-Slug naming:
-  Pull 2–3 key words from the request
-  Lowercase + hyphens
-  Max 30 characters
-  "build auth with JWT" → PLAN-auth-jwt.md
-  "shopping cart checkout" → PLAN-cart-checkout.md
-```
+---
 
-### After the File is Written
+### Plan File Creation
 
 ```
-✅ Plan written: docs/PLAN-{slug}.md
+Location: docs/PLAN-{task-slug}.md
 
-Review it, then:
-  Run /create to begin implementation
-  Or edit the file to refine scope first
+Slug naming rules:
+  - Pull 2–3 key words from the request
+  - Lowercase + hyphens
+  - Max 30 characters
+  Examples:
+    "build auth with JWT"       → PLAN-auth-jwt.md
+    "shopping cart checkout"    → PLAN-cart-checkout.md
+    "multi-tenant user roles"   → PLAN-user-roles.md
 ```
 
 ---
@@ -65,37 +72,71 @@ Review it, then:
 # Plan: [Feature Name]
 
 ## What Done Looks Like
-[Observable outcome — one sentence]
+[Observable outcome — one specific, testable sentence]
 
 ## Won't Include in This Version
-- [Explicit exclusion]
+- [Explicit exclusion 1]
+- [Explicit exclusion 2]
 
 ## Unresolved Questions
-- [Thing that needs external confirmation: VERIFY]
+- [Item needing external confirmation: VERIFY]
 
 ## Estimates (Ranges + Confidence)
-All time estimates include: optimistic / realistic / pessimistic + confidence level
+| Task | Optimistic | Realistic | Pessimistic | Confidence |
+|------|-----------|-----------|-------------|------------|
+| DB schema | 30min | 1h | 2h | High |
+| API layer | 2h | 4h | 8h | Medium |
+| Frontend | 3h | 6h | 12h | Low |
 
 ## Task Table
 | # | Task | Agent | Depends on | Done when |
-|---|------|-------|-----------|-----------|
-| 1 | ... | database-architect | none | migration runs |
-| 2 | ... | backend-specialist | #1 | returns 201 |
+|---|------|-------|-----------|-----------| 
+| 1 | DB schema | database-architect | none | migration runs |
+| 2 | API routes | backend-specialist | #1 | returns 201 |
+| 3 | Frontend component | frontend-specialist | #2 | renders without errors |
+| 4 | Tests | test-engineer | #2 | all specs pass |
 
 ## Review Gates
 | Task | Tribunal |
 |---|---|
 | #1 schema | /tribunal-database |
 | #2 API | /tribunal-backend |
+| #3 UI | /tribunal-frontend |
+| #4 tests | test-coverage-reviewer |
+```
+
+---
+
+### After the File is Written
+
+```
+✅ Plan written: docs/PLAN-{slug}.md
+
+Review it, then:
+  /create    → Begin full implementation (uses this plan)
+  /generate  → Implement a single task from the table
+  /orchestrate → Coordinate all agents across the full plan
 ```
 
 ---
 
 ## Hallucination Guard
 
-- Every tool/library mentioned in the plan must be real and verified
-- All time estimates are ranges with a confidence label — never single-point guarantees
+- Every tool, library, or API mentioned in the plan must be **real and verified** before being listed
+- Time estimates are **ranges with confidence labels** — never single-point guarantees
 - External dependencies that aren't confirmed get a `[VERIFY: check this exists]` tag
+- The done condition is **observable and specific** — "it works" is not a done condition
+
+---
+
+## Cross-Workflow Navigation
+
+| After /plan produces the file... | Go to |
+|---|---|
+| Ready to build the full plan | `/create` reads the plan and starts building |
+| Need a single task implemented | `/generate [task description]` |
+| Multi-agent coordination needed | `/orchestrate` to run the plan as a managed build |
+| Need to review existing code first | `explorer-agent` before committing to the plan |
 
 ---
 
@@ -105,4 +146,6 @@ All time estimates include: optimistic / realistic / pessimistic + confidence le
 /plan REST API with user auth
 /plan dark mode toggle for the settings page
 /plan multi-tenant account switching
+/plan event-driven notification system with queues
+/plan admin dashboard with user management and analytics
 ```