tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/parallel-agents/SKILL.md

@@ -1,181 +1,88 @@
 ---
 name: parallel-agents
-description: Multi-agent orchestration patterns. Use when multiple independent tasks can run with different domain expertise or when comprehensive analysis requires multiple perspectives.
+description: Parallel processing coordination for multi-agent swarms. Asynchronous dispatches, merging divergent logic streams, race conditions in autonomous agents, avoiding Git conflicts in concurrent generation, and fan-out/fan-in processing patterns. Use when orchestrating multiple agents simultaneously.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Multi-Agent Orchestration
-
-> Parallel agents are faster. They are also harder to keep consistent.
-> Coordinate them — don't just fire them simultaneously and hope for compatible outputs.
-
----
-
-## When to Use Parallel Agents
-
-Use multiple agents when:
-- Tasks are genuinely **independent** (output of A doesn't feed input of B)
-- Different tasks require **different domain expertise**
-- Comprehensive **review** needs multiple specialist perspectives simultaneously
-- Speed matters and tasks can be assigned and awaited independently
-
-Do **not** use parallel agents when:
-- Tasks have sequential dependencies (you need the result to start the next)
-- The overhead of coordination exceeds the time saved
+# Parallel Agents — Concurrent Orchestration Mastery
 
 ---
 
-## Orchestration Patterns
+## 1. Fan-Out / Fan-In Pattern
 
-### Pattern 1 — Parallel Review (Tribunal)
+The foundation of parallel multi-agent architecture.
 
-Multiple reviewers look at the same code simultaneously, each from a different angle.
+1. **Fan-Out (Scatter):** A central Supervisor breaks an objective into isolated pieces, dispatching them concurrently across multiple independent Worker agents.
+2. **Execute:** The Workers process simultaneously without blocking one another.
+3. **Fan-In (Gather):** The Supervisor waits for ALL promises to resolve, collects the outputs, merges them logically, and assesses the final unified state.
 
-```
-Code (input)
-    ├── → logic-reviewer      → finds logic errors
-    ├── → security-auditor    → finds vulnerabilities  
-    ├── → type-safety-reviewer → finds type unsafe code
-    └── → performance-reviewer → finds bottlenecks
-
-All verdicts → synthesize → Human Gate (approve/reject/revise)
-```
+```typescript
+// Architectural representation (Fan-out/Fan-in)
+async function executeParallelAudit(sourceCode: string) {
+  // Fan-Out
+  const promises = [
+    agentDispatch({ role: 'security-auditor', task: sourceCode }),
+    agentDispatch({ role: 'performance-profiling', task: sourceCode }),
+    agentDispatch({ role: 'web-accessibility-auditor', task: sourceCode })
+  ];
 
-**When:** `/tribunal-*` commands, code review before merge
+  // Await concurrent resolution
+  // If one takes 10s and another takes 2s, the total wait is max(10s)
+  const [securityReport, perfReport, a11yReport] = await Promise.all(promises);
 
-### Pattern 2 — Domain Specialization
-
-Different specialists handle different parts of the same task simultaneously.
-
-```
-"Build a user auth system" (input)
-    ├── → backend-specialist    → API routes + JWT logic
-    ├── → frontend-specialist   → Login/register UI
-    └── → database-architect    → User schema + sessions table
-
-All outputs → orchestrator synthesizes into coherent system
-(ensures API contract matches what frontend calls,
- and DB schema matches what backend queries)
-```
-
-**When:** Full-stack feature builds via `/orchestrate`
-
-### Pattern 3 — Sequential with Parallel Phases
-
-Some tasks are inherently sequential at the macro level but can parallelize within each phase.
-
-```
-Phase 1 (sequential):
-  database-architect → schema design
-
-Phase 2 (parallel, after Phase 1):
-  backend-specialist  → API uses schema from Phase 1
-  frontend-specialist → UI uses API contract from Phase 2a (estimated)
-
-Phase 3 (sequential, after Phase 2):
-  test-engineer → E2E tests with real API + UI
+  // Fan-In Synthesization
+  return synthesizeReports({ securityReport, perfReport, a11yReport });
+}
 ```
 
 ---
 
-## Orchestrator Responsibilities
+## 2. Preventing Workspace Collision Risks
 
-The orchestrator coordinates agents. It:
+When multiple agents write to disk concurrently, catastrophic race conditions occur.
 
-1. **Assigns scope** — each agent gets exactly what it needs, nothing more
-2. **Manages state** — passes the right outputs from each agent to the next that needs them
-3. **Resolves conflicts** — when two agents propose incompatible solutions, the orchestrator decides or asks the user
-4. **Verifies consistency** — ensures that the API contract the backend builds matches what the frontend calls
+**The Golden Rules of Parallel Agents:**
+1. **Never allow concurrent agents to modify the same file.** Standard Git/File lockers will fail. The last one to save entirely overwrites the changes of the others.
+2. **Read-Only Concurrency:** It is infinitely safe to run 10 agents reading and reviewing the same directory simultaneously.
+3. **Directory Isolation:** If multiple agents MUST generate code simultaneously, enforce strict boundaries. Add boundary guards instructing Agent A to stay out of the directories Agent B is designated to manipulate.
 
 ---
 
-## Consistency Rules for Multi-Agent Output
-
-The biggest failure in parallel agent work is **inconsistency at boundaries**:
+## 3. Reviewer Swarms (The Tribunal Principle)
 
-- Backend generates `userId` but frontend calls it `user_id`
-- Database schema has `user_email` but backend queries `email`
-- Agent A designs one error shape; Agent B assumes a different one
+The Tribunal uses parallel processing exclusively for the review phase to drastically speed up output validation without slowing down the user.
 
-**Prevention:**
-- Establish contracts (types, schemas, API shapes) **before** parallel work begins
-- Each agent receives the shared contract as context
-- Orchestrator reviews all outputs for boundary consistency before presenting to user
+- **The Maker:** Generates code (Sequential, isolated).
+- **The Reviewers:** 4x Reviewer Agents analyze the Maker's generated code simultaneously from independent angles (Security, Typing, Logic, Performance).
+- **The Gate:** The outputs merge into a synthesis report for human approval.
 
 ---
 
-## Communication Format Between Agents
+## 4. Handling Differential Failures
 
-When one agent's output feeds another:
+What happens when 4 parallel tasks run, and 1 fails?
+Does the whole pipeline crash?
 
-```
-[AGENT: backend-specialist OUTPUT]
-API Contract:
-  POST /api/users → { id: string, email: string, createdAt: string }
-  POST /api/auth/login → { token: string, expiresAt: string }
+```typescript
+// ❌ BAD: Promise.all fails instantly if ANY sub-agent crashes or hallucinates
+const results = await Promise.all(agentJobs);
 
-[AGENT: frontend-specialist RECEIVES]
-Use the above API contract. Build the UI to match these exact request/response shapes.
-```
+// ✅ GOOD: Use Promise.allSettled to ensure resilient aggregation
+const results = await Promise.allSettled(agentJobs);
 
----
-
-## Output Format
-
-When this skill completes a task, structure your output as:
-
-```
-━━━ Parallel Agents Output ━━━━━━━━━━━━━━━━━━━━━━━━
-Task:        [what was performed]
-Result:      [outcome summary — one line]
-─────────────────────────────────────────────────
-Checks:      ✅ [N passed] · ⚠️  [N warnings] · ❌ [N blocked]
-VBC status:  PENDING → VERIFIED
-Evidence:    [link to terminal output, test result, or file diff]
+for (const result of results) {
+  if (result.status === 'fulfilled') {
+    aggregatedOutput.push(result.value);
+  } else {
+    // 1 agent failed (e.g. rate limit, or runtime crash)
+    // The supervisor can retry just this branch, or proceed with partial success
+    logger.warn(`Sub-agent sequence failed: ${result.reason}`);
+    flagForHumanReview(result.reason);
+  }
+}
 ```
 
-
-
----
-
-## 🤖 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.
-
 ---
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-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.
-
-### ✅ Pre-Flight Self-Audit
-
-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?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**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.

package/.agent/skills/performance-profiling/SKILL.md

@@ -1,197 +1,217 @@
 ---
 name: performance-profiling
-description: Performance profiling principles. Measurement, analysis, and optimization techniques.
+description: Performance profiling mastery. Core Web Vitals (LCP, CLS, INP), Lighthouse auditing, JavaScript profiling, React rendering optimization, bundle analysis, memory leak detection, database query profiling (EXPLAIN ANALYZE), load testing, and performance budgets. Use when optimizing performance, debugging slow pages, or establishing performance standards.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-01
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Performance Profiling Principles
-
-> Never optimize code you haven't measured.
-> The bottleneck is almost never where you expect it to be.
+# Performance Profiling — Measurement-Driven Optimization
 
 ---
 
-## The Measurement-First Rule
-
-Every performance investigation follows the same sequence:
+## Core Web Vitals
 
 ```
-Measure → Identify hotspot → Form hypothesis → Change one thing → Measure again
+LCP (Largest Contentful Paint) → Loading speed
+  ✅ Good: ≤ 2.5s  │  ⚠️ Needs work: 2.5-4s  │  ❌ Poor: > 4s
+  What: Time until the largest visible element renders
+  Fix: Optimize images, preload fonts, reduce server time
+
+INP (Interaction to Next Paint) → Responsiveness
+  ✅ Good: ≤ 200ms  │  ⚠️ Needs work: 200-500ms  │  ❌ Poor: > 500ms
+  What: Delay between user interaction and visual response
+  Fix: Break long tasks, use web workers, defer non-critical JS
+
+CLS (Cumulative Layout Shift) → Visual stability
+  ✅ Good: ≤ 0.1  │  ⚠️ Needs work: 0.1-0.25  │  ❌ Poor: > 0.25
+  What: How much the page layout shifts unexpectedly
+  Fix: Set explicit dimensions on images/ads, font-display: swap
+
+TTFB (Time to First Byte) → Server responsiveness
+  ✅ Good: ≤ 800ms
+  Fix: CDN, caching, optimize database queries, use edge
+
+// ❌ HALLUCINATION TRAP: FID is deprecated. Use INP (Interaction to Next Paint).
+// FID only measured the FIRST interaction. INP measures ALL interactions.
 ```
 
-Breaking this sequence — jumping straight to "fix" — wastes time and creates new problems.
-
 ---
 
-## What to Measure
+## JavaScript Profiling
 
-### Backend
+### Bundle Analysis
 
-| Metric | Tool | Target |
-|---|---|---|
-| Request throughput | ab, k6, wrk | Baseline + stress test |
-| P50/P95/P99 latency | DataDog, Grafana, k6 | P99 < SLA threshold |
-| Memory usage | `process.memoryUsage()`, heap snapshot | Stable under load (no growth) |
-| CPU usage | clinic.js flame chart | Identify blocking operations |
-| Database query time | Query logs, pg_stat_statements | No query > 100ms without index |
+```bash
+# Analyze what's in your JavaScript bundle
+npx vite-bundle-visualizer   # Vite
+npx @next/bundle-analyzer    # Next.js
 
-### Frontend
-
-| Metric | Tool | Target (2025 Core Web Vitals) |
-|---|---|---|
-| LCP (Largest Contentful Paint) | Lighthouse, CrUX | < 2.5s |
-| INP (Interaction to Next Paint) | Lighthouse, Web Vitals | < 200ms |
-| CLS (Cumulative Layout Shift) | Lighthouse | < 0.1 |
-| Bundle size (JS) | `npm run build` + analyzer | < 200kB initial JS |
-
----
-
-## Common Backend Bottlenecks
-
-### N+1 Queries (most common)
-
-```ts
-// ❌ 1 + N queries
-const posts = await db.post.findMany();
-for (const post of posts) {
-  post.author = await db.user.findUnique({ where: { id: post.authorId } });
-}
-
-// ✅ 2 queries total
-const posts = await db.post.findMany({ include: { author: true } });
+# Key targets:
+# Total JS < 200KB (gzipped) for initial load
+# No single dependency > 50KB (gzipped)
+# Tree-shaking working (no dead code)
 ```
 
-**Detection:** Enable query logging. Repeated identical queries differing only by ID = N+1.
+```typescript
+// Common bundle bloat sources:
+// ❌ import _ from "lodash";           // 72KB — imports everything
+// ✅ import debounce from "lodash/debounce";  // 1KB — specific import
 
-### Missing Database Indexes
+// ❌ import { format } from "date-fns";  // may import entire library
+// ✅ import { format } from "date-fns/format";  // specific import
 
-```sql
--- EXPLAIN ANALYZE tells you if a query is doing a sequential scan
-EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = $1;
-
--- Sequential scan on large table → add index
-CREATE INDEX idx_orders_user_id ON orders(user_id);
-```
-
-### Blocking the Event Loop (Node.js)
-
-```ts
-// ❌ Synchronous CPU work blocks all requests
-const result = JSON.parse(fs.readFileSync('huge.json', 'utf8'));
-
-// ✅ Non-blocking
-const content = await fs.promises.readFile('huge.json', 'utf8');
-const result = JSON.parse(content);  // still sync but no disk I/O blocking
+// ❌ import moment from "moment";        // 67KB + locales
+// ✅ Use native Intl.DateTimeFormat or date-fns (tree-shakeable)
 ```
 
----
-
-## Common Frontend Bottlenecks
+### React Rendering Profiling
 
-### Bundle Size
+```typescript
+// React DevTools Profiler — find unnecessary re-renders
 
-- Identify large packages with `npx vite-bundle-visualizer` or `@next/bundle-analyzer`
-- Replace heavy packages with lighter alternatives (e.g., `date-fns` instead of `moment`)
-- Code-split routes — don't ship all JavaScript on first load
+// 1. Why Did You Render (development tool)
+// npm i @welldone-software/why-did-you-render -D
 
-### Render Performance
+// 2. Manual render tracking
+const RenderCounter = ({ label }: { label: string }) => {
+  const renderCount = useRef(0);
+  renderCount.current++;
+  console.log(`[${label}] rendered ${renderCount.current} times`);
+  return null;
+};
 
-```ts
-// ❌ Recalculates on every render
-function ExpensiveList({ items }) {
-  const sorted = items.sort((a, b) => a.name.localeCompare(b.name));
-  return sorted.map(item => <Item key={item.id} item={item} />);
-}
+// 3. React.memo — prevent re-renders when props haven't changed
+const ExpensiveList = React.memo(function ExpensiveList({ items }: Props) {
+  return items.map((item) => <ListItem key={item.id} {...item} />);
+});
 
-// ✅ Recalculates only when items change
-function ExpensiveList({ items }) {
-  const sorted = useMemo(
-    () => [...items].sort((a, b) => a.name.localeCompare(b.name)),
-    [items]
-  );
-  return sorted.map(item => <Item key={item.id} item={item} />);
-}
+// 4. useMemo / useCallback — memoize expensive computations
+const sortedItems = useMemo(
+  () => items.toSorted((a, b) => a.name.localeCompare(b.name)),
+  [items],
+);
 ```
 
----
-
-## Profiling Tools
-
-| Tool | Platform | Best For |
-|---|---|---|
-| `clinic.js` (`clinic doctor`) | Node.js | CPU flame charts, memory leaks |
-| Chrome DevTools → Performance | Browser | JS execution, paint, layout |
-| `EXPLAIN ANALYZE` | PostgreSQL | Query plan analysis |
-| Lighthouse | Web | Full Core Web Vitals audit |
-| `k6` | Backend load testing | Throughput and latency under load |
-
----
-
-## Scripts
-
-| Script | Purpose | Run With |
-|---|---|---|
-| `scripts/lighthouse_audit.py` | Lighthouse performance audit | `python scripts/lighthouse_audit.py <url>` |
+### Memory Leak Detection
+
+```typescript
+// Common memory leaks in JavaScript:
+// 1. Event listeners not cleaned up
+useEffect(() => {
+  const handler = () => console.log("resize");
+  window.addEventListener("resize", handler);
+  return () => window.removeEventListener("resize", handler); // ✅ cleanup
+}, []);
+
+// 2. Timers not cleared
+useEffect(() => {
+  const interval = setInterval(pollData, 5000);
+  return () => clearInterval(interval); // ✅ cleanup
+}, []);
+
+// 3. AbortController not used for fetch
+useEffect(() => {
+  const controller = new AbortController();
+  fetch("/api/data", { signal: controller.signal })
+    .then((res) => res.json())
+    .then(setData)
+    .catch((e) => { if (e.name !== "AbortError") throw e; });
+  return () => controller.abort(); // ✅ cancel on unmount
+}, []);
+
+// Detection: Chrome DevTools → Memory → Heap Snapshot
+// Take snapshot, perform action, take another, compare growth
+```
 
 ---
 
-## Output Format
-
-When this skill produces a recommendation or design decision, structure your output as:
-
-```
-━━━ Performance Profiling Recommendation ━━━━━━━━━━━━━━━━
-Decision:    [what was chosen / proposed]
-Rationale:   [why — one concise line]
-Trade-offs:  [what is consciously accepted]
-Next action: [concrete next step for the user]
-─────────────────────────────────────────────────
-Pre-Flight:  ✅ All checks passed
-             or ❌ [blocking item that must be resolved first]
+## Image Optimization
+
+```html
+<!-- Modern image loading -->
+<img
+  src="hero.webp"
+  srcset="hero-480.webp 480w, hero-768.webp 768w, hero-1200.webp 1200w"
+  sizes="(max-width: 768px) 100vw, 50vw"
+  width="1200"
+  height="800"
+  loading="lazy"
+  decoding="async"
+  alt="Product hero"
+  fetchpriority="high"
+/>
+
+<!-- Rules:
+  - ALWAYS set width and height (prevents CLS)
+  - Use WebP/AVIF (30-50% smaller than JPEG)
+  - loading="lazy" for below-the-fold images
+  - fetchpriority="high" for LCP image
+  - Use srcset for responsive images
+  - Serve from CDN with auto-format negotiation
+-->
 ```
 
-
-
 ---
 
-## 🤖 LLM-Specific Traps
+## Database Query Profiling
 
-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.
+```sql
+-- Always EXPLAIN before optimizing
+EXPLAIN ANALYZE SELECT u.*, COUNT(p.id) AS post_count
+FROM users u
+LEFT JOIN posts p ON p.author_id = u.id
+WHERE u.is_active = true
+GROUP BY u.id
+ORDER BY post_count DESC
+LIMIT 20;
+
+-- Look for:
+-- Seq Scan → needs an index (on large tables)
+-- Nested Loop → consider index or different join strategy
+-- Sort → can an index provide sorted data?
+-- execution time > 100ms → optimize
+
+-- Common fixes:
+-- Add index: CREATE INDEX idx_posts_author ON posts (author_id);
+-- Use partial index: CREATE INDEX idx_active_users ON users (id) WHERE is_active;
+-- Avoid SELECT *: SELECT only needed columns
+-- Paginate with cursor: WHERE id > $cursor ORDER BY id LIMIT 20
+```
 
 ---
 
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-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.
-
-### ✅ Pre-Flight Self-Audit
+## Performance Budgets
+
+```javascript
+// Lighthouse CI budget
+// lighthouserc.js
+module.exports = {
+  ci: {
+    assert: {
+      assertions: {
+        "categories:performance": ["error", { minScore: 0.9 }],
+        "first-contentful-paint": ["error", { maxNumericValue: 1500 }],
+        "largest-contentful-paint": ["error", { maxNumericValue: 2500 }],
+        "cumulative-layout-shift": ["error", { maxNumericValue: 0.1 }],
+        "total-byte-weight": ["error", { maxNumericValue: 500000 }],
+      },
+    },
+  },
+};
+```
 
-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?
+Performance budget targets:
+  Total JS (gzipped):     < 200KB
+  Total CSS (gzipped):    < 50KB
+  Total page weight:      < 500KB
+  LCP:                    < 2.5s
+  INP:                    < 200ms
+  CLS:                    < 0.1
+  TTFB:                   < 800ms
+  Time to Interactive:    < 3.8s
 ```
 
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**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.
+---