claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/codex/skills/r3f-scroll-driven-3d/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: r3f-scroll-driven-3d
+description: Connect GSAP ScrollTrigger to React Three Fiber — Zustand bridge, useFrame animation, scroll progress to 3D transforms. The pattern for scroll-driven 3D product showcases.
+user-invocable: false
+---
+
+# Scroll-Driven 3D with GSAP + R3F
+
+Architecture pattern for connecting GSAP ScrollTrigger to React Three Fiber scenes via Zustand store.
+
+## Why This Pattern?
+
+**Problem:** GSAP runs in the DOM. R3F runs in WebGL. They can't communicate directly.
+
+**Solution:** Zustand store as a bridge — GSAP writes scroll progress, R3F reads it in useFrame.
+
+```
+[GSAP ScrollTrigger] → writes → [Zustand Store] → reads → [R3F useFrame]
+       (DOM)                      (shared state)              (WebGL)
+```
+
+## Why Zustand (Not React State/Context)?
+
+- React state/context triggers re-renders on every scroll tick (60fps = 60 re-renders/sec)
+- Zustand `getState()` reads directly without subscribing — zero re-renders
+- useFrame already runs at 60fps — just read the latest value
+
+## Implementation
+
+### Step 1: Create the store
+
+```tsx
+// stores/useScrollStore.ts
+import { create } from 'zustand';
+
+interface ScrollStore {
+  progress: number;          // 0-1 scroll progress
+  currentTexture: string;    // active screen texture path
+  setProgress: (p: number) => void;
+  setTexture: (t: string) => void;
+}
+
+export const useScrollStore = create<ScrollStore>((set) => ({
+  progress: 0,
+  currentTexture: '/textures/screen-1.png',
+  setProgress: (p) => set({ progress: p }),
+  setTexture: (t) => set({ currentTexture: t }),
+}));
+```
+
+### Step 2: GSAP writes to store
+
+```tsx
+// components/ScrollSection.tsx
+import { useRef, useEffect } from 'react';
+import gsap from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+import { useScrollStore } from '@/stores/useScrollStore';
+
+gsap.registerPlugin(ScrollTrigger);
+
+export function ScrollSection() {
+  const ref = useRef<HTMLDivElement>(null);
+  const { setProgress, setTexture } = useScrollStore();
+
+  useEffect(() => {
+    const ctx = gsap.context(() => {
+      const tl = gsap.timeline({
+        scrollTrigger: {
+          trigger: ref.current,
+          start: 'top top',
+          end: 'bottom bottom',
+          scrub: 1,                    // number, NOT true
+          invalidateOnRefresh: true,   // MUST have
+          pin: true,
+        },
+      });
+
+      // Animate progress 0 → 1
+      tl.to({}, {
+        duration: 1,
+        onUpdate: function() {
+          setProgress(this.progress());
+        },
+      });
+
+      // Swap texture at 50% scroll
+      tl.call(() => setTexture('/textures/screen-2.png'), [], 0.5);
+
+      // CRITICAL: extend timeline to full duration
+      tl.set({}, {}, 1.0);
+
+    }, ref);
+
+    return () => ctx.revert();
+  }, []);
+
+  return <div ref={ref} style={{ height: '300vh' }} />;
+}
+```
+
+### Step 3: R3F reads in useFrame
+
+```tsx
+// components/3d/PhoneModel.tsx
+import { useFrame } from '@react-three/fiber';
+import { useScrollStore } from '@/stores/useScrollStore';
+import { useRef } from 'react';
+import * as THREE from 'three';
+
+export function PhoneModel() {
+  const groupRef = useRef<THREE.Group>(null);
+
+  useFrame(() => {
+    if (!groupRef.current) return;
+
+    // CRITICAL: getState() not hook — no re-renders
+    const { progress } = useScrollStore.getState();
+
+    // Rotate based on scroll
+    groupRef.current.rotation.y = progress * Math.PI * 2;
+
+    // Phase-based animation
+    if (progress < 0.3) {
+      // Entry: scale up
+      const t = progress / 0.3;
+      groupRef.current.scale.setScalar(0.5 + t * 0.5);
+    } else if (progress < 0.7) {
+      // Showcase: full size, rotate
+      groupRef.current.scale.setScalar(1);
+    } else {
+      // Exit: scale down
+      const t = (progress - 0.7) / 0.3;
+      groupRef.current.scale.setScalar(1 - t * 0.3);
+    }
+  });
+
+  return (
+    <group ref={groupRef}>
+      {/* Your 3D model here */}
+    </group>
+  );
+}
+```
+
+## Performance Tips
+
+- **Pre-allocate:** No `new THREE.Vector3()` inside useFrame — use refs
+- **getState():** Always in useFrame, never hook subscription
+- **DPR:** `dpr={[1, 2]}` — higher wastes mobile GPU
+- **Dispose:** `dispose={null}` on reusable groups
+
+## Dynamic Texture Swapping
+
+```tsx
+useFrame(() => {
+  const { currentTexture } = useScrollStore.getState();
+  // Load and apply texture based on store value
+});
+```
+
+Use `tl.call(() => setTexture('/new.png'), [], timePosition)` in GSAP timeline to trigger swaps at specific scroll positions.

package/packages/codex/skills/reality-checker/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: reality-checker
+description: Assess completion or readiness claims against agreed scope and traceable evidence. Distinguish demonstrated defects, missing verification, and external blockers; return READY, NEEDS WORK, or BLOCKED.
+user-invocable: false
+tokens: 1165
+---
+
+# Reality Checker
+
+Determine which completion claims are supported and what remains mandatory. Use for requested readiness assessment, a required delivery/release gate, or when a claimed outcome exceeds its evidence. Do not impose production deployment requirements on a local prototype or routine edit.
+
+## Input, context, and authority
+
+Require the claimed outcome, agreed task/spec, intended environment, and supporting artifacts. Read applicable project requirements and only implementation/architecture needed to interpret those claims. If the meaning of "ready" is unspecified, identify the decision needed instead of inventing a production bar.
+
+Assess only: do not edit implementation or criteria, deploy, modify external state, or expand the task. Authorized local checks may create disposable output. Follow explicit model/effort routing; Sol may collect and review bounded evidence, while Astra accepts consequential release, security, authority, data-loss, and irreversible decisions. Record missing acceptance as a gate, not implied approval. When no authorized independent worker is available, work inline and disclose self-review.
+
+## Evidence assessment
+
+Evaluate each material claim as VERIFIED, FAILED, UNVERIFIED, or N/A with rationale tied to agreed scope. FAILED means observed contradiction. UNVERIFIED means insufficient evidence, an unexecuted check, or unavailable capability; it is not a measured defect or zero score. Do not remove mandatory criteria as N/A without a valid scope basis.
+
+Select evidence for the claim:
+
+- Behavioral claims need relevant implementation and execution evidence. Name whether it comes from fixtures, local integration, staging, or production; one does not prove the others.
+- Test claims need command, target/environment, result, and relevant coverage of behavior. Coverage percentages or new-test counts are not universally required and do not prove correctness.
+- Live API claims need traceable endpoint/environment, authorized request, and observed response. Redact credentials, cookies, tokens, and private data; never require full authenticated traffic in a report.
+- UI/design claims may need rendered capture at the relevant viewport/state. Screenshots are not a universal backend acceptance requirement.
+- Migration, performance, recovery, and security claims need checks appropriate to specific risks and promised guarantees. State their limits; do not promise exhaustive absence of regressions.
+
+Reuse evidence only if command/results or captured artifacts are bound to unchanged relevant code, inputs, and environment. Rerun for relevant changes or concrete uncertainty. A report, hedge word, TODO, or confidence score alone neither proves nor disproves completion. No default completion percentage and no findings quota applies.
+
+## Verdict
+
+- **READY:** all mandatory claims for this delivery scope are verified and required acceptance is present. Explicit non-blocking limitations may remain.
+- **NEEDS WORK:** demonstrated defects or missing verification remain, with an actionable path within current authority/capability.
+- **BLOCKED:** a mandatory decision, authorization, external dependency, or unavailable capability prevents closure. State what resolves it and any useful bounded work still possible.
+
+A single consequential gap can block readiness; irrelevant observations cannot. READY never authorizes publication, deployment, or release by itself.
+
+## Output and stop
+
+```text
+READINESS — verdict: NEEDS WORK | READY | BLOCKED
+Confidence: HIGH | MEDIUM | LOW — <basis>
+Evidence status: COMPLETE | PARTIAL | UNAVAILABLE
+Execution: INDEPENDENT | INLINE SELF-REVIEW
+Requested model/effort: <task route or labeled configured default; UNSPECIFIED if absent>
+Observed model/effort: <runtime evidence reference and values, or UNVERIFIED>
+Subject / evaluated against: <claim, spec, scope, environment>
+Evidence provided: <each claim, VERIFIED/FAILED/UNVERIFIED/N/A, evidence and limits>
+Critical gaps: <observed failures separate from unavailable evidence; or none>
+Non-blocking concerns: <scope-relevant limitations; or none>
+Verdict justification: <what is established and what remains mandatory>
+Path to ready: <bounded correction/check/decision and owner, or none>
+```
+
+Stop once each material claim has a supported status, or a specific missing contract/dependency prevents assessment. Report the blocker instead of retrying unavailable checks indefinitely.
+
+Adapted from VKirill/codex-starter-kit (MIT).
+
+Keep requested/configured routing separate from runtime evidence. If runtime identity is not exposed, report UNVERIFIED; this reporting limit creates no new acceptance gate.

package/packages/codex/skills/redis-patterns/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: redis-patterns
+description: Redis patterns — caching (cache-aside, write-through), sessions, pub/sub, work queues, distributed locks, data structures (sorted sets, streams, hashes). Covers ioredis, node-redis, Redis 7+. Use when designing Redis usage in Node.js or Python apps
+user-invocable: false
+---
+
+# Redis Patterns
+
+Production patterns for Redis as a cache, session store, pub/sub bus, work queue backbone, and distributed coordination primitive.
+
+## Use this skill when
+
+- Implementing caching (cache-aside, write-through, write-back)
+- Setting up pub/sub or BLPOP-based work queues
+- Using Redis data structures (Sorted Sets, Streams, Hash, Sets)
+- Configuring ioredis for Node.js production
+- Designing key naming and TTL strategies
+- Implementing distributed locks with atomic `SET NX EX`
+
+## Do not use this skill when
+
+- The task requires a message broker with guaranteed delivery — use BullMQ, RabbitMQ, or Kafka
+- The task is about Redis server-level configuration / cluster setup
+
+## Workflow
+
+1. Identify the use case: caching, pub/sub, queue, session, or rate limiting
+2. Choose the right data structure for the access pattern
+3. Design keys with `namespace:entity:id` convention
+4. Set TTL on every key (unless intentionally persistent: queues, locks-with-expiry)
+5. Validate error handling and graceful shutdown
+
+## Connection (ioredis — recommended for Node.js)
+
+```typescript
+import Redis from 'ioredis';
+
+export const redis = new Redis({
+  host: process.env.REDIS_HOST,
+  port: 6379,
+  lazyConnect: true,
+  connectionName: 'api-server',
+  retryStrategy(times) {
+    return Math.min(times * 200, 2000);
+  },
+});
+
+redis.on('error', (err) => logger.error({ err }, 'redis'));
+redis.on('ready', () => logger.info('redis ready'));
+```
+
+- Singleton client; `lazyConnect` defers connection until first command
+- `retryStrategy` for exponential backoff
+- Separate dedicated **subscriber** connection for pub/sub (can't mix with commands)
+- **BullMQ**: `maxRetriesPerRequest: null` is mandatory
+
+## Cache-Aside Pattern
+
+```typescript
+async function getUser(id: string): Promise<User> {
+  const key = `cache:user:${id}`;
+  const cached = await redis.get(key);
+  if (cached) return JSON.parse(cached);
+
+  const user = await db.users.findUnique({ where: { id } });
+  if (user) await redis.set(key, JSON.stringify(user), 'EX', 300);
+  return user;
+}
+
+async function invalidateUser(id: string) {
+  await redis.del(`cache:user:${id}`);
+}
+```
+
+TTL strategy:
+- Volatile data (counters, hot lists): seconds
+- Stable data (config, user profiles): minutes to hours
+- Rarely-changing reference data: hours to days
+
+Bulk invalidation: `SCAN` + `DEL` (NEVER `KEYS *` in production).
+
+## Pub/Sub
+
+```typescript
+// Publisher (regular connection)
+await redis.publish('orders:new', JSON.stringify({ orderId: 123 }));
+
+// Subscriber (DEDICATED connection — can't issue other commands)
+const sub = new Redis({ ...config });
+await sub.subscribe('orders:new');
+sub.on('message', (channel, message) => {
+  const data = JSON.parse(message);
+  handleOrder(data);
+});
+```
+
+Pub/sub is fire-and-forget — messages dropped if no subscriber. For durable messaging use **Streams**.
+
+## BLPOP Wake Queue
+
+```typescript
+// Producer
+await redis.lpush('queue:emails', JSON.stringify(payload));
+
+// Consumer (blocks until item arrives)
+while (true) {
+  const [, raw] = await redis.brpop('queue:emails', 0);
+  await processEmail(JSON.parse(raw));
+}
+```
+
+Instant wake-up without polling. For complex queue needs use **BullMQ** built on this primitive.
+
+## Data Structures
+
+| Structure | Use case |
+|-----------|----------|
+| **Sorted Set** | Leaderboards, sliding-window rate limit, scheduled jobs by score |
+| **Stream** (`XADD`/`XREAD`) | Event sourcing, consumer groups, persistent log |
+| **Hash** (`HSET`/`HGETALL`) | Object storage with partial updates (user sessions) |
+| **Set** | Unique tag membership, set operations (union, intersect, diff) |
+| **List** | FIFO/LIFO queues; recent activity via `LPUSH` + `LTRIM` |
+
+## Batch Operations
+
+```typescript
+// Pipeline — multiple commands, one round-trip (no atomicity)
+const results = await redis
+  .pipeline()
+  .get('a')
+  .get('b')
+  .incr('counter')
+  .exec();
+
+// Multi/Exec — atomic transaction (all-or-nothing)
+const results = await redis
+  .multi()
+  .decrby('inventory:x', 1)
+  .lpush('orders', orderId)
+  .exec();
+```
+
+Pipeline for **performance**, multi/exec for **atomicity**.
+
+## Distributed Locks
+
+```typescript
+async function acquireLock(key: string, ttlMs: number, token: string): Promise<boolean> {
+  const r = await redis.set(key, token, 'PX', ttlMs, 'NX');
+  return r === 'OK';
+}
+
+const releaseScript = `
+  if redis.call('get', KEYS[1]) == ARGV[1] then
+    return redis.call('del', KEYS[1])
+  else
+    return 0
+  end
+`;
+
+async function releaseLock(key: string, token: string) {
+  await redis.eval(releaseScript, 1, key, token);
+}
+```
+
+Lua script for release prevents one process releasing another's lock. Always set expiry to prevent deadlock on crash.
+
+For production-grade locking with renewal use **Redlock** algorithm or a hosted lock service.
+
+## Lua Scripts
+
+`redis.defineCommand()` caches EVALSHA automatically:
+
+```typescript
+redis.defineCommand('rateLimit', {
+  numberOfKeys: 1,
+  lua: `
+    local current = redis.call('incr', KEYS[1])
+    if current == 1 then redis.call('expire', KEYS[1], ARGV[1]) end
+    return current
+  `,
+});
+
+const count = await redis.rateLimit(`rate:${userId}`, 60);
+```
+
+Use for atomic read-modify-write that can't be expressed with `MULTI`/`EXEC`.
+
+## Key Naming Convention
+
+Pattern: `scope:entity:id`
+
+- `session:user:123`
+- `cache:products:featured`
+- `lock:payment:456`
+- `rate:api:user:789`
+- `queue:emails:high`
+- `stream:events:user-activity`
+
+Consistent colon separator enables prefix-based scanning and invalidation.
+
+## TTL Strategy Guide
+
+| Use case | Suggested TTL |
+|----------|---------------|
+| User session | 24h – 7 days |
+| API response cache | 1 min – 1 hour |
+| Rate limit window | = window size (60s for per-minute) |
+| Distributed lock | Slightly longer than expected op duration |
+| BLPOP queue keys | No TTL (persistent until consumed) |
+
+## Eviction Policies
+
+| Policy | Behavior | Use case |
+|--------|----------|----------|
+| `allkeys-lru` | Evict LRU from all keys | Pure caching |
+| `volatile-lru` | Evict LRU from keys with TTL | Protect persistent queues |
+| `allkeys-lfu` | Evict LFU | Repeated-access patterns |
+| `noeviction` | Error on write when full | Required for BullMQ |
+
+## Graceful Shutdown
+
+```typescript
+process.on('SIGTERM', async () => {
+  await redis.quit();  // waits for pending commands
+  process.exit(0);
+});
+```
+
+Use `quit()`, NOT `disconnect()` (latter drops in-flight commands).
+
+## Behavioral Traits
+
+- Sets TTL on every SET unless the key is intentionally persistent (queue, lock)
+- Uses SCAN, never `KEYS *` in production
+- Keeps subscriber connections separate from command connections
+- Attaches error event handler before connecting
+- Pipeline for batching, multi/exec for atomicity
+- BullMQ clients have `maxRetriesPerRequest: null`
+- Lua scripts for atomic read-modify-write
+
+## Common Mistakes
+
+- `KEYS *` in production — blocks Redis on large keyspaces
+- Missing error handler — unhandled events crash the Node.js process
+- Mixing subscribe + command mode on one connection
+- No TTL on cache keys — unbounded memory growth
+- `disconnect()` in shutdown — drops in-flight commands; use `quit()`
+- Omitting `maxRetriesPerRequest: null` for BullMQ — connection failures under load
+
+## Constraints
+
+- **ALWAYS** set TTL on every SET unless intentionally persistent
+- **NEVER** use `KEYS *` in production code — use SCAN
+- **DEDICATED** connection for subscriber — never mix with commands
+- **BullMQ** clients MUST have `maxRetriesPerRequest: null`
+- **ERROR HANDLER** attached to every Redis client
+- **GRACEFUL SHUTDOWN** uses `quit()`, not `disconnect()`
+
+Adapted from VKirill/codex-starter-kit (community skill).

package/packages/codex/skills/review-orchestrator/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: review-orchestrator
+description: Coordinate requested code review or required review gates by identifying changed scope, selecting available reviewers, and consolidating evidence and findings.
+user-invocable: true
+tokens: 2068
+---
+
+# Unified Orchestrated Code Review
+
+Detect changed scope, gather relevant context, use available and authorized reviewers, and collect/deduplicate findings. Review is read-only: do not fix files, post comments, merge, or perform external writes without a separate authorized action. Follow project model/effort routing; Astra accepts high-risk decisions, while Sol may gather evidence or review bounded scope.
+
+## Target
+
+Parse the user's request to determine scope and parameters. Accepted formats:
+- `PR#NNN` or a number — review a pull request
+- A branch name — diff against that branch
+- `--full` — review all tracked files
+- Empty — default to the last committed change (`HEAD~1..HEAD`)
+
+Read applicable `AGENTS.md` instructions. Resolve role files from the current skill catalog or the project's `.agents/skills/<name>/SKILL.md` / `.codex/skills/<name>/SKILL.md` and read the selected file directly. These paths may alias the same installation. Pass the resolved role path to workers; skill names are not automatically registered agent types. Discover runtime tools instead of assuming a global skill loader, a Claude plugin, or a particular delegation API. Do not recursively invoke this orchestrator to load a role.
+
+## Step 1 — Detect Changed Files and Gather Context
+
+Bind the file list, statistics, contents, and line references to one review target. Validate user-supplied refs/PR identifiers as data and pass them as quoted arguments, never as executable shell text.
+- PR: use an available read-only provider tool or installed `gh` to obtain repository identity, base/head SHAs, changed files and the PR diff. Read supporting files at that head; local `HEAD` is not a substitute. If the head changes during review, refresh affected evidence or report the reviewed SHA as stale.
+- Branch/ref: resolve it to a commit and review the merge-base-to-`HEAD` diff; use that same range for names, statistics and hunks.
+- `--full`: review tracked files at a declared snapshot. State whether current working changes are included.
+- Empty: review the last committed change, `HEAD~1..HEAD`, consistently for names, statistics and hunks; exclude unstaged/staged changes unless requested. If no parent exists, review the initial commit against the empty tree or ask for the intended target.
+
+Collect relevant commit messages from that target as intent evidence. For a requested working-tree review, identify staged, unstaged and selected untracked scope separately. Missing access or unavailable diff content means incomplete coverage, not a fallback to unrelated local changes.
+
+Build a `REVIEW_CONTEXT` block:
+```
+=== REVIEW CONTEXT ===
+## Changed Files (N files, +X/-Y lines)
+<statistics and base/head or working-snapshot identity for the selected target>
+
+## Recent Commits (intent)
+<relevant commit messages from the selected review target>
+
+## Diff Hunks
+<relevant complete diff, or exact references the reviewer can read>
+=== END CONTEXT ===
+```
+
+## Step 2 — Map Files to Agents
+
+Based on file extension and path patterns, build a dispatch plan. Each pattern maps to one or more agents:
+
+| File Pattern | Agents |
+|---|---|
+| `*.go` (excluding `*_test.go`, `migrations/`) | **go-reviewer**, **security-scanner** |
+| `migrations/*.sql` or `db/migrate/*.sql` | **migration-reviewer** |
+| `*.tsx` | **ts-reviewer**, **design-system-reviewer** |
+| `*.vue`, `*.svelte` | **design-system-reviewer** |
+| `*.ts` | **ts-reviewer** |
+| `*.py` | **py-reviewer**, **security-scanner** |
+| `*.rs` | **rs-reviewer** |
+| `**/bot*/**/*.go` or `**/bot*/**/*.py` | **bot-reviewer** |
+| `*.yaml` / `*.yml` (OpenAPI/config) | **api-contract-sync** (if available) |
+
+Rules:
+- A single agent is dispatched **at most once** even if multiple files match
+- Only dispatch roles with an available resolved skill file; missing required expertise remains uncovered and blocks acceptance.
+- If no pattern matches, report the unmatched scope and whether a suitable generic review is available; do not call unreviewed changes a clean pass.
+- List the dispatch plan before executing (agent name + matched file count)
+
+## Step 3 — Dispatch Agents in Parallel
+
+Inspect available delegation tools and authorization before dispatch. For independent scopes, use supported concurrency within available slots and clean worker contexts with explicit model/effort. Supply scope, read-only authority, criteria, relevant evidence, and required output. If delegation or routing is unavailable, perform suitable skills as separate inline passes and disclose self-review; mandatory independence/Astra acceptance remains pending.
+
+**Parallel Group 1 (code quality)**:
+- go-reviewer (if triggered)
+- ts-reviewer (if triggered)
+- py-reviewer (if triggered)
+- rs-reviewer (if triggered)
+- bot-reviewer (if triggered)
+- migration-reviewer (if triggered)
+- design-system-reviewer (if triggered)
+
+**Parallel Group 2 (cross-cutting)**:
+- security-scanner (if triggered)
+- api-contract-sync (if triggered)
+
+Groups 1 and 2 can run concurrently when their assigned scopes are independent and runtime capacity permits. Reviewers may not recursively delegate unless assigned.
+
+For each agent, inject the `REVIEW_CONTEXT` block into the prompt:
+
+```
+You are reviewing code changes.
+
+Model/effort: <explicit supported route from task/project policy>
+Role instructions: <resolved installed SKILL.md path; read before reviewing>
+Authority: read-only; no edits or external writes.
+Scope/criteria: <exact diff identity, owned review scope, requested contract>
+Existing evidence: <commands/results bound to code, inputs, and environment>
+
+{REVIEW_CONTEXT — filtered to files relevant to this agent}
+
+## Your Task
+Review the diff hunks above against your checklist. The recent commits section
+provides intent — use it to judge whether changes are complete and consistent.
+
+Focus on:
+- Changes that contradict the stated commit intent
+- Missing pieces (e.g., commit says "add endpoint" but no route registration)
+- Regressions in existing patterns
+
+Report findings in your standard format, plus coverage (COMPLETE/PARTIAL/UNAVAILABLE), evidence references, and unresolved mandatory criteria. Zero findings is valid. Mark any unreviewed scope explicitly. Reuse results only for unchanged relevant code, inputs, environment, and recorded command/results; rerun for concrete uncertainty or relevant change.
+```
+
+**Per-agent diff filtering** — only include relevant file hunks:
+- **go-reviewer**: `*.go` hunks (excluding `*_test.go`, migrations)
+- **ts-reviewer**: `*.ts` and `*.tsx` hunks
+- **py-reviewer**: `*.py` hunks
+- **rs-reviewer**: `*.rs` hunks
+- **migration-reviewer**: `*.sql` migration hunks only
+- **security-scanner**: all hunks (cross-cutting concern)
+- **bot-reviewer**: bot-related file hunks only
+- **design-system-reviewer**: `*.tsx` / `*.vue` / `*.svelte` UI component hunks
+
+## Step 4 — Collect and Deduplicate Findings
+
+After all agents complete:
+
+1. **Merge** all findings into a unified report
+2. **Deduplicate** by root cause and impact, preserving distinct issues on the same line and unresolved blockers from prior reviews.
+3. **Group by severity**:
+
+### Blocking
+- [agent-name] file:line — description
+
+### Important
+- [agent-name] file:line — description
+
+### Nit
+- [agent-name] file:line — description
+
+4. **Summary table**:
+
+| Agent | Blocking | Important | Nit | Status |
+|-------|----------|-----------|-----|--------|
+| go-reviewer | 0 | 2 | 1 | PASS |
+| ts-reviewer | 1 | 0 | 3 | FAIL |
+| ... | | | | |
+
+Status: **FAIL** if a supported blocking finding or unresolved mandatory acceptance condition prevents progression; distinguish defects from missing evidence. **WARN** for non-blocking concerns or partial optional coverage. **PASS** only when assigned coverage is complete, mandatory conditions are met, and remaining items are nits-only or clean. Carry each reviewer's coverage and evidence status into the summary; no findings is not proof of complete review.
+
+### Overall Verdict
+
+**PASS / WARN / FAIL** — one-line reason, coverage, and any required next action. Preserve native plan-checker/evaluator/goal-verifier/critic verdicts when included; do not translate unresolved mandatory criteria into PASS. Missing required capability ends the review with an incomplete result, not endless retries.