rsc-universal 0.1.1

package/skills/scaling/references/load-testing-k6.md

@@ -0,0 +1,127 @@
+# Load testing with k6
+
+The full hands-on companion to Lever 4 in `../SKILL.md`. k6 is a load generator: you write a JS test, k6 spins up *virtual users* (VUs) that run it in a loop, and it reports latency distribution, throughput, and error rate against the **thresholds** you declared. k6 hit v1.0.0 on 2025-04-28 (SemVer); the current v1 line is v1.7.x and v2.0.0 shipped May 2026.
+
+## Install
+
+```bash
+brew install k6                  # macOS
+docker run --rm -i grafana/k6 run - <script.js   # containerized, no local install
+# linux: see grafana.com/docs/k6 for the apt/yum repo
+```
+
+Verify with `k6 version`.
+
+## The mental model: VU, iteration, stage
+
+- **VU (virtual user):** one concurrent worker running the default function in a loop. 50 VUs ≈ 50 users hammering at once.
+- **Iteration:** one full pass through `export default function`. `sleep()` inside it models think-time between user actions — without it each VU loops as fast as the machine allows, which is unrealistic.
+- **Stage:** a `{ duration, target }` step that ramps VUs up, holds, or ramps down. Stages chained together shape the load profile.
+
+VUs are *not* requests-per-second. RPS is an emergent result of `VUs × (1 / iteration_time)`. If you need an exact RPS, use the `constant-arrival-rate` executor (below) instead of VU stages.
+
+## Thresholds = the SLO gate
+
+Thresholds turn a test into pass/fail. The process exits non-zero when any threshold is breached — that is what lets CI fail the build.
+
+```javascript
+export const options = {
+  thresholds: {
+    http_req_duration: ['p(95)<500', 'p(99)<1500'], // tail latency budget
+    http_req_failed: ['rate<0.01'],                  // <1% errors
+    http_reqs: ['rate>200'],                         // sustained throughput floor
+  },
+};
+```
+
+Note: in Grafana Cloud, thresholds are evaluated every 60 s, so `abortOnFail` can lag up to a minute — fine for CI gating on the final summary, relevant only if you depend on instant aborts.
+
+## The test-type ladder
+
+Run these in order; each answers a different question. Same script, different `stages`.
+
+```javascript
+// SMOKE — does the script work and the system respond at all? (run this first, always)
+stages: [{ duration: '1m', target: 2 }]
+
+// LOAD — does it hold the expected steady-state traffic within SLO?
+stages: [
+  { duration: '2m', target: 100 },   // ramp
+  { duration: '5m', target: 100 },   // hold at expected peak
+  { duration: '2m', target: 0 },
+]
+
+// STRESS — where is the knee? push past expected until latency goes vertical.
+stages: [
+  { duration: '2m', target: 200 },
+  { duration: '5m', target: 200 },
+  { duration: '2m', target: 400 },
+  { duration: '5m', target: 400 },
+  { duration: '2m', target: 0 },
+]
+
+// SPIKE — survive a sudden surge (Product Hunt / Reddit hug) and recover?
+stages: [
+  { duration: '10s', target: 500 },  // slam
+  { duration: '1m', target: 500 },
+  { duration: '10s', target: 0 },    // does it recover, or stay degraded?
+]
+
+// SOAK — any leak/degradation over hours? memory creep, connection exhaustion.
+stages: [
+  { duration: '5m', target: 100 },
+  { duration: '4h', target: 100 },
+  { duration: '5m', target: 0 },
+]
+```
+
+For exact-RPS targets, swap stages for an arrival-rate executor:
+
+```javascript
+export const options = {
+  scenarios: {
+    steady: {
+      executor: 'constant-arrival-rate',
+      rate: 500, timeUnit: '1s',       // 500 rps regardless of latency
+      duration: '5m',
+      preAllocatedVUs: 100, maxVUs: 800,
+    },
+  },
+};
+```
+
+## Reading the summary
+
+After a run, look at three things in order:
+
+1. **`http_req_failed`** — if errors climbed under load, latency numbers are meaningless. Fix capacity/errors first.
+2. **`http_req_duration` p95/p99** — the tail. p50 looking fine while p99 explodes is the classic "most users fine, some users furious" signal.
+3. **The knee** — the VU/RPS level where p95 stops being flat and turns vertical. That number *is* your capacity ceiling. Everything above it is the danger zone.
+
+Export raw results for graphing:
+
+```bash
+k6 run --out json=results.json script.js
+k6 run --out experimental-prometheus-rw script.js   # → Grafana/Prometheus
+```
+
+## CI gate
+
+k6 exits non-zero on threshold breach, so the gate is just the exit code:
+
+```yaml
+# .github/workflows/load-test.yml (excerpt)
+- name: k6 load test (gates on thresholds)
+  run: k6 run --quiet load.js
+  env:
+    TARGET_URL: ${{ secrets.STAGING_URL }}   # prod-like, never localhost
+```
+
+A failed threshold fails the step, which fails the job. No extra assertion logic needed.
+
+## Rules that keep results honest
+
+- **Target a prod-like environment**, ideally staging that mirrors prod (same instance sizes, same DB tier, same pooler). Localhost measures your laptop.
+- **Ramp gradually** in load/stress tests — instant max load tests cold-start behavior, not steady-state. Use the spike test deliberately when cold-start *is* the question.
+- **Decide cache state on purpose.** Warm the cache first to test steady-state, or test stone-cold to measure the miss-storm against the origin — but know which one you're measuring.
+- **Run from outside your own network** when WAN latency and the CDN matter to the result; a runner inside the same VPC hides the real client experience.

package/skills/scaling/scripts/example.load.js

@@ -0,0 +1,24 @@
+// Example k6 load test shipped with the scaling skill.
+// Used as the checkable artifact for verify.sh and as a copy-paste starting point.
+// Run against a PROD-LIKE target, never localhost: TARGET_URL=https://staging.example.com k6 run example.load.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 }, // ramp up to 50 virtual users
+    { duration: '3m', target: 50 }, // hold steady (this is the load test)
+    { duration: '1m', target: 0 },  // ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500'], // SLO: 95% of requests under 500 ms
+    http_req_failed: ['rate<0.01'],   // SLO: under 1% errors
+  },
+};
+
+export default function () {
+  const target = __ENV.TARGET_URL || 'https://staging.example.com';
+  const res = http.get(`${target}/api/health`);
+  check(res, { 'status is 200': (r) => r.status === 200 });
+  sleep(1);
+}

package/skills/scaling/scripts/verify.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# verify.sh — config-validity gate for the scaling skill's k6 artifacts.
+#
+# Read-only by default: it statically asserts that every k6 test script in the
+# skill declares the structure a real load test needs — an `export const options`
+# block, a `thresholds` SLO gate, and a load profile (`stages` or `scenarios`).
+# If `k6` is on PATH it additionally runs `k6 inspect` to confirm the script
+# parses. It never makes a network request and never runs a load test.
+#
+# Exits 0 on a clean/empty target (no k6 scripts found is not a failure).
+# Exits 1 only when a k6 script that DOES exist is missing required structure.
+set -euo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+fail=0
+checked=0
+
+# Collect candidate k6 scripts: every .js under scripts/. We hard-check real .js
+# files; the reference doc is checked best-effort below. Portable to bash 3.x
+# (no mapfile), so loop over find output via a temp list.
+
+check_script() {
+  local file="$1"
+  local body
+  body="$(cat "$file")"
+  local missing=()
+  grep -q 'export const options' <<<"$body" || missing+=("export const options")
+  grep -q 'thresholds' <<<"$body"            || missing+=("thresholds block")
+  grep -Eq 'stages|scenarios' <<<"$body"     || missing+=("stages/scenarios load profile")
+
+  if [ "${#missing[@]}" -ne 0 ]; then
+    echo "FAIL  $file"
+    printf '      missing: %s\n' "${missing[@]}"
+    fail=1
+  else
+    echo "OK    $file"
+    # Optional deeper validation only when k6 is installed; still no network.
+    if command -v k6 >/dev/null 2>&1; then
+      if k6 inspect "$file" >/dev/null 2>&1; then
+        echo "      k6 inspect: parses cleanly"
+      else
+        echo "      k6 inspect: parse error"
+        fail=1
+      fi
+    fi
+  fi
+  checked=$((checked + 1))
+}
+
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  check_script "$f"
+done < <(find "$SKILL_DIR/scripts" -type f -name '*.js' 2>/dev/null || true)
+
+# Best-effort: confirm the reference doc still carries a thresholds example so the
+# prose and the shipped artifact don't drift. Absence is a warning, not a failure.
+ref="$SKILL_DIR/references/load-testing-k6.md"
+if [ -f "$ref" ]; then
+  if grep -q 'thresholds' "$ref"; then
+    echo "OK    $ref (documents thresholds)"
+  else
+    echo "WARN  $ref no longer shows a thresholds example"
+  fi
+fi
+
+if [ "$checked" -eq 0 ]; then
+  echo "No k6 scripts found — nothing to verify (clean)."
+fi
+
+exit "$fail"

package/skills/sdd/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: sdd
+description: "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the rsc-sdd dispatcher / front door. It states the SDD method, reads the accompaniment dial from 02-DOCS, and routes to the right phase skill: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel callable on demand. Use it to START a feature, when unsure which SDD phase you are in, or to govern the whole flow. Triggers: 'spec-driven development', 'sdd', 'build this feature properly', 'start a new feature', 'I have an idea, take it to production', 'which phase am I in', 'run the sdd flow', 'desarrollo dirigido por especificación', 'monta esta feature bien', 'de la idea a producción'. NOT itself a single phase (it dispatches), NOT the workspace harness (harness), NOT a stack build skill."
+tags: [sdd, spec, workflow, plan]
+recommends: [sdd-init, constitution, specify]
+profiles: [core, full]
+origin: risco
+---
+
+# sdd — the rsc Spec-Driven Development dispatcher
+
+*The front door for building software the rsc way: intent in, shipped-and-verified software out, with the spec, plan and decisions recorded into the project's living knowledge model as you go.*
+
+`sdd` is the **engineering counterpart of the `harness`**. The harness runs the chaos → knowledge loop (inbox → `02-DOCS` wiki). `sdd` runs the **intent → shipped software** loop, and it writes the artifacts of that loop — constitution, specs, plans, decisions — into the same `02-DOCS/wiki/sdd/` so the project's knowledge grows with every feature instead of leaking into chat history.
+
+This skill does **not** do a phase itself. It is the dispatcher: it names the method, reads how much accompaniment you want, tells you which phase you are in, and hands off to the phase skill that owns the work. Each phase skill, when it finishes, points you at the next one — so once you enter the chain you rarely come back here.
+
+## The method in one breath
+
+Spec-Driven Development (SDD, GitHub Spec Kit lineage) says: **decide what and why before how, write it down, and let each written artifact gate the next step.** You do not jump from a sentence in chat to a pull request. You move through ordered phases, each producing a durable artifact that the next phase reads. The payoff is that the *intent* is reviewable before any code exists, drift is caught at a gate instead of in production, and the whole thing is legible to the next person (or the next session) because it lives in `02-DOCS`, not in a scrollback.
+
+If you only remember one rule: **the artifact is the contract.** Code is checked against the plan, the plan against the spec, the spec against the constitution. When they disagree, you fix the disagreement before writing more code — you do not let the code silently win.
+
+## Step zero: calibrate the SDD runtime
+
+Before the first non-trivial feature in a repo, run `../sdd-init/SKILL.md`. It detects the stack, package manager, test runners, scripts, monorepo signals and review budget, refreshes `.rsc/skill-registry.json`, and writes:
+
+```text
+02-DOCS/wiki/sdd/config.yaml
+```
+
+If `config.yaml` is missing and the request is more than a tiny one-line change, route to `sdd-init` before `specify`. This is not the same as `init`: `init` profiles the user/workspace; `sdd-init` calibrates the technical SDD runtime.
+
+## The chained phase map
+
+The canonical chain runs left to right. Solid arrows are the default path; you move forward when the current phase's exit gate passes.
+
+```text
+constitution ─(once per project)─┐
+                                 ▼
+   sdd-init ─(once per repo/runtime)─┐
+                                     ▼
+   proposal? ─► specify ─► clarify ─► plan ─► tasks ─► analyze ─► implement ─► verify ─► review ─► ship ─► archive
+                                                         ▲
+                                          on demand ─────┴─────────────────────
+                                          debug · worktrees · parallel
+```
+
+| Phase | Owns | Writes | Sibling skill |
+| --- | --- | --- | --- |
+| **sdd-init** | Technical runtime calibration: stack, tests, commands, registry, budgets | `02-DOCS/wiki/sdd/config.yaml`, `.rsc/skill-registry.*` | `../sdd-init/SKILL.md` |
+| **proposal** | Optional pre-execution briefing for ambiguous/architectural/risky work | `02-DOCS/wiki/sdd/proposals/<slug>.md` | handled by `../specify/SKILL.md` when needed |
+| **constitution** | Project non-negotiables: stack canon, quality bars, conventions | `02-DOCS/wiki/sdd/constitution.md` | `../constitution/SKILL.md` |
+| **specify** | Turn a fuzzy intent into a spec — what & why, no how | `02-DOCS/wiki/sdd/specs/<slug>.md` | `../specify/SKILL.md` |
+| **clarify** | Surface ambiguities / edge cases, ask, bake answers back in | updates the spec | `../clarify/SKILL.md` |
+| **plan** | Technical plan: architecture, interfaces, data flow, tests, risks | `02-DOCS/wiki/sdd/plans/<slug>.md` | `../plan/SKILL.md` |
+| **tasks** | Break the plan into ordered, independently-verifiable tasks | task list in the plan artifact | `../tasks/SKILL.md` |
+| **analyze** | Consistency gate: constitution ↔ spec ↔ plan ↔ tasks (report only) | a gap report | `../analyze/SKILL.md` |
+| **implement** | Execute tasks with checkpoints; TDD discipline embedded | logs to `02-DOCS/wiki/sdd/decisions.md` | `../implement/SKILL.md` |
+| **verify** | Post-build gate: run the stack's checks + done-checks + acceptance | evidence | `../verify/SKILL.md` |
+| **review** | Adversarial code review — give and receive with rigor | review notes | `../review/SKILL.md` |
+| **ship** | Close the branch: PR / merge / cleanup. **Git authorship = Eric** | the merge/PR and archive bundle | `../ship/SKILL.md` |
+| **debug** | Root-cause diagnosis: reproduce → isolate → fix → verify | a diagnosis | `../debug/SKILL.md` |
+| **worktrees** | Isolate feature work in a branch/worktree before executing a plan | an isolated workspace | `../worktrees/SKILL.md` |
+| **parallel** | Fan out independent tasks across subagents, gather results | merged results | `../parallel/SKILL.md` |
+
+> If a phase skill above does not yet exist in this repo, the chain still holds — do that phase's work inline following the method here, and skip the broken handoff. Never invent a sibling that is not installed.
+
+## The invoke rule — route to the phase that fits
+
+When a request lands, do not start typing code. Place it on the map first, then invoke the phase skill that owns it.
+
+1. **No `02-DOCS/wiki/sdd/config.yaml` and this is non-trivial?** → `sdd-init`.
+2. **No constitution yet AND this project will grow?** → `constitution` once, then come back to the chain.
+3. **Ambiguous / architectural / risky change before spec?** → optional proposal artifact via `specify`.
+4. **A new idea, fuzzy, no spec on disk?** → `specify`.
+5. **A spec exists but feels risky / has open questions?** → `clarify`.
+6. **A clarified spec, no technical plan?** → `plan`.
+7. **A plan with no task breakdown?** → `tasks`.
+8. **Tasks exist, about to code, want a safety check?** → `analyze`.
+9. **Green light to build?** → `implement` (it embeds strict TDD from config and calls `parallel`/`worktrees` when useful).
+10. **Code written, claiming it works?** → `verify`, then `review`, then `ship`/archive.
+11. **Something is broken mid-flight?** → `debug`, then resume where you were.
+
+If you genuinely cannot tell which phase you are in, ask the user one question: *"Do we have a written spec for this yet?"* The answer puts you before or after `specify`, and the rest follows.
+
+### Skip rules (be honest about them)
+
+- A **one-line, low-risk change** (typo, copy tweak, config bump) does not need the full chain. Say so, do it, and verify. The method serves shipping, not ceremony.
+- `constitution` runs **once per project**, not per feature. If `02-DOCS/wiki/sdd/constitution.md` exists, read it as guardrails and move on.
+- `clarify` and `analyze` are **gates, not paperwork**. If a spec is genuinely unambiguous and tiny, name that out loud and pass through — but the bias is to run them, because skipped gates are where drift hides.
+
+## Read the accompaniment dial first
+
+Before dispatching, read `02-DOCS/wiki/harness/user-profile.md` and adapt — exactly as every rsc skill does. The dial sets **how much you explain and how many questions you ask at each gate**, not whether the gates exist.
+
+| Level | At each phase | At gates (clarify / analyze / decisions) |
+| --- | --- | --- |
+| **L0** "cavernícola" | Name the phase, do it, show the artifact. Minimal prose. | Ask only the questions that actually change the outcome. |
+| **L1** "breve" | One line of *why this phase now*. | One-line rationale per question. |
+| **L2** "explica decisiones" | Justify each significant choice as you go. | Walk the trade-offs before the user picks. |
+| **L3** "acompañamiento total" | Explain the phase, why it matters, what it produces. | Ask broadly, teach the SDD reasoning, narrate every decision. |
+
+If there is no profile yet, default to **non-technical + ask the two harness gauging questions** (technical level, accompaniment level) before dispatching, and persist them — that is the harness's job and `sdd` honors it.
+
+## Where the artifacts live (and why it matters)
+
+Every phase writes under `02-DOCS/wiki/sdd/` so the feature's reasoning outlives the chat:
+
+```text
+02-DOCS/wiki/sdd/
+├── config.yaml              ← repo runtime calibration from sdd-init
+├── constitution.md          ← project non-negotiables (once)
+├── proposals/<slug>.md      ← optional pre-execution briefing
+├── specs/<slug>.md          ← one spec per feature
+├── plans/<slug>.md          ← one plan per feature (tasks live inside)
+├── progress/<slug>.md       ← append-only apply progress
+├── verifications/<slug>-YYYY-MM-DD.md
+├── archive/<slug>/          ← final report, state, verify/review/ship records
+├── sessions/<date>-<slug>.md
+└── decisions.md             ← append-only log of decisions taken while building
+```
+
+Index these from the root `CLAUDE.md` `## Knowledge map` under an `sdd/` topic, so every other skill reads them before working in the area. The harness maintains and improves these files just like any other wiki topic — `sdd` produces them, the harness keeps them honest.
+
+```markdown
+## Knowledge map
+| Topic | Where | What |
+| --- | --- | --- |
+| sdd/ | 02-DOCS/wiki/sdd/ | Constitution, specs, plans, decisions for spec-driven feature work |
+```
+
+## Stack handoff
+
+`sdd` and its phases are **process, not stack**. Concrete tooling — test runners, lint/type/build, framework idioms — belongs to the stack skills. `plan` defers stack specifics, `implement` borrows the stack skill's testing approach, and `verify` runs the stack skill's checks. Route to the stack that matches the work: `../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`. Visual/UX work routes to `../design/SKILL.md` and copy to `../marketing/SKILL.md`.
+
+## Skill registry and compact skill rules
+
+The registry is the cheap index:
+
+```text
+.rsc/skill-registry.json
+.rsc/skill-registry.md
+```
+
+Use it to choose the few relevant skill paths for the current phase/stack. Do not load the whole catalog. Before dispatching subagents, digest selected skills into 4-5 compact rules and include them in the brief. Each phase reports `skill_resolution`: which skills were used, which were missing, fallback behavior, and the compact rules handed to subagents.
+
+## Standard result envelope
+
+Every SDD phase ends with the same parseable block so the dispatcher can chain phases without interpreting a novel:
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "one short paragraph",
+  "artifact": "path/to/artifact-or-none",
+  "next_recommended": "sdd-init|specify|clarify|plan|tasks|analyze|implement|verify|review|ship",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": [],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": []
+  },
+  "evidence": []
+}
+```
+
+If a phase cannot produce the envelope because the user stopped it mid-flight, write a session summary instead.
+
+## Session summary / compaction recovery
+
+When a session is long, about to pause, or context is at risk, write:
+
+```text
+02-DOCS/wiki/sdd/sessions/<date>-<slug>.md
+```
+
+Include current phase, active artifacts, last verdict, completed tasks, next steps, risks, useful commands, and the current `skill_resolution`. This lets the next agent resume from artifacts instead of scrollback.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality / fix |
+| --- | --- |
+| "I get the feature, I'll just start coding." | That is the failure SDD prevents. At minimum write the spec; the artifact is the contract. |
+| "`sdd` should write the spec itself." | No. `sdd` dispatches. Invoke `specify` — it owns the spec and asks the right questions. |
+| "Clarify and analyze are bureaucracy, skip them." | Skipped gates are where drift hides. Run them; only pass through if the change is genuinely trivial and you say so. |
+| "Profile says L0, so I'll skip the gates to be terse." | L0 changes verbosity, not the method. Fewer words, same gates. |
+| "I'll keep the plan in chat, it's faster." | Chat is not durable. Write it under `02-DOCS/wiki/sdd/` or the next session is blind. |
+| "I'll skip `sdd-init`; I remember the test command." | The runtime contract belongs in `config.yaml`, not memory. |
+| "I'll load every skill into the subagent." | That contaminates context. Use registry -> selected paths -> compact rules. |
+| "The phase wrote a nice summary, so no envelope needed." | The envelope is the phase contract. Add it. |
+| "Run constitution again for this feature." | Constitution is once per project. If it exists, read it as guardrails and move on. |
+| "Ship now, I'll add Co-Authored-By: Claude." | `ship` enforces Eric-only authorship. No Claude co-author, no generated-with footer. |
+| "Invoke the `release` phase." | There is no such phase. Never invent a sibling — the chain is the chain. |
+
+## Start here
+
+- **New project, nothing on disk yet** → `../sdd-init/SKILL.md` for runtime calibration, `../constitution/SKILL.md` for non-negotiables, then `../specify/SKILL.md`.
+- **Existing project, no SDD config** → `../sdd-init/SKILL.md`, then route by phase.
+- **Existing project, new feature** → `../specify/SKILL.md` (or proposal first if risky/architectural).
+
+Then follow the arrows: each phase ends by pointing at the next, all the way to `ship`.

package/skills/sdd/evals/README.md

@@ -0,0 +1,60 @@
+# Eval harness — `sdd`
+
+Evaluates the `sdd` dispatcher (the rsc-sdd front door) on two axes: **triggering**
+(does it fire when a feature should run the spec-driven flow, and stay quiet when a
+single phase or a different skill owns the request) and **capability** (does loading it
+measurably improve how the agent opens and routes the work). Cases live in `cases.yaml`.
+These run via an **agent harness**, not a pure shell script — a human or driver agent
+feeds prompts to Claude Code and judges the result against the rubrics.
+
+## What's in `cases.yaml`
+
+- `should_trigger` (7) — prompts that MUST invoke `sdd`, including non-obvious phrasings
+  ("which step am I on", "decide what and why, write it down, then build") with no SDD
+  jargon.
+- `should_not_trigger` (6) — near-misses that must route elsewhere. Each carries a
+  `route_to` naming the correct sibling (`specify`, `constitution`, `ship`, `harness`,
+  `debug`, `nextjs`).
+- `capability` (2) — scenarios with `must_include` rubrics graded WITH vs WITHOUT the skill.
+
+## A. Triggering eval
+
+1. Load **only** `sdd` into the agent (no other rsc skills available, so routing is honest).
+2. For each `should_trigger` prompt: open a fresh session, paste the prompt verbatim, and
+   record whether `sdd` activates — a pass means it names the method, places the request on
+   the phase map, and routes to a phase (it should NOT start writing the spec or coding
+   itself). Run **3–5 trials** per prompt.
+3. For each `should_not_trigger` prompt: same procedure, but a **pass** = `sdd` does NOT
+   fire. Where a `route_to` sibling is named, sanity-check the prompt genuinely belongs there
+   (e.g. "write the spec" → `specify`, "open the PR and merge" → `ship`).
+4. Score: a prompt passes if the **majority of its trials** go the expected way.
+
+**Pass bar:** ≥ 90% trigger accuracy across all `should_trigger` + `should_not_trigger`
+prompts (at most 1 of the 13 may misbehave).
+
+## B. Capability eval
+
+1. **Without the skill:** fresh session, skill NOT loaded, give the `scenario` prompt. Save output A.
+2. **With the skill:** fresh session, `sdd` loaded, same prompt. Save output B.
+3. Grade each output against that scenario's `must_include` points — count points clearly covered.
+4. Repeat across **3 trials** per scenario per condition and average the coverage.
+
+**Pass bar:** WITH the skill covers **≥ 80%** of `must_include` points; WITHOUT the skill is
+materially lower (target a ≥ 30-point gap). If the skill doesn't measurably beat the baseline,
+the skill — or these rubrics — needs work.
+
+## Judging notes (honest caveats)
+
+- This is **LLM-as-judge / human-in-the-loop**, not deterministic. Use a consistent grader
+  (same model + rubric) across A/B to keep the comparison fair.
+- The headline differentiators for `sdd`: it **dispatches, it does not perform a phase**; it
+  states the method ("the artifact is the contract"), reads the **accompaniment dial** and
+  adapts verbosity (not the gates), presents the **chained phase map**, applies the **invoke
+  rule** and the **skip rules** honestly, and writes artifacts under `02-DOCS/wiki/sdd/`.
+- Key confusables to watch: "write the spec" is `specify`, not `sdd`; "set the principles" is
+  `constitution`; "open the PR" is `ship`; "build 01-TOOLS/02-DOCS" is `harness`. If the agent
+  does the phase work itself instead of routing, that's a fail even if the output looks good.
+- Because `sdd` is the front door, some phase siblings may not yet be installed. A correct
+  response still routes by name and does the phase inline if the sibling is absent — it must
+  never invent a phase that isn't in the chain.
+- Run after any edit to `SKILL.md` or its `description`, since both axes are sensitive to wording.

package/skills/sdd/evals/cases.yaml

@@ -0,0 +1,78 @@
+skill: sdd
+
+# Cases for the rsc-sdd "sdd" dispatcher / front door.
+# sdd states the SDD method, reads the accompaniment dial from
+# 02-DOCS/wiki/harness/user-profile.md, and ROUTES to the right phase skill in
+# the chain constitution -> specify -> clarify -> plan -> tasks -> analyze ->
+# implement -> verify -> review -> ship (debug/worktrees/parallel on demand).
+# It does NOT perform a single phase itself and is NOT the workspace harness.
+
+should_trigger:
+  - prompt: "I want to build this feature properly, spec-driven, from idea to shipped. Where do I start?"
+    why: "Canonical SDD entry: explicit 'spec-driven' + 'idea to shipped' is exactly what the dispatcher routes — it should name the method and hand off to constitution/specify, not start coding."
+
+  - prompt: "Quiero llevar esta idea a producción haciéndolo bien, paso a paso."
+    why: "Spanish 'de la idea a producción, haciéndolo bien, paso a paso' is the intent->shipped loop the dispatcher governs; it should place the request on the phase map and route to specify."
+
+  - prompt: "I'm somewhere in the middle of building a feature and I've lost track of which step I'm on. Can you orient me?"
+    why: "Non-obvious: no SDD jargon, but 'which step am I on' is precisely the dispatcher's 'which phase are you in' job — it asks the one orienting question (is there a written spec?) and routes."
+
+  - prompt: "Run the full sdd flow on this new authentication requirement."
+    why: "Direct request to run the chained flow — the dispatcher owns the flow and routes the first phase; it should not try to do every phase inline itself."
+
+  - prompt: "I have a one-paragraph idea for a notifications feature. Take it all the way to a PR the disciplined way."
+    why: "Fuzzy idea + 'all the way to a PR' + 'disciplined' implies the whole chain; the dispatcher should start at specify and explain the gates rather than jumping to implementation."
+
+  - prompt: "Before we touch code, I want a proper process: decide what and why, write it down, then build. Set that up."
+    why: "Describes SDD by definition (what/why before how, write it down) without the acronym — a deliberately non-obvious trigger the dispatcher must claim and route from."
+
+  - prompt: "What's the right order to do this feature in, and which phase skill handles each part?"
+    why: "Asks for the phase map and the per-phase ownership — the dispatcher's core deliverable; it should produce the chain and the routing rule."
+
+  - prompt: "We have an existing repo and no SDD config yet. Start the SDD flow properly before we write a spec."
+    why: "The dispatcher should notice the missing runtime calibration and route to sdd-init before specify on non-trivial work."
+
+should_not_trigger:
+  - prompt: "Write the spec for the new export-to-CSV feature."
+    route_to: "specify"
+    why: "A concrete request to PRODUCE the spec is a single phase the dispatcher hands off — specify owns writing specs and asking the focused questions. sdd only routes."
+
+  - prompt: "Set this repo's non-negotiable engineering principles and stack canon."
+    route_to: "constitution"
+    why: "Capturing project-wide non-negotiables is the constitution phase, which runs once per project. The dispatcher would point here, but the work itself belongs to the constitution skill."
+
+  - prompt: "All the code is written and tests pass — open the PR and merge it."
+    route_to: "ship"
+    why: "Closing the branch (PR/merge/cleanup, Eric-only authorship) is the ship phase. No dispatching needed; this is squarely ship's job."
+
+  - prompt: "Audita mi proyecto y monta el 01-TOOLS y el 02-DOCS."
+    route_to: "harness"
+    why: "Workspace control plane (01-TOOLS/02-DOCS scaffolding/audit) is the harness, not the SDD engineering flow. sdd writes its artifacts INTO 02-DOCS but does not build the harness."
+
+  - prompt: "There's a failing test and I don't know why — help me find the root cause before I change anything."
+    route_to: "debug"
+    why: "Root-cause diagnosis of a specific failure is the on-demand debug phase. The dispatcher references it, but a direct 'find the root cause' request goes straight to debug, not through routing."
+
+  - prompt: "Scaffold a new Next.js app with the App Router and Tailwind."
+    route_to: "nextjs"
+    why: "A concrete stack build with a named framework is the nextjs stack skill. sdd is process, not stack; it would defer build specifics to nextjs rather than fire itself."
+
+capability:
+  - scenario: "A developer at accompaniment level L1 says: 'I've got a rough idea for a feature and I want to build it the spec-driven way, end to end. Where do I begin?' Show how the dispatcher opens the engagement."
+    must_include:
+      - "States the SDD method in brief: decide what & why before how, write it down, each artifact gates the next ('the artifact is the contract')"
+      - "Reads (or notes it should read) 02-DOCS/wiki/harness/user-profile.md for the accompaniment dial and, at L1, gives a one-line why per step rather than long explanations"
+      - "Presents the chained phase map: sdd-init -> constitution -> proposal? -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship -> archive, with debug/worktrees/parallel on demand"
+      - "Includes sdd-init as step zero when 02-DOCS/wiki/sdd/config.yaml is missing, and explains that it detects test commands, strict TDD and .rsc/skill-registry.json"
+      - "Applies the invoke rule: a fuzzy idea with no spec on disk routes to specify (and notes constitution runs once per project if not yet present)"
+      - "Does NOT itself write the spec or start coding — it hands off to the specify phase skill (../specify/SKILL.md)"
+      - "Notes that artifacts will be written under 02-DOCS/wiki/sdd/ (specs/, plans/, decisions.md) and indexed in the root CLAUDE.md Knowledge map"
+      - "Mentions standard result envelopes with status, artifact, next_recommended, risk, skill_resolution and evidence"
+      - "Defers concrete stack tooling (test runner, build, framework idioms) to the relevant stack skill rather than prescribing it here"
+
+  - scenario: "A user says: 'It's a tiny copy change in the footer — do I really have to run this whole spec/plan/tasks ceremony?' Show how the dispatcher handles the skip case honestly."
+    must_include:
+      - "Applies the skip rule: a one-line, low-risk change does not need the full chain, and says so explicitly"
+      - "Still requires a verification step after the change (the method serves shipping, not ceremony, but evidence before claiming done remains)"
+      - "Does not abandon the method for genuinely risky work — distinguishes trivial from non-trivial and is honest about which this is"
+      - "If git authorship comes up, notes ship enforces Eric-only authorship (no Co-Authored-By Claude, no generated-with footer)"