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

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

@@ -0,0 +1,122 @@
+# Register & Profile — the first-contact question and how it persists
+
+This file holds the runtime detail behind the SKILL.md section "First contact". It defines: the first-contact question, the register it sets, the exact `02-DOCS` file formats, and the rule every downstream skill follows. (The filename is historical: the accompaniment dial it once described is retired.)
+
+## 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 analogies, asks once before assuming otherwise, and keeps one voice for everyone. The profile is the contract; every skill honors it.
+
+## The first-contact question
+
+Ask exactly one thing before anything else. Do not bundle it with discovery questions.
+
+Spanish:
+
+> "¿Te hablo en lenguaje técnico o con analogías?"
+
+English:
+
+> "Should I talk to you in technical terms or with analogies?"
+
+Map the answer to one of:
+
+- `technical` — technical terms used directly; can read code and configs.
+- `non-technical` — plain words and everyday analogies; no undefined jargon; no code shown unless asked.
+- `mixed` — still valid in older profiles; treat it like `non-technical`.
+
+`non-technical` and `mixed` (and no profile at all) also arm the danger guard, which blocks irreversible commands; `technical` never does. Say so when you record the answer.
+
+If the user does not answer clearly, record `non-technical`. Never guess "technical" from the fact that they opened a terminal — many non-technical people are handed one. The user can change it any time ("háblame técnico", "con analogías"); update `user-profile.md` when they do.
+
+## How every skill adapts
+
+There is no per-user depth setting. Every skill speaks in the one voice the `orient` skill owns (`skills/orient/references/orientation-contract.md`): short sentences, one idea per sentence, simple words, active voice, the instruction before the reason, and every answer understandable on its own. `technical_level` only picks the register:
+
+- `technical` — use the term directly; skip the 101 explanations.
+- `non-technical` / `mixed` — translate every term ("a database is where the app remembers things"), prefer analogies, never paste raw config without explaining it.
+
+If the person still does not understand, `orient` climbs its explanation ladder (text → diagram → one HTML page → a video, only offered).
+
+**Legacy keys.** A profile written by an older `init` or `onboard` may carry `accompaniment_level:` or the even older `accompaniment:`. Both are retired: ignore their value, and drop the line the next time you touch the profile.
+
+**Rule:** read `user-profile.md` at the start of every session. If it is missing, you are likely being run before `init` — ask the first-contact question before doing the requested work, or at minimum speak with analogies and note that the profile is unset.
+
+## Persistence format
+
+Both files live under `02-DOCS/wiki/harness/`. `init` creates this directory even on greenfield; the rest of `02-DOCS` is built by the `harness` skill.
+
+### `02-DOCS/wiki/harness/user-profile.md`
+
+A living document — updated whenever the user reveals new goals, context, constraints, or changes the register. It is the single source of truth other skills read.
+
+```markdown
+# User Profile
+
+> Source of truth for how every ai-hub skill talks to this user. Updated continuously.
+
+## Register
+- technical_level: non-technical            <!-- technical | non-technical (mixed: legacy, reads as non-technical) -->
+- 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.
+```
+
+### `02-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](02-DOCS/wiki/harness/user-profile.md) — register (technical or analogies), goals, context, constraints. **Every skill reads this first and speaks in that register.**
+- [Decisions log](02-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 `02-DOCS/` — it does not replace the harness entries written here.

package/skills/shared/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 `02-DOCS/wiki/harness/user-profile.md` as you learn it. Ask in short batches — 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/`, `02-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) + `02-DOCS` (the wiki/second-brain) structure.
+
+---
+
+## Software — questionnaire
+
+### Greenfield software
+
+Ask in short batches, only what changes the plan.
+
+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 `02-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 `02-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.

package/skills/shared/init/references/recommend-skills.md

@@ -0,0 +1,115 @@
+# Recommend Skills — the skill map, sample printouts & the "siempre 3 opciones" pattern
+
+Phase 3 detail. Map discovery to individual ai-hub skills, print the exact
+`npx ai-hub add` commands, and run the requirements-first 3-option decision pattern
+for any significant choice. A skill **cannot install anything** — it recommends
+and prints commands the user runs.
+
+## The skill map
+
+| Discovery signal | Skills | One-line *why* (in the user's register) |
+| --- | --- | --- |
+| Always (every project) | `harness` | The control plane — scaffolds and governs the whole workspace (`suggest` installs with it as the floor). |
+| Backend / API / database | `fastapi` or `go`, `postgresdb` | The server, the API, the database that remembers things. |
+| Web or mobile UI | `nextjs` or `flutter`, `design` | The screens people actually see and tap. |
+| Marketing / landing / decks / teaching | `marketing`, `presentations`, `course-storytelling` | The words, slides, and lessons that explain and sell it. |
+| AI agents | `building-agents` | Agents that use tools and reason over your data. |
+| Security & shipping / ops (incl. non-code company harness connecting tools) | `secure-coding`, `deployment` | Ship it safely and wire up the external tools (email, payments, hosting). |
+
+Recommend a skill **only if discovery justified it** — same discipline as "no
+speculative tools". Don't recommend `building-agents` because agents are trendy;
+recommend it because the user said they want an agent.
+
+Note on the non-code harness: a company/ops/research/content harness almost
+always wants `harness` (the structure) + `deployment`/`secure-coding` (to connect
+external tools and handle credentials securely), and often `marketing`. It
+usually does NOT want `fastapi`/`nextjs` unless they're also building software.
+
+## What to print
+
+One `npx ai-hub add` line per recommendation (or batch them on one line), each with
+its *why* in the user's language and register.
+
+```text
+npx ai-hub add <skill> [<skill> ...]
+```
+
+### Sample printout — software, full-stack web app with marketing
+
+```text
+Based on what you described (a web app with a backend, a Next.js UI, a landing
+page, and you want to ship it securely), install these:
+
+npx ai-hub add harness        # the control plane — scaffolds and governs the workspace
+npx ai-hub add fastapi postgresdb   # the API and the database
+npx ai-hub add nextjs design  # the web UI people see
+npx ai-hub add marketing      # the words for your landing page
+npx ai-hub add secure-coding deployment   # ship it safely
+
+Once they're installed, run the harness skill and I'll build the project structure.
+```
+
+### Sample printout — non-code harness, running an agency's operations
+
+```text
+You're organizing how your agency runs — client emails, contracts, invoicing,
+and you want it all findable. That's a non-code harness; install:
+
+npx ai-hub add harness        # your 01-TOOLS (connections) + 02-DOCS (your second brain)
+npx ai-hub add secure-coding deployment   # connect email, payments, drive — and keep credentials safe
+npx ai-hub add marketing      # for the proposals, decks and copy you send clients
+
+Once installed, run the harness skill and I'll set up the structure that holds it all.
+```
+
+### Sample printout — greenfield AI agent
+
+```text
+You want an AI agent that answers questions over your own documents. Install:
+
+npx ai-hub add harness            # the control plane
+npx ai-hub add building-agents    # agent loops, tools, RAG
+npx ai-hub add fastapi postgresdb # an API + database to serve it
+npx ai-hub add secure-coding deployment   # ship it safely
+
+Then run the harness skill.
+```
+
+## The "siempre 3 opciones" decision pattern
+
+For any significant decision — deploy target, database, framework, hosting, which CRM, where documents live — never decide silently and never dump ten choices. Four steps:
+
+### 1. Gather the driving requirements first
+
+Ask only the questions that actually change the answer, in one short batch. Checklists per decision type:
+
+- **Deploy target:** expected number of users; concurrent users; budget; data region / residency rules; the team's comfort operating servers; scaling needs (steady vs spiky); existing org/cloud constraints.
+- **Database:** data shape (relational vs documents vs key-value); expected size and growth; query patterns; consistency vs scale needs; managed vs self-hosted preference; budget.
+- **Framework / language:** team's existing skills; the surfaces needed; performance constraints; ecosystem/libraries required; hiring/longevity.
+- **Where knowledge/documents live (non-code harness):** volume and formats; who needs access; privacy / residency of client data; search needs; existing tools already paid for.
+
+### 2. Present EXACTLY three options
+
+Three, with honest trade-offs — what each is good at, what it costs, what it demands. Not two (false binary), not ten (paralysis). If a fourth is genuinely worth knowing, mention it in one line under the third — but the choice is between three.
+
+### 3. Recommend one, matched to their answers
+
+State your recommendation and why, in their register. For a `non-technical` user, explain each option with an everyday analogy and check they followed before they pick.
+
+### 4. Log the decision
+
+Once they choose, append an entry to `02-DOCS/wiki/harness/decisions.md` (format in `accompaniment-and-profile.md`): context (the requirements you gathered), the three options, the decision, and why.
+
+## Canonical worked example — deploy target
+
+Requirements gathered: ~500 users, ~20 concurrent, low budget, EU data residency required, small team comfortable with a little server work, steady (non-spiky) traffic.
+
+> **Option 1 — Hetzner VPS + Coolify.** Cheapest by far (a capable box is a few euros a month), total control, and Hetzner has EU regions so residency is covered. The catch: you self-manage the server — updates, backups, keeping it up. Coolify makes deploys push-button, but the box is yours.
+>
+> **Option 2 — Vercel.** Zero-ops: you push, it deploys, it scales itself, nothing to maintain. The catch: it gets expensive as you grow, and you're shaped by its model (best for frontend/serverless; data residency and always-on backends need care).
+>
+> **Option 3 — Fly.io.** Managed containers that run in an EU region close to your users, simpler than raw cloud, more hands-off than a VPS. The catch: a bit pricier than Hetzner and you still think in containers.
+>
+> **Recommendation:** Option 1 (Hetzner + Coolify, EU region). Your budget is tight, EU residency is a hard requirement Hetzner satisfies cleanly, traffic is steady so you don't need autoscaling, and your team is fine managing one box. We log this and move on; if ops ever becomes a burden, Option 3 is the easy step up.
+
+This decision triggers the `deployment` skill at build time, which knows Hetzner+Coolify, Vercel, Fly.io and the rest in depth. `init` makes the choice and records it; `deployment` executes it.

package/skills/shared/init/scripts/verify.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+#
+# verify.sh — bootstrap gate for the `init` skill.
+#
+# WHAT IT DOES (read-only; never edits or creates a file)
+#   Static checks that Phase 1 (PROFILE) actually landed in the workspace:
+#     1. docs/user-profile.md exists and carries technical_level
+#        line — the one dial (technical, or with analogies). The accompaniment dial
+#        is retired: an old profile that still carries it is not flagged.
+#     2. .planning/history.md exists (append-only decisions log).
+#     3. Root AGENTS.md exists and its "## Knowledge map" section links the profile.
+#   Everything is detect-or-skip: a missing workspace piece is a WARNING, never a
+#   failure — `init` may simply not have run yet. The script never fails the build;
+#   it only reports. (No --strict mode: this is a presence check, not a CI gate.)
+#
+# HOW TO RUN (inside YOUR workspace, not the skills repo)
+#   ./verify.sh                 # check ./ for the profile + Knowledge-map link
+#   ./verify.sh --path some/dir # check a different workspace root
+#
+# EXIT CODES
+#   0  always, unless usage is wrong (this is a warn-only presence check)
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, no process
+# substitution; arrays avoided; everything POSIX-ish under `set -euo pipefail`.
+
+set -euo pipefail
+
+# --- color helpers (no escape codes when not a TTY) -------------------------
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+
+usage() {
+  # print the header comment block (lines 2..24), stripping the leading "# "
+  sed -n '2,24p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+# --- arg parse --------------------------------------------------------------
+ROOT="."
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    ROOT="${2:?--path needs a value}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -e "$ROOT" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$ROOT" "$NC"; exit 2
+fi
+
+PROFILE="$ROOT/docs/user-profile.md"
+DECISIONS="$ROOT/.planning/history.md"
+CLAUDE_MD="$ROOT/AGENTS.md"
+
+# has <file> <pattern>: true if a non-empty file contains a case-insensitive match.
+has() {
+  [ -s "$1" ] || return 1
+  grep -iq -e "$2" "$1" 2>/dev/null
+}
+
+printf 'Checking init PROFILE artifacts under: %s\n\n' "$ROOT"
+
+# --- 1. user profile --------------------------------------------------------
+if [ ! -s "$PROFILE" ]; then
+  warn "no user profile at docs/user-profile.md — run init's PROFILE phase first"
+else
+  ok "user profile present: $PROFILE"
+  if has "$PROFILE" 'technical_level'; then
+    ok "profile records technical_level"
+  else
+    warn "profile is missing a technical_level line"
+  fi
+fi
+
+# --- 2. decisions log -------------------------------------------------------
+if [ ! -s "$DECISIONS" ]; then
+  warn "no decisions log at .planning/history.md — significant decisions should be appended here"
+else
+  ok "decisions log present: $DECISIONS"
+fi
+
+# --- 3. AGENTS.md Knowledge map link ----------------------------------------
+if [ ! -s "$CLAUDE_MD" ]; then
+  warn "no root AGENTS.md — init should create it with a '## Knowledge map' section"
+else
+  ok "root AGENTS.md present"
+  if has "$CLAUDE_MD" '## *Knowledge map'; then
+    ok "AGENTS.md has a '## Knowledge map' section"
+    if has "$CLAUDE_MD" 'user-profile.md'; then
+      ok "Knowledge map links the user profile"
+    else
+      warn "Knowledge map does not link docs/user-profile.md"
+    fi
+  else
+    warn "AGENTS.md has no '## Knowledge map' section linking the profile"
+  fi
+fi
+
+# --- summary ----------------------------------------------------------------
+printf '\nok=%d skip=%d warn=%d\n' "$ok_count" "$skip_count" "$warn_count"
+
+cat <<'EOF'
+
+Note: every finding is a presence WARNING, not a failure. If init has not run yet,
+warnings are expected. Run init's PROFILE phase, then re-run this check.
+EOF
+
+exit 0