feat: add JTBD descriptions to all critics, skills, and manifests

- Update frontmatter descriptions in all 5 agents and 4 skills to
  JTBD-oriented phrasing that tells agents when/why to invoke each critic
- Add "Jobs To Be Done" sections to all 4 SKILL.md files with concrete
  trigger scenarios and router dispatch context
- Add jtbd: field to all 43 skill entries across 4 external-skills manifests
- Expand all 4 skill-routing-maps with JTBD annotations per skill
- Reframe visual explainer hero from security focus to value proposition

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: AlexU-A

.claude/agents/js-critic-router.md

@@ -1,6 +1,6 @@
 ---
 name: js-critic-router
-description: Routes JavaScript/TypeScript review requests to the appropriate specialist critic (react-critic, next-critic, react-native-critic, or proposal-critic) based on framework signals, file paths, imports, and artifact type.
+description: "Use as the entry point for any JavaScript/TypeScript code review or plan critique. Reads imports, file paths, package.json, and document signals to dispatch to the right specialist critic (react-critic, next-critic, react-native-critic, or proposal-critic). Invoke this instead of picking a critic directly."
 model: claude-haiku-4-5
 disallowedTools: Write, Edit
 ---

.claude/agents/next-critic.md

@@ -1,6 +1,6 @@
 ---
 name: next-critic
-description: Next.js App Router-focused harsh reviewer with evidence-backed findings and context-driven audience lenses
+description: "Use when reviewing Next.js App Router code, RSC boundaries, cache/revalidation behavior, route handlers, server actions, runtime decisions, and upgrade plans where evidence-backed critique is required."
 model: claude-opus-4-6
 disallowedTools: Write, Edit
 ---

.claude/agents/proposal-critic.md

@@ -1,6 +1,6 @@
 ---
 name: proposal-critic
-description: Plan-first harsh reviewer for technical proposals, ADRs, RFCs, and migration specs across the React ecosystem
+description: "Use when reviewing RFCs, ADRs, migration plans, architecture decisions, or feature specs across the React ecosystem where evidence-backed plan critique is required."
 model: claude-opus-4-6
 disallowedTools: Write, Edit
 ---

.claude/agents/react-critic.md

@@ -1,6 +1,6 @@
 ---
 name: react-critic
-description: React-specific harsh reviewer with evidence-backed findings and context-driven audience lenses
+description: "Use when reviewing React components, hooks, state management, rendering performance, or upgrade plans where evidence-backed critique with security/new-hire/ops perspectives is required."
 model: claude-opus-4-6
 disallowedTools: Write, Edit
 ---

.claude/agents/react-native-critic.md

@@ -1,6 +1,6 @@
 ---
 name: react-native-critic
-description: React Native and Expo-focused harsh reviewer with evidence-backed findings and context-driven audience lenses
+description: "Use when reviewing React Native or Expo code for native performance, platform APIs, mobile architecture, upgrade safety, and release workflows where evidence-backed critique is required."
 model: claude-opus-4-6
 disallowedTools: Write, Edit
 ---

.claude/skills/next-critic/SKILL.md

@@ -1,13 +1,28 @@
 ---
 name: next-critic
-description: Next.js App Router-specific harsh review orchestration for plans, code, and implementation notes. Use when reviewing RSC boundaries, cache/revalidation behavior, route handlers/server actions, runtime decisions, and upgrade plans where evidence-backed critique is required.
+description: "Use when reviewing Next.js App Router code, RSC boundaries, cache/revalidation behavior, route handlers, server actions, runtime decisions, and upgrade plans where evidence-backed critique is required."
 ---
 
 # Next Critic
 
 ## Overview
 Run a harsh-critic style review with Next.js App Router checks, explicit evidence requirements, and context-driven audience perspectives.
 
+## Jobs To Be Done
+
+Use next-critic when you need to:
+
+- **Review App Router architecture** — layout nesting, parallel routes, intercepting routes, loading/error boundaries
+- **Audit RSC boundaries** — `'use client'`/`'use server'` placement, serialization across the boundary, component tree splits
+- **Evaluate caching and revalidation** — fetch cache, ISR, `revalidatePath`/`revalidateTag`, on-demand revalidation strategy
+- **Review server actions and route handlers** — mutation patterns, error handling, redirect behavior, form actions
+- **Catch runtime configuration issues** — edge vs Node.js runtime choices, middleware behavior, streaming pitfalls
+- **Assess auth integration** — Clerk, Auth0, or NextAuth.js patterns, session handling, protected routes
+- **Review Next.js version upgrades** — breaking changes between versions, codemods, migration scope
+- **Evaluate data fetching patterns** — waterfall risk, parallel fetching, server component data loading, Suspense boundaries
+
+The router (`js-critic-router`) dispatches here when it detects: `next` in package.json, App Router conventions (`app/**/page.tsx`), Pages Router conventions, Next.js APIs (`next/navigation`, `next/cache`), or `next.config.*`.
+
 ## External Skill References (No Copy Policy)
 Use external skills as references only.
 

.claude/skills/next-critic/references/external-skills-manifest.yaml

@@ -15,6 +15,7 @@ skills:
   - performance-engineer
   priority: 100
   status: active
+  jtbd: "Load for any Next.js review — core App Router patterns, RSC best practices, and data fetching guidance from Vercel."
 - id: vercel-labs/next-skills/next-cache-components
   skills_url: https://skills.sh/vercel-labs/next-skills/next-cache-components
   repo_url: https://github.com/vercel-labs/next-skills
@@ -27,6 +28,7 @@ skills:
   - performance-engineer
   priority: 95
   status: active
+  jtbd: "Load when reviewing caching, ISR, revalidation strategies, or fetch cache behavior in Next.js."
 - id: vercel-labs/next-skills/next-upgrade
   skills_url: https://skills.sh/vercel-labs/next-skills/next-upgrade
   repo_url: https://github.com/vercel-labs/next-skills
@@ -39,6 +41,7 @@ skills:
   - dx-maintainer
   priority: 92
   status: active
+  jtbd: "Load when reviewing Next.js version upgrades, breaking changes, codemods, or migration plans."
 - id: wshobson/agents/nextjs-app-router-patterns
   skills_url: https://skills.sh/wshobson/agents/nextjs-app-router-patterns
   repo_url: https://github.com/wshobson/agents
@@ -51,6 +54,7 @@ skills:
   - ops
   priority: 88
   status: active
+  jtbd: "Load when reviewing App Router architecture — layout nesting, parallel routes, route groups, and advanced patterns."
 - id: wsimmonds/claude-nextjs-skills/nextjs-app-router-fundamentals
   skills_url: https://skills.sh/wsimmonds/claude-nextjs-skills/nextjs-app-router-fundamentals
   repo_url: https://github.com/wsimmonds/claude-nextjs-skills
@@ -62,6 +66,7 @@ skills:
   - new-hire
   priority: 82
   status: active
+  jtbd: "Load when reviewing App Router fundamentals — server/client component split, basic routing, and data flow patterns."
 - id: clerk/skills/clerk-nextjs-patterns
   skills_url: https://skills.sh/clerk/skills/clerk-nextjs-patterns
   repo_url: https://github.com/clerk/skills
@@ -73,6 +78,7 @@ skills:
   - security
   priority: 78
   status: active
+  jtbd: "Load when code uses Clerk for authentication — middleware setup, protected routes, and session management patterns."
 - id: auth0/agent-skills/auth0-nextjs
   skills_url: https://skills.sh/auth0/agent-skills/auth0-nextjs
   repo_url: https://github.com/auth0/agent-skills
@@ -84,6 +90,7 @@ skills:
   - security
   priority: 78
   status: active
+  jtbd: "Load when code uses Auth0 for authentication — SDK integration, callback handling, and session patterns for Next.js."
 - id: mindrally/skills/nextauth-authentication
   skills_url: https://skills.sh/mindrally/skills/nextauth-authentication
   repo_url: https://github.com/mindrally/skills
@@ -95,6 +102,7 @@ skills:
   - security
   priority: 76
   status: active
+  jtbd: "Load when code uses NextAuth.js / Auth.js — provider configuration, session strategy, and callback patterns."
 - id: wshobson/agents/javascript-testing-patterns
   skills_url: https://skills.sh/wshobson/agents/javascript-testing-patterns
   repo_url: https://github.com/wshobson/agents
@@ -106,6 +114,7 @@ skills:
   - ops
   priority: 86
   status: active
+  jtbd: "Load when reviewing test strategy, async test patterns, or coverage gaps in JavaScript/TypeScript projects."
 - id: wshobson/agents/modern-javascript-patterns
   skills_url: https://skills.sh/wshobson/agents/modern-javascript-patterns
   repo_url: https://github.com/wshobson/agents
@@ -117,6 +126,7 @@ skills:
   - new-hire
   priority: 76
   status: active
+  jtbd: "Load when reviewing modern JS idioms — ESM usage, async patterns, and contemporary language features."
 - id: sickn33/antigravity-awesome-skills/api-security-best-practices
   skills_url: https://skills.sh/sickn33/antigravity-awesome-skills/api-security-best-practices
   repo_url: https://github.com/sickn33/antigravity-awesome-skills
@@ -128,3 +138,4 @@ skills:
   - security
   priority: 72
   status: active
+  jtbd: "Load when code handles API boundaries, auth tokens, user input, or sensitive data — trust boundary and input validation patterns."

.claude/skills/next-critic/references/skill-routing-map.md

@@ -1,23 +1,23 @@
 # Next Critic Skill Routing Map
 
-Core:
-- vercel-labs/next-skills/next-best-practices
+Core (always loaded):
+- vercel-labs/next-skills/next-best-practices — core Next.js App Router patterns and data fetching from Vercel
 
-Specialists:
-- vercel-labs/next-skills/next-cache-components
-- vercel-labs/next-skills/next-upgrade
-- wshobson/agents/nextjs-app-router-patterns
-- wsimmonds/claude-nextjs-skills/nextjs-app-router-fundamentals
+Specialists (load one based on context):
+- vercel-labs/next-skills/next-cache-components — when reviewing caching, ISR, or revalidation behavior
+- vercel-labs/next-skills/next-upgrade — when reviewing Next.js version upgrades or migrations
+- wshobson/agents/nextjs-app-router-patterns — when reviewing advanced App Router architecture patterns
+- wsimmonds/claude-nextjs-skills/nextjs-app-router-fundamentals — when reviewing basic App Router component structure
 
-Auth conditional:
-- clerk/skills/clerk-nextjs-patterns
-- auth0/agent-skills/auth0-nextjs
-- mindrally/skills/nextauth-authentication
+Auth conditional (load when auth imports detected):
+- clerk/skills/clerk-nextjs-patterns — when Clerk imports are present
+- auth0/agent-skills/auth0-nextjs — when Auth0 imports are present
+- mindrally/skills/nextauth-authentication — when NextAuth.js / Auth.js imports are present
 
-Shared support:
-- wshobson/agents/javascript-testing-patterns
-- wshobson/agents/modern-javascript-patterns
-- sickn33/antigravity-awesome-skills/api-security-best-practices
+Shared support (load one):
+- wshobson/agents/javascript-testing-patterns — when reviewing test strategy or coverage gaps
+- wshobson/agents/modern-javascript-patterns — when reviewing modern JS idioms and async patterns
+- sickn33/antigravity-awesome-skills/api-security-best-practices — when code handles API boundaries or sensitive data
 
 Rules:
 - Load max 3 skills: 1 core + 1 context specialist + 1 shared support.

.claude/skills/proposal-critic/SKILL.md

@@ -1,13 +1,29 @@
 ---
 name: proposal-critic
-description: Plan-first harsh review orchestration for technical proposals, ADRs, RFCs, migration plans, and architecture decision records across the React ecosystem. Use when reviewing any pre-implementation artifact — proposals, specs, design docs, migration plans, feature briefs, or refactor RFCs — where evidence-backed plan critique is required.
+description: "Use when reviewing RFCs, ADRs, migration plans, architecture decisions, or feature specs across the React ecosystem where evidence-backed plan critique is required."
 ---
 
 # Proposal Critic
 
 ## Overview
 Run a harsh-critic style plan review for technical proposals and decision records across the React, Next.js, and React Native/Expo ecosystem. This critic is plan-first by default: every review is a plan review. Never downgrade findings because code hasn't been written yet — underspecified proposals are a category of risk, not a grace period.
 
+## Jobs To Be Done
+
+Use proposal-critic when you need to:
+
+- **Review RFCs and ADRs** — alternatives analysis, assumption extraction, hidden constraints, and decision justification
+- **Critique migration plans** — rollback strategy, phased rollout risks, dependency ordering, blast radius of each phase
+- **Evaluate architecture decisions** — boundary definitions, coupling risks, scalability assumptions, and devil's-advocate challenges
+- **Assess feature specs** — feasibility, ambiguity scan, missing acceptance criteria, and implementation risk
+- **Pre-mortem analysis** — identify how the plan could fail before resources are committed
+- **Dependency audit** — surface hidden dependencies, version assumptions, and integration risks across the plan
+- **Review refactor proposals** — scope creep risk, test coverage implications, and incremental delivery strategy
+
+The router (`js-critic-router`) dispatches here when it detects: pre-implementation documents with signal phrases like "we propose", "alternatives considered", "rollback strategy", "RFC", "ADR", or "migration plan" — with no real code or only illustrative pseudocode.
+
+Uses **executor/stakeholder/skeptic** perspectives instead of the standard security/new-hire/ops lenses.
+
 ## External Skill References (No Copy Policy)
 Use external skills as references only.
 

.claude/skills/proposal-critic/references/external-skills-manifest.yaml

@@ -15,6 +15,7 @@ skills:
   - skeptic
   priority: 92
   status: active
+  jtbd: "Load when evaluating architecture proposals — provides cross-framework architectural patterns and boundary analysis."
 - id: dotneet/claude-code-marketplace/typescript-react-reviewer
   skills_url: https://skills.sh/dotneet/claude-code-marketplace/typescript-react-reviewer
   repo_url: https://github.com/dotneet/claude-code-marketplace
@@ -28,6 +29,7 @@ skills:
   - dx-maintainer
   priority: 78
   status: active
+  jtbd: "Load when evaluating TypeScript API design proposals — type safety patterns and interface design review."
 - id: wshobson/agents/modern-javascript-patterns
   skills_url: https://skills.sh/wshobson/agents/modern-javascript-patterns
   repo_url: https://github.com/wshobson/agents
@@ -40,6 +42,7 @@ skills:
   - skeptic
   priority: 76
   status: active
+  jtbd: "Load when evaluating JS/TS pattern choices in proposals — modern idioms and contemporary language feature assessment."
 - id: sickn33/antigravity-awesome-skills/api-security-best-practices
   skills_url: https://skills.sh/sickn33/antigravity-awesome-skills/api-security-best-practices
   repo_url: https://github.com/sickn33/antigravity-awesome-skills
@@ -51,6 +54,7 @@ skills:
   - security-engineer
   priority: 72
   status: active
+  jtbd: "Load when proposals involve API design, auth flows, or data handling — security architecture and trust boundary review."
 - id: wshobson/agents/javascript-testing-patterns
   skills_url: https://skills.sh/wshobson/agents/javascript-testing-patterns
   repo_url: https://github.com/wshobson/agents
@@ -62,3 +66,4 @@ skills:
   - executor
   priority: 70
   status: active
+  jtbd: "Load when evaluating test strategy feasibility in proposals — coverage planning and test architecture assessment."