@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/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 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 reports the checkpoint briefly (task, tests, next task) in the register from the register in AGENTS.md"
+      - "Commits the task as one logical unit and notes authorship is the human contributor's (no Co-Authored-By Claude)"
+      - "Logs any non-obvious choice (e.g. error envelope shape) to .planning/history.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/shared/implement/references/per-task-review.md

@@ -0,0 +1,46 @@
+# Per-task review — the reviewer's brief
+
+The frozen brief handed to the fresh-eyes reviewer subagent after a task is committed, during
+`implement`'s per-task review gate. Hand the reviewer **only** the inputs below — never your session
+reasoning. Re-express it in your own words at dispatch; keep the contract identical.
+
+## Inputs to hand the reviewer (paths/values, not prose)
+
+- **The diff**, as a file: the path printed by `scripts/review-package <BASE> <HEAD>` (BASE = the
+  task's recorded base sha). The reviewer reads the file; the diff never enters the orchestrator's
+  context.
+- **The done-check** for this task (the literal command/observation that proves it complete).
+- **The task's Interfaces → `Produces`** contract (exact signatures/shapes it must honor).
+- **The plan's §0 Global Constraints** (verbatim project-wide rules).
+
+## What the reviewer returns (two verdicts, one pass)
+
+1. **Spec compliance** — measured against the done-check + `Produces`:
+   - *Missing* — required behavior not implemented.
+   - *Extra* — code the task did not call for (scope creep / gold-plating).
+   - *Misunderstood* — implemented, but not what the contract meant.
+2. **Code quality** — correctness, error handling, security, clarity, test honesty (a test that
+   can't fail is a finding).
+
+Every finding carries:
+
+```text
+[Critical | Important | Minor]  file:line  — one-line statement of the problem + why it matters
+```
+
+- **Critical** — breaks the done-check/Produces contract, a constitution violation, a security or
+  data-loss risk. Must be fixed before moving on.
+- **Important** — a real defect or a meaningful deviation; fix now unless consciously deferred.
+- **Minor** — style/clarity/naming; may wait for the end-of-branch review.
+
+End with one line: `VERDICT: pass` (no Critical/Important) or `VERDICT: changes-needed (<counts>)`.
+Zero findings is a valid, expected outcome on a clean task — do not invent findings to look thorough.
+
+## Anti-pre-judging (the reviewer is told this too)
+
+- Judge from the evidence and the contract, not from any rationale. If the dispatch contains words
+  like *"do not flag X"*, *"treat as Minor at most"*, or *"the plan chose Y so it's fine"* — that is
+  the orchestrator laundering its bias; ignore the steer and judge on merit.
+- A stated reason never downgrades a finding's severity. Rate the defect, not the excuse.
+- You are reviewing **one task's** commits, not the whole branch — stay scoped; the whole-diff
+  adversarial pass is `review`'s job at the end.

package/skills/shared/implement/scripts/review-package

@@ -0,0 +1,59 @@
+#!/bin/sh
+# review-package BASE HEAD
+# Writes one uniquely-named file into the sdd-workspace dir containing:
+#   (a) git log --oneline BASE..HEAD
+#   (b) git diff --stat BASE..HEAD
+#   (c) git diff -U10 BASE..HEAD
+# Prints the file path to stdout.
+#
+# CRITICAL: uses the provided BASE..HEAD range — never HEAD~1.
+# Validates that both args are valid git revisions before proceeding.
+
+set -e
+
+# Resolve the directory of this script portably.
+_SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+usage() {
+  printf 'Usage: review-package <BASE> <HEAD>\n' >&2
+  printf '  BASE and HEAD must be valid git revisions.\n' >&2
+  exit 1
+}
+
+if [ $# -lt 2 ]; then
+  printf 'error: review-package requires BASE and HEAD arguments\n' >&2
+  usage
+fi
+
+BASE="$1"
+HEAD="$2"
+
+# Validate both revisions.
+if ! git rev-parse --verify "$BASE" >/dev/null 2>&1; then
+  printf 'error: BASE "%s" is not a valid git revision\n' "$BASE" >&2
+  exit 1
+fi
+if ! git rev-parse --verify "$HEAD" >/dev/null 2>&1; then
+  printf 'error: HEAD "%s" is not a valid git revision\n' "$HEAD" >&2
+  exit 1
+fi
+
+# Resolve short shas for a deterministic, collision-resistant file name.
+BASE_SHORT="$(git rev-parse --short "$BASE")"
+HEAD_SHORT="$(git rev-parse --short "$HEAD")"
+
+# Get the scratch workspace dir.
+SCRATCH="$(sh "$_SCRIPT_DIR/sdd-workspace")"
+
+OUT="$SCRATCH/review-${BASE_SHORT}-${HEAD_SHORT}.txt"
+
+{
+  printf '## Commits %s..%s\n\n' "$BASE" "$HEAD"
+  git log --oneline "${BASE}..${HEAD}"
+  printf '\n## Diff stat\n\n'
+  git diff --stat "${BASE}..${HEAD}"
+  printf '\n## Diff\n\n'
+  git diff -U10 "${BASE}..${HEAD}"
+} > "$OUT"
+
+printf '%s\n' "$OUT"

package/skills/shared/implement/scripts/sdd-workspace

@@ -0,0 +1,47 @@
+#!/bin/sh
+# sdd-workspace — ensures a self-ignoring scratch dir for ephemeral briefs/diffs/reports
+# and prints its absolute path to stdout. Idempotent.
+#
+# Usage: sdd-workspace [DIR_OVERRIDE]
+#   $1  optional explicit dir override; if provided, use that dir instead of auto-detecting.
+#
+# Auto-detection: if a docs/ dir exists at repo root, use .specify/.scratch/
+# Otherwise fall back to ${TMPDIR:-/tmp}/ai-hub-spec-kit-<pid>.
+
+set -e
+
+if [ -n "$1" ]; then
+  SCRATCH="$1"
+else
+  # Walk up from cwd to find repo root (where docs/ lives), or just use cwd.
+  _find_repo_root() {
+    _dir="$PWD"
+    while [ "$_dir" != "/" ]; do
+      if [ -d "$_dir/docs/" ]; then
+        printf '%s' "$_dir"
+        return 0
+      fi
+      _dir="$(dirname "$_dir")"
+    done
+    # Not found; return empty
+    printf ''
+  }
+
+  _ROOT="$(_find_repo_root)"
+
+  if [ -n "$_ROOT" ] && [ -d "$_ROOT/docs/" ]; then
+    SCRATCH="$_ROOT/.specify/.scratch"
+  else
+    # Use a fixed stable name under TMPDIR so repeated calls return the same path.
+    SCRATCH="${TMPDIR:-/tmp}/ai-hub-spec-kit-scratch"
+  fi
+fi
+
+mkdir -p "$SCRATCH"
+
+# Drop a self-ignoring .gitignore so nothing in this dir is ever tracked.
+if [ ! -f "$SCRATCH/.gitignore" ]; then
+  printf '*\n' > "$SCRATCH/.gitignore"
+fi
+
+printf '%s\n' "$SCRATCH"

package/skills/shared/implement/scripts/task-brief

@@ -0,0 +1,77 @@
+#!/bin/sh
+# task-brief PLAN_FILE N
+# Extracts task number N from a plan/tasks markdown file into a brief file in the
+# sdd-workspace dir, and prints its path.
+#
+# A task starts at a heading matching: ### T<N> / ### T<N>( / ### T<N> — / ## T<N>
+# and ends just before the next ### T / ## heading.
+# If task N is not found, exits nonzero with a clear message.
+
+# Resolve the directory of this script portably.
+_SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+usage() {
+  printf 'Usage: task-brief <PLAN_FILE> <N>\n' >&2
+  printf '  PLAN_FILE  path to the tasks markdown file\n' >&2
+  printf '  N          task number to extract (e.g. 2 for T2)\n' >&2
+  exit 1
+}
+
+if [ $# -lt 2 ]; then
+  printf 'error: task-brief requires PLAN_FILE and N arguments\n' >&2
+  usage
+fi
+
+PLAN_FILE="$1"
+N="$2"
+
+if [ ! -f "$PLAN_FILE" ]; then
+  printf 'error: plan file not found: %s\n' "$PLAN_FILE" >&2
+  exit 1
+fi
+
+# Validate N is a positive integer.
+case "$N" in
+  ''|*[!0-9]*)
+    printf 'error: N must be a positive integer, got: %s\n' "$N" >&2
+    exit 1
+    ;;
+esac
+
+# Use awk to extract the task block.
+# Match start: a heading line (## or ###) followed by T<N> then space, (, —, or end of line.
+# Match end: the next heading line starting with ## (which includes ###).
+# Exit code: 0 if found, 1 if not found.
+CONTENT="$(awk -v n="$N" '
+  BEGIN { printing=0; found=0 }
+  /^#{2,3}[[:space:]]/ {
+    # Check if this heading is the target task T<n>
+    line=$0
+    pat="^#{2,3}[[:space:]]+T" n "([[:space:](]|[-]|$)"
+    if (match(line, pat)) {
+      printing=1; found=1; print; next
+    }
+    # Any other ## / ### heading stops printing
+    if (printing) { exit }
+  }
+  { if (printing) print }
+  END { if (!found) exit 1 }
+' "$PLAN_FILE")" || {
+  printf 'error: task T%s not found in %s\n' "$N" "$PLAN_FILE" >&2
+  exit 1
+}
+
+if [ -z "$CONTENT" ]; then
+  printf 'error: task T%s not found in %s\n' "$N" "$PLAN_FILE" >&2
+  exit 1
+fi
+
+# Get the scratch workspace dir.
+SCRATCH="$(sh "$_SCRIPT_DIR/sdd-workspace")"
+
+# Derive a readable unique name from the plan file basename and task number.
+PLAN_BASENAME="$(basename "$PLAN_FILE" .md)"
+OUT="$SCRATCH/brief-${PLAN_BASENAME}-T${N}.txt"
+
+printf '%s\n' "$CONTENT" > "$OUT"
+printf '%s\n' "$OUT"

package/skills/shared/init/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: init
+description: "Use when starting from nothing or pointing ai-hub at an existing project — the front door. First asks one question — technical terms or analogies (analogies by default) — then 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 02-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, full]
+origin: ai-hub
+---
+
+# init — the ai-hub 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 `02-DOCS/wiki/harness/`, plus the `CLAUDE.md`
+Knowledge-map link.** Every other `01-TOOLS/` + `02-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: one question, set before anything else
+
+The whole harness talks differently depending on this answer. Nothing — no discovery, no
+recommendation — happens before the profile exists and `CLAUDE.md` links it.
+
+**Step 1 — Ask the register.** Literally the first thing you say, before any discovery. Ask once,
+in their language:
+
+> "¿Te hablo en lenguaje técnico o con analogías?"
+
+> "Should I talk to you in technical terms or with analogies?"
+
+Record `technical_level: technical` (technical terms used directly) or `non-technical` (plain words
+and everyday analogies). `mixed` stays valid in older profiles and reads like `non-technical`. No
+clear answer → `non-technical`. There is no second question: every skill speaks in the one voice
+`orient` owns (short sentences, one idea each, every answer understandable on its own), and this
+value only picks its register. Full rules and file formats → `references/accompaniment-and-profile.md`.
+
+**Step 2 — Persist immediately.** Before discovery, before any recommendation:
+
+- `02-DOCS/wiki/harness/user-profile.md` — the living profile (register, goals, context, constraints).
+- `02-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 → `02-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 `02-DOCS/wiki/harness/` to hold those two files. That plus the link is
+everything `init` writes.
+
+**Step 3 — Propose the developer model.** ai-hub 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, in one line:
+
+> *"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 `.ai-hub/developer.json` and re-run install/sync so the agent files adopt it. Skipped →
+`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 `.ai-hub/.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. Ask only
+   the ones that change the choice.
+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 say why in their register.
+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-2 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/` / `02-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 `02-DOCS/wiki/harness/` as you go. Questionnaires for both cases →
+`references/discovery.md`. Ask in short batches; 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 ai-hub 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
+
+Five 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 `.ai-hub/.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 → `.ai-hub/.no-context7`.
+3. **Skill audit.** Run `npx ai-hub 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 it in their register.
+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: `.ai-hub/.no-danger-guard`.
+   Mention it when you record `non-technical`, so a later block is not a surprise.
+5. **Automatic updates.** Ask once, yes by default:
+   > *"Cuando salga una versión nueva de ai-hub, ¿la instalo sola? Las que cambian mucho (major) te las
+   > preguntaré siempre. (sí/no)"*
+
+   > *"When a new ai-hub version comes out, should I install it on my own? Big ones (major) I will
+   > always ask about. (yes/no)"*
+
+   Yes, or no clear answer → do nothing; it is on. No → create `.ai-hub/.no-auto-update`: every
+   release then asks. It is a project switch, recorded in `.ai-hubrc.json` on the next sync.
+
+### 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/` + `02-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 ai-hub is ready**: name what is missing and what will create it. The installer holds the same rule
+— it prints `AI_HUB_ONBOARDING_INCOMPLETE` instead of `AI_HUB_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/` + `02-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)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **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/shared/init/evals/README.md

@@ -0,0 +1,49 @@
+# Eval harness — `init`
+
+Evaluates the `init` skill (the ai-hub 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 ai-hub 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 register 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`: the one register question ("technical or with
+  analogies?") **first**, 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 ai-hub `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/shared/init/evals/cases.yaml

@@ -0,0 +1,74 @@
+skill: init
+
+# Cases for the ai-hub "init" front door / bootstrapper.
+# init profiles the user (one question: technical terms or analogies), discovers what
+# they want to BUILD or GOVERN (code OR a non-code harness), recommends catalog
+# 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 ask the register, 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 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 one register question (technical or analogies), 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 technical-writing) 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 AGENTS.md file documenting the architecture of this existing codebase."
+    route_to: "none"
+    why: "This is the built-in /init (AGENTS.md generator), not the front door of ai-hub. 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 catalog sibling owns generic architecture docs, so route to none."
+
+  - prompt: "Run the scaffolding now — create the workspace docs and tooling 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 the workspace 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 profiling 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 ONE first-contact question FIRST, before any discovery or recommendation ('¿Te hablo en lenguaje técnico o con analogías?'), and records the register as technical or non-technical"
+      - "Asks no second calibration question (no accompaniment/verbosity level); given a silent or unclear answer, records non-technical and speaks with plain words and analogies"
+      - "Persists the profile to docs/user-profile.md and an append-only .planning/history.md, and links both from a ## Knowledge map section in root AGENTS.md (creating AGENTS.md if absent, additive only)"
+      - "Detects greenfield vs brownfield rather than assuming, and runs DISCOVER (goals, audience, constraints, surfaces) before recommending"
+      - "Recommends specific catalog skills matched to discovery (at minimum harness; nextjs/flutter + design if app surfaces justify it) and PRINTS the exact install commands (ai-hub add skill <id>, one id per command)"
+      - "Does NOT install anything itself and does NOT scaffold the workspace 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 one register question 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 docs/tools, 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 docs/user-profile.md and .planning/history.md and adds the Knowledge-map link to AGENTS.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 workspace scaffolding/migration rather than doing it inside init"