rsc-universal 0.1.1

package/skills/compose-multiplatform/references/project-setup.md

@@ -0,0 +1,96 @@
+# Project setup — Gradle, source sets, module layouts
+
+Full setup for the 2026 default KMP structure. Floors: CMP 1.11.0 (Jetpack Compose 1.11.1), Kotlin 2.1.0+ (2.2.20 recommended), K2 mandatory since CMP 1.8.0, AGP 9.0.
+
+## Version catalog (`gradle/libs.versions.toml`)
+
+```toml
+[versions]
+kotlin = "2.2.20"
+compose = "1.11.0"
+agp = "9.0.0"
+androidx-lifecycle = "2.9.0"
+koin = "4.0.0"
+navigation = "2.9.0"
+
+[plugins]
+kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
+composeMultiplatform = { id = "org.jetbrains.compose", version.ref = "compose" }
+composeCompiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+androidLibrary = { id = "com.android.library", version.ref = "agp" }
+
+[libraries]
+lifecycle-viewmodel = { module = "org.jetbrains.androidx.lifecycle:lifecycle-viewmodel", version.ref = "androidx-lifecycle" }
+navigation-compose = { module = "org.jetbrains.androidx.navigation:navigation-compose", version.ref = "navigation" }
+koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
+koin-compose-viewmodel = { module = "io.insert-koin:koin-compose-viewmodel", version.ref = "koin" }
+```
+
+## `shared/build.gradle.kts`
+
+```kotlin
+plugins {
+    alias(libs.plugins.kotlinMultiplatform)
+    alias(libs.plugins.composeMultiplatform)
+    alias(libs.plugins.composeCompiler)
+    alias(libs.plugins.androidLibrary)
+}
+
+kotlin {
+    androidTarget()
+    jvm("desktop")
+    listOf(iosArm64(), iosSimulatorArm64()).forEach { it.binaries.framework { baseName = "shared" } }
+    // wasmJs { browser() }  // Beta — enable to pilot Web only
+
+    sourceSets {
+        commonMain.dependencies {
+            implementation(compose.runtime)
+            implementation(compose.foundation)
+            implementation(compose.material3)
+            implementation(compose.components.resources)   // generated Res accessors
+            implementation(libs.lifecycle.viewmodel)
+            implementation(libs.navigation.compose)
+            implementation(libs.koin.core)
+            implementation(libs.koin.compose.viewmodel)
+        }
+        androidMain.dependencies { implementation(compose.preview) }
+    }
+}
+```
+
+## Source-set hierarchy
+
+```text
+commonMain
+├── androidMain
+├── desktopMain (jvm)
+├── wasmJsMain (Beta)
+└── iosMain (intermediate)
+    ├── iosArm64
+    └── iosSimulatorArm64
+```
+
+Use the intermediate `iosMain` for code shared by both iOS targets; only drop to `iosArm64`/`iosSimulatorArm64` for arch-specific cinterop.
+
+## Module-layout variants
+
+- **Mobile-only:** `shared` + `androidApp` + `iosApp`.
+- **+ Desktop:** add `desktopApp` (`./gradlew :desktopApp:run`).
+- **+ Web (Beta):** add `webApp` with the `wasmJs` target; do not promise parity.
+- **Mixed native UI:** split `shared` into **`sharedLogic`** (all platforms, no Compose UI) + **`sharedUI`** (CMP platforms only). Native screens depend on `sharedLogic`; shared screens live in `sharedUI`.
+- **+ Server:** add a root **`core`** module consumed by both clients and a JVM/Ktor server.
+
+## Scaffolding
+
+- New project: **kmp.new** or the Kotlin Multiplatform wizard (IntelliJ IDEA 2025.2.2+ / Android Studio Otter 2025.2.1+ with the KMP plugin).
+- Existing Android app: Android Studio **Shared Module Template** (added May 2025) adds a KMP `shared` module in place.
+
+## AGP 9.0 migration notes
+
+The new default structure aligns with AGP 9.0. When migrating from the old single `composeApp` module: extract shared `@Composable`s/VMs into a `shared` library module, turn `composeApp` into a thin `androidApp` host that calls `setContent { App() }`, and move the iOS framework export into `shared`.
+
+## Packaging
+
+- Desktop: `./gradlew :desktopApp:packageDistributionForCurrentOS` (dmg/msi/deb). Needs **JDK 17+** for `jpackage`; desktop runtime floor is JDK 11+.
+- iOS: archive the `iosApp` Xcode project (App Store signing is `swift-ios` territory).
+- Web (Beta): `./gradlew :webApp:wasmJsBrowserDistribution`.

package/skills/compose-multiplatform/scripts/verify.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# verify.sh — static, read-only checks for a Compose Multiplatform / KMP project.
+# No Gradle/Xcode run required. Exits 0 on a clean OR empty target (no false failure).
+#
+# Usage: verify.sh [PROJECT_DIR]   (default: current directory)
+#
+# Hard failures (exit 1): missing commonMain when KMP is present, orphaned `expect`
+# (no matching `actual`), platform import leaking into commonMain.
+# Warnings (still exit 0): Kotlin < 2.1.0, missing Compose plugin.
+
+set -uo pipefail
+
+ROOT="${1:-.}"
+FAIL=0
+WARN=0
+
+note()  { printf '  %s\n' "$1"; }
+ok()    { printf 'PASS  %s\n' "$1"; }
+bad()   { printf 'FAIL  %s\n' "$1"; FAIL=1; }
+warn()  { printf 'WARN  %s\n' "$1"; WARN=1; }
+
+if [ ! -d "$ROOT" ]; then
+  echo "verify.sh: '$ROOT' is not a directory" >&2
+  exit 2
+fi
+
+# Locate commonMain source dirs (KMP marker). Ignore build output dirs.
+# Portable to bash 3.2 (macOS) — no mapfile.
+COMMON_DIRS=()
+while IFS= read -r d; do
+  [ -n "$d" ] && COMMON_DIRS+=("$d")
+done < <(find "$ROOT" -type d -name commonMain \
+  -not -path '*/build/*' -not -path '*/.gradle/*' 2>/dev/null)
+
+# Detect whether this looks like a KMP/CMP project at all.
+HAS_KMP=0
+if [ "${#COMMON_DIRS[@]}" -gt 0 ]; then HAS_KMP=1; fi
+if grep -rqsl 'org.jetbrains.kotlin.multiplatform\|org.jetbrains.compose' \
+     "$ROOT" --include='*.kts' --include='*.toml' 2>/dev/null; then HAS_KMP=1; fi
+
+if [ "$HAS_KMP" -eq 0 ]; then
+  echo "verify.sh: no KMP/CMP project detected under '$ROOT' — nothing to check."
+  exit 0
+fi
+
+# 1) commonMain must exist.
+if [ "${#COMMON_DIRS[@]}" -eq 0 ]; then
+  bad "no commonMain source set found (a shared module is the core of CMP)"
+else
+  ok "commonMain present (${#COMMON_DIRS[@]} found)"
+fi
+
+# 2) Every `expect` in commonMain needs a matching `actual` somewhere.
+#    Match on the declared symbol name to catch orphans cheaply.
+ORPHANS=0
+for cm in ${COMMON_DIRS[@]+"${COMMON_DIRS[@]}"}; do
+  # collect expect declarations: fun/class/val/var/object/interface
+  while IFS= read -r decl; do
+    [ -z "$decl" ] && continue
+    name="$decl"
+    if grep -rqs "actual[[:space:]].*\b${name}\b" "$ROOT" \
+         --include='*.kt' 2>/dev/null \
+         | grep -qv "commonMain" 2>/dev/null; then
+      :
+    elif grep -rs "actual[[:space:]]" "$ROOT" --include='*.kt' 2>/dev/null \
+           | grep -q "\b${name}\b"; then
+      :
+    else
+      bad "orphaned expect '${name}' has no matching actual in any platform source set"
+      ORPHANS=$((ORPHANS+1))
+    fi
+  done < <(grep -rhsoE '^[[:space:]]*expect[[:space:]]+(fun|class|val|var|object|interface)[[:space:]]+[A-Za-z_][A-Za-z0-9_]*' \
+             "$cm" --include='*.kt' 2>/dev/null \
+             | sed -E 's/.*(fun|class|val|var|object|interface)[[:space:]]+([A-Za-z_][A-Za-z0-9_]*).*/\2/')
+done
+[ "$ORPHANS" -eq 0 ] && ok "no orphaned expect declarations"
+
+# 3) Compose plugin + Kotlin version.
+if grep -rqs 'org.jetbrains.compose' "$ROOT" \
+     --include='*.kts' --include='*.toml' 2>/dev/null; then
+  ok "Compose Multiplatform plugin (org.jetbrains.compose) present"
+else
+  warn "Compose Multiplatform plugin (org.jetbrains.compose) not found"
+fi
+
+KVER=$(grep -rhsoE 'kotlin[^=]*=[[:space:]]*"?([0-9]+\.[0-9]+\.[0-9]+)' \
+         "$ROOT" --include='*.toml' --include='*.kts' 2>/dev/null \
+         | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | sort -V | tail -1)
+if [ -n "$KVER" ]; then
+  MAJ=${KVER%%.*}; REST=${KVER#*.}; MIN=${REST%%.*}
+  if [ "$MAJ" -gt 2 ] || { [ "$MAJ" -eq 2 ] && [ "$MIN" -ge 1 ]; }; then
+    ok "Kotlin $KVER (>= 2.1.0 K2 floor)"
+  else
+    warn "Kotlin $KVER is below 2.1.0 — CMP 1.8+ requires K2 (Kotlin 2.1.0+); bump to 2.2.x"
+  fi
+else
+  warn "could not detect a Kotlin version in version catalog / build scripts"
+fi
+
+# 4) No platform-only imports leaking into commonMain.
+FORBIDDEN='^import[[:space:]]+(android\.|androidx\.activity|platform\.UIKit|platform\.Foundation|java\.awt|javax\.swing|org\.w3c\.dom)'
+LEAKS=0
+for cm in ${COMMON_DIRS[@]+"${COMMON_DIRS[@]}"}; do
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    bad "platform import in commonMain: $line"
+    LEAKS=$((LEAKS+1))
+  done < <(grep -rhsnE "$FORBIDDEN" "$cm" --include='*.kt' 2>/dev/null)
+done
+[ "$LEAKS" -eq 0 ] && ok "commonMain free of platform-only imports"
+
+echo "----"
+if [ "$FAIL" -ne 0 ]; then
+  echo "RESULT: FAIL"
+  exit 1
+fi
+if [ "$WARN" -ne 0 ]; then
+  echo "RESULT: PASS (with warnings)"
+else
+  echo "RESULT: PASS"
+fi
+echo "(Optional: if ./gradlew exists, ':shared:compileKotlinMetadata' compiles the common metadata.)"
+exit 0

package/skills/constitution/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: constitution
+description: "Use when capturing or revising a project's non-negotiable principles — its stack canon, quality bars, naming/structure conventions, branching/commit rules, testing thresholds, security and accessibility floors, the things every later phase must obey. This is the FIRST rsc-sdd phase, run once per project (then amended). Writes/updates 02-DOCS/wiki/sdd/constitution.md and links it from the root CLAUDE.md Knowledge map; reconciles with conventions the harness already holds under 02-DOCS/wiki/stack/*. Triggers: 'set the project principles', 'define our engineering standards', 'establecer las reglas del proyecto', 'project constitution', 'what are our non-negotiables', 'lock the stack canon', 'quality bar', 'coding standards doc', 'amend the constitution', 'ratify principle', 'definition of done for the repo'. NOT a feature spec (that's specify) and NOT an implementation plan (that's plan)."
+tags: [sdd, constitution, principles]
+recommends: [specify]
+profiles: [core, full]
+origin: risco
+---
+
+# constitution — the project's non-negotiable principles
+
+*The first rsc-sdd phase. Run once per project, then amend. It writes down the rules every later phase obeys: stack canon, quality bars, conventions. Everything downstream — specify, plan, analyze, implement, verify, review — reads this file as guardrails.*
+
+A constitution is small, durable, and enforceable. It is **not** a wiki of everything you know about the project (that is what `02-DOCS/wiki/` already is, run by the `harness`). It is the short list of principles that, if violated, mean the work is wrong regardless of whether it runs. If a rule here cannot be checked or pointed at later, it does not belong here — move it to the stack wiki and link it.
+
+This skill produces `02-DOCS/wiki/sdd/constitution.md` and one Knowledge-map row in the root `CLAUDE.md`. It reconciles with — never duplicates — the stack conventions the harness keeps under `02-DOCS/wiki/stack/*`.
+
+## Honor the accompaniment dial first
+
+Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` and match its `technical_level` and `accompaniment_level`. The constitution interview adapts:
+
+| Level | How this skill behaves |
+|-------|------------------------|
+| L0 — cavernícola | Infer almost everything from the codebase and stack wiki. Ask only the 1-2 questions that genuinely change a principle. Draft, show, ratify. |
+| L1 — breve | One line of *why* per principle proposed. Ask 3-4 questions max. |
+| L2 — explica decisiones | Justify each principle as you propose it; surface trade-offs where a rule constrains the team. |
+| L3 — acompañamiento total | Explain what a constitution is and why each section matters, one kind question at a time, before writing anything. Non-technical framing. |
+
+If there is no profile yet, default to non-technical and ask the two gauging questions (technical level, accompaniment level) before proceeding — or point the user at `init`. Never assume fluency.
+
+## When to use / when NOT to use
+
+Use when:
+
+- A project is being set up and needs its principles fixed before features are specified.
+- The team keeps relitigating the same decisions (test coverage, formatting, branch naming) and wants them ratified once.
+- An existing repo has implicit conventions that should be made explicit and enforceable.
+- A principle needs to change — amend the constitution (see the amendment protocol).
+
+Do NOT use when (route instead):
+
+- The user wants to describe *what to build* → `../specify/SKILL.md` (a feature spec, not project-wide law).
+- The user wants the *technical approach* for a feature → `../plan/SKILL.md`.
+- The user wants to set up `01-TOOLS/` + `02-DOCS/` or capture general project knowledge → `harness` (the constitution lives inside that wiki, but the wiki itself is the harness's job).
+- The user wants concrete stack mechanics (e.g. *how* to configure Ruff, pytest, Tailwind tokens) → the relevant stack skill (`fastapi`, `nextjs`, `go`, `postgresdb`, `flutter`, `design`). The constitution *names* the bar; the stack skill *enforces* it.
+
+## Reconcile before you write (do not duplicate the stack wiki)
+
+The harness may already hold real conventions under `02-DOCS/wiki/stack/*` (e.g. `nextjs.md`, `fastapi.md`, `postgresdb.md`). The constitution does not copy them — it **ratifies the principle and links the detail**. Run this reconciliation pass first:
+
+1. **Read the Knowledge map** in the root `CLAUDE.md`. List every `02-DOCS/wiki/stack/*` article that exists.
+2. **Read each stack article.** Pull out anything already phrased as a rule (a version pin, a lint config, a test threshold, a naming convention).
+3. **For each existing rule, decide:** is it a *project-wide non-negotiable* (→ ratify it as a principle, linking the stack article for detail) or a *local mechanic* (→ leave it in the stack wiki, do not lift it into the constitution)?
+4. **Contradictions are findings, not fixes.** If two stack articles disagree, or a stack article contradicts what the user states now, surface it and let the user resolve — never silently pick a winner.
+
+The rule of thumb: the constitution says *"every endpoint is typed and tested to ≥80% line coverage — see `wiki/stack/fastapi.md` for the pytest setup"*. It does not paste the pytest config.
+
+## What a principle must have
+
+Every principle in the constitution is one numbered, testable statement. A vague aspiration is not a principle.
+
+- **Imperative and specific.** "Code is formatted with the repo's formatter on every commit" — not "we value clean code".
+- **Checkable.** There must be a way for `analyze` and `verify` to tell whether it held. Prefer a number, a command, or a named artifact.
+- **Owned.** If enforcement lives in a stack skill or a script, link it.
+- **Falsifiable in review.** A reviewer can point at a diff and say "this violates principle 4".
+
+```text
+Weak   — "We care about security."
+Strong — "4. No secret is ever committed; secrets load from 01-TOOLS/<provider>/.env
+          (gitignored). Enforced by secure-coding + a pre-commit secret scan."
+```
+
+## The interview (requirements-first, batched)
+
+Gather what you cannot infer, then draft. Ask in batches sized to the accompaniment level (L0: the 1-2 that matter; L3: one at a time, explained). Cover these dimensions — skip any the stack wiki already answers, and confirm rather than re-ask:
+
+1. **Stack canon** — languages, frameworks, runtime/versions, package manager. What is fixed vs. open?
+2. **Quality bar** — formatter/linter (must pass clean?), type checking (strict?), test discipline (TDD? coverage floor? what kind of tests gate a merge?).
+3. **Conventions** — naming, directory structure, module boundaries, API/error shapes, commit message format.
+4. **Branching & shipping** — branch naming, PR required?, who/what gates a merge, release cadence. (Authorship rule is fixed — see below.)
+5. **Security & privacy floor** — secret handling, authn/z baseline, data residency, dependency policy.
+6. **Accessibility & UX floor** (if there's a UI) — the minimum bar (e.g. WCAG AA, keyboard-navigable).
+7. **Performance budgets** (where they matter) — a named budget, not "should be fast".
+8. **Documentation & knowledge** — what must be written down (decisions log, the wiki) and when.
+
+For any significant either/or (e.g. "strict types or gradual?", "squash or merge commits?"), use the harness **"siempre 3 opciones"** shape where it applies: gather the constraint, present up to 3 honest options with a recommendation matched to the team's level, then ratify the choice and log it.
+
+## Fixed principles (always present)
+
+Two principles are inherited from the rsc ecosystem and appear in every constitution unless the user explicitly overrides them:
+
+- **Git authorship is the human's.** Commits and PRs are authored by the human (Eric, or whoever owns the repo). No `Co-Authored-By` an AI, no "generated with" footer. Enforced at the `ship` phase.
+- **Decisions are logged.** Every significant decision is appended to `02-DOCS/wiki/sdd/decisions.md` (or the harness `decisions.md`) with date, options considered, and the why. The constitution itself is the highest-order decision record.
+
+## Drafting the constitution
+
+Write `02-DOCS/wiki/sdd/constitution.md` from the template in `references/constitution-template.md`. Keep it short — a readable constitution is 1-2 screens, not a manual. Structure:
+
+- **Header** — project name, version (`v1.0.0`), ratified date, last-amended date.
+- **Principles** — numbered, grouped by the dimensions above. Each is one testable statement; link the stack article or script that enforces it.
+- **The bar (Definition of Done)** — the merge checklist every feature must pass. This is what `verify` runs against.
+- **Amendment log** — append-only; every change recorded (see protocol below).
+
+Create `02-DOCS/wiki/sdd/` if it does not exist. Do not overwrite an existing constitution — amend it.
+
+## Versioning & amendment protocol
+
+The constitution is versioned so `analyze` and `review` can cite "constitution v1.2.0, principle 4".
+
+- **Semantic-ish versioning.** MAJOR when a principle is removed or reversed (breaks existing work); MINOR when a principle is added or materially tightened; PATCH for wording/clarity with no behavior change.
+- **Amendments are append-only in the log.** Never silently edit a ratified principle — strike it (mark superseded) and add the new one, bump the version, and record date + why in the amendment log.
+- **Ratification.** A new or amended constitution is shown to the user and ratified explicitly before it takes effect. At L0, "ratify" is a quick yes; at L3, walk each change.
+- **Downstream notice.** When a principle changes mid-project, flag that existing specs/plans may now be inconsistent — `analyze` will catch the drift on the next run.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality / fix |
+|-----------------|---------------|
+| "I'll write a thorough constitution covering everything about the project." | That's the wiki, not the constitution. Keep only enforceable non-negotiables; link the rest. |
+| "This stack detail is important, I'll paste the lint config in here." | No. Ratify the principle, link `wiki/stack/*` for the mechanic. The constitution names the bar; the stack skill enforces it. |
+| "Two stack articles disagree — I'll just pick the stricter one." | Contradictions are findings. Surface them; the user resolves. |
+| "The principle is 'write good code' — everyone knows what that means." | Not checkable, not a principle. Make it testable or drop it. |
+| "I'll rewrite the existing constitution to match what they said today." | Amend, don't overwrite. Strike + add + bump version + log the why. |
+| "No profile yet, I'll assume they're technical and skip the dial." | Default non-technical; ask the two gauging questions or send them to `init`. |
+| "I'll add a Co-Authored-By so the commit credits the assist." | No. Git authorship is the human's — it's a fixed principle, enforced at `ship`. |
+| "I'll ratify it myself since it's obvious." | The user ratifies. Show the draft, get the explicit yes, then it takes effect. |
+
+## Checklist before handing off
+
+- [ ] `02-DOCS/wiki/harness/user-profile.md` read; verbosity matched to the dial (or gauging questions asked).
+- [ ] Reconciliation pass done against every `02-DOCS/wiki/stack/*` article; contradictions surfaced, not auto-resolved.
+- [ ] Every principle is numbered, imperative, testable, and links its enforcer where one exists.
+- [ ] The Definition-of-Done checklist is present (what `verify` runs against).
+- [ ] Fixed principles included: human git authorship + decisions logged.
+- [ ] `02-DOCS/wiki/sdd/constitution.md` written with version + ratified date + amendment log.
+- [ ] Root `CLAUDE.md` Knowledge map has a row for the constitution (additive only — never delete sections).
+- [ ] The constitution was shown to the user and explicitly ratified.
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+This skill's `02-DOCS` record is the constitution at `02-DOCS/wiki/sdd/constitution.md`, linked from a `## Knowledge map` row in the root `CLAUDE.md` (create `CLAUDE.md` if absent, additive only — never delete existing sections). Add this row if it is not already present:
+
+```markdown
+| Project constitution (SDD non-negotiables) | `02-DOCS/wiki/sdd/constitution.md` |
+```
+
+Every later rsc-sdd phase reads this file before it works. The harness maintains and improves the article over the life of the project; this skill is the place that ratifies and amends it.
+
+## Next in the chain
+
+The constitution is the guardrail; now describe what to build. Hand off to **`../specify/SKILL.md`** — turn a fuzzy intent into a spec (what & why, no implementation), grounded in these principles. The full chain: **constitution → specify → clarify → plan → tasks → analyze → implement → verify → review → ship** (with `debug`, `worktrees`, `parallel` callable on demand). The dispatcher is `../sdd/SKILL.md`.
+
+## See Also
+
+- `../sdd/SKILL.md` — the rsc-sdd dispatcher: the method, the phase map, the invoke rule.
+- `../specify/SKILL.md` — the next phase: intent → spec.
+- `../analyze/SKILL.md` — the consistency gate that checks specs/plans against this constitution.
+- `harness` — owns `02-DOCS/wiki/` (including `wiki/stack/*` and the Knowledge map this skill reconciles with and links into).
+- Stack skills the constitution *names but does not duplicate*: `../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`, `../design/SKILL.md`, `../secure-coding/SKILL.md`.
+- References: `references/constitution-template.md`.

package/skills/constitution/evals/README.md

@@ -0,0 +1,68 @@
+# Eval harness — `constitution` skill
+
+Two things are checked: that the skill **triggers** on the right prompts (and
+stays quiet on near-misses that belong to a sibling), and that it **measurably
+improves** the constitution it produces. Cases live in `cases.yaml`. There is no
+shell runner — `constitution` is a process skill judged on safety rails and
+judgment, so grading is done by an **agent harness** (a Claude Code agent with
+skills loaded) plus a human spot-check.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `constitution`.
+- `should_not_trigger` — near-misses that must route elsewhere (`route_to` names
+  a real sibling in this repo: `harness`, `init`, `fastapi`, `secure-coding`,
+  `design`).
+- `capability` — a scenario with a `must_include` rubric to grade with vs without.
+
+## Triggering eval
+
+Goal: the skill fires when it should and never on a near-miss.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing (constitution + its rsc-sdd phase siblings once they exist, plus
+   harness, init, fastapi, nextjs, go, postgresdb, flutter, design, secure-coding,
+   deployment, marketing, presentations, course-storytelling, building-agents) so
+   routing competes realistically.
+2. For each `should_trigger` prompt: feed it cold, record whether `constitution`
+   is the skill the agent loads. Run **3-5 trials** per prompt (fresh context).
+3. For each `should_not_trigger` prompt: confirm `constitution` does NOT load and
+   that the chosen skill matches `route_to`. Same 3-5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: >= 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the `harness`/`init` near-misses — those are the
+known traps, since "set up the project" reads close to "set the project's
+principles". A scaffolding-or-bootstrap prompt must not pull in `constitution`.
+
+## Capability eval
+
+Goal: prove the skill changes the answer, not just the routing.
+
+1. For the `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `constitution` loaded).
+   - **WITH** the `constitution` skill loaded.
+2. Grade each output against the `must_include` checklist — one point per
+   checkable item covered. A human or grading agent marks each present / absent.
+3. Compute coverage = `items_covered / total_items` for each run.
+
+**Pass bar: WITH the skill covers >= 80% of `must_include`; WITHOUT clearly
+lower** (target a >= 30-point gap). The discriminating behaviors are: the
+reconciliation pass against `02-DOCS/wiki/stack/*` (link, don't paste), testable
+numbered principles, the fixed authorship + decisions-logged principles,
+versioning + amendment log, the Definition-of-Done checklist, and explicit user
+ratification. A base agent typically writes a vague, unversioned wall of
+aspirations that duplicates the stack wiki — score that as a capability failure
+even if it reads tidy.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- The highest-signal capability check is reconciliation: a correct answer reads
+  the existing stack articles and LINKS them; it never pastes their config into
+  the constitution or silently resolves a contradiction between them.
+- Re-run after any edit to `SKILL.md` or `references/constitution-template.md` —
+  wording changes shift both triggering and rubric coverage.
+- Several `route_to` targets are rsc-sdd phase siblings (`specify`, `plan`,
+  `analyze`, `sdd`) that ship alongside this skill; the near-misses here route
+  only to skills already present in the repo so the eval is runnable today.

package/skills/constitution/evals/cases.yaml

@@ -0,0 +1,72 @@
+skill: constitution
+
+# Prompts that MUST load the `constitution` skill. It is the FIRST rsc-sdd phase:
+# capture a project's non-negotiable principles (stack canon, quality bars,
+# conventions, branching/security/a11y floors) into 02-DOCS/wiki/sdd/constitution.md,
+# reconciling with 02-DOCS/wiki/stack/*. It NAMES bars and links enforcers; it does
+# not describe a feature (specify) or design an implementation (plan).
+should_trigger:
+  - prompt: "Let's set the non-negotiable principles for this project before we start building features."
+    why: "Capturing project-wide non-negotiables once, up front, is the exact purpose of the constitution phase."
+
+  - prompt: "I want a project constitution: stack canon, the quality bar, and our coding conventions in one place."
+    why: "Names the artifact and the three pillars (stack canon, quality bar, conventions) the skill produces."
+
+  - prompt: "We keep relitigating test coverage and branch naming — can we ratify these as project rules once and for all?"
+    why: "Turning repeatedly-relitigated decisions into ratified, enforceable principles is a core trigger, phrased without naming the skill."
+
+  - prompt: "Amend our engineering standards to require strict TypeScript and bump the version."
+    why: "Amending a ratified principle with a version bump is the amendment protocol this skill owns."
+
+  - prompt: "What's the definition of done for the whole repo that every PR has to pass?"
+    why: "The repo-wide Definition of Done (the merge bar verify runs against) lives in the constitution, not in any single feature spec."
+
+  - prompt: "Lock down our stack canon and quality floors so the SDD phases have guardrails to read."
+    why: "Explicitly the guardrail document every later SDD phase reads — the constitution's defining role."
+
+  - prompt: "Write our project's coding standards doc — formatter must pass clean, types strict, secrets never committed."
+    why: "These are enforceable project-wide non-negotiables (quality bar + security floor), the constitution's content."
+
+  - prompt: "Establecer las reglas del proyecto: convenciones de nombres, cobertura mínima y cómo hacemos los commits."
+    why: "Spanish phrasing for setting project-wide conventions, coverage floor, and commit rules — all constitution principles."
+
+# NEAR-MISS prompts that must NOT load `constitution`. Each routes to the genuinely
+# correct sibling that exists in this repo. The recurring trap: anything that sounds
+# like 'project setup' or 'standards' but is actually a feature, a stack mechanic,
+# the wiki scaffolding, or a security implementation.
+should_not_trigger:
+  - prompt: "Set up 01-TOOLS and 02-DOCS for this workspace and generate the root CLAUDE.md."
+    route_to: "harness"
+    why: "Scaffolding the tooling + wiki layers and the Knowledge map is the harness's job; the constitution only writes one article INTO that wiki and links one row."
+
+  - prompt: "I'm starting from scratch and don't know where to begin — help me bootstrap the project."
+    route_to: "init"
+    why: "Front-door bootstrapping (gauge the user, set the accompaniment dial, recommend bundles) is init; the constitution runs after the harness exists and the profile is set."
+
+  - prompt: "Show me how to actually configure Ruff and pytest with an 80% coverage gate in our FastAPI service."
+    route_to: "fastapi"
+    why: "The constitution NAMES the coverage bar; the concrete lint/test config is a stack mechanic owned by fastapi — the skill explicitly defers this."
+
+  - prompt: "Add input validation and proper authz to our login endpoint so it can't be abused."
+    route_to: "secure-coding"
+    why: "Implementing the security baseline is secure-coding; the constitution only ratifies the principle (e.g. 'authn/z baseline met') and links the enforcer."
+
+  - prompt: "Pick the type scale, color tokens, and spacing system for our app's design language."
+    route_to: "design"
+    why: "Choosing concrete design tokens is the design skill; the constitution at most names an accessibility floor and links wiki/stack/design.md."
+
+# Concrete tasks the skill should guide, with a rubric to grade WITH vs WITHOUT
+# the skill loaded. A skill-guided answer reconciles with the stack wiki, keeps
+# principles testable, includes the fixed authorship/decisions rules, versions
+# the file, and ratifies with the user — an ungrounded answer writes a vague,
+# unversioned wall of aspirations.
+capability:
+  - scenario: "Stand up the constitution for a new project that has a Next.js frontend and a FastAPI backend. The harness already wrote 02-DOCS/wiki/stack/nextjs.md and fastapi.md with some conventions. There is a user-profile at L1 (brief)."
+    must_include:
+      - "Reads 02-DOCS/wiki/harness/user-profile.md and matches L1 verbosity (one line of why per principle, few questions) rather than a long interview."
+      - "Runs the reconciliation pass: reads the existing wiki/stack/nextjs.md and fastapi.md, lifts only project-wide non-negotiables, and LINKS those articles instead of pasting their config; surfaces any contradiction for the user to resolve rather than auto-picking."
+      - "Every principle is numbered, imperative, and testable (a number, command, or named artifact), not an aspiration like 'write clean code'."
+      - "Includes the two fixed principles: git authorship is the human's (no Co-Authored-By AI / generated-with footer, enforced at ship) and significant decisions are logged."
+      - "Produces a Definition of Done checklist (the merge bar verify runs against) covering format/lint, types, tests/coverage, conventions, branch+PR+authorship, security, and decisions logged."
+      - "Writes 02-DOCS/wiki/sdd/constitution.md with a version (v1.0.0), ratified date, and an append-only amendment log; adds the Knowledge-map row to root CLAUDE.md additively (never deleting sections)."
+      - "Shows the draft and gets explicit ratification from the user before it takes effect, and ends by pointing to the specify phase as next in the chain."

package/skills/constitution/references/constitution-template.md

@@ -0,0 +1,90 @@
+# Constitution template
+
+Render this into `02-DOCS/wiki/sdd/constitution.md`. Keep it to 1-2 screens. Every principle is one numbered, testable statement; link the `02-DOCS/wiki/stack/*` article or the script that enforces it rather than pasting the mechanic. Strike-and-replace on amendment — never silently edit a ratified principle.
+
+---
+
+```markdown
+# <Project> — Constitution
+
+> Version: v1.0.0 · Ratified: YYYY-MM-DD · Last amended: YYYY-MM-DD
+> The non-negotiable principles every rsc-sdd phase obeys. Stack mechanics live in
+> `02-DOCS/wiki/stack/*`; this file ratifies the principle and links the detail.
+
+## 1. Stack canon
+
+1. Primary language(s) and runtime: <e.g. TypeScript on Node 22, Python 3.12>. Pinned in
+   `<manifest>`. Detail: `02-DOCS/wiki/stack/<x>.md`.
+2. Frameworks fixed: <e.g. Next.js App Router, FastAPI>. Changing one is a MAJOR amendment.
+3. Package manager: <e.g. pnpm / uv>. One lockfile, committed.
+
+## 2. Quality bar
+
+4. Code is formatted and lint-clean on every commit (<formatter/linter>, zero warnings).
+   Enforced by `<pre-commit / CI step>` — detail in `02-DOCS/wiki/stack/<x>.md`.
+5. Types are <strict / checked>; the type checker passes with no errors before merge.
+6. Tests gate the merge: <TDD red→green→refactor>; line coverage ≥ <N>% on changed code.
+   Test tooling: `02-DOCS/wiki/stack/<x>.md`.
+
+## 3. Conventions
+
+7. Naming & structure: <directory layout, module boundaries, file naming>.
+8. API & errors: <error shape, status codes, response envelope> where applicable.
+9. Commit messages: <format, e.g. Conventional Commits>.
+
+## 4. Branching & shipping
+
+10. Work happens on a branch off `<default>`; merge via PR. Direct pushes to `<default>` are
+    not allowed.
+11. **Git authorship is the human's.** No `Co-Authored-By` an AI, no "generated with" footer.
+    Enforced at the `ship` phase.
+
+## 5. Security & privacy floor
+
+12. No secret is ever committed. Secrets load from `01-TOOLS/<provider>/.env` (gitignored).
+    Baseline: `secure-coding`.
+13. <authn/z baseline, data residency, dependency policy> as applicable.
+
+## 6. UX / accessibility floor (if there is a UI)
+
+14. Minimum accessibility bar: <e.g. WCAG 2.2 AA, keyboard-navigable, visible focus>.
+    Detail: `02-DOCS/wiki/stack/design.md`.
+
+## 7. Performance budgets (where they matter)
+
+15. <named budget, e.g. LCP ≤ 2.5s on the marketing site; p95 API latency ≤ 300ms>.
+
+## 8. Knowledge & decisions
+
+16. Every significant decision is appended to `02-DOCS/wiki/sdd/decisions.md` (date, options,
+    why). The constitution is the highest-order decision record.
+
+## Definition of Done (the merge bar `verify` runs against)
+
+A change ships only when ALL hold:
+
+- [ ] Formatter + linter clean (principle 4).
+- [ ] Type checker passes (principle 5).
+- [ ] Tests pass; coverage floor met on changed code (principle 6).
+- [ ] Conventions followed (principles 7-9).
+- [ ] On a branch, merged via PR, authored by the human (principles 10-11).
+- [ ] No secret committed; security baseline met (principles 12-13).
+- [ ] Accessibility / performance budgets met where they apply (principles 14-15).
+- [ ] Significant decisions logged (principle 16).
+
+## Amendment log (append-only)
+
+| Date | Version | Change | Why |
+|------|---------|--------|-----|
+| YYYY-MM-DD | v1.0.0 | Ratified initial constitution. | Project kickoff. |
+```
+
+---
+
+## Rendering notes
+
+- **Drop sections that don't apply.** No UI → drop §6. No hard perf budget → drop §7. Do not pad.
+- **Renumber on amendment carefully.** Prefer striking a principle (`~~10. …~~ (superseded by 17)`) and appending the new one over renumbering, so existing citations ("principle 10") stay valid.
+- **Version bump rules:** MAJOR = remove/reverse a principle; MINOR = add/tighten; PATCH = wording only.
+- **Link, don't paste.** Any concrete config (lint rules, pytest ini, Tailwind tokens) stays in `02-DOCS/wiki/stack/*`; the principle points to it.
+- **One screen test.** If the rendered file scrolls past ~2 screens, you are documenting, not legislating — move detail to the wiki.