@ericrisco/rsc 1.1.5 → 1.2.0

package/skills/motion-craft/scripts/verify.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+#
+# verify.sh — the never-animate list of `motion-craft`, made mechanical.
+#
+# The SKILL.md declares rules as binding ("never animate layout", "never
+# `transition: all`"). A rule declared binding without a mechanism that checks it
+# is a decorative gate: it buys the feeling of safety without the safety. So each
+# hard rule in the skill body has a row here, and each row has a fixture in
+# tests/motion-craft-rules.test.js that watches it FAIL and then PASS.
+#
+# Static and network-free. Everything WARNS by default; --strict makes findings
+# fatal, which is what CI should use.
+set -u
+TARGET="${1:-.}"
+STRICT=0
+[ "${2:-}" = "--strict" ] && STRICT=1
+[ "${1:-}" = "--strict" ] && { STRICT=1; TARGET="."; }
+
+warn_count=0
+warn() { printf '  ⚠  %s\n' "$1"; warn_count=$((warn_count + 1)); }
+ok()   { printf '  ✓  %s\n' "$1"; }
+
+# id <TAB> grep -E pattern <TAB> message
+# One row per hard rule in SKILL.md §"What must never animate". Adding a rule to
+# the prose without adding it here is what the test suite refuses to allow.
+#
+# Fields are TAB-separated on purpose: the patterns are extended regexes and are
+# full of `|`, so a pipe delimiter silently truncated every pattern at its first
+# alternation and only the one rule without alternation ever fired.
+rules() {
+  printf '%b\n' \
+    "transition-all\ttransition:[[:space:]]*all\t\`transition: all\` animates layout by accident — list the exact properties" \
+    "layout-anim\ttransition:[^;]*(width|height|top:|left:|right:|bottom:|margin|padding)\tanimating layout properties forces reflow every frame — use transform and opacity" \
+    "linear-move\t(transition|animation):[^;]*(transform|translate|scale)[^;]*linear\tlinear easing on positional movement reads as mechanical — nothing physical starts at full speed" \
+    "long-duration\t(transition|animation):[^;]*[^0-9]([5-9][0-9][0-9]|[0-9][0-9][0-9][0-9])ms\tover 400ms stops being a transition and becomes a wait"
+}
+
+files=$(find "$TARGET" \( -name node_modules -o -name .git -o -name dist -o -name build -o -name .next \) -prune -o \
+  \( -name '*.css' -o -name '*.scss' -o -name '*.tsx' -o -name '*.jsx' -o -name '*.ts' -o -name '*.js' -o -name '*.vue' -o -name '*.svelte' \) -print 2>/dev/null)
+
+echo "motion-craft — never-animate checks"
+if [ -z "$files" ]; then
+  echo "  (no style or component files found under $TARGET)"
+  exit 0
+fi
+
+while IFS=$'\t' read -r id pattern message; do
+  [ -z "$id" ] && continue
+  hits=$(printf '%s\n' "$files" | xargs grep -lEi -- "$pattern" 2>/dev/null | head -5)
+  if [ -n "$hits" ]; then
+    warn "$id: $message"
+    printf '        %s\n' $hits
+  else
+    ok "$id"
+  fi
+done <<< "$(rules)"
+
+# reduced-motion is a finishing condition, not an edge case: if anything animates
+# at all, the project must say what it does for people who asked for less motion.
+if printf '%s\n' "$files" | xargs grep -lEi -- '(transition|animation|@keyframes)' >/dev/null 2>&1; then
+  if printf '%s\n' "$files" | xargs grep -lEi -- 'prefers-reduced-motion' >/dev/null 2>&1; then
+    ok "reduced-motion: honoured somewhere"
+  else
+    warn "reduced-motion: this project animates and never mentions prefers-reduced-motion — unchecked means unfinished"
+  fi
+fi
+
+echo
+if [ "$warn_count" -gt 0 ]; then
+  echo "$warn_count finding(s)."
+  [ "$STRICT" -eq 1 ] && exit 1
+else
+  echo "No findings."
+fi
+exit 0

package/skills/react/SKILL.md

@@ -10,8 +10,8 @@ origin: risco
 
 **Hand-off — picking dependencies.** Which library to reach for (UI primitives, command menus,
 toasts, OTP inputs, charts, virtualization, drag and drop, state, styling, theming) is
-`../pick-ui-library/SKILL.md`'s — reach for it before hand-rolling a component. Animating what you
-install is `../animate/SKILL.md`'s.
+`../ui-engineering/SKILL.md`'s — build vs adopt is decided there, before hand-rolling a component. Animating what you
+install is `../motion-craft/SKILL.md`'s.
 
 
 > Build or review a fast, typed, correctly-architected **client-side** React single-page app bundled by Vite. No server runtime, no RSC tree, no framework router. Server-rendered React (App Router, server actions, SSR/SSG) is not this skill — that is `../nextjs/SKILL.md`.

package/skills/react-native/SKILL.md

@@ -10,7 +10,7 @@ origin: risco
 
 **Hand-off — the app vs its motion.** Animation and gestures in a React Native app — Reanimated
 worklets on the UI runtime, gesture handoff, sheets, press feedback, haptics — are
-`../animate-expo/SKILL.md`'s, whose guidance applies to bare React Native as well as Expo.
+`../motion-craft/SKILL.md`'s, whose guidance is platform-agnostic and applies to bare React Native as well as Expo.
 
 
 You write the code that runs *inside* the app: render, navigate, animate, list, persist, and author native modules. Mobile is split across two skills by **verb** — run the verb test before doing anything:

package/skills/swift-ios/SKILL.md

@@ -12,8 +12,8 @@ origin: risco
 **Hand-off — the language vs the platform.** This skill owns the **platform**: SwiftUI/UIKit views,
 app lifecycle, Xcode, iOS APIs, App Store shipping. Language-level Swift — Swift 6 data-race safety
 and approachable concurrency, actors and task groups, `some` vs `any`, ARC and performance, Swift
-Testing, macros — is `../write-swift/SKILL.md`'s. A concurrency error, a hang, a data race or a
-retain cycle goes there, not here. Interface feel, springs and materials: `../apple-design/SKILL.md`.
+Testing, macros — is this skill's own ground. A concurrency error, a hang, a data race or a
+retain cycle belongs here. Interface feel, springs and materials: `../motion-craft/SKILL.md`.
 
 
 Native Apple-platform apps: the code is `.swift`, the UI is SwiftUI, and the compiler enforces actor isolation. If the answer is a `@MainActor`, `@Observable`, `async let`, `#expect`, `NavigationStack`, or `@Model`, you are in the right place.

package/skills/ui-engineering/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: ui-engineering
+description: "Use when the question is how interface should be BUILT — component boundaries, state that belongs in the URL vs the component, loading/empty/error states, forms, optimistic updates, build vs adopt. NOT the visual system (`design`), NOT framework mechanics (`react`/`nextjs`)."
+tags: [interface, frontend, architecture, components, state, craft]
+recommends: [design, motion-craft]
+profiles: [core, full]
+origin: risco
+---
+
+# UI engineering — the decisions between the design and the framework
+
+There is a layer that neither the design skill nor the framework skill owns. The design says what
+the screen should be. The framework says how its API works. **In between sits every decision that
+makes an interface either durable or a maintenance tax** — and it is where most interface work
+actually goes wrong.
+
+Nothing here is framework-specific. These decisions are the same in React, Vue, Svelte, SwiftUI and
+plain HTML; only the syntax moves.
+
+## The one rule
+
+**State goes to the outermost place that still needs it, and no further.** Almost every interface
+tangle is that rule broken in one of two directions: state hoarded in a component that others need,
+or state hoisted into a global store that only one component ever reads.
+
+| Where the state lives | When that is right |
+| --- | --- |
+| **The URL** | Anything a user would bookmark, share, or expect the back button to restore: filters, tabs, pagination, the open item |
+| **The server** | Anything that outlives the session or belongs to more than one user |
+| **A shared parent** | Two siblings genuinely need it, and it dies with the screen |
+| **The component** | Nobody else reads it: hover, focus, an open menu, an in-flight draft |
+
+The most common and most expensive mistake is the first row: state that belongs in the URL kept in a
+component. It looks fine until someone reloads, shares a link, or presses back — and then the
+interface silently loses what the user did.
+
+## Every state, not just the happy one
+
+An interface is not finished when it renders data. It is finished when it renders **all five**:
+
+| State | The question it answers | The usual failure |
+| --- | --- | --- |
+| **Loading** | "Is it working?" | A spinner where the shape is already known — use the shape |
+| **Empty** | "Is it broken, or is there nothing?" | Blank. It must say which, and what to do next |
+| **Error** | "What now?" | A message with no action. Every denial carries its own way out |
+| **Partial** | "Some of it failed" | Ignored entirely; the screen shows a half-truth |
+| **Success** | "It worked" | Silence, so the user does it twice |
+
+The empty state is the one that gets skipped, and it is the first state a new user ever sees.
+
+## Component boundaries
+
+A component earns its existence by **hiding a decision**, not by being reused. Splitting for reuse
+alone produces the worst interfaces: a wrapper around a wrapper, each passing props through, none
+owning anything.
+
+Draw the boundary where:
+
+- it owns a piece of state nothing outside needs;
+- it can be described in one sentence without "and";
+- swapping its internals changes nothing outside it.
+
+Do **not** draw a boundary because a file is long. Long is not a defect; a file that does two
+unrelated things is, and it is usually short.
+
+## Forms
+
+Forms are where interfaces most often insult people, and the rules are unglamorous:
+
+- **Validate on blur, not on keystroke.** Telling someone their email is invalid while they are on
+  the third character is scolding them for not having finished.
+- **Never clear what they typed.** Not on error, not on refresh, not on navigation. Their input is
+  theirs.
+- **Disable the submit only while submitting**, never as a way of enforcing validity — a disabled
+  button with no reason is a dead end.
+- **The error goes next to the field**, and says what to do, not what is wrong.
+
+## Optimistic updates
+
+Show the result before the server confirms **only** when you can honestly undo it. That means: the
+operation is idempotent, the failure is rare, and reverting it is visible and comprehensible.
+
+Optimism on a destructive or an expensive action is a lie you will have to retract in front of the
+user. Deleting, paying, sending — those wait.
+
+## Build or adopt
+
+Adopting a component costs bundle size, an API you did not design, and an upgrade you will owe
+later. Building costs the accessibility work you will get wrong.
+
+The split is not about difficulty, it is about **who is the authority on the behaviour**:
+
+- **Adopt** for behaviour with a specification you would otherwise be reimplementing badly: focus
+  trapping, combobox semantics, date handling, virtualisation.
+- **Build** for anything that is your product's own logic wearing a UI, or where the library gives
+  you 60% and you fight the remaining 40% forever.
+
+## Anti-patterns → STOP
+
+| If you're about to… | Reality / Fix |
+| --- | --- |
+| Put a filter or tab selection in component state | It belongs in the URL. Reload, share and back are part of the interface. |
+| Add a global store because passing props feels tedious | Tedious is not broken. Global state that one component reads is a leak with ceremony. |
+| Ship a screen with only the loaded state | Loading, empty, error and partial are not extras. The empty one is what a new user sees first. |
+| Split a component because the file got long | Length is not the defect. Two unrelated responsibilities are, and they are usually short. |
+| Show a delete as done before the server confirms | Optimism on a destructive action is a lie you will retract in public. |
+| Reach here for how the framework's hooks work | That is `../react/SKILL.md` or `../nextjs/SKILL.md`. This skill decides what to build; those decide how to express it. |
+
+## See Also
+
+- `../design/SKILL.md` — the visual system these decisions serve.
+- `../motion-craft/SKILL.md` — how the pieces here move once they exist.
+- `../design-loop/SKILL.md` — the graded critique that judges the result.
+- `../accessibility/SKILL.md` — the ground under focus, semantics and forms.

package/skills/ui-engineering/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: ui-engineering
+
+should_trigger:
+  - prompt: "Where should the filter state live — component, context or the URL?"
+    why: "The canonical case: the one rule this skill exists to apply."
+  - prompt: "How should I split these components? The file is getting big."
+    why: "Component boundaries, and the file-length premise is one this skill corrects."
+  - prompt: "We only render the loaded state. What else does this screen need?"
+    why: "The five states are the checklist this skill owns."
+  - prompt: "¿Valido el formulario mientras escribe o al salir del campo?"
+    why: "Form behaviour, in Spanish; the trigger is the decision, not the language."
+  - prompt: "Should I use a component library for the date picker or build it?"
+    why: "Build vs adopt, decided by who owns the behaviour's specification."
+  - prompt: "Can we show the delete as done immediately and roll back if it fails?"
+    why: "Optimistic updates, and this is the case where the answer is no."
+
+should_not_trigger:
+  - prompt: "Design the pricing page — layout, type scale, the colour system."
+    route_to: "design"
+    why: "The visual system is decided before this layer has anything to build."
+  - prompt: "My useEffect runs twice in development and I don't understand why."
+    route_to: "react"
+    why: "Framework mechanics. This skill decides what to build, not how the framework behaves."
+  - prompt: "The dropdown animation feels cheap, what duration should it use?"
+    route_to: "motion-craft"
+    why: "Once the component exists, how it moves is motion craft."
+  - prompt: "Grade this dashboard and tell me if it is actually good."
+    route_to: "design-loop"
+    why: "Judging a finished screen is the critique loop, not the build decisions."
+  - prompt: "Set up the Next.js App Router with server actions for this project."
+    route_to: "nextjs"
+    why: "Stack setup is the stack skill's; this one is framework-agnostic by construction."
+
+capability:
+  - prompt: "Our search page keeps its query and filters in component state. Users complain the back button loses everything. What is wrong and what is the fix?"
+    why: "The single most expensive instance of the one rule, stated as a real symptom rather than as theory."
+  - prompt: "This list screen shows a spinner, then rows. What states are we missing and why does each matter?"
+    why: "Forces the five-state checklist, including the empty state that a new user sees first."

package/skills/variant-explorer/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: variant-explorer
+description: "Use when someone wants OPTIONS rather than an answer — 'show me a few versions', picking between approaches by seeing them. Genuinely different candidates, cheap to throw away, trade-off named. NOT the critique that judges one (`design-loop`), NOT the spec (`specify`)."
+tags: [prototyping, divergence, options, exploration, decision]
+recommends: [design-loop]
+profiles: [full]
+origin: risco
+---
+
+# Variant explorer — several real options, cheap enough to discard
+
+"Show me a few versions and I'll pick" is a different request from "build this". It asks for
+**divergence**: several candidates that are actually different, each cheap enough that throwing it
+away costs nothing, with the difference between them stated out loud so a human can decide.
+
+Done badly it produces the thing that wastes the most time in creative work: three variations of one
+idea, dressed up as a choice.
+
+## The one rule
+
+**Variants must differ in a decision, not in a detail.** If two candidates could both be reached by
+editing the other, there is one candidate.
+
+```text
+Not variants:   the same layout in blue, in green, in dark
+Variants:       a single scrolling page · a three-step wizard · a table with inline editing
+```
+
+The test before showing anything: **name the decision each variant is taking.** If you cannot name
+it, or two share it, that set is not ready.
+
+## How many, and how finished
+
+- **Three.** Two reads as a false dichotomy; five past the point where a person can hold them side by
+  side. Three forces the middle option to justify itself.
+- **Finished enough to judge the decision, and no more.** If the decision is about structure, the
+  copy can be placeholder. If it is about tone, the layout can be crude. Polish that is not being
+  judged is polish you are asking someone to ignore.
+- **Comparable.** Same content, same constraints, same fidelity across all three. A variant that is
+  prettier wins for reasons nobody chose.
+
+## Making them genuinely different
+
+The failure mode is anchoring: the first idea contaminates the rest. Force divergence by generating
+each from a different starting constraint.
+
+| Angle | Ask |
+| --- | --- |
+| **Cheapest** | What if this had to ship this week? |
+| **Boldest** | What if we ignored what similar products do? |
+| **Fewest steps** | What if the user only did one thing? |
+| **Familiar** | What if it worked exactly like the thing they already know? |
+| **Inverted** | What if the primary and secondary swapped? |
+
+Pick three angles that are actually in tension for this problem. Do not run all five — the point is
+tension, not coverage.
+
+## Presenting them so a decision is possible
+
+Each candidate carries three things, and no more:
+
+1. **What decision it takes** — one sentence, in the user's terms.
+2. **What it costs** — the honest downside, not a hedge. A variant with no downside is one you have
+   not thought about.
+3. **What it would take to be wrong** — the fact that would kill it.
+
+Then: **a recommendation.** Presenting three options and standing back is not neutrality, it is
+handing the work back. Say which one you would pick and why, and make it easy to overrule.
+
+## When this is the wrong skill
+
+- The answer is already known and only needs building → build it. Manufacturing options to look
+  thorough wastes everyone's time.
+- The decision is reversible and cheap → just pick one and ship. Exploration is for decisions that
+  are expensive to unwind.
+- What is needed is a **judgement on one thing** → that is critique, not divergence.
+
+## Anti-patterns → STOP
+
+| If you're about to… | Reality / Fix |
+| --- | --- |
+| Show the same idea in three colours | Those are not variants. Name the decision each takes; if you cannot, you have one. |
+| Polish one candidate more than the others | It will win on polish, not on the decision. Same fidelity, always. |
+| Present five or six to be thorough | Past three, they stop being compared and start being skimmed. |
+| Give options with no recommendation | Standing back is not neutrality; it hands the work back to the person who asked. |
+| Explore a decision that is cheap to reverse | Just ship one. Divergence is for what is expensive to unwind. |
+| Keep iterating on the winner here | Once one is chosen, refining it is `../design-loop/SKILL.md` or the relevant build skill. |
+
+## See Also
+
+- `../design-loop/SKILL.md` — the graded critique that takes over once a direction is chosen.
+- `../specify/SKILL.md` — when what is missing is an agreed WHAT/WHY, not options.
+- `../design/SKILL.md` — building the chosen direction properly.

package/skills/variant-explorer/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: variant-explorer
+
+should_trigger:
+  - prompt: "Show me a few versions of this onboarding and I'll pick one."
+    why: "The canonical phrasing: options to choose from, not an answer."
+  - prompt: "Give me three directions for how this could work before we commit."
+    why: "Explicit divergence ahead of an expensive decision."
+  - prompt: "Enséñame varias opciones de cómo montar el checkout, que ya elijo yo."
+    why: "Same request in Spanish; the trigger is the ask for options."
+  - prompt: "I can't decide between a wizard and a single page. Can I see both?"
+    why: "Two named approaches where seeing them is what settles it."
+  - prompt: "What are some different ways we could structure this dashboard?"
+    why: "Open-ended exploration of structural decisions, which is exactly divergence."
+  - prompt: "Before we build it, I want to compare a couple of approaches side by side."
+    why: "Comparability is the property this skill guarantees."
+
+should_not_trigger:
+  - prompt: "Review this checkout screen and grade it."
+    route_to: "design-loop"
+    why: "Judging one finished thing is critique, the opposite of divergence."
+  - prompt: "We need to agree what this feature is for before anyone builds it."
+    route_to: "specify"
+    why: "A missing WHAT/WHY is a spec problem; options would be premature."
+  - prompt: "Build the pricing page we agreed on last week."
+    route_to: "design"
+    why: "The decision is already made; manufacturing options would waste the time this skill is meant to save."
+  - prompt: "Which colour should the primary button be?"
+    route_to: "design"
+    why: "Cheap and reversible, and a detail rather than a decision — the explicit non-case here."
+  - prompt: "Run an A/B test to see which headline converts better."
+    route_to: "ab-testing"
+    why: "Measuring a winner with users is experimentation, not showing a human candidates to choose from."
+
+capability:
+  - prompt: "Give me three options for this signup flow. Make sure they are actually different, not the same thing restyled."
+    why: "Goes straight at the failure mode this skill exists to prevent, and demands the decision behind each be nameable."
+  - prompt: "Here are three variants I made. Are these real alternatives or the same idea three times?"
+    why: "Applies the one rule as a test on someone else's set, which is where it is hardest and most useful."

package/targets/agent-catalog.js

@@ -0,0 +1,220 @@
+const REVIEW_TOOLS = Object.freeze(['read', 'search']);
+const RESOLVER_TOOLS = Object.freeze(['read', 'search', 'edit', 'shell']);
+
+const reviewerBody = ({ label, scope, probes, escalation = '' }) => `You are the ${label} reviewer. Review the requested diff or pull request; do not edit files.
+
+Boundary: ${scope}
+
+Work from changed lines outward just far enough to verify callers, imports, guards, and tests. Record an **attack list** even when every attack is clean. For each proposed finding, answer before reporting:
+1. What exact changed line supports it?
+2. What concrete input and state produce what wrong result?
+3. Which caller, import, and relevant test did you inspect?
+4. Why do existing guards not reduce the severity?
+
+HIGH and CRITICAL findings require the exact line and the full failure path. If either is missing, lower the severity or omit the finding. Prefer a clean verdict with a useful attack list over speculative volume.
+
+Stack attacks:
+${probes.map((probe) => `- ${probe}`).join('\n')}
+${escalation ? `\n${escalation}\n` : ''}
+Return: scope, attack list, findings ordered by severity, and verdict. A finding names file:line, failure mode, evidence, and the smallest test that would expose it.`;
+
+const resolverBody = ({ label, scope, signals, attempts = 3 }) => `You are the ${label} build resolver. Diagnose and repair one failing build with the smallest stack-correct change.
+
+Boundary: ${scope}
+
+1. Reproduce the named failure and preserve its exact command and first causal diagnostic.
+2. Trace that diagnostic to configuration, dependency, generated code, compiler, linker, or runtime setup.
+3. Change only what is needed for that cause; do not refactor, upgrade broadly, or clean unrelated warnings.
+4. Re-run the narrow failing command, then the nearest relevant test/build gate.
+5. Stop after ${attempts} unsuccessful repair attempts or as soon as the next step requires a refactor or product choice.
+
+Signals to distinguish:
+${signals.map((signal) => `- ${signal}`).join('\n')}
+
+Return the root cause, commands run, files changed, proof of the result, and any remaining blocker.`;
+
+const reviewer = ({ name, label, skills, not, probes, should, shouldNot, tier = 'balanced', escalation }) => ({
+  name,
+  role: 'reviewer',
+  tier,
+  tools: [...REVIEW_TOOLS],
+  skills,
+  desc: `${label} reviewer: inspects changed code for stack-specific failure modes and reports evidence without editing. NOT ${not}.`,
+  routing: { should, shouldNot },
+  body: reviewerBody({ label, scope: `Use for ${skills.join(' or ')} code. NOT ${not}.`, probes, escalation }),
+});
+
+const resolver = ({ name, label, skills, not, signals, should, shouldNot, tier = 'balanced' }) => ({
+  name,
+  role: 'build-resolver',
+  tier,
+  tools: [...RESOLVER_TOOLS],
+  skills,
+  desc: `${label} build resolver: reproduces a failing build and applies the minimum verified repair. NOT ${not}.`,
+  routing: { should, shouldNot },
+  body: resolverBody({ label, scope: `Use for ${skills.join(' or ')} build failures. NOT ${not}.`, signals }),
+});
+
+const REVIEWERS = [
+  reviewer({
+    name: 'django-reviewer', label: 'Django', skills: ['django'], not: 'general Python review or build repair',
+    probes: ['QuerySet evaluation, N+1 reads, and accidental full-table work.', 'Transaction boundaries, row locking, retries, and side effects inside atomic blocks.', 'Migration reversibility, historical models, nullable transitions, and deploy ordering.', 'Authorization at object/query boundaries rather than only at the view.'],
+    should: ['Review a Django ORM diff for query and transaction defects.'], shouldNot: ['Fix a failing Django migration command.'],
+  }),
+  reviewer({
+    name: 'java-reviewer', label: 'Java and Spring', skills: ['java', 'spring-boot'], not: 'Android/Kotlin review or generic build repair',
+    probes: ['Nullability and Optional contracts across public boundaries.', 'Equality, hashing, mutability, and collection aliasing.', 'Spring proxy boundaries: transactions, self-invocation, scopes, and configuration binding.', 'Thread ownership, blocking work, interruption, and resource closure.'],
+    should: ['Review a Spring transaction change.'], shouldNot: ['Repair a Gradle dependency resolution failure.'],
+  }),
+  reviewer({
+    name: 'kotlin-reviewer', label: 'Kotlin Android', skills: ['kotlin-android'], not: 'Java server review or Gradle repair',
+    probes: ['Coroutine scope ownership, cancellation, dispatcher choice, and exception propagation.', 'Lifecycle collection, recomposition stability, and state restoration.', 'Nullable/platform types and sealed-state exhaustiveness.', 'Context/activity retention and Android resource lifetime.'],
+    should: ['Review a coroutine-driven Android screen.'], shouldNot: ['Resolve an Android Gradle Plugin mismatch.'],
+  }),
+  reviewer({
+    name: 'flutter-reviewer', label: 'Flutter', skills: ['flutter'], not: 'native Android review or Flutter build repair',
+    probes: ['Widget identity, keys, rebuild scope, and stale BuildContext use.', 'Controller, subscription, isolate, and animation disposal.', 'Async mounted checks and state changes after teardown.', 'Platform-channel contracts and divergent iOS/Android behavior.'],
+    should: ['Review a Flutter widget state diff.'], shouldNot: ['Fix a CocoaPods build failure.'],
+  }),
+  reviewer({
+    name: 'react-reviewer', label: 'React and Next.js', skills: ['react', 'nextjs'], not: 'Vue review or frontend build repair',
+    probes: ['Render purity, hook dependency identity, stale closures, and effect cleanup.', 'Server/client boundaries, serialization, caching, and request-scoped data.', 'Concurrent rendering races, transitions, hydration, and optimistic rollback.', 'Keys, controlled state, accessibility semantics, and error/loading states.'],
+    should: ['Review a Next.js server/client boundary.'], shouldNot: ['Repair a webpack or Turbopack build.'],
+  }),
+  reviewer({
+    name: 'rust-reviewer', label: 'Rust', skills: ['rust'], not: 'C++ review or Cargo build repair',
+    probes: ['Ownership workarounds that hide lifetime or aliasing defects.', 'Unsafe blocks: stated invariant, pointer provenance, layout, and synchronization.', 'Error propagation, panic reachability, and poisoned/shared state.', 'Async cancellation, Send/Sync assumptions, locks across await, and task lifetime.'],
+    should: ['Review an unsafe Rust boundary.'], shouldNot: ['Fix a Cargo feature conflict.'],
+  }),
+  reviewer({
+    name: 'swift-reviewer', label: 'Swift iOS', skills: ['swift-ios'], not: 'Kotlin review or Xcode build repair',
+    probes: ['Actor isolation, Sendable claims, cancellation, and main-thread ownership.', 'Reference cycles, escaping closures, and resource lifetime.', 'Value/reference semantics, copy-on-write, and mutation through shared state.', 'View identity, navigation state, persistence, and platform availability.'],
+    should: ['Review Swift concurrency changes in an iOS app.'], shouldNot: ['Resolve a signing or linker failure.'],
+  }),
+  reviewer({
+    name: 'go-reviewer', label: 'Go', skills: ['go'], not: 'generic service review or Go build repair',
+    probes: ['Goroutine lifetime, cancellation ownership, channel closure, and races.', 'Error wrapping and identity where callers use errors.Is or errors.As.', 'Interface nil values, slice/map aliasing, loop capture, and deferred cleanup lifetime.', 'API and doc-comment contracts, zero values, receiver choice, and lock copying.'],
+    should: ['Review Go concurrency and error handling.'], shouldNot: ['Repair a missing Go module or compile error.'],
+  }),
+  reviewer({
+    name: 'cpp-reviewer', label: 'C++', skills: ['cpp'], not: 'Rust review or compiler/linker repair',
+    probes: ['Ownership expressed through RAII and any raw pointer whose lifetime is unstated.', 'Dangling views/references, moved-from values, invalidation, and destructor behavior.', 'Bounds, narrowing, signedness, undefined behavior, and exception guarantees.', 'Synchronization, data races, virtual destruction, and unsafe casts.'],
+    should: ['Review a C++ ownership or lifetime diff.'], shouldNot: ['Resolve a CMake or linker failure.'],
+  }),
+  reviewer({
+    name: 'vue-reviewer', label: 'Vue and Nuxt', skills: ['vue-nuxt'], not: 'React review or Vue build repair',
+    probes: ['Reactive identity, destructuring, watcher cleanup, and computed side effects.', 'SSR/client divergence, hydration, route middleware, and request-scoped state.', 'Composable lifetime, provide/inject contracts, and error/loading states.', 'Template keys, accessibility semantics, and unsafe rendered content.'],
+    should: ['Review a Nuxt SSR and hydration diff.'], shouldNot: ['Fix a Vite build.'],
+  }),
+  reviewer({
+    name: 'csharp-reviewer', label: 'C# and .NET', skills: ['csharp-dotnet'], not: 'Java review or dotnet build repair',
+    probes: ['Async cancellation, sync-over-async, disposal, and scoped service lifetime.', 'Nullable annotations versus runtime validation and serializer behavior.', 'LINQ query translation, repeated enumeration, tracking, and transaction scope.', 'Records/equality, mutable shared state, authorization, and configuration binding.'],
+    should: ['Review an ASP.NET or EF Core change.'], shouldNot: ['Repair a NuGet restore failure.'],
+  }),
+  reviewer({
+    name: 'php-reviewer', label: 'PHP and Laravel', skills: ['laravel', 'php'], not: 'Django review or Composer/build repair',
+    probes: ['Request validation, mass assignment, policy scope, and tenant isolation.', 'Eloquent loading, query count, transactions, and queued work after commit.', 'PHP type coercion, nullable boundaries, array shape assumptions, and error conversion.', 'Migration deploy ordering, cache/config behavior, and serialization.'],
+    should: ['Review Laravel authorization and ORM code.'], shouldNot: ['Resolve a Composer dependency error.'],
+  }),
+  reviewer({
+    name: 'typescript-reviewer', label: 'TypeScript', skills: ['typescript'], not: 'framework-specific UI review or TypeScript build repair',
+    probes: ['Runtime validation at boundaries where static types disappear.', 'Unsound assertions, any/unknown narrowing, variance, and optional-property semantics.', 'Promise ownership, rejection paths, cancellation, and event-listener cleanup.', 'Module/export contracts and type/value divergence across build targets.'],
+    should: ['Review a TypeScript library API diff.'], shouldNot: ['Fix tsconfig or bundler errors.'],
+  }),
+  reviewer({
+    name: 'fastapi-reviewer', label: 'FastAPI', skills: ['fastapi'], not: 'generic Python review or environment repair',
+    probes: ['Dependency lifetime and cleanup, override leakage, and request-scoped state.', 'Async blocking, cancellation, background task ownership, and exception mapping.', 'Pydantic input/output boundaries, partial updates, and response data exposure.', 'Authorization per resource, transaction completion, and OpenAPI contract drift.'],
+    should: ['Review a FastAPI endpoint and dependency change.'], shouldNot: ['Repair a Python package installation.'],
+  }),
+  reviewer({
+    name: 'python-reviewer', label: 'Python', skills: ['python'], not: 'FastAPI/Django-specific review or environment repair',
+    probes: ['Async tasks that are never awaited, cancellation loss, and TaskGroup failure propagation.', 'Mutable defaults, late binding, descriptor/protocol behavior, and truthiness edge cases.', 'Context-manager and iterator cleanup, exception chaining, and generator finalization.', 'Shared mutable state, import-time effects, typing/runtime gaps, and process/thread boundaries.'],
+    should: ['Review Python language and asyncio correctness.'], shouldNot: ['Review Django ORM behavior.'],
+  }),
+  reviewer({
+    name: 'postgres-reviewer', label: 'PostgreSQL', skills: ['postgresdb'], not: 'application ORM review or migration execution',
+    probes: ['Lock strength/order, long transactions, deadlocks, and concurrent DDL behavior.', 'Index/operator compatibility, selectivity, null semantics, and query-plan regressions.', 'RLS policy coverage, SECURITY DEFINER/search_path, grants, and tenant isolation.', 'Migration reversibility, constraint validation, backfill batching, and replication effects.'],
+    should: ['Review a PostgreSQL migration and policy diff.'], shouldNot: ['Run or repair application migrations.'],
+  }),
+  reviewer({
+    name: 'rag-reviewer', label: 'RAG', skills: ['rag'], not: 'general ML training review or retrieval implementation',
+    probes: ['Evaluation set leakage, temporal leakage, and mismatch between offline and live queries.', 'Chunk/metadata identity, permission filtering before retrieval, and deletion propagation.', 'Recall/rerank trade-offs, empty retrieval, citation grounding, and abstention.', 'Embedding/model/index version compatibility and rollback behavior.'],
+    should: ['Review a retrieval pipeline for leakage and grounding.'], shouldNot: ['Tune a neural training loop.'],
+  }),
+  reviewer({
+    name: 'mle-reviewer', label: 'production ML', skills: ['machine-learning'], not: 'notebook style review or model training implementation', tier: 'heavy',
+    probes: ['Temporal/entity leakage in splits and features available only after prediction time.', 'Training-serving schema skew, data contracts, null/category drift, and feature ownership.', 'Promotion gates that fail open, canary comparability, monitoring delay, and rollback without retraining.', 'Reproducible artifacts: data/code/model lineage, seeds, environment, and deterministic evaluation.'],
+    should: ['Review an ML promotion and rollback pipeline.'], shouldNot: ['Implement or tune the model.'],
+  }),
+];
+
+const RESOLVERS = [
+  resolver({ name: 'django-build-resolver', label: 'Django', skills: ['django'], not: 'ORM performance review or feature refactoring', signals: ['Migration graph conflicts versus unapplied migrations.', 'Settings/import errors versus database connectivity.', 'Static collection/template failures versus application tests.'], should: ['Fix a failing Django migrate/check command.'], shouldNot: ['Review an ORM diff for N+1 queries.'] }),
+  resolver({ name: 'java-build-resolver', label: 'Java and Spring', skills: ['java', 'spring-boot'], not: 'code review or broad dependency upgrades', signals: ['Compiler diagnostics versus annotation/generated-source failures.', 'Maven/Gradle resolution versus toolchain/JDK mismatch.', 'Spring context/bootstrap failures versus test assertion failures.'], should: ['Fix a Gradle/Maven/Spring build failure.'], shouldNot: ['Review transaction correctness.'] }),
+  resolver({ name: 'kotlin-build-resolver', label: 'Kotlin Android', skills: ['kotlin-android'], not: 'UI/coroutine review or project modernization', signals: ['Kotlin/AGP/Gradle/JDK compatibility.', 'KSP/KAPT/generated source failures.', 'Manifest/resource merge versus compiler diagnostics.'], should: ['Repair an Android Gradle build.'], shouldNot: ['Review Compose state.'] }),
+  resolver({ name: 'flutter-build-resolver', label: 'Flutter', skills: ['flutter'], not: 'widget review or package modernization', signals: ['Dart analyzer/compile errors versus generated-code drift.', 'CocoaPods/Xcode signing versus Android Gradle failures.', 'Plugin platform constraints versus app code failures.'], should: ['Repair a Flutter build failure.'], shouldNot: ['Review widget lifecycle.'] }),
+  resolver({ name: 'react-build-resolver', label: 'React and Next.js', skills: ['react', 'nextjs'], not: 'UI review or broad package upgrades', signals: ['Type/lint failure versus bundler/module resolution.', 'Server/client boundary or static rendering diagnostics.', 'Environment/config presence versus application logic.'], should: ['Repair a Next.js or React production build.'], shouldNot: ['Review hydration correctness.'] }),
+  resolver({ name: 'rust-build-resolver', label: 'Rust', skills: ['rust'], not: 'unsafe-code review or dependency modernization', signals: ['Borrow/type diagnostics versus feature unification.', 'Build-script/native library/linker failures.', 'Toolchain/edition mismatch versus source error.'], should: ['Repair a Cargo build failure.'], shouldNot: ['Review unsafe invariants.'] }),
+  resolver({ name: 'swift-build-resolver', label: 'Swift iOS', skills: ['swift-ios'], not: 'concurrency review or signing-policy changes', signals: ['Swift compiler/generic diagnostics versus package resolution.', 'Linker/module map/generated interface failure.', 'Simulator/device availability versus signing/provisioning.'], should: ['Repair an Xcode or SwiftPM build.'], shouldNot: ['Review actor isolation.'] }),
+  resolver({ name: 'go-build-resolver', label: 'Go', skills: ['go'], not: 'concurrency review or module-wide upgrades', signals: ['Compiler/type error versus generated code drift.', 'Module/version/sum failure versus private module credentials.', 'CGO/toolchain/linker failure versus test failure.'], should: ['Repair a go build failure.'], shouldNot: ['Review goroutine lifetime.'] }),
+  resolver({ name: 'cpp-build-resolver', label: 'C++', skills: ['cpp'], not: 'ownership review or build-system modernization', signals: ['Compiler diagnostic versus template instantiation cause.', 'CMake/configuration/generator failure versus source failure.', 'Undefined reference/ABI/library order versus runtime test failure.'], should: ['Repair a CMake/compiler/linker failure.'], shouldNot: ['Review C++ lifetime safety.'] }),
+  resolver({ name: 'pytorch-build-resolver', label: 'PyTorch', skills: ['machine-learning'], not: 'model-quality review or training redesign', signals: ['Python package/import mismatch versus compiled extension ABI.', 'CUDA/driver/toolkit/architecture incompatibility.', 'Distributed launcher/environment failure versus model code failure.'], should: ['Repair a PyTorch environment or extension build.'], shouldNot: ['Review data leakage or model promotion.'] }),
+];
+
+const SPEC_MINER = {
+  name: 'spec-miner',
+  role: 'spec-miner',
+  tier: 'heavy',
+  tools: ['read', 'search', 'edit'],
+  skills: [],
+  desc: 'Brownfield spec miner: extracts an anchored SDD draft from existing code under a bounded read budget. NOT feature planning or overwriting an approved spec.',
+  routing: {
+    should: ['Extract an initial SDD spec from an existing repository with no specs.'],
+    shouldNot: ['Design a new feature or amend an approved spec in place.'],
+  },
+  body: `You are the brownfield spec miner. Produce an **extracted draft**, never a claim that undocumented intent is approved.
+
+Read at most 40 files or 20,000 lines. Start from entry points, public interfaces, tests, schemas, migrations, configuration, and user-facing documentation. For every inferred invariant, cite a stable repository anchor (symbol plus path; line only as a convenience). Separate observed behavior, inferred requirement, contradiction, and unknown.
+
+Write a new SDD-shaped draft with problem, users, observable behavior, invariants, non-goals, acceptance criteria, source anchors, and open points. Mark status extracted-draft. If the intended slug already has an approved spec, do not edit it: propose a new slug or a revision artifact. Do not plan implementation or invent product intent absent from evidence.
+
+Return the read budget used, artifacts inspected, confidence per requirement, and the draft path.`,
+};
+
+const STACK_AGENTS = Object.freeze([...REVIEWERS, ...RESOLVERS, SPEC_MINER]);
+
+export const STACK_AGENT_BY_SKILL = Object.freeze(Object.fromEntries(
+  ['django', 'java', 'spring-boot', 'kotlin-android', 'flutter', 'react', 'nextjs', 'rust', 'swift-ios', 'go', 'cpp', 'vue-nuxt', 'csharp-dotnet', 'laravel', 'php', 'typescript', 'fastapi', 'python', 'postgresdb', 'rag', 'machine-learning']
+    .map((skill) => [skill, STACK_AGENTS.filter((agent) => agent.skills.includes(skill)).map((agent) => agent.name)]),
+));
+
+export const stackAgents = () => STACK_AGENTS.map((agent) => ({ ...agent, tools: [...agent.tools], skills: [...agent.skills], routing: { should: [...agent.routing.should], shouldNot: [...agent.routing.shouldNot] } }));
+export const stackAgentNames = () => STACK_AGENTS.map((agent) => agent.name);
+export const stackAgentByName = (name) => STACK_AGENTS.find((agent) => agent.name === name);
+
+export function resolveStackAgentNames(skillIds = [], explicitAgentIds = []) {
+  const names = new Set();
+  for (const skill of skillIds) for (const name of STACK_AGENT_BY_SKILL[skill] || []) names.add(name);
+  for (const name of explicitAgentIds) if (stackAgentByName(name)) names.add(name);
+  return [...names].sort();
+}
+
+export function validateAgentCatalog(definitions = STACK_AGENTS) {
+  const errors = [];
+  const seen = new Set();
+  const allowedRoles = new Set(['reviewer', 'build-resolver', 'spec-miner']);
+  for (const agent of definitions) {
+    const prefix = agent?.name || '<unnamed>';
+    if (!agent?.name || seen.has(agent.name)) errors.push(`${prefix}: unique name required`);
+    seen.add(agent?.name);
+    if (!agent?.desc?.includes('NOT ')) errors.push(`${prefix}: description requires a NOT boundary`);
+    if (!allowedRoles.has(agent?.role)) errors.push(`${prefix}: invalid role`);
+    if (!['balanced', 'heavy'].includes(agent?.tier)) errors.push(`${prefix}: tier must be balanced or heavy`);
+    if (!agent?.routing?.should?.length || !agent?.routing?.shouldNot?.length) errors.push(`${prefix}: routing cases required`);
+    if (Buffer.byteLength(agent?.body || '', 'utf8') > 6500) errors.push(`${prefix}: body exceeds 6500 bytes`);
+    if (/everything[- ]claude|affaan|worldflow|\.claude\/plugins\/ecc/iu.test(`${agent?.desc || ''}\n${agent?.body || ''}`)) errors.push(`${prefix}: foreign project vocabulary`);
+    if (agent?.role === 'reviewer' && JSON.stringify(agent.tools) !== JSON.stringify(REVIEW_TOOLS)) errors.push(`${prefix}: reviewer tools must be read-only`);
+    if (agent?.role === 'build-resolver' && JSON.stringify(agent.tools) !== JSON.stringify(RESOLVER_TOOLS)) errors.push(`${prefix}: resolver tools must be bounded`);
+  }
+  return errors;
+}