@damiangilgonzalez/harness 1.3.7

package/skills/init/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: init
+description: "Use when starting from nothing or pointing rsc at an existing project — the front door. Gauges technical level and the accompaniment dial first (non-technical by default), discovers what the user wants to build or govern (any stack, or a non-code harness: company/ops, research, knowledge, content), writes the profile to docs, and installs the skills discovery justified. NOT the scaffolder (that is `harness`), NOT a stack skill."
+tags: [init, bootstrap, start, new, setup]
+recommends: [harness]
+profiles: [minimal, core, ui, 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, installs the right skills, and hands off to
+`harness` to build the workspace.*
+
+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. The boundary is fixed: **`init`
+writes only the user-profile and decisions log under `docs/wiki/harness/`, plus the `CLAUDE.md`
+Knowledge-map link.** Every other `01-TOOLS/` + `docs/` scaffold belongs to `harness`.
+
+It is **domain-agnostic**. The thing being built or governed may be software on any stack, or a
+non-code harness — running a company, an ops desk, a research program, a knowledge base, a content
+operation. No code required; the same structure governs it. Never assume "project" means "code".
+
+## First contact: two values, set before anything else
+
+The whole harness behaves differently depending on these two. Nothing — no discovery, no
+recommendation — happens before the profile exists and `CLAUDE.md` links it.
+
+**Step 1 — Gauge technical level.** Literally the first thing you say, before any discovery, framed
+so nobody feels small. Ask once, in their language:
+
+> "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."
+
+> "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."
+
+Record `technical_level: non-technical | mixed | technical`. Until they say otherwise, assume
+non-technical: plain language, analogies over acronyms.
+
+**Step 2 — Set the accompaniment dial.** Present it and let them pick; describe the options, do not
+just list letters.
+
+| Level | What they get |
+| --- | --- |
+| L0 — cavernícola | Results, almost no explanation. One line of output; no questions beyond hard blockers. |
+| L1 — breve | One line of *why* per step; questions only when genuinely ambiguous. |
+| L2 — explica decisiones | Each relevant decision justified; asks before each significant one. |
+| L3 — acompañamiento total | Explains everything, reasons out loud, asks a lot. Ideal for learning while building. |
+
+Non-technical and silent → default **L3**. Technical and silent → **L1**. `technical_level` is an
+orthogonal modifier: even at L0 a non-technical user gets plain phrasing; even at L3 a technical one
+skips the 101s. Every rsc skill reads these two values and obeys them — L0 means *do it and stop
+talking*. Full rules and file formats → `references/accompaniment-and-profile.md`.
+
+**Step 3 — Persist immediately.** Before discovery, before any recommendation:
+
+- `docs/wiki/harness/user-profile.md` — the living profile (levels, goals, context, constraints).
+- `docs/wiki/harness/decisions.md` — append-only. Entries are never edited or deleted.
+- Root `CLAUDE.md` → a **short** `## Knowledge map` pointer: those two read-first entries plus a
+  "full index → `docs/wiki/index.md`" line. Keep it tiny; it loads on every turn, and every other
+  index entry belongs in the wiki index. Create `CLAUDE.md` if absent, additive only — never delete
+  user content.
+
+Greenfield? Create just `docs/wiki/harness/` to hold those two files. That plus the link is
+everything `init` writes.
+
+**Step 4 — Propose the developer model.** rsc installs a `developer` subagent (the implementation
+worker) for every assistant supporting file-based agents. It runs at the **balanced** tier by
+default — Sonnet on Anthropic tools, the provider's mid model elsewhere — and never the cheapest
+`light` model, which is too weak to build with. Offer once, calibrated to the dial:
+
+> *"La implementación la hará un sub-agente `developer`. ¿Qué modelo? **balanced / Sonnet** (rápido y
+> económico — recomendado) o **heavy / Opus** (máxima calidad, más caro)."*
+
+Record to `.rsc/developer.json` and re-run install/sync so the agent files adopt it. Skipped (e.g.
+at L0) → `balanced`, which install also writes by default.
+
+**Opt-out.** A fresh session auto-starts `init` while `user-profile.md` is absent. If the user does
+not want a harness in this repo, write an empty `.rsc/.no-harness` — that silences the auto-start
+permanently, even before a profile exists. Completing first contact silences it too. Commit the
+marker so the decision is shared by the team.
+
+## Significant decisions: requirements first, then exactly three options
+
+For **any** significant decision — deploy target, database, framework, hosting, which CRM, where
+documents live — never decide silently and never dump ten options.
+
+1. **Gather the requirements that actually drive the choice.** For a deploy target: expected users,
+   concurrency, budget, data residency, the team's comfort operating servers, scaling needs. Match
+   the number of questions to the dial.
+2. **Present exactly three 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 follow.
+4. **Log it** to `decisions.md` once they pick.
+
+Canonical deploy example — Hetzner VPS + Coolify (cheapest, total control, you self-manage), Vercel
+(zero-ops, scales itself, expensive at scale), and a third matched to the case (Fly.io, Railway, or
+a managed cloud when compliance demands it). Requirements checklists per decision type and the
+worked example → `references/recommend-skills.md`.
+
+## The flow
+
+```text
+PROFILE → DISCOVER → INSTALL → GROUND → HANDOFF
+```
+
+### Phase 1 — PROFILE
+
+Steps 1-3 above. Do not proceed until `user-profile.md` exists and `CLAUDE.md` links it. The
+framing of every later question depends on it, which is why it cannot wait until after discovery.
+
+### Phase 2 — DISCOVER
+
+Establish **the state of the ground** and **what they want**.
+
+Detect greenfield vs brownfield; 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/` / `docs/`. Detect the stack the way `harness`
+SCAN does — a read-only walk ignoring `node_modules/`, `.venv/`, `.next/`, `.git/`, `dist/`,
+`build/`, `__pycache__/`, `.dart_tool/`. Summarize what you found and confirm it. **Greenfield** if
+the workspace is empty or holds only stray notes: interview from zero.
+
+Then the domain. Software (backend, frontend, mobile, agents) or a non-code harness (company/ops,
+research, knowledge, content)? Capture goals, audience, constraints, and any tools already in play.
+Record to `docs/wiki/harness/` as you go. Questionnaires for both cases →
+`references/discovery.md`. Ask in batches sized to the dial; never dump every question at once.
+
+### Phase 3 — INSTALL
+
+Map what you learned to skills. **You have a terminal — install them yourself** after a one-word
+confirm: `npx @damiangilgonzalez/harness add <ids>`. Only if you genuinely cannot run a shell, hand the exact
+command over for another tab. Never install without the confirm; it changes their environment.
+
+| Need | Skills |
+| --- | --- |
+| Always | `harness` — the control plane that scaffolds and governs the workspace |
+| Software backend | `fastapi` / `go`, `postgresdb` |
+| Software frontend | `nextjs` / `flutter`, `design` |
+| Marketing / landing / decks / teaching | `marketing`, `presentations`, `course-storytelling` |
+| AI agents | `building-agents` |
+| Shipping, security, wiring external tools | `secure-coding`, `deployment` |
+
+Show the shortlist with a one-line *why* per skill in their language, confirm, install. Recommend
+only what discovery justified — no "you'll probably want agents too".
+
+Then flag activation, matched to their IDE: *"Listo, instaladas. Para que se activen, abre una
+pestaña/sesión nueva de Claude Code (o recarga Cursor/Codex/Gemini) en esta carpeta — las skills se
+cargan al arrancar la sesión."* Full skill map and sample printouts → `references/recommend-skills.md`.
+
+### Phase 4 — GROUND
+
+Four checks once the skills are in. The SessionStart hook nudges each of these too; doing them here
+means the user starts clean.
+
+1. **Version control.** No `.git/` → offer `git init`; the SDD chain and the ship guard assume it.
+   Declined → write `.rsc/.no-git` so neither you nor the hook asks again, and log the decision.
+2. **Context7 (live library docs).** For software, offer to wire it once:
+   `claude mcp add --transport http context7 https://mcp.context7.com/mcp`. It gives version-correct
+   docs instead of guessing from memory. Declined → `.rsc/.no-context7`.
+3. **Skill audit.** Run `npx @damiangilgonzalez/harness audit`. It inventories what is installed here and on the
+   machine and flags overlap or skills with no footprint, so the project starts with the right set
+   rather than a pile. Summarize at their level.
+4. **Tell them about the danger guard.** A `technical_level` of `non-technical` or `mixed` (and the
+   state before any profile exists) turns on a `PreToolUse` guard that blocks irreversible commands —
+   `rm -rf`, `git push --force`, `git reset --hard`, `DROP`/`TRUNCATE`, `DELETE`/`UPDATE` with no
+   `WHERE`, `dd` to a device, `curl | bash` — and asks for a safer alternative. A fully `technical`
+   user is never guarded. It turns off only if the user explicitly asks: `.rsc/.no-danger-guard`.
+   Mention it when you set a non-technical level, so a later block is not a surprise.
+
+### Phase 5 — HANDOFF
+
+The profile is set, the discovery recorded, the skills installed. What is missing is the workspace
+itself, and this is where onboarding used to end with a request: *"now run `harness`"*. Nothing ran
+it. Finishing depended on the user reading a line and typing something — and in a chat install that
+user has just delegated precisely so they would not have to know what to type.
+
+So **invoke `harness` yourself, now**, as the last step of this phase. Say what you are doing in one
+line, then do it:
+
+> "Tu perfil y lo que hemos hablado ya están guardados. Monto ahora el esqueleto del proyecto
+> (`01-TOOLS/` + `docs/`) leyendo todo lo que acabamos de decidir."
+
+`harness` still owns *how* the scaffold is built — you are calling it, not reimplementing it. Do not
+hand-roll directories here.
+
+**And if it does not happen, say so.** If `harness` cannot run, or stops half-way, **do not tell the
+user rsc is ready**: name what is missing and what will create it. The installer holds the same rule
+— it prints `RSC_ONBOARDING_INCOMPLETE` instead of `RSC_ONBOARDING_READY` when the harness floor is
+absent — and an agent that contradicts its own installer is worse than either alone. Claiming a
+harness that is not there is the one failure the user cannot diagnose, because everything looks
+installed and nothing behaves as if it were.
+
+## Project grounding
+
+`init`'s record is the profile plus the append-only decisions log, both written in Phase 1 and
+updated throughout, and both kept in the short `## Knowledge map` pointer because they are the
+read-first entries. `scripts/verify.sh` checks the profile and the link exist (read-only; warns,
+never fails).
+
+## See Also
+
+- `harness` — the scaffolder this hands off to; builds `01-TOOLS/` + `docs/` from the profile.
+- `deployment` — invoked when the deploy decision above is actually made.
+- `secure-coding` — recommended whenever software is being shipped.
+- Stack skills (`fastapi`, `go`, `nextjs`, `flutter`, `building-agents`…) are recommended at runtime
+  by Phase 3 from discovery, never 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 `docs/wiki/harness/user-profile.md`. Nunca termines
+en seco. Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`.

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.

package/skills/init/evals/cases.yaml

@@ -0,0 +1,74 @@
+skill: init
+
+# Cases for the rsc-skills "init" front door / bootstrapper.
+# init profiles the user (technical level + accompaniment dial), discovers what
+# they want to BUILD or GOVERN (code OR a non-code harness), recommends rsc
+# skills, and hands off to the harness skill. It is NOT the scaffolder and NOT
+# a specific stack skill.
+
+should_trigger:
+  - prompt: "Quiero montar un proyecto nuevo pero no sé por dónde empezar."
+    why: "Canonical greenfield entry with explicit uncertainty ('no sé por dónde empezar') — init's job is to gauge level, discover, and recommend before anything is built."
+
+  - prompt: "I have an existing repo and I want to set up the harness on it. Where do I start?"
+    why: "Brownfield bootstrapping: pointing the rsc harness at an existing project is exactly init's front-door role (detect greenfield vs brownfield, profile, recommend skills)."
+
+  - prompt: "Acabo de instalar esto. ¿Qué hago primero?"
+    why: "First-contact phrasing without naming any tool — init is the literal first thing you run; it should claim 'what do I do first' onboarding moments."
+
+  - prompt: "Tengo una idea para una app pero soy de negocio, no técnico. Ayúdame a arrancar esto desde cero."
+    why: "Greenfield + explicitly non-technical user — init leads with the technical-level question and the accompaniment dial, the core reason it exists, before any stack choice."
+
+  - prompt: "I want to use this to run my company's operations, not to write code. Can I bootstrap that here?"
+    why: "Non-code harness (company/ops) bootstrap — init is domain-agnostic and explicitly governs non-code harnesses the same way; this is a deliberately non-obvious trigger."
+
+  - prompt: "Set me up. I want to build a personal knowledge base / wiki with this."
+    why: "'Set me up' + a non-code knowledge-base goal: init profiles and recommends (likely harness, possibly marketing) then hands off to harness — it owns the setup conversation, not a specific stack skill."
+
+  - prompt: "Bootstrap a workspace for a research program I'm planning."
+    why: "Explicit 'bootstrap a workspace' for a non-code (research) domain — init's discover+recommend+handoff flow, including the iron rule that 'project' is not assumed to mean code."
+
+should_not_trigger:
+  - prompt: "Create a CLAUDE.md file documenting the architecture of this existing codebase."
+    route_to: "none"
+    why: "This is the built-in /init (CLAUDE.md generator), not the rsc-skills front door. init only writes the user-profile + a Knowledge-map link, and it does NOT scaffold or document the codebase — that is harness/other tooling. No rsc sibling owns generic architecture docs, so route to none."
+
+  - prompt: "Run the scaffolding now — create the 01-TOOLS and docs folders and wire up the structure."
+    route_to: "harness"
+    why: "init explicitly hands off scaffolding to the harness skill. The moment the user asks to actually BUILD 01-TOOLS/docs, it is harness's job, not init's (init writes only the profile + link)."
+
+  - prompt: "Set up a FastAPI backend with a Postgres database for my new service."
+    why: "User already knows the stack and wants a specific backend built — this is the fastapi/backend stack skill, not the level-gauging front door. init recommends skills; it does not implement stacks."
+    route_to: "fastapi"
+
+  - prompt: "Help me pick and configure a deploy target — Hetzner vs Vercel vs Fly.io — and ship it."
+    why: "Although init uses the 3-option deploy example to illustrate the decision pattern, an actual 'configure and ship the deployment' request is the deployment ops skill's runtime job, which init only references."
+    route_to: "deployment"
+
+  - prompt: "Scaffold a new Next.js app with the App Router and Tailwind."
+    route_to: "nextjs"
+    why: "Concrete frontend build with a named framework — the nextjs stack skill. init would only ever recommend the nextjs skill, not scaffold the app itself."
+
+  - prompt: "Review this auth code for security issues like injection and broken access control."
+    route_to: "secure-coding"
+    why: "A security-only review of existing code, no bootstrapping or profiling involved — squarely the secure-coding skill, not the front-door init."
+
+capability:
+  - scenario: "A non-technical founder says: 'I want to build an app to connect dog owners but I don't know where to start.' Show how init opens the engagement."
+    must_include:
+      - "Asks the technical-level question FIRST, before any discovery or recommendation (e.g. 'are you comfortable with code or prefer plain language?'), and records technical_level"
+      - "Presents the accompaniment dial L0–L3 and, given a silent non-technical user, defaults to L3 (full accompaniment)"
+      - "Persists the profile to docs/wiki/harness/user-profile.md and an append-only docs/wiki/harness/decisions.md, and links both from a ## Knowledge map section in root CLAUDE.md (creating CLAUDE.md if absent, additive only)"
+      - "Detects greenfield vs brownfield rather than assuming, and runs DISCOVER (goals, audience, constraints, surfaces) before recommending"
+      - "Recommends specific rsc skills matched to discovery (at minimum harness; nextjs/flutter + design if app surfaces justify it) and PRINTS the exact install commands (npx @damiangilgonzalez/harness add <skill> ...)"
+      - "Does NOT install anything itself and does NOT scaffold 01-TOOLS/docs — it hands off to the harness skill as the final step"
+      - "Does not recommend speculative skills (e.g. building-agents) unless discovery justified them"
+
+  - scenario: "A user with an existing multi-package repo says: 'Point the harness at my project and get me started.' Show the brownfield front-door flow."
+    must_include:
+      - "Still asks the technical-level question and sets the accompaniment dial first — profile before anything, even on brownfield"
+      - "Detects brownfield via manifests (package.json / pyproject.toml / pubspec.yaml / go.mod / Cargo.toml), source files, legacy XX-* folders, or existing 01-TOOLS/docs, with a read-only scan that ignores node_modules/.venv/.next/.git/dist/build"
+      - "Summarizes the detected stack and current state and CONFIRMS with the user instead of assuming"
+      - "Writes profile + decisions log under docs/wiki/harness/ and adds the Knowledge-map link to CLAUDE.md without deleting existing content"
+      - "Recommends skills matched to the detected stack and prints the exact install commands, recommending only what was justified"
+      - "Hands off to the harness skill for the actual 01-TOOLS/docs scaffolding/migration rather than doing it inside init"

package/skills/init/references/accompaniment-and-profile.md

@@ -0,0 +1,140 @@
+# Accompaniment & Profile — the non-technical-first script, the dial, and how it persists
+
+This file holds the runtime detail behind the SKILL.md section "Non-technical-first + the accompaniment dial". It defines: the first-contact script, the dial, the exact `docs` file formats, and the rules every downstream skill follows to adapt.
+
+## Why this matters
+
+The single biggest failure mode of a developer-built harness is talking like a developer to someone who is not one. This system inverts the default: it assumes non-technical, asks before assuming otherwise, and lets the user turn explanation up or down at will. The profile is the contract; every skill honors it.
+
+## The first-contact script
+
+Ask exactly two things, in order, before anything else. Do not bundle them with discovery questions.
+
+### Question 1 — technical level (the literal first message)
+
+Spanish:
+
+> "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."
+
+English:
+
+> "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."
+
+Map the answer to one of:
+
+- `non-technical` — plain language, analogies, no jargon, no code shown unless asked.
+- `mixed` — comfortable with concepts, not necessarily syntax; define terms once.
+- `technical` — full jargon OK, can read code and configs.
+
+If the user does not answer clearly, assume `non-technical`. Never guess "technical" from the fact that they opened a terminal — many non-technical people are handed one.
+
+### Question 2 — the accompaniment dial
+
+Present all four levels with their plain descriptions (do not show only labels):
+
+- **L0 — "Modo cavernícola"**: mínimas palabras. Hago las cosas y ya, casi sin explicar.
+- **L1 — "Breve"**: una línea de *por qué* en cada paso.
+- **L2 — "Explica decisiones"**: justifico cada decisión relevante a medida que avanzo.
+- **L3 — "Acompañamiento total"**: te lo explico TODO, te hago muchas preguntas para entender tu contexto, y razono cada decisión. Ideal para no-técnicos.
+
+Defaults when the user gives no preference: `non-technical → L3`, `mixed → L2`, `technical → L1`. The user can change the dial any time by saying so ("ponlo en breve", "explícamelo todo"); update `user-profile.md` when they do.
+
+## How every skill adapts
+
+Both values combine. `accompaniment_level` controls **how much** is said and **how many questions** are asked; `technical_level` controls **the vocabulary**.
+
+| Level | Output verbosity | Questions before acting | On a decision |
+| --- | --- | --- | --- |
+| L0 | Result line only | None beyond hard blockers | Pick the recommended option, log it, mention it in one line |
+| L1 | One *why* line per step | Only on genuine ambiguity | Present the 3 options tersely, recommend, proceed on confirm |
+| L2 | Justify each relevant decision | Ask before each significant decision | Full 3-option pattern with trade-offs |
+| L3 | Narrate reasoning throughout | Many — contextualize every choice | Full 3-option pattern + explain each option in plain language and check understanding |
+
+Vocabulary modifier:
+
+- `non-technical` — translate every term ("a database is where the app remembers things"), prefer analogies, never paste raw config without explaining it.
+- `mixed` — use the term, define it inline the first time.
+- `technical` — use the term directly; skip the 101 explanations even at L3.
+
+**Rule:** read `user-profile.md` at the start of every session. If it is missing, you are likely being run before `init` — run the first-contact script before doing the requested work, or at minimum default to `non-technical` + `L3` and note that the profile is unset.
+
+## Persistence format
+
+Both files live under `docs/wiki/harness/`. `init` creates this directory even on greenfield; the rest of `docs` is built by the `harness` skill.
+
+### `docs/wiki/harness/user-profile.md`
+
+A living document — updated whenever the user reveals new goals, context, constraints, or changes the dial. It is the single source of truth other skills read.
+
+```markdown
+# User Profile
+
+> Source of truth for how every rsc skill talks to this user. Updated continuously.
+
+## Levels
+- technical_level: non-technical            <!-- non-technical | mixed | technical -->
+- accompaniment_level: L3                    <!-- L0 | L1 | L2 | L3 -->
+- language: es                               <!-- the user's working language -->
+- last_updated: 2026-06-01
+
+## Who they are
+- One or two lines: role, relationship to the project, what they already know.
+
+## What they want to build or govern
+- domain: non-code-harness                   <!-- software | non-code-harness -->
+- one-line description of the thing.
+- software surfaces (if any): backend | frontend | mobile | agents
+- non-code surfaces (if any): company/ops | research | personal-knowledge | content
+
+## Goals
+- The outcome that means "this worked".
+- Secondary goals.
+
+## Context
+- Greenfield or brownfield, detected stack/state.
+- Tools/providers already in play (email, CRM, payments, hosting…).
+- Team size and ops comfort.
+
+## Constraints
+- Budget, timeline, data region/residency, compliance, non-negotiables.
+
+## Open questions
+- Anything not yet answered, to revisit.
+```
+
+### `docs/wiki/harness/decisions.md`
+
+**Append-only.** Never edit or delete an entry — if a decision is reversed, append a new entry that supersedes the old one and references it. This is the audit trail of why the project is the way it is.
+
+```markdown
+# Decisions Log (append-only)
+
+> One entry per significant decision. Never edit or delete; supersede by appending.
+
+---
+## D-0001 — Deploy target
+- date: 2026-06-01
+- context: ~500 users expected, 20 concurrent, EU data residency required, small team, low budget.
+- options considered:
+  1. Hetzner VPS + Coolify — cheap, full control, self-managed.
+  2. Vercel — zero-ops, managed, scales; pricey at scale.
+  3. Fly.io — managed containers, EU region, middle ground.
+- decision: Hetzner VPS + Coolify (Falkenstein, EU).
+- why: budget + EU residency + team OK self-managing one box.
+- supersedes: none
+---
+## D-0002 — …
+```
+
+### Linking from the root `CLAUDE.md`
+
+Add (or update) a `## Knowledge map` section that links BOTH files. Create `CLAUDE.md` if absent; if it exists, only add/update this section — never delete user content.
+
+```markdown
+## Knowledge map
+
+- [User profile](docs/wiki/harness/user-profile.md) — technical level, accompaniment dial, goals, context, constraints. **Every skill reads this first and adapts its verbosity and questions.**
+- [Decisions log](docs/wiki/harness/decisions.md) — append-only record of every significant decision and why.
+```
+
+When the `harness` skill later builds the full wiki, it extends this same `## Knowledge map` with links to the rest of `docs/` — it does not replace the harness entries written here.

package/skills/init/references/discovery.md

@@ -0,0 +1,90 @@
+# Discovery — greenfield & brownfield questionnaires (software AND non-code harnesses)
+
+Phase 2 detail. Establish two things: **the state of the ground** (greenfield vs brownfield) and **what the user wants to build or govern**. Record everything to `docs/wiki/harness/user-profile.md` as you learn it. Ask in batches sized to `accompaniment_level` — never dump every question at once.
+
+## First: greenfield vs brownfield (detect, then confirm)
+
+Do a read-only walk of the workspace root, the way `harness` SCAN does. Ignore these directories entirely: `node_modules/`, `.venv/`, `.next/`, `.git/`, `dist/`, `build/`, `__pycache__/`, `.dart_tool/`.
+
+**Brownfield signals** (any one is enough):
+
+- A subproject manifest: `package.json`, `pyproject.toml`, `pubspec.yaml`, `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`.
+- Source files, a `src/`, an `app/`.
+- Legacy numbered folders matching `^[0-9]+-[A-Z_]+$` (`00-TOOLS`, `03-NOTES`…).
+- An existing `01-TOOLS/`, `docs/`, `CLAUDE.md`, or `AGENTS.md`.
+
+Read manifest contents to name the stack (Next.js, FastAPI, Flutter, Go, Express…). Capture `git status --short` per subproject if it's a repo; flag dirty trees rather than acting on them. Then **summarize what you found and confirm** with the user before treating it as ground truth — detection can be wrong.
+
+**Greenfield** = none of the above; an empty or notes-only workspace. Then it is a brand-new idea and you interview from zero.
+
+## Then: what do they want to build OR govern?
+
+The single most important branch. Establish the **domain** before any stack questions.
+
+> "¿Lo que quieres montar es **software** (una app, una web, un backend, un agente…) o más bien una forma de **organizar y gobernar algo** que no es código — llevar una empresa o unas operaciones, una investigación, tu conocimiento personal, una operación de contenido…? Las dos cosas se montan igual de bien aquí."
+
+Record `domain: software | non-code-harness`. Both are first-class. A non-code harness uses the exact same `01-TOOLS` (connections to email, calendar, CRM, payments, docs) + `docs` (the wiki/second-brain) structure.
+
+---
+
+## Software — questionnaire
+
+### Greenfield software
+
+Ask in batches. Adapt depth to the dial.
+
+1. **The idea in one sentence.** What does it do, for whom?
+2. **Surfaces.** Which of these does it need? (This drives the skill recommendation.)
+   - A **backend / API / database** → `fastapi` or `go`, `postgresdb`.
+   - A **web or mobile UI** → `nextjs` or `flutter`, `design`.
+   - **AI agents** (tools, RAG, autonomous loops) → `building-agents`.
+   - **Marketing / landing / decks / teaching** around it → `marketing`, `presentations`, `course-storytelling`.
+   - It will be **shipped / needs security** → `secure-coding`, `deployment`.
+3. **Audience & scale.** Who uses it? Roughly how many users, how many at once?
+4. **Constraints.** Budget, timeline, data region / residency, compliance, must-use technologies.
+5. **Existing tools/providers** already chosen or in play (auth, payments, email, hosting, analytics).
+
+### Brownfield software
+
+Lead with what you detected, then fill gaps:
+
+1. **Confirm the stack** you found per subproject. Correct anything wrong.
+2. **What's the goal of this session** — extend it, ship it, document it, add a surface?
+3. **Providers in the code.** Which external services are already integrated (you'll have seen imports/env vars in SCAN)? These map to `01-TOOLS` folders that `harness` will scaffold.
+4. **Pain points.** What's missing or messy (no docs, no ops, no tests, scattered config)?
+5. **Constraints & scale** as in greenfield, but informed by current reality.
+
+---
+
+## Non-code harness — questionnaire
+
+Same structure, different surfaces. The "stack" here is the set of **tools the harness connects to** and the **knowledge it governs**.
+
+### Greenfield non-code harness
+
+1. **What are you running or organizing?** A company, a department's ops, a research line, your personal knowledge, a content operation?
+2. **What does "this worked" look like?** The outcome — e.g. "every client email lands in the right place and I never lose a document", "my research notes compile into a queryable wiki".
+3. **Tools to connect** (`01-TOOLS` candidates). Which of these do you use, and would you want wired in?
+   - Email (Gmail, Outlook), Calendar.
+   - Documents / drive (Google Drive, Notion, Dropbox).
+   - CRM / sales, support inbox.
+   - Payments / billing (Stripe…), accounting.
+   - Hosting / infra, if any automation runs somewhere.
+4. **What knowledge piles up?** PDFs, contracts, notes, spreadsheets, emails — the raw material that should become a queryable wiki in `docs`.
+5. **Constraints.** Budget, data residency / privacy (especially for client data), who else touches this, compliance.
+
+### Brownfield non-code harness
+
+The "brownfield" of a non-code harness is an existing pile of tools and documents with no structure:
+
+1. **Inventory the tools** already in use and how they connect today (or don't).
+2. **Where does knowledge live now** and why is it hard to find — that's the `docs` job.
+3. **What's the recurring pain** — onboarding, handoffs, lost context, manual copying between tools?
+4. **Confirm any integrations** you can detect (config files, exported credentials, `.env`-style files) — these become `01-TOOLS` folders.
+5. **Constraints & ownership** as above.
+
+---
+
+## What to record
+
+After discovery, `user-profile.md` should have, for both domains: a one-line description, the domain and its surfaces, goals, audience/scale, context (greenfield/brownfield + detected state + tools in play), and constraints (budget, timeline, region/residency, compliance, ops comfort). These are exactly the inputs Phase 3 needs to recommend skills and run the "siempre 3 opciones" pattern, and that the `harness` skill reads to scaffold. Anything still unknown goes under "Open questions" to revisit — do not invent answers.