@damiangilgonzalez/harness 1.3.7

package/skills/structured-extraction/references/providers.md

@@ -0,0 +1,152 @@
+# Provider reference — exact shapes, limits, and feature support
+
+Current as of 2026-06-02. Pins and shapes verified against the OpenAI Structured Outputs guide, the
+Anthropic Structured Outputs docs (GA after the 2025-11-14 public beta), and Instructor
+(python.useinstructor.com / github.com/567-labs/instructor). The SKILL body carries the rules; this file
+carries the literal request blocks and the limit tables so the body stays lean.
+
+## OpenAI
+
+### Chat Completions — `response_format`
+
+```python
+resp = client.chat.completions.create(
+    model="gpt-5.1",
+    messages=[{"role": "user", "content": text}],
+    response_format={
+        "type": "json_schema",
+        "json_schema": {
+            "name": "invoice",
+            "strict": True,
+            "schema": {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["vendor", "total_cents", "due_date"],
+                "properties": {
+                    "vendor":     {"type": "string"},
+                    "total_cents":{"type": "integer", "description": "Total in cents, no symbol."},
+                    "due_date":   {"type": ["string", "null"], "description": "ISO date or null."},
+                },
+            },
+        },
+    },
+)
+data = json.loads(resp.choices[0].message.content)
+```
+
+### Responses API — `text.format`
+
+Same json_schema block, relocated:
+
+```python
+resp = client.responses.create(
+    model="gpt-5.1",
+    input=text,
+    text={"format": {"type": "json_schema", "name": "invoice", "strict": True, "schema": {...}}},
+)
+```
+
+### OpenAI strict rules
+
+- `strict: true` gives constrained decoding: the model **cannot** emit tokens that violate the schema
+  (~100% schema conformance in OpenAI's evals).
+- Every object **must** set `"additionalProperties": false`.
+- **Every** property must appear in `required`. Optional = a union with `null`
+  (`"type": ["string","null"]`), never omission from `required`.
+- `response_format` (shape the final answer) and `tools`/function calling (the model calls your code) are
+  different jobs — pick function calling when you want a tool invoked, structured outputs when you want a
+  shaped answer. Don't use both to shape the same final answer.
+
+## Anthropic (Claude Developer Platform)
+
+### `output_config.format` (current, GA)
+
+```python
+resp = client.messages.create(
+    model="claude-opus-4-8",
+    max_tokens=2048,
+    messages=[{"role": "user", "content": text}],
+    output_config={"format": {"type": "json_schema", "schema": {
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["vendor", "total_cents", "due_date"],
+        "properties": {
+            "vendor":      {"type": "string"},
+            "total_cents": {"type": "integer"},
+            "due_date":    {"type": ["string", "null"]},
+        },
+    }}},
+)
+```
+
+- Anthropic compiles the schema into a grammar and **caches it for 24h**, then constrains decoding
+  token-by-token.
+- Supported models: Claude Opus 4.5 / 4.6 / 4.7 / 4.8, Sonnet 4.5 / 4.6, Haiku 4.5. Also on Bedrock,
+  Vertex, and Foundry (beta).
+- SDK helpers: Python `client.messages.parse(...)` returns a parsed object; TS `zodOutputFormat(schema)` /
+  `jsonSchemaOutputFormat(schema)`.
+- **Deprecated** (transition window only — do not write new code against these): the `output_format` param
+  and the `structured-outputs-2025-11-13` beta header.
+
+### Strict tool use (separate feature)
+
+To constrain a *tool call's* input, set `"strict": true` on the tool's `input_schema`. This is independent
+of `output_config.format`, which shapes the assistant's final answer.
+
+```python
+tools=[{"name": "save_order", "input_schema": {"type": "object", "strict": True, ...}}]
+```
+
+### Anthropic schema constraints (the runtime gotchas)
+
+- `additionalProperties` must be `false` for all objects.
+- **Not supported**: recursive schemas; numeric bounds (`minimum`, `maximum`, `multipleOf`); string length
+  (`minLength`, `maxLength`); array constraints beyond `minItems` of 0 or 1; complex regex (lookahead,
+  lookbehind, backreferences).
+- Complexity limits per request (combined across all strict schemas): **≤20 strict tools**, **≤24 optional
+  parameters** total, **≤16 union-typed (`anyOf`) parameters**, **180s** schema-compile timeout.
+- Implication: the schema enforces **shape and types only, never values or ranges**. Push every value rule
+  into a post-decode validator.
+
+## Instructor (cross-provider, Pydantic-based)
+
+```python
+import instructor
+from pydantic import BaseModel
+
+class Order(BaseModel):
+    vendor: str
+    total_cents: int
+    due_date: str | None
+
+client = instructor.from_provider("anthropic/claude-opus-4-8")  # or "openai/gpt-5.1", "ollama/llama3.3"
+order = client.chat.completions.create(
+    response_model=Order,
+    max_retries=2,            # bound the reask loop
+    messages=[{"role": "user", "content": text}],
+)
+```
+
+- Built on **Pydantic**; unified `from_provider("<provider>/<model>", ...)` across 15+ backends (OpenAI,
+  Anthropic, Gemini, Ollama, DeepSeek, …). TS / Go / Ruby ports exist.
+- Core value beyond native decoding: the **validate→retry** loop. A failed Pydantic validation — including
+  custom `@field_validator` rules the model never saw in the schema — is fed back to the model as the error
+  message; `max_retries` caps the reasks.
+- Use it for **provider portability** or **value-level validation with reask**. For a single provider and
+  the simplest dependency footprint, the native SDK helper (`messages.parse` / `zodOutputFormat`) is enough.
+- Add a hook to log reasks (count + reason) so a rising reask rate surfaces a bad field instruction early.
+
+## Consolidated: unsupported JSON Schema features (push these to validators)
+
+| Feature | OpenAI strict | Anthropic | Where it must go instead |
+| --- | --- | --- | --- |
+| `additionalProperties: false` | required | required | n/a (must set it) |
+| Optional via omission from `required` | rejected | rejected | union with `null`, keep in `required` |
+| `minimum` / `maximum` / `multipleOf` | not enforced | not supported | Pydantic `@field_validator` / Zod `.refine` |
+| `minLength` / `maxLength` | not enforced | not supported | validator after decode |
+| Array `minItems`/`maxItems` (beyond 0/1) | limited | beyond `minItems` 0/1 unsupported | validator after decode |
+| Complex regex (lookahead/backref) | unsupported | unsupported | validator with a real regex engine |
+| Recursive schemas | limited | not supported | flatten / split into multiple extractions |
+
+The single safe assumption: **strict/native modes enforce shape and type only.** Every range, length,
+format, cross-field, or enum-legitimacy rule is your validator's job.

package/skills/structured-extraction/scripts/verify.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — structured-extraction skill check. Run from anywhere. Read-only, no network, no SDK calls.
+#
+# This skill ships code-shaped guidance, so its rigor is a checkable artifact: a STATIC lint of the
+# skill's OWN markdown examples. It asserts the guidance is internally consistent — it never runs any
+# model or SDK.
+#
+# Checks:
+#   1. SKILL.md exists and frontmatter has name/description/tags/recommends/origin; description is one line.
+#   2. references/providers.md exists and is non-empty.
+#   3. Every fenced code block in SKILL.md + references carries a language tag.
+#   4. At least one example sets additionalProperties: false.
+#   5. Optional fields are shown as a nullable union (["...","null"]) somewhere — not the omit-from-required trap.
+#   6. The deprecated Anthropic output_format / structured-outputs-2025-11-13 header is NOT used as a
+#      primary (Good) example — it may only appear flagged as deprecated.
+#   7. No raw json.loads(/JSON.parse( on model output presented as the recommended path (the Good fences
+#      must use native decoding; a raw-parse line is only allowed in a Bad/anti-pattern context).
+#
+# Exit: 0 when every present artifact passes (and 0 if SKILL.md is simply absent — empty target, no false
+# failure). Non-zero only on a real inconsistency in a file that exists.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; }
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(dirname "$SCRIPT_DIR")"
+SKILL="$SKILL_DIR/SKILL.md"
+REF="$SKILL_DIR/references/providers.md"
+fail=0
+
+# ---- empty target: nothing to check, do not fake a failure ----
+if [ ! -f "$SKILL" ]; then
+  skip "no SKILL.md at $SKILL — nothing to lint"; exit 0
+fi
+ok "SKILL.md present"
+
+# ---- frontmatter keys ----
+for key in "name:" "description:" "tags:" "recommends:" "origin:"; do
+  if grep -q "^${key}" "$SKILL"; then
+    ok "frontmatter has ${key%:}"
+  else
+    err "frontmatter missing ${key%:}"; fail=1
+  fi
+done
+
+desc_lines="$(grep -c '^description:' "$SKILL" || true)"
+if [ "$desc_lines" = "1" ]; then
+  ok "description is a single key line"
+else
+  err "expected exactly one 'description:' line, found $desc_lines"; fail=1
+fi
+
+# ---- references present ----
+if [ -s "$REF" ]; then
+  ok "references/providers.md present and non-empty"
+else
+  err "references/providers.md missing or empty"; fail=1
+fi
+
+# Files to lint (only those that exist).
+FILES=("$SKILL")
+[ -f "$REF" ] && FILES+=("$REF")
+
+# ---- every code fence is language-tagged ----
+# A fence opener is a line starting with ``` ; count those with no language word after the backticks.
+# Closers are paired, so we look at odd-indexed openers only via awk toggling.
+for f in "${FILES[@]}"; do
+  bad_fence="$(awk '
+    /^```/ {
+      infence = !infence
+      if (infence) {            # this is an opener
+        lang = substr($0, 4)
+        gsub(/[ \t\r]/, "", lang)
+        if (lang == "") c++
+      }
+      next
+    }
+    END { print c+0 }
+  ' "$f")"
+  if [ "$bad_fence" = "0" ]; then
+    ok "$(basename "$f"): all code fences language-tagged"
+  else
+    err "$(basename "$f"): $bad_fence untagged code fence(s)"; fail=1
+  fi
+done
+
+# ---- at least one additionalProperties: false example ----
+if grep -Eq '"additionalProperties":[[:space:]]*[fF]alse|additionalProperties.*[fF]alse' "$SKILL" "$REF" 2>/dev/null; then
+  ok "additionalProperties:false shown in an example"
+else
+  err "no example sets additionalProperties:false"; fail=1
+fi
+
+# ---- nullable union shown (optional-as-null, not omit-from-required) ----
+if grep -Eq '"null"' "$SKILL" "$REF" 2>/dev/null; then
+  ok "nullable union (\"...\",\"null\") shown for optional fields"
+else
+  err "no nullable-union example for optional fields"; fail=1
+fi
+
+# ---- deprecated Anthropic surface must not be a primary example ----
+# Allowed ONLY on a line that also flags it as deprecated.
+dep_bad=0
+while IFS= read -r line; do
+  case "$line" in
+    *output_format*|*structured-outputs-2025-11-13*)
+      case "$line" in
+        *[Dd]eprecat*) : ;;                 # fine: flagged as deprecated
+        *output_config*) : ;;               # fine: contrasting against the current param name
+        *) dep_bad=1 ;;
+      esac ;;
+  esac
+done < "$SKILL"
+if [ "$dep_bad" = "0" ]; then
+  ok "deprecated Anthropic output_format/header not used as a primary example"
+else
+  err "deprecated output_format / structured-outputs-2025-11-13 used without a deprecation flag"; fail=1
+fi
+
+# ---- raw parse on model output only allowed inside an explicitly-Bad context ----
+# Walk SKILL.md tracking the nearest preceding 'Bad' marker per fenced block.
+raw_bad=0
+ctx_bad=0
+infence=0
+while IFS= read -r line; do
+  case "$line" in
+    '**Bad'*|'# Bad'*|'## Bad'*|*'Bad —'*|*'Bad -'*) ctx_bad=1 ;;
+    '**Good'*|*'Good —'*|*'Good -'*) ctx_bad=0 ;;
+  esac
+  case "$line" in
+    '```'*) infence=$((1-infence)); continue ;;
+  esac
+  if [ "$infence" = "1" ]; then
+    case "$line" in
+      *json.loads\(*|*JSON.parse\(*)
+        # guaranteed-valid string is fine (parsing a decoder output is OK if it's the Good native path);
+        # we only flag a raw parse that is NOT in a Bad block AND has no 'guaranteed'/'now' reassurance.
+        case "$line" in
+          *guaranteed*|*now\ guaranteed*) : ;;
+          *)
+            if [ "$ctx_bad" = "0" ]; then raw_bad=1; fi ;;
+        esac ;;
+    esac
+  fi
+done < "$SKILL"
+if [ "$raw_bad" = "0" ]; then
+  ok "no raw json.loads/JSON.parse on model output outside a Bad/anti-pattern context"
+else
+  err "raw json.loads(/JSON.parse( on model output presented as a recommended path"; fail=1
+fi
+
+if [ "$fail" -ne 0 ]; then
+  err "static lint failed"; exit 1
+fi
+ok "all static checks passed"
+exit 0

package/skills/suggest/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: suggest
+description: "Always-on. Use whenever the current user turn would clearly benefit from an rsc skill that is not yet installed — detect the gap during normal agent use, name the skill, and (with a one-word confirm) install it via `npx @damiangilgonzalez/harness add <id>`. Triggers on capability intent in any language: building technology, creating content/assets, automating workflows, analyzing data, connecting tools, shipping/deploying, security, business ops, marketing, education, research, or company/documentation harness work."
+tags: [suggest, detect, install, meta, always-on]
+recommends: []
+profiles: [minimal, core, ui, full]
+origin: risco
+---
+
+# rsc-suggest — the always-on layer
+
+Your body is injected at the start of **every** session and again after every compaction, so you
+are the one piece guaranteed to be present before any other skill is matched. Two jobs, in order:
+
+1. **Route feature intent into the right workflow** before any code is written.
+2. **Keep the session equipped** — spot the skill the task needs but the user does not have.
+
+Everything below is what only this layer can do. The method behind each rule lives in the skill that
+owns it; this is the pointer, not the manual.
+
+---
+
+## 1. Routing: feature intent goes through the chain first
+
+The moment someone wants something to **exist or behave differently** — build, add, change,
+integrate, "it should also…", "¿y si…?", in any language — the request earns a clear *what* and
+the user's go-ahead before any line of code lands. No skill outranks this, stack and builder
+skills included (`nextjs`, `react`, `fastapi`, `flutter`, `go`, `postgresdb`, `building-agents`,
+`design`, `chatbot`, `course-builder`, `marketing`…): they run **inside** the chain, once the plan
+is approved — matching strongly is not a reason to skip ahead.
+
+The shape of the chain:
+
+- Still fuzzy, or an open question? Open with `grill-with-docs`; reach for `wayfinder` instead
+  when the effort will not fit one sitting.
+- Once the shape is known, capture it as a spec, noting any call that would be costly to undo.
+- Size the build: a single sitting runs straight through its own plan-then-build pair; anything
+  bigger, or anything that grew out of the wayfinding step, gets broken into tickets first.
+
+Two exceptions, and say out loud when you take one:
+
+- a genuinely one-line, low-risk change (typo, copy tweak, config bump, non-breaking bump) — just do it;
+- fixing a regression to restore behaviour that already existed — hand that to
+  `superpowers:systematic-debugging` instead, then resume.
+
+When you cannot tell, take the clarifying step. A skipped one is where drift hides.
+
+Judge the **meaning**, not the wording: the trigger is semantic, so it holds in any language,
+including ones with no example here. A URL plus a description of desired behaviour is a feature
+request. If the user already engaged an autopilot over this chain, that one consent covers the
+whole run — advance through the phases without re-asking.
+
+If a step's skill is not installed, offer to add it (§2) before routing. `implement` always
+pairs with test-driven development and a verification pass before anything is called done.
+
+Exact skill names and order: `grill-with-docs` or `wayfinder` -> `to-spec` (and `write-adr` for
+decisions) -> `superpowers:writing-plans` -> `superpowers:executing-plans`, or `to-tickets` ->
+`implement`. On Claude Code this rule also arrives as a per-turn hook; the brevity here is
+deduplication, not relaxation.
+
+---
+
+## 2. Keeping the session equipped
+
+When the task needs a capability the user has **not installed** — building, creating, automating,
+analyzing, connecting, shipping, securing, selling, teaching, governing or documenting something —
+name it and offer it. This runs mid-conversation, not only at project start.
+
+1. `npx @damiangilgonzalez/harness catalog --available` lists every not-installed skill as
+   `id  available  short description`.
+2. Pick the single best fit **by meaning**, the way you would match a request to a teammate's
+   expertise — "mandar emails de bienvenida" → an email/outreach skill, though not one keyword
+   overlaps; "login con Google" → an auth skill, not `flutter`. If nothing genuinely fits, say so
+   and move on: a tangential suggestion is worse than none.
+3. Ask once, plainly: "Para esto instalaría `<id>`, que aún no tienes. ¿La instalo? (sí/no)".
+4. On yes, run `npx @damiangilgonzalez/harness add <id>`, then continue the original task.
+
+Installing changes the user's environment, so it is always their call. One suggestion at a time,
+and never to interrupt a flow with a nice-to-have. Never recommend something already installed
+(`npx @damiangilgonzalez/harness list`).
+
+`npx @damiangilgonzalez/harness consult "<task>"` is a **lexical** hint only: it keyword-matches, and returns
+nothing for natural-language or non-English intent. Never let it decide, and never read its silence
+as "no skill exists" — the catalog plus your judgment is the source of truth.
+
+### Automation gap — after the work
+
+Delivered work a repeatable **procedure**? Before proposing to *build* anything, run
+`npx @damiangilgonzalez/harness capabilities`: covered by a skill or agent → use it, say nothing.
+Not covered → one line, skill or agent. Rules: `skill-scout`.
+
+---
+
+## 3. A harness that is broken fixes itself
+
+You are injected into every session, so you are the only thing that can notice a broken
+harness before its owner does — and its owner usually cannot, because the symptoms name
+nothing they recognise. When any of these is true, act on it **once** in the session:
+
+- the assistant sees no skills in a project that clearly has a harness;
+- `.rsc.json` exists and what it declares is not what is installed;
+- the same hook seems to run several times;
+- the harness is wired for an assistant that is not the one running.
+
+Run `npx @damiangilgonzalez/harness doctor`, and say in one line what is wrong **as a symptom**, not as
+a cause. Then:
+
+- Anything that only puts the harness back to what was already declared — dangling links, a
+  repeated hook, a layout no version uses — say you are fixing it and run
+  `npx @damiangilgonzalez/harness repair`. Restoring is not deciding, and a recoverable copy is kept.
+- Anything that would change a decision — moving to another assistant, adopting a skill a
+  teammate added, disarming a gate — **ask first**. A `git pull` never rewrites someone's
+  machine.
+
+Offer once. A "no" holds for the session; a new session may look again, because the problem
+has not gone away. Never mention it when the harness is healthy.
+
+## 4. First contact
+
+Before handling the first request of a session, check the workspace:
+
+- No `docs/wiki/harness/user-profile.md` **and** no `.rsc/.no-harness` → the harness has never
+  been set up here. Invoke `init` first; it opens with the two gauging questions (technical level +
+  accompaniment dial). Do not start the user's task before first contact is done.
+- The user declines a harness here ("sin harness", "solo código") → create an empty
+  `.rsc/.no-harness`, confirm in one line, and never auto-start `init` in this repo again.
+- Once the profile exists, this gate is inert. Never re-onboard.
+
+## Explain without assuming
+
+Define a term at first use; never give a command, flag or path without saying what it does.
+
+## 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`.
+(Defiere a este mismo cuerpo, §2, el "¿instalo la skill que falta?".)

package/skills/suggest/evals/README.md

@@ -0,0 +1,17 @@
+# Evals — rsc-suggest
+
+The always-on detector. These cases check that it proposes the right missing
+skill (and stays quiet when the task needs nothing new).
+
+| Prompt | Expected |
+|---|---|
+| "crear la tabla de pedidos en la base de datos" | suggests `postgresdb` |
+| "publicar mi web online con docker" | suggests `deployment` |
+| "quiero montar una pagina web para vender cursos online" | during agent use, consults the catalog and suggests the first missing startup/web skill, usually `nextjs` after base install |
+| "Automatiza el flujo de leads desde el formulario hasta mi CRM" | during agent use, consults the catalog and suggests the first missing automation/connector skill |
+| "Write a cold email sequence to sell my SaaS to agencies" | during agent use, consults the catalog and suggests the first missing email/marketing skill |
+| "renombra esta variable" | no suggestion (trivial, nothing to install) |
+
+A pass = the detector names the expected skill, asks a one-word confirm, and on
+"sí" runs `npx @damiangilgonzalez/harness add <id>`. It must never auto-install without confirmation and
+must not recommend a skill already in `npx @damiangilgonzalez/harness list`.

package/skills/suggest/evals/cases.yaml

@@ -0,0 +1,78 @@
+skill: suggest
+
+# The always-on detector. It fires when the current task would clearly benefit
+# from an rsc skill that is NOT yet installed, names it, and (with confirmation)
+# runs `npx @damiangilgonzalez/harness add <id>`. It should stay silent for trivial work and defer to a
+# skill that already owns the task.
+
+should_trigger:
+  - prompt: "Quiero montar una pagina web para vender cursos online."
+    why: "Mid-conversation project-start intent — the detector should consult the catalog and propose the first missing skill from the startup queue (usually `nextjs` after the base install, or `init` in a bare install) before building."
+
+  - prompt: "Automatiza el flujo de leads desde el formulario hasta mi CRM."
+    why: "Mid-conversation automation/integration intent — the detector should consult the catalog and propose the first missing automation or connector skill before designing the workflow."
+
+  - prompt: "Write a cold email sequence to sell my SaaS to agencies."
+    why: "Mid-conversation creation/marketing intent — the detector should consult the catalog and propose the first missing email or marketing skill before writing generic copy."
+
+  - prompt: "Ayúdame a montar la tabla de pedidos en la base de datos."
+    why: "A database task with no DB skill present — the detector should propose `npx @damiangilgonzalez/harness add postgresdb` before diving in."
+
+  - prompt: "Quiero publicar mi web online, creo que con Docker."
+    why: "A deployment task with no deploy skill present — propose installing `deployment`."
+
+  - prompt: "Necesito una API en Python para esta app."
+    why: "Backend Python work with no stack skill present — propose installing `fastapi`."
+
+  - prompt: "Vamos a hacer la landing y que convierta bien."
+    why: "A design/conversion task with no design skill present — propose installing `design`."
+
+  - prompt: "Quiero un agente de IA que conteste sobre mis documentos."
+    why: "Agent/RAG work with no agents skill present — propose installing `building-agents`."
+
+  - prompt: "Documenta cómo funciona mi empresa y conéctalo todo."
+    why: "Company harness work with no harness skill present — propose installing `harness`. A deliberately non-code, non-obvious trigger."
+
+should_not_trigger:
+  - prompt: "Renombra esta variable a `userCount`."
+    route_to: "none"
+    why: "Trivial mechanical edit — nothing to install; the detector must stay silent and not interrupt the flow."
+
+  - prompt: "Revisa este código de login por inyección y control de acceso."
+    route_to: "secure-coding"
+    why: "A security review is squarely owned by the secure-coding skill; if it is installed the detector defers to it rather than proposing anything."
+
+  - prompt: "Optimiza esta query de Postgres que va lenta."
+    route_to: "postgresdb"
+    why: "A concrete database task owned by the postgresdb skill — the detector does not fire over a skill that already owns the work."
+
+  - prompt: "Arregla este bug del test que falla."
+    route_to: "external:superpowers-systematic-debugging"
+    why: "Root-cause debugging is superpowers' systematic-debugging's job; no new install is implied, so the detector stays quiet."
+
+capability:
+  - scenario: "Mid-conversation, the user says 'ayúdame a guardar los pedidos en una base de datos' and no database skill is installed. Show how rsc-suggest behaves."
+    must_include:
+      - "Names the missing skill in plain language ('para esto va bien `postgresdb`, que aún no tienes')"
+      - "Asks a single short confirmation (sí/no) before doing anything — never auto-installs"
+      - "On confirmation, runs `npx @damiangilgonzalez/harness add postgresdb` via Bash, then continues the original task"
+      - "Checks what is already installed (npx @damiangilgonzalez/harness list) and never proposes a skill the user already has"
+      - "Makes at most one suggestion and does not interrupt the flow for nice-to-haves"
+
+  - scenario: "Mid-conversation, after base install, the user says 'quiero montar una pagina web para vender cursos online'. `init`, `harness`, `orient`, `suggest`, and `bro` are already installed; `nextjs` is not. Show how rsc-suggest behaves."
+    must_include:
+      - "Treats the message as in-agent capability intent, not as a CLI-only consult task"
+      - "Runs `npx @damiangilgonzalez/harness catalog --available` to see the not-installed skills (already excludes installed `init`/`harness`)"
+      - "Picks the best-fit skill by MEANING from the catalog, not by relying on lexical `consult` ranking"
+      - "Names `nextjs` as the missing useful skill for the website work"
+      - "Asks one short confirmation before installing and does not auto-install"
+      - "On confirmation, runs `npx @damiangilgonzalez/harness add nextjs`, then resumes the original website task"
+
+  - scenario: "Mid-conversation, the user says 'Automatiza el flujo de leads desde el formulario hasta mi CRM'. The base skills are installed, but `automation-flows` and CRM/connector skills are not. Show how rsc-suggest behaves."
+    must_include:
+      - "Treats the message as in-agent capability intent for automation/integration, not only as a coding task"
+      - "Runs `npx @damiangilgonzalez/harness catalog --available` to see the not-installed skills"
+      - "Picks the best-fit missing automation/connector skill by MEANING (not by lexical `consult` ranking, which may return nothing)"
+      - "Names that one missing automation/connector skill"
+      - "Asks one short confirmation before installing and does not auto-install"
+      - "On confirmation, runs `npx @damiangilgonzalez/harness add <id>` for that one missing skill, then resumes the automation task"