rsc-universal 0.1.1

package/skills/implement/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: implement
+description: "Use when executing a planned feature into working, tested code — turning the tasks list into commits, writing code task-by-task under TDD discipline (failing test first, then the code that passes it, then refactor), with a stop-and-show checkpoint after each task. Triggers: 'implement the plan', 'build out the tasks', 'start coding this feature', 'work through the task list', 'execute the implementation', 'write the code for this spec', 'do task 3', 'continue implementing', 'red-green-refactor this', 'implement with tests first'. The SDD phase AFTER analyze and BEFORE verify. Embeds red→green→refactor and delegates concrete test tooling to the stack skill (fastapi/go/nextjs/flutter); fans independent tasks out via parallel; logs every non-obvious choice to 02-DOCS/wiki/sdd/decisions.md and stays inside the constitution. NOT spec writing, NOT planning, NOT the final lint/audit gate."
+tags: [sdd, implement, code]
+recommends: [verify]
+profiles: [core, full]
+origin: risco
+---
+
+# implement — turn the task list into tested code
+
+You have a spec, a plan, and an ordered task list (from `specify` → `plan` → `tasks`), and the
+`analyze` gate has cleared. This skill does the building: it walks the tasks in order, writes each
+one **test-first**, stops to show its work after every task, and records the decisions it makes
+along the way. It is the *intent → shipped code* engine's hands — `verify` is the gate that comes
+after, not part of this skill.
+
+This is a **process skill**. It owns the discipline (red → green → refactor, checkpoints, decision
+logging, constitution adherence). It does **not** own the test tooling — pytest fixtures, `go test`
+table-drivers, Vitest/Playwright, `flutter test` — those belong to the stack skill, and you call
+into them rather than reinventing them.
+
+## Before you write a line of code
+
+Run this short gate. Skipping it is the most common way an implement session goes sideways.
+
+1. **Read the inputs.** Open the spec (`02-DOCS/wiki/sdd/specs/<slug>.md`), the plan
+   (`02-DOCS/wiki/sdd/plans/<slug>.md`, which holds the task list), and the constitution
+   (`02-DOCS/wiki/sdd/constitution.md`). If any is missing, you are not ready to implement — route
+   back: no plan → `plan`; no task list inside the plan → `tasks`; unresolved `analyze` findings →
+   resolve them first. Do not start coding to "discover the plan as you go".
+2. **Read the SDD runtime config.** Open `02-DOCS/wiki/sdd/config.yaml`. If it is missing on
+   non-trivial work, stop and route to `sdd-init`. Use `testing.strict_tdd`,
+   `testing.commands.apply`, `testing.commands.verify`, `sdd.review_budget` and
+   `sdd.registry_path`. Do not choose a different test command from memory while config exists.
+3. **Read the skill registry.** Open `.rsc/skill-registry.json` if present. Select only the
+   relevant stack/process skills for this task, then digest them into compact rules. If the
+   registry is missing, run or recommend `npx rsc registry refresh` and record the fallback.
+4. **Read the accompaniment dial.** Open `02-DOCS/wiki/harness/user-profile.md` and read the
+   technical + accompaniment level. It sets how loud you are at each checkpoint (see the dial table
+   below). No profile yet → assume non-technical, narrate more, and ask before any irreversible step.
+5. **Confirm isolation.** Implementation happens on a feature branch or worktree, never directly on
+   the default branch. If you are on `main`/`master`, stop and hand to `worktrees` before the first
+   commit.
+6. **Scan the tasks for independence.** Mark which tasks share files/state and which are disjoint.
+   Disjoint clusters are candidates for `parallel`; everything else runs in order.
+
+## The loop — one task at a time
+
+For **each task** in the list, in order (or dispatched per the parallel rule below):
+
+```text
+RED      → write the smallest failing test that encodes the task's done-check. Run it. Watch it FAIL
+           for the right reason (assertion, not import error). A test that was never red proves nothing.
+GREEN    → write the least code that makes that test pass. No extra features, no "while I'm here".
+           Run the test. Watch it PASS.
+TRIANGULATE → add the smallest edge-case test that proves the behavior is not hard-coded
+           (only when config.testing.strict_tdd is true and the task has meaningful edge cases).
+REFACTOR → with the test green, clean up names/duplication/shape. Re-run; still green. Only now.
+CHECK    → re-read the task's done-check. Met? Constitution still honored? Decision worth logging?
+PROGRESS → append task/test/blocker/decision state to 02-DOCS/wiki/sdd/progress/<slug>.md.
+COMMIT   → commit this task as one logical unit (authorship = Eric; see ship for the rule).
+CHECKPOINT → stop and show: what changed, test output, the next task. Wait per the dial.
+```
+
+The order is load-bearing. **Red before green** is not a suggestion — a test you write *after* the
+code tells you nothing about whether it can fail. **Refactor only on green** keeps every cleanup
+reversible against a passing bar. **Checkpoint after each task** is what makes this resumable and
+reviewable instead of a 2000-line surprise diff.
+
+### The done-check is the contract
+
+Each task carries a done-check from the `tasks` phase ("returns 409 on duplicate email", "list
+renders empty state when zero items"). That sentence **is** your first failing test. Do not invent a
+looser check, and do not mark a task done because the code "looks right" — done means the done-check's
+test is green and the relevant acceptance criterion in the spec is satisfied.
+
+## Delegating the test tooling (do not reinvent it)
+
+Write the *intent* of the test here; get the *mechanics* from the stack skill. The discipline is
+yours; the fixtures, runners and idioms are theirs.
+
+| Stack | Where the test mechanics live | What you delegate |
+| --- | --- | --- |
+| FastAPI / async Python | `../fastapi/references/testing.md` | `ASGITransport` in-process client, `dependency_overrides`, transactional rollback fixture, `pytest-asyncio` |
+| Go services | `../go/references/testing.md` | table-driven subtests, `httptest`, interface fakes, golden files, `errors.Is` checks |
+| Next.js / React | `../nextjs/references/testing.md` | Vitest + Testing Library for units, Playwright for flows, server-action / RSC testing |
+| Flutter | `../flutter/references/testing.md` | `flutter test` widget tests, `pump`/`pumpAndSettle`, golden tests, mocked repositories |
+
+If the feature spans two stacks (a Next.js front-end calling a FastAPI back-end), each task names its
+stack and pulls that stack's testing reference — you do not mix idioms inside one task.
+
+## Skill digestion and resolution
+
+When a task or subagent needs skill context, use the registry path from config:
+
+```text
+.rsc/skill-registry.json
+```
+
+Select the smallest set of skills that match the task. Digest each selected skill into 4-5 compact rules that affect this task. A task brief or checkpoint includes:
+
+```text
+Selected skills: fastapi, postgresdb, implement
+Compact rules:
+- Use the configured apply command from config.yaml.
+- Red test first; verify it fails for the right reason.
+- Keep DB migrations expand-contract when touching production tables.
+Skill resolution:
+- used: [...]
+- missing: [...]
+- fallback: [...]
+```
+
+If a skill is referenced but unavailable, say so and record the fallback. Do not silently pretend it was used.
+
+## Apply progress
+
+Maintain an append-only progress file:
+
+```text
+02-DOCS/wiki/sdd/progress/<slug>.md
+```
+
+Entry shape:
+
+```markdown
+## T004 — 2026-06-02
+- status: complete
+- red: `pytest tests/auth/test_login.py::test_bad_password_returns_401` failed for expected missing route
+- green: same test passed
+- triangulation: blank title returns 422
+- files: app/auth.py, tests/auth/test_login.py
+- decision: none
+- blocker: none
+```
+
+This file is what makes resumes and archive reliable. Never rewrite old entries; append corrections as new entries.
+
+## Running independent tasks in parallel
+
+When two or more tasks are genuinely disjoint — **no shared files, no shared state, no ordering
+dependency** — fan them out with `parallel` rather than serializing. The rule of thumb:
+
+- **Serialize** when a later task imports, edits, or asserts against an earlier task's output, or
+  when they touch the same file.
+- **Parallelize** when each task could be done by a different person who never talks to the others
+  (e.g. "add the `users` repository" and "add the `invoices` repository" in separate modules).
+
+Each parallel branch still runs its own full red → green → refactor loop and reports back its diff +
+test output. You merge the branches, then run the *combined* test suite before the next checkpoint —
+green-in-isolation is not green-together. Hand the orchestration to `parallel`; keep the TDD
+discipline inside each branch.
+
+## The accompaniment dial — how loud at each checkpoint
+
+Read the level from `02-DOCS/wiki/harness/user-profile.md` and match it. Same work, different volume.
+
+| Level | At each checkpoint you show… | Questions you ask |
+| --- | --- | --- |
+| **L0** terse | one line: task done, tests green, moving on | none unless blocked or about to do something irreversible |
+| **L1** brief | task + the one *why* behind any non-obvious choice | only where the plan genuinely forked |
+| **L2** decisions | task + each relevant decision and its trade-off | confirm before deviating from the plan |
+| **L3** full | task + reasoning, test output read aloud, what's next and why | ask to contextualize each decision; teach as you go |
+
+The dial changes verbosity and question count — it **never** changes the engineering. TDD, the
+done-checks, the constitution and decision logging hold at every level, including L0.
+
+## Logging decisions (the 02-DOCS trail)
+
+When you make a choice the plan did not fully specify — a library, a data shape, an error contract, a
+deviation from the plan — append it to `02-DOCS/wiki/sdd/decisions.md` (append-only; create it if
+absent and add a row to the root `CLAUDE.md` `## Knowledge map` under the `sdd/` topic). One entry:
+
+```text
+## YYYY-MM-DD — <short title>  (feature: <slug>, task: <n>)
+Context   — what forced the choice
+Options    — the 2–3 real alternatives weighed
+Decision   — what you chose
+Why        — the trade-off that decided it
+```
+
+Log the **non-obvious** ones — the choices a reviewer would otherwise have to reverse-engineer from
+the diff. Do not log "named the variable `count`". If a decision contradicts the constitution, you do
+not get to log your way around it: stop (see red flags).
+
+## Staying inside the constitution
+
+`02-DOCS/wiki/sdd/constitution.md` holds the project's non-negotiables (stack canon, quality bars,
+naming, security posture). Every task you implement must honor it. If a task can only be done by
+breaking a constitutional rule, that is a contradiction the `analyze` phase should have caught —
+surface it and stop; do not quietly violate the constitution to make a test pass. The constitution
+outranks the plan, and the plan outranks your in-the-moment preference.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality |
+| --- | --- |
+| "I'll write the tests after, once the code settles" | Then the test only confirms what you built, not what was asked. Red first, always. |
+| "This task is trivial, skip the failing test" | Trivial code breaks too, and the next task may lean on it. Smallest red test still goes first. |
+| "I'm here anyway, I'll also fix that other thing" | Scope creep buries the diff and breaks the done-check contract. One task, one commit. |
+| "The test passed first try without ever being red" | It tests nothing. Make it fail on purpose, then make it pass. |
+| "I'll batch ten tasks into one big commit to save time" | You just made the work unreviewable and un-resumable. One logical unit per task. |
+| "The constitution's rule doesn't fit here, I'll bend it" | The constitution outranks you. Surface the conflict; don't bend it silently. |
+| "These two tasks touch the same file but I'll parallelize anyway" | Shared file = shared state = merge pain and lost work. Serialize them. |
+| "Refactor now, the test is still red" | Never refactor on red — you can't tell a cleanup from a regression. Get green first. |
+| "I'll mark it done, the code looks correct" | Done = the done-check's test is green and the acceptance criterion holds. Looks ≠ green. |
+| "I'll just write the .env so the integration test runs" | Never. Secrets are the user's; mock/stub the boundary or use a test fixture. |
+
+## Red flags — stop and re-route
+
+- **No plan or no task list** → you cannot implement intent you haven't planned. Route to `plan` /
+  `tasks`.
+- **Unresolved `analyze` findings** (contradiction between constitution ↔ spec ↔ plan ↔ tasks) →
+  resolve them before any code; they will only get more expensive after the diff exists.
+- **A task forces a constitution violation** → surface it, stop, kick it back to `analyze`/`plan`.
+- **You're on the default branch** → stop before the first commit; hand to `worktrees`.
+- **A test won't go red** (wrong reason — import error, syntax) → fix the test before trusting it.
+- **The combined suite is red after a parallel merge** → do not checkpoint as done; debug with
+  `debug` before continuing.
+- **You're tempted to disable/skip a failing test to "make progress"** → that's the bug talking.
+  Diagnose with `debug`; never ship around a red test.
+
+## Checklist (copy per task)
+
+```text
+- [ ] Read the task's done-check; it is my first test's assertion
+- [ ] RED: smallest test written, run, fails for the RIGHT reason
+- [ ] GREEN: least code to pass; test now green
+- [ ] REFACTOR: cleaned up on green; still green
+- [ ] Constitution honored; no banned pattern introduced
+- [ ] Non-obvious decision (if any) logged to 02-DOCS/wiki/sdd/decisions.md
+- [ ] Apply progress appended to 02-DOCS/wiki/sdd/progress/<slug>.md
+- [ ] Skill resolution recorded (used/missing/fallback/compact rules)
+- [ ] Committed as one logical unit (authorship = Eric)
+- [ ] Checkpoint shown at the dial's level; next task named
+```
+
+## Result envelope
+
+End every implementation checkpoint or completed batch with:
+
+```json result-envelope
+{
+  "status": "complete",
+  "executive_summary": "Implemented task(s) with red/green/triangulate/refactor evidence.",
+  "artifact": "02-DOCS/wiki/sdd/progress/<slug>.md",
+  "next_recommended": "implement|verify",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["implement"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Use config testing commands.", "Append progress after every task."]
+  },
+  "evidence": ["red test output", "green test output", "progress entry path"]
+}
+```
+
+## What this skill is NOT
+
+- **Not the lint/type/audit gate.** Per-task tests prove the task; the *whole-suite* run plus
+  lint/type/security audit and acceptance-criteria sign-off is `verify`'s job. Don't claim the
+  feature is done here — that claim belongs to `verify`, on evidence.
+- **Not spec or plan writing.** If you find the plan is wrong mid-build, stop and amend it via
+  `plan`; don't silently re-architect inside a commit.
+- **Not the deep-debug protocol.** When a test fails for a reason you don't understand, switch to
+  `debug` (reproduce → isolate → hypothesize → fix → verify) instead of guessing.
+
+## Where you are in the chain
+
+`constitution` → `specify` → `clarify` → `plan` → `tasks` → `analyze` → **implement** → `verify` →
+`review` → `ship`. On-demand from here: `debug` (a test fails mysteriously), `worktrees` (need
+isolation), `parallel` (independent tasks to fan out).
+
+**Next:** when every task's done-check is green and committed, go to `verify` — run the stack skill's
+`scripts/verify.sh`, confirm the spec's acceptance criteria, and let evidence (not assertion) declare
+the feature done.
+
+## Orientación (siempre)
+
+Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
+

package/skills/implement/evals/README.md

@@ -0,0 +1,56 @@
+# Eval harness — `implement` skill
+
+Run by an **agent harness** (an LLM agent with the Skill tool), not a pure shell script.
+`cases.yaml` is the fixture; this README is the honest run procedure. Three things to measure:
+**triggering** (should fire), **anti-triggering** (must not fire), and **capability** (does the
+skill make the build better).
+
+`implement` is a process skill — it ships no `scripts/verify.sh`. It is judged on its safety rails
+(test-first ordering, per-task checkpoints, decision logging, constitution adherence), not on a
+deterministic command.
+
+## 1. Triggering accuracy
+
+For each prompt in `should_trigger` and `should_not_trigger`:
+
+1. Start a fresh agent session with the `implement` skill available in the catalog, plus its named
+   routing siblings (`verify`, `tasks`, `debug`, `worktrees`, and the stack skills such as
+   `fastapi`) present but not the subject — so routing is realistic.
+2. Feed the prompt verbatim. Do **not** hint that a skill exists.
+3. Observe whether the agent invokes the `implement` skill.
+4. Run **3–5 trials** per prompt (LLM routing is stochastic); record the fire rate.
+
+Pass conditions:
+- Every `should_trigger` prompt fires `implement` in **≥ 90%** of trials.
+- Every `should_not_trigger` prompt does **not** fire it in ≥ 90% of trials, and the agent prefers
+  the named `route_to` sibling. The boundaries to watch: `tasks` (makes the list, doesn't build it),
+  `verify` (the final whole-suite gate, not per-task tests), `debug` (mysterious failures), and the
+  stack skills (concrete test tooling). A near-miss leaking into `implement` is a harder failure
+  than a missed trigger — fix the description boundary before shipping.
+
+## 2. Capability uplift (with vs without)
+
+For the `capability` scenario:
+
+1. **Without skill:** run the scenario in a clean session, no `implement` skill loaded. Capture the
+   answer.
+2. **With skill:** run the same prompt with `implement` (and the named stack sibling) loaded.
+3. Grade both against the scenario's `must_include` checklist — one point per bullet that is
+   *concretely* present (e.g. an actual failing test shown first, not just the phrase "test-first").
+4. Use 3 trials each side; average the coverage.
+
+Pass conditions:
+- **With** the skill: `must_include` coverage **≥ 80%**.
+- **Measurable uplift:** with-skill coverage beats without-skill. The expected gaps in the
+  without-skill run are the ones this skill exists to close: writing the test *after* the code (or
+  skipping the red step), barrelling through multiple tasks with no checkpoint, hand-rolling a test
+  runner instead of delegating to the stack reference, omitting the decisions.md trail, and claiming
+  "done" without tying it to the done-check + acceptance criterion.
+
+## What a failing eval tells you
+
+- Trigger misses → the description's "Use when…" triggers are too narrow; widen the phrasings.
+- Near-miss leaks → the boundary against `tasks`/`verify`/`debug` is blurry in the description; sharpen
+  the NOT clauses.
+- Capability gaps → the SKILL.md body under-specifies the loop (red→green→refactor), the checkpoint,
+  the delegation, or the decision log; tighten the relevant section.

package/skills/implement/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: implement
+
+should_trigger:
+  - prompt: "We've got the plan and the task list approved. Start building it out — work through the tasks and write the code."
+    why: "Canonical entry: a planned feature with an approved task list, now asking to execute it into code. Squarely this skill."
+  - prompt: "Do task 3 from the plan, write the test first then the code, and stop so I can review before you move on."
+    why: "Single task, test-first, stop-and-show checkpoint — the red→green loop plus the checkpoint discipline this skill owns."
+  - prompt: "Implement this feature red-green-refactor: failing test, make it pass, then clean it up. One commit per task."
+    why: "Explicit TDD cadence and one-commit-per-task — the core discipline of this skill, named without naming the phase."
+  - prompt: "Continue implementing where we left off; the users repo is done, next is the invoices repo. Those two don't share state — can you do the rest in parallel?"
+    why: "Resuming an in-progress build and asking about parallelizing disjoint tasks — the independence rule lives in this skill (which hands orchestration to parallel)."
+  - prompt: "Take the approved spec and turn it into working, tested code. I want a checkpoint after every task and the design choices written down somewhere."
+    why: "Execute spec→code with per-task checkpoints and decision logging to 02-DOCS — exactly this skill's loop and its decisions.md trail."
+  - prompt: "The analyze gate passed. Build it. Write each piece test-first and don't let it drift from the plan."
+    why: "Post-analyze, pre-verify execution with TDD and plan-adherence — the precise slot this skill fills in the SDD chain."
+
+should_not_trigger:
+  - prompt: "The feature's all coded and committed. Run the full lint, type-check, test suite and security audit and tell me if it's actually done."
+    route_to: "verify"
+    why: "Whole-suite lint/type/audit + acceptance sign-off is the verify gate, not per-task implementation. This skill explicitly defers the done-claim to verify."
+  - prompt: "Before we write any code, break this plan into an ordered list of small tasks, each with a way to tell it's finished."
+    route_to: "tasks"
+    why: "Producing the ordered task list with done-checks is the tasks phase; this skill consumes that list, it doesn't create it."
+  - prompt: "One of my tests is failing intermittently and I can't tell why. Help me find the root cause before I change anything."
+    route_to: "debug"
+    why: "Mysterious failure needing reproduce→isolate→hypothesize is the debug protocol; this skill routes to debug rather than guessing."
+  - prompt: "We need an isolated branch/worktree for this feature so it doesn't touch my current working tree. Set that up."
+    route_to: "worktrees"
+    why: "Creating the isolated branch/worktree is the worktrees skill; implement only checks that isolation exists before the first commit."
+  - prompt: "Write me the exact pytest fixture that gives an in-process FastAPI client with a transactional rollback per test."
+    route_to: "fastapi"
+    why: "Concrete test-tooling mechanics for FastAPI live in the fastapi testing reference; this skill delegates the mechanics rather than reinventing them."
+
+capability:
+  - scenario: "User asks: 'Implement this task from the plan: POST /tasks creates a task and returns 201; the done-check says it must reject a blank title with 422. Do it test-first and stop after.' (FastAPI stack noted in the plan.)"
+    must_include:
+      - "RED first: writes the smallest FAILING test encoding the done-check (asserts 201 on a valid create AND 422 on a blank title) and states the test must be run and seen to fail for the right reason before any implementation"
+      - "GREEN: writes the least endpoint code to pass — no extra fields or features beyond what the done-check requires"
+      - "REFACTOR only after green, with a note to re-run and confirm still green"
+      - "Delegates the test mechanics to the FastAPI testing reference (ASGITransport in-process client + dependency_overrides + transactional rollback fixture) rather than hand-rolling a runner"
+      - "Stops at a checkpoint after the task (does not barrel into the next task) and adapts checkpoint verbosity to the accompaniment level in 02-DOCS/wiki/harness/user-profile.md"
+      - "Commits the task as one logical unit and notes authorship is Eric (no Co-Authored-By Claude)"
+      - "Logs any non-obvious choice (e.g. error envelope shape) to 02-DOCS/wiki/sdd/decisions.md, and ties done to the done-check + spec acceptance criterion (not 'looks right'), pointing to verify for the final whole-suite gate"

package/skills/init/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: init
+description: "Use when starting from nothing or pointing the rsc-skills harness at an existing project — the front door / bootstrapper. It gauges the user's technical level FIRST (non-technical by default), sets an explanation/accompaniment dial, then discovers what they want to build OR govern (any software stack, OR a non-code harness: running a company/ops, research, personal knowledge, content). It detects greenfield vs brownfield, profiles the user into 02-DOCS, RECOMMENDS which rsc skills to install (printing the exact `npx rsc add` commands), and hands off to the harness skill to scaffold 01-TOOLS + 02-DOCS. Triggers: 'empezar de cero', 'no sé por dónde empezar', 'start a new project', 'bootstrap', 'set up the harness', 'monta el proyecto', 'quiero montar una empresa/ops/wiki con esto', 'arranca', 'init'. NOT the scaffolder itself (that's the harness skill) and NOT a specific stack skill."
+tags: [init, bootstrap, start, new, setup]
+recommends: [harness]
+profiles: [minimal, core, full]
+origin: risco
+---
+
+# init — the rsc-skills Front Door
+
+*The very first thing you run. It meets the user where they are — assuming non-technical until told otherwise — figures out what they actually want, recommends the right skills, and hands off to the `harness` skill to build the workspace.*
+
+It **profiles, discovers, and recommends**, then prints the exact install commands and the handoff. The boundary is fixed: **`init` writes ONLY the user-profile + decisions log under `02-DOCS/wiki/harness/` and the `CLAUDE.md` Knowledge-map link; ALL other `01-TOOLS/` + `02-DOCS/` scaffolding is the `harness` skill's job.** Think of `init` as the receptionist: it learns who you are and what you need, writes that down where every other skill can read it, and walks you to the right room.
+
+It is **domain-agnostic**. The thing being built or governed may be:
+
+- **Software** — any stack (web, mobile, backend, agents, a CLI, a data pipeline).
+- **A non-code harness** — running a company / operations, a research program, a personal knowledge base, or a content operation that connects to tools (email, calendar, CRM, docs, payments). No code required; the same `01-TOOLS/` + `02-DOCS/` structure governs it (scaffolded by the `harness` skill, not here).
+
+## Non-technical-first + the accompaniment dial (read this first)
+
+This is the most important section. The whole harness behaves differently depending on two values set here. **Set them before doing anything else, on first contact, in this order.**
+
+### Step 1 — Gauge technical level (the VERY FIRST question)
+
+The system **always starts assuming the user is non-technical.** The very first thing you say, before any discovery, gauges their technical level — framed kindly, never making anyone feel small. Ask once, in their language. For a Spanish speaker:
+
+> "Antes de nada, para hablarte como te resulte más cómodo: ¿te manejas con código y términos técnicos, o prefieres que te lo explique todo en cristiano? No hay respuesta mala — solo me ayuda a no aburrirte ni perderte."
+
+For an English speaker:
+
+> "First, so I talk to you the right way: are you comfortable with code and technical terms, or would you rather I explain everything in plain language? There's no wrong answer — it just helps me not bore you or lose you."
+
+Until they say otherwise, **default to non-technical framing**: plain language, no jargon, analogies over acronyms. Record the answer as `technical_level: non-technical | mixed | technical`.
+
+### Step 2 — Set the accompaniment / explanation dial
+
+Immediately after, present the dial and let them pick. Describe each option clearly — do not just list letters:
+
+- **L0 — "Modo cavernícola"**: mínimas palabras. Hago las cosas y ya, casi sin explicar. Para quien quiere resultados y cero ruido.
+- **L1 — "Breve"**: una línea de *por qué* en cada paso. Sabes lo que hago sin que te cuente la vida.
+- **L2 — "Explica decisiones"**: justifico cada decisión relevante a medida que avanzo. Para quien quiere entender el porqué de lo importante.
+- **L3 — "Acompañamiento total"**: te lo explico TODO, te hago muchas preguntas para entender bien tu contexto, y razono cada decisión. Ideal si no eres técnico y quieres aprender mientras montamos esto.
+
+Record as `accompaniment_level: L0 | L1 | L2 | L3`. If the user is non-technical and gives no preference, **default to L3**. If technical and silent, default to L1.
+
+### Step 3 — Persist BEFORE anything else
+
+Before discovery, before any recommendation, write the profile to `02-DOCS` and link it from the root `CLAUDE.md`. This is non-negotiable: every other skill reads these values to decide how much to explain and how many questions to ask.
+
+- `02-DOCS/wiki/harness/user-profile.md` — the living profile (technical level, accompaniment level, goals, context, constraints). Format in `references/accompaniment-and-profile.md`.
+- `02-DOCS/wiki/harness/decisions.md` — an **append-only** decisions log. Every significant decision gets one entry, never edited or deleted. Format in `references/accompaniment-and-profile.md`.
+- Root `CLAUDE.md` → a `## Knowledge map` section linking to BOTH files. Create `CLAUDE.md` if absent (additive only — never delete existing sections).
+
+If `02-DOCS/` does not yet exist (greenfield), create `02-DOCS/wiki/harness/` now — just enough to hold these two files. That, plus the `CLAUDE.md` Knowledge-map link, is everything `init` writes; ALL other `01-TOOLS/` + `02-DOCS/` scaffolding is the `harness` skill's job.
+
+### How every skill adapts to the dial
+
+Every rsc skill MUST read `user-profile.md` at the start of a session and adapt:
+
+| Level | Verbosity | Questions it asks | Jargon |
+| --- | --- | --- | --- |
+| L0 | One line of output, results only | None beyond hard blockers | Avoided |
+| L1 | One *why* line per step | Only when genuinely ambiguous | Minimal, defined inline |
+| L2 | Justify each relevant decision | Asks before each significant decision | OK if defined once |
+| L3 | Explain everything, narrate reasoning | Many — contextualizes every choice | Always translated to plain language |
+
+`technical_level` is an orthogonal modifier: even at L0, a non-technical user gets plain-language phrasing; even at L3, a technical user gets to skip the 101 explanations. Full rules and the exact file formats → `references/accompaniment-and-profile.md`.
+
+## The "siempre 3 opciones" decision pattern
+
+For **any** significant decision — deploy target, database, framework, hosting, tooling, which CRM, where to keep documents — never decide silently and never dump ten options. Run this pattern:
+
+1. **Gather requirements first.** Ask the questions that actually drive the choice. For a deploy target: expected number of users, concurrent users, budget, data region / residency rules, the team's comfort operating servers, and scaling needs. Match the number and depth of questions to the accompaniment level (L0: ask only blockers; L3: ask all, explaining why each matters).
+2. **Present EXACTLY 3 options** with honest trade-offs — what each is good at, what it costs, what it demands of them.
+3. **Recommend one**, matched to their answers AND their level, and say why in language they understand.
+4. **Log the decision** to `02-DOCS/wiki/harness/decisions.md` (append-only) once they pick.
+
+Canonical deploy example (tailor the third option to the case):
+
+1. **Hetzner VPS + Coolify** — cheapest, total control, but you self-manage the server (updates, backups, uptime).
+2. **Vercel** — zero-ops, fully managed, scales itself; gets expensive at scale and locks you into its model.
+3. **A third matched to the case** — Fly.io (run close to users, simple containers), Railway (managed, gentle learning curve), or a managed cloud (AWS/GCP) when compliance or an existing org demands it.
+
+Full pattern, the requirements-gathering checklists per decision type, and the worked deploy example → `references/recommend-skills.md`.
+
+## The flow
+
+Run these phases in order. Phase 1 is mandatory and comes before everything.
+
+```text
+PROFILE → DISCOVER → RECOMMEND → HANDOFF
+```
+
+### Phase 1 — PROFILE
+
+Gauge technical level (Step 1), set the accompaniment dial (Step 2), and persist the profile + Knowledge-map link (Step 3) — all per the section above. Do not proceed until `user-profile.md` exists and `CLAUDE.md` links it.
+
+### Phase 2 — DISCOVER
+
+Figure out two things: **the state of the ground** and **what they want**.
+
+**Greenfield vs brownfield** — detect, don't ask blindly:
+
+- **Brownfield** if the workspace has subproject manifests (`package.json`, `pyproject.toml`, `pubspec.yaml`, `go.mod`, `Cargo.toml`), source files, legacy `XX-*` folders, or an existing `01-TOOLS/` / `02-DOCS/`. Detect the stack and current state the way `harness` SCAN does (read-only walk; ignore `node_modules/`, `.venv/`, `.next/`, `.git/`, `dist/`, `build/`, `__pycache__/`, `.dart_tool/`). Summarize what you found and confirm with the user.
+- **Greenfield** if the workspace is empty or has only stray notes. Then it's a brand-new idea — interview from zero.
+
+**What they want to build OR govern** — establish the domain. Is it software (which surfaces: backend, frontend, mobile, agents)? Or a non-code harness (company/ops, research, personal knowledge, content)? Then capture goals, audience, constraints, and any tools/providers already in play.
+
+Record everything to `02-DOCS/wiki/harness/` as you go. Use the greenfield and brownfield questionnaires (for software AND non-code harnesses) in `references/discovery.md`. Ask in batches sized to the accompaniment level — never dump every question at once.
+
+### Phase 3 — RECOMMEND
+
+Map what you learned to individual rsc skills and **print the exact `npx rsc add` commands**. A skill cannot install anything itself — it recommends and prints commands the user runs. Skill map:
+
+| Need | Skills | Why (one line, matched to level) |
+| --- | --- | --- |
+| Always | `harness` | The control plane that scaffolds and governs the workspace (`suggest` comes with it as the floor). |
+| Software backend | `fastapi` / `go`, `postgresdb` | The server, the database, the API. |
+| Software frontend | `nextjs` / `flutter`, `design` | The web/mobile UI people see. |
+| Marketing / landing / decks / teaching | `marketing`, `presentations`, `course-storytelling` | The words and slides. |
+| AI agents | `building-agents` | Agent loops, tools, RAG. |
+| Security & shipping / ops (incl. non-code company harness connecting tools) | `secure-coding`, `deployment` | Ship it safely and wire up external tools. |
+
+Print, with a one-line *why* per recommended skill (language matched to the user's level):
+
+```text
+npx rsc add <skill> [<skill> ...]
+```
+
+Recommend only skills their answers justify — same discipline as "no speculative tools". Full skill map, sample printouts per scenario, and the requirements-first decision pattern → `references/recommend-skills.md`.
+
+### Phase 4 — HANDOFF
+
+Tell the user to install `harness` (`npx rsc add harness`) and then run the **`harness`** skill to actually scaffold the `01-TOOLS/` + `02-DOCS/` workspace. `init` stops here — it has set the profile, recorded the discovery, and recommended the skills. `harness` reads the profile and builds the structure.
+
+> "Tu perfil y lo que hemos hablado ya están guardados. Cuando hayas instalado las skills de arriba (`npx rsc add …`), ejecuta `harness` y monto el esqueleto del proyecto (`01-TOOLS/` + `02-DOCS/`) leyendo todo lo que acabamos de decidir."
+
+## Iron rules (non-negotiable)
+
+1. **Profile first, always.** Technical-level question is the literal first thing. Nothing — no discovery, no recommendation — happens before `user-profile.md` exists and `CLAUDE.md` links it.
+2. **Non-technical by default.** Plain language until told otherwise. Never assume the user reads code.
+3. **The dial governs verbosity AND question count.** Read it, obey it, in this skill and every skill downstream. L0 means *do it and stop talking*; L3 means *explain everything and ask*.
+4. **Three options, requirements first.** For any significant decision: gather the driving requirements, present exactly 3 options with honest trade-offs, recommend one, log it.
+5. **Recommend, never install.** A skill cannot run `npx rsc add`. Print the commands; the user runs them.
+6. **No speculative skills.** Recommend a skill only if the discovery justified it. No "you'll probably want agents too".
+7. **Persist as you learn.** Goals, context, constraints, decisions go to `02-DOCS/wiki/harness/` continuously — `user-profile.md` for state, `decisions.md` append-only for choices.
+8. **`init` writes only the profile + the link.** It writes ONLY the user-profile + decisions log under `02-DOCS/wiki/harness/` and the `CLAUDE.md` Knowledge-map link. ALL other `01-TOOLS/` + `02-DOCS/` scaffolding is the `harness` skill's job. Hand off; do not do its job.
+9. **Additive to `CLAUDE.md`.** Create it if absent; otherwise add/update only the `## Knowledge map` section. Never delete user content.
+10. **Domain-agnostic.** Software and non-code harnesses get the same first-class treatment. Never assume "project" means "code".
+
+## Rationalizations — STOP
+
+These thoughts mean the skill is about to break its own rules. Recognize and abort:
+
+| Excuse | Reality |
+| --- | --- |
+| "They sound technical, I'll skip the level question" | No. The level question is the first thing, always. Ask it. |
+| "I'll just pick Vercel, it's obviously best" | No. Gather requirements, present 3, recommend with reasons, log it. |
+| "I'll recommend every skill to be safe" | No. Recommend only what discovery justified. |
+| "I'll scaffold 01-TOOLS now while I'm here" | No. That's the `harness` skill. `init` profiles and hands off. |
+| "The profile can wait until after discovery" | No. Profile first — every later question's framing depends on it. |
+| "This is a company, not code, so the harness doesn't apply" | No. Domain-agnostic. A non-code harness uses the same structure. |
+| "I'll install the skills for them" | No. A skill can't install. Print the `npx rsc add` commands. |
+| "They said 'ok', that's enough to pick the database" | No. A significant decision needs the 3-option pattern and a log entry. |
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+This skill's `02-DOCS` record is the **user profile** at `02-DOCS/wiki/harness/user-profile.md` plus the append-only **decisions log** at `02-DOCS/wiki/harness/decisions.md`. Both are written in Phase 1 and updated throughout, and both are linked from a `## Knowledge map` section in the root `CLAUDE.md` (created if absent, additive only). Every rsc skill reads the profile first and adapts its verbosity and question count to `accompaniment_level` and `technical_level`. Those two files plus the Knowledge-map link are everything `init` writes; ALL other `01-TOOLS/` + `02-DOCS/` scaffolding is the `harness` skill's job, and it reads this same profile.
+
+Verify the profile and the Knowledge-map link exist with `scripts/verify.sh` (read-only; warns, never fails).
+
+## See Also
+
+- `harness` — the scaffolder this skill hands off to; builds `01-TOOLS/` + `02-DOCS/` from the profile (the SCAN→AUDIT→CONSENT→APPLY→VERIFY engine).
+- `deployment` — invoked at runtime when the deploy decision (the "siempre 3 opciones" canonical example) is made; Hetzner+Coolify, Vercel, Fly.io and friends.
+- `secure-coding` — input validation, authn/z, secret handling; recommended whenever software is being shipped.
+- Stack skills (`fastapi`, `go`, `nextjs`, `flutter`, `building-agents`, …) are **recommended at runtime** by Phase 3 based on discovery — not hardwired here.
+- References: `references/accompaniment-and-profile.md`, `references/discovery.md`, `references/recommend-skills.md`.
+
+## Orientación (siempre)
+
+Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/init/evals/README.md

@@ -0,0 +1,49 @@
+# Eval harness — `init`
+
+Evaluates the `init` skill (the rsc-skills front door / bootstrapper) on two axes:
+**triggering** (does it fire on the right prompts and stay quiet on near-misses) and
+**capability** (does loading it measurably improve the agent's answer). Cases live in
+`cases.yaml`. These run via an **agent harness**, not a pure shell script — a human or a
+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 `init`.
+- `should_not_trigger` (6) — near-misses that must route elsewhere (`route_to` names the
+  correct sibling, or `none`).
+- `capability` (2) — scenarios with `must_include` rubrics to grade WITH vs WITHOUT the skill.
+
+## A. Triggering eval
+
+1. Load **only** `init` 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 `init` activates (the agent should lead with the technical-level question /
+   profiling, not jump into building). Run **3–5 trials** per prompt.
+3. For each `should_not_trigger` prompt: same procedure, but a **pass** = `init` does NOT fire.
+   Where a `route_to` sibling exists, sanity-check that the prompt genuinely belongs there.
+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 (i.e. at most 1 of the 13 prompts 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, `init` 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 `init`: technical-level question **first**, the L0–L3
+  accompaniment dial, writing **only** the profile + decisions log + CLAUDE.md Knowledge-map
+  link, and **handing off** scaffolding to `the harness skill` (never doing it itself).
+- Watch the key confusable: the built-in `/init` (CLAUDE.md architecture doc generator) is a
+  different thing — the rsc `init` does discovery/profiling/recommendation, not codebase docs.
+- Run after any edit to `SKILL.md` or its `description`, since both axes are sensitive to wording.