@ericrisco/rsc 1.0.10 → 1.0.11

package/README.md

@@ -12,7 +12,7 @@
   ██    ██   ███████     ███████ 
 ```
 
-# `rsc` — 256 agent skills, one CLI, zero bloat
+# `rsc` — 264 agent skills, one CLI, zero bloat
 
 **A self-recommending skill catalog for 17 coding assistants** — Claude Code,
 Codex, GitHub Copilot, Cursor, Gemini, Windsurf, Cline, Antigravity, Zed and more.
@@ -21,7 +21,7 @@ skills that fit — one at a time — into every assistant you pick, and keeps t
 equipped as you work.
 
 From *"document my company"* to *"ship a FastAPI service"* to *"grow my YouTube
-channel"* — **232 skills across 21 domains**, every one researched against live
+channel"* — **264 skills across 21 domains**, every one researched against live
 2025-2026 sources and **adversarially scored ≥ 8.5/10** before it shipped.
 
 ```bash
@@ -43,7 +43,7 @@ npx @ericrisco/rsc@latest
 ```
 
 That launches a plain-language wizard: it asks **which assistants** to target and **what the
-user wants**, reads the repo, then installs the floor (`orient` + `rsc-suggest` + `harness` +
+user wants**, reads the repo, then installs the floor (`orient` + `rsc-suggest` + `bro` + `harness` +
 `init`) plus only the skills that fit — one at a time. No global install and no API key needed.
 
 - **Choose assistants non-interactively:** `npx @ericrisco/rsc@latest --target claude` (comma-separate for several).
@@ -109,7 +109,7 @@ cd ~/rsc-skills && npm install && npm link
 The first run asks **which assistants** you want — Claude Code, Codex, Copilot,
 Cursor, Gemini, Windsurf, Cline and 11 more (pick any combination) — and installs
 the **floor**:
-`orient` + `rsc-suggest` (always-on) + `harness` + `init`. In Claude Code it
+`orient` + `rsc-suggest` (always-on) + `bro` (on request) + `harness` + `init`. In Claude Code it
 also wires a `SessionStart` hook (so your assistant proposes new skills on its
 own) and a `UserPromptSubmit` hook that re-asserts the **SDD new-feature gate**
 on every turn — so a feature request, in any language, routes through `specify`
@@ -129,10 +129,10 @@ $ rsc
  ██████╗ ███████╗ ██████╗     ← animated gradient wordmark
  ██╔══██╗██╔════╝██╔════╝
  ██████╔╝███████╗██║
-  232 skills · one CLI · zero bloat
+  264 skills · one CLI · zero bloat
 
 What do you want to do?          ↑↓ move · enter select
-❯ Base install — the essentials (orient + suggest + harness + init)
+❯ Base install — the essentials (orient + suggest + bro + harness + init)
   Base + Spec-Driven Development — specify → plan → implement → ship
   Pick skills by hand, by area
 ```
@@ -175,9 +175,9 @@ rsc                                  # plain-language wizard (recommended) — p
 rsc add fastapi postgresdb           # install specific skills, by name
 rsc add youtube-api remotion-video   # …grow a channel, edit with Remotion
 rsc add fastapi --target claude,codex   # install into several assistants at once
-rsc install --profile minimal        # the floor: orient + suggest + harness + init
+rsc install --profile minimal        # the floor: orient + suggest + bro + harness + init
 rsc install --profile core           # floor + the full SDD workflow
-rsc install --profile full           # everything (all 231)
+rsc install --profile full           # everything (all 264)
 rsc install --profile full --without go
 rsc consult "I want to launch a SaaS"  # recommend only, no install
 rsc registry refresh                 # write .rsc/skill-registry.{json,md}
@@ -228,7 +228,7 @@ rsc restore <snapshot-id>              # restore it
 Two faces, one catalog (`manifest.json`):
 
 - **In the terminal** — `rsc` / `rsc consult` rank the catalog against your words
-  (an FTS index over each skill's description + tags), merge that with what they
+  (multilingual TF-IDF blended with exact tag/id weights and intent synonyms), merge that with what they
   detect in your repo, and expand via each skill's `recommends`.
 - **In the chat** — `rsc-suggest` is a tiny always-on skill. When a task would
   benefit from a skill you don't have, it names it and (one-word confirm) runs
@@ -243,18 +243,20 @@ just asks in plain language.
 
 ## The catalog
 
-257 skills, grouped by what you're trying to do. Click any skill to read its
+264 skills, grouped by what you're trying to do. Click any skill to read its
 `SKILL.md`. It fires on its own when a task matches.
 
 ### 🧭 Core & control plane
 The front door and the workspace brain.
 
-[init](skills/init/) · [harness](skills/harness/) · [orient](skills/orient/) · [suggest](skills/suggest/) · [author-skill](skills/author-skill/) · [sdd-init](skills/sdd-init/)
+[init](skills/init/) · [harness](skills/harness/) · [orient](skills/orient/) · [suggest](skills/suggest/) · [bro](skills/bro/) · [author-skill](skills/author-skill/) · [sdd-init](skills/sdd-init/)
 
 > **harness** is the Karpathy *chaos→knowledge* engine — a `01-TOOLS/` layer (one
 > folder per provider, each with a working `test_connection`) and a `02-DOCS/`
 > self-improving wiki. It governs software *or* a whole company. **orient** is the
 > always-on compass that keeps a non-technical human oriented after every step.
+> **bro** is installed with every profile and rewrites any answer in plain, natural
+> language when the user asks — without making its full body always-on.
 
 > #### 📦 The `02-DOCS/` brain is now 100% Open Knowledge Format (OKF v0.1) conformant
 >
@@ -279,7 +281,7 @@ The front door and the workspace brain.
 ### 📐 Spec-Driven Development
 Take a fuzzy intent to a shipped, verified change — phase by phase. `npx @ericrisco/rsc install --profile core`.
 
-[sdd](skills/sdd/) · [constitution](skills/constitution/) · [specify](skills/specify/) · [clarify](skills/clarify/) · [plan](skills/plan/) · [tasks](skills/tasks/) · [analyze](skills/analyze/) · [implement](skills/implement/) · [verify](skills/verify/) · [review](skills/review/) · [ship](skills/ship/) · [debug](skills/debug/) · [worktrees](skills/worktrees/) · [parallel](skills/parallel/)
+[sdd](skills/sdd/) · [constitution](skills/constitution/) · [idea-refinement](skills/idea-refinement/) · [specify](skills/specify/) · [clarify](skills/clarify/) · [plan](skills/plan/) · [tasks](skills/tasks/) · [analyze](skills/analyze/) · [decision-challenge](skills/decision-challenge/) · [implement](skills/implement/) · [source-grounded-development](skills/source-grounded-development/) · [verify](skills/verify/) · [review](skills/review/) · [simplify-code](skills/simplify-code/) · [ship](skills/ship/) · [debug](skills/debug/) · [worktrees](skills/worktrees/) · [parallel](skills/parallel/)
 
 ### 💼 Run a business
 
@@ -354,7 +356,7 @@ Three engines + engine-agnostic disciplines. Every engine skill pins the current
 
 ### 🛠️ Ship & operate — devops
 
-[docker](skills/docker/) · [github-actions](skills/github-actions/) · [git-workflow](skills/git-workflow/) · [domains-dns](skills/domains-dns/) · [monitoring](skills/monitoring/) · [email-deliverability](skills/email-deliverability/) · [scaling](skills/scaling/) · [deployment](skills/deployment/)
+[docker](skills/docker/) · [github-actions](skills/github-actions/) · [git-workflow](skills/git-workflow/) · [domains-dns](skills/domains-dns/) · [monitoring](skills/monitoring/) · [email-deliverability](skills/email-deliverability/) · [scaling](skills/scaling/) · [deployment](skills/deployment/) · [deprecation](skills/deprecation/)
 
 ### 🔒 Ship & operate — quality & security
 

package/manifest.json

@@ -1,7 +1,7 @@
 {
-  "version": "1.0.10",
+  "version": "1.0.11",
   "counts": {
-    "skills": 258
+    "skills": 264
   },
   "skills": [
     {
@@ -458,6 +458,29 @@
       ],
       "profiles": []
     },
+    {
+      "id": "bro",
+      "description": "Use whenever the user asks to make an answer or draft sound human, natural, plain-spoken or less AI-written — including a terse bro after the last response. Rewrites or drafts in the same language while preserving meaning, facts and channel. NOT a reusable brand voice (that is `brand-voice`), NOT translation (that is `translation-l10n`).",
+      "tags": [
+        "bro",
+        "human-writing",
+        "humano",
+        "plain-language",
+        "natural-language",
+        "rewrite",
+        "no-jargon"
+      ],
+      "recommends": [
+        "brand-voice",
+        "technical-writing",
+        "translation-l10n"
+      ],
+      "profiles": [
+        "minimal",
+        "core",
+        "full"
+      ]
+    },
     {
       "id": "building-agents",
       "description": "Use when building or restructuring an LLM agent — provider adapter, tool calling, structured output, RAG, agent loop, eval gate, cost routing, tracing, MCP server — model-agnostic across OpenAI/Anthropic/Gemini/OSS so a model swap is a config change. NOT vector-store SQL alone (that is `postgresdb`) or service deployment (that is `deployment`).",
@@ -1168,6 +1191,28 @@
         "full"
       ]
     },
+    {
+      "id": "decision-challenge",
+      "description": "Use when a high-impact plan, migration or architecture claim needs a bounded adversarial challenge before commitment. Isolates claims from persuasion, attacks assumptions, reconciles doubts with evidence and emits proceed/hold/stop. NOT a finished-diff review (`review`/`code-review`), NOT SDD artifact consistency (`analyze`).",
+      "tags": [
+        "adversarial-review",
+        "decision-quality",
+        "assumptions",
+        "risk",
+        "preflight"
+      ],
+      "recommends": [
+        "analyze",
+        "review",
+        "code-review",
+        "decision-records",
+        "security-scan"
+      ],
+      "profiles": [
+        "core",
+        "full"
+      ]
+    },
     {
       "id": "decision-records",
       "description": "Use when a hard-to-reverse choice (database, framework, vendor, auth model) must be frozen as an immutable numbered ADR — the context that forced it, the options weighed, the decision, consequences both ways — or superseded without erasing history. NOT a meeting recap (that is meeting-notes), NOT standing project principles (that is constitution).",
@@ -1232,6 +1277,28 @@
       ],
       "profiles": []
     },
+    {
+      "id": "deprecation",
+      "description": "Use when retiring a public API, feature, integration, service or legacy path without abandoning consumers. Inventories usage, classifies advisory vs compulsory migration, ships compatibility/tooling, assigns owners and gates removal on evidence. NOT live schema expand-contract (`db-migrations`), NOT replacement API design (`api-design`).",
+      "tags": [
+        "deprecation",
+        "migration",
+        "compatibility",
+        "consumer-migration",
+        "removal"
+      ],
+      "recommends": [
+        "api-design",
+        "db-migrations",
+        "deployment",
+        "git-workflow",
+        "monitoring"
+      ],
+      "profiles": [
+        "core",
+        "full"
+      ]
+    },
     {
       "id": "design",
       "description": "Use when designing or refreshing a web UI or landing page — visual concept, type/color/spacing/motion tokens, composition, rescuing a UI that reads AI-generic, or a graded design review. Brand-grounded and research-first; ships Tailwind v4 + Next.js 15 under WCAG 2.2 AA and Core Web Vitals budgets. NOT the words on the page (that is `marketing`), NOT the App Router build (that is `nextjs`).",
@@ -2278,6 +2345,27 @@
       ],
       "profiles": []
     },
+    {
+      "id": "idea-refinement",
+      "description": "Use when a rough product, service, workflow or feature idea needs divergent options and assumption pressure-testing before it becomes a spec. Produces a decision brief with alternatives, evidence gaps, Not Now and a cheap experiment. NOT requirements or acceptance criteria (`specify`), NOT market sizing (`market-research`).",
+      "tags": [
+        "ideation",
+        "idea-refinement",
+        "product-discovery",
+        "assumptions",
+        "decision-brief"
+      ],
+      "recommends": [
+        "specify",
+        "market-research",
+        "competitor-watch",
+        "ab-testing"
+      ],
+      "profiles": [
+        "core",
+        "full"
+      ]
+    },
     {
       "id": "implement",
       "description": "Use when an approved plan and task list exist and it is time to turn them into working, tested code — the SDD phase after `analyze` and before `verify`. Enforces TDD: a failing test comes before the code that makes it pass, one task at a time, appended to a progress ledger that survives compaction. Delegates test tooling to the stack skill and fans disjoint tasks out via `parallel`. NOT spec writing (that is `specify`), NOT planning (that is `plan`), NOT the final lint/test/audit gate (that is `verify`).",
@@ -4346,6 +4434,28 @@
       ],
       "profiles": []
     },
+    {
+      "id": "simplify-code",
+      "description": "Use when correct working code is unnecessarily hard to read, change or verify and needs behaviour-preserving simplification in a bounded scope. Characterizes the observable contract, removes accidental complexity one concept at a time and proves equivalence. NOT fixing a failure (`debug`), NOT read-only diff judgment (`review`/`code-review`).",
+      "tags": [
+        "code-simplification",
+        "refactoring",
+        "readability",
+        "complexity",
+        "behavior-preservation"
+      ],
+      "recommends": [
+        "code-review",
+        "review",
+        "verify",
+        "debug",
+        "performance"
+      ],
+      "profiles": [
+        "core",
+        "full"
+      ]
+    },
     {
       "id": "skill-scout",
       "description": "Use when a specialized skill probably exists but is not loaded, when a task feels harder than it should because generic reasoning is doing a domain skill's job, when the work just delivered was a repeatable procedure worth turning into a skill or an agent, or when auditing coverage for holes. Resolves against what already exists — installed skills, catalog skills and agent files — then names the gap and emits the install command. NOT routing among skills you already have (that is `suggest`), NOT writing the artifact when none exists (that is `author-skill` for skills, `building-agents` for agents).",
@@ -4423,6 +4533,27 @@
       ],
       "profiles": []
     },
+    {
+      "id": "source-grounded-development",
+      "description": "Use when implementation or review depends on current version-specific framework, SDK, protocol or platform behaviour and memory is unsafe. Detects exact local versions, verifies primary sources, tests applicability and marks unknowns. NOT a standalone cited memo (`research-ops`), NOT diagnosis of a reproduced failure (`debug`).",
+      "tags": [
+        "official-docs",
+        "primary-sources",
+        "version-detection",
+        "implementation",
+        "verification"
+      ],
+      "recommends": [
+        "research-ops",
+        "decision-records",
+        "debug",
+        "technical-writing"
+      ],
+      "profiles": [
+        "core",
+        "full"
+      ]
+    },
     {
       "id": "specify",
       "description": "Use when a feature, change, or product idea is still fuzzy and must become an approved WHAT/WHY spec before any planning or code — the brainstorming front door of SDD. Turns a one-line intent into problem, goals, users, scope, behaviour and acceptance criteria, via one-question-at-a-time dialogue and 2-3 approaches with a recommendation, carrying zero implementation detail. Fires whenever someone jumps to HOW before WHAT is agreed, in any language. NOT the technical plan (that is `plan`), NOT the de-risking ambiguity sweep (that is `clarify`), NOT project-wide principles (that is `constitution`).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "validate": "node scripts/build-manifest.js --validate",
     "drift:check": "node scripts/drift-check.js",
     "drift:knowledge": "node scripts/drift-check.js --knowledge",
+    "routing:audit": "node scripts/routing-audit.js",
     "test": "node --test",
     "coverage": "c8 --reporter=text node --test",
     "version": "npm run manifest && git add manifest.json",
@@ -23,8 +24,7 @@
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",
-    "ajv": "^8.18.0",
-    "sql.js": "^1.14.1"
+    "ajv": "^8.18.0"
   },
   "devDependencies": {
     "c8": "^10.1.3"

package/scripts/consult.js

@@ -1,4 +1,4 @@
-import initSqlJs from 'sql.js';
+import { buildTextCorpus, rankText } from './lib/text-rank.js';
 
 // Stopwords (es + en + common EU words) — these match everywhere via LIKE and drown the signal.
 const STOP = new Set([
@@ -43,6 +43,43 @@ const SYNONYMS = {
   presentacion: ['presentations'], 'presentación': ['presentations'], diapositivas: ['slides'],
   curso: ['course', 'teaching'], 'enseñar': ['teaching'], ensenar: ['teaching'],
   marketing: ['marketing'], copy: ['copywriting'], texto: ['copywriting'], textos: ['copywriting'],
+  human: ['bro', 'human-writing', 'natural-language', 'plain-language'],
+  humano: ['bro', 'human-writing', 'natural-language', 'plain-language'],
+  humana: ['bro', 'human-writing', 'natural-language', 'plain-language'],
+  huma: ['bro', 'human-writing', 'natural-language', 'plain-language'],
+  natural: ['bro', 'human-writing', 'natural-language', 'plain-language'],
+  robotico: ['bro', 'human-writing'], robotica: ['bro', 'human-writing'],
+  robotic: ['bro', 'human-writing'], roboticamente: ['bro', 'human-writing'],
+  jerga: ['bro', 'plain-language', 'no-jargon'], jargon: ['bro', 'plain-language', 'no-jargon'],
+  // Cross-cutting workflow vocabulary. These map multilingual/colloquial
+  // wording to the exact compound tags used by the catalog.
+  challenge: ['adversarial-review', 'decision-quality', 'preflight'], challenged: ['adversarial-review'],
+  cuestiona: ['adversarial-review', 'decision-quality', 'preflight'], cuestionar: ['adversarial-review'],
+  'qüestiona': ['adversarial-review', 'decision-quality', 'preflight'],
+  supuestos: ['assumptions', 'adversarial-review'], suposiciones: ['assumptions'],
+  afirmaciones: ['assumptions', 'adversarial-review'], claims: ['assumptions', 'adversarial-review'],
+  stress: ['adversarial-review', 'preflight'],
+  retire: ['deprecation', 'removal', 'consumer-migration'], retired: ['deprecation', 'removal'],
+  deprecated: ['deprecation', 'removal'], deprecada: ['deprecation', 'removal'],
+  retirar: ['deprecation', 'removal'], retirada: ['deprecation', 'removal', 'consumer-migration'],
+  legado: ['deprecation', 'compatibility'], legacy: ['deprecation', 'compatibility'],
+  simplifica: ['code-simplification', 'refactoring', 'readability'],
+  simplificar: ['code-simplification', 'refactoring', 'readability'],
+  simplify: ['code-simplification', 'refactoring', 'readability'],
+  simplified: ['code-simplification', 'readability'], clarity: ['readability', 'complexity'],
+  enginyos: ['readability', 'complexity'], caracterizacion: ['behavior-preservation'],
+  'caracterización': ['behavior-preservation'], caracteritzacio: ['behavior-preservation'],
+  'caracterització': ['behavior-preservation'], wrappers: ['code-simplification'],
+  official: ['official-docs', 'primary-sources'], oficiales: ['official-docs', 'primary-sources'],
+  oficial: ['official-docs', 'primary-sources'], documentacion: ['official-docs'],
+  'documentación': ['official-docs'], fonts: ['primary-sources'], fuentes: ['primary-sources'],
+  sources: ['primary-sources'], lockfile: ['version-detection'],
+  specification: ['primary-sources'], specifications: ['primary-sources'],
+  version: ['version-detection'], versions: ['version-detection'], versioned: ['version-detection'],
+  'versión': ['version-detection'], versio: ['version-detection'], 'versió': ['version-detection'],
+  cite: ['primary-sources'], cited: ['primary-sources'], citations: ['primary-sources'],
+  concepts: ['idea-refinement', 'ideation'], conceptos: ['idea-refinement', 'ideation'],
+  conceptes: ['idea-refinement', 'ideation'], premortem: ['idea-refinement', 'ideation'],
 };
 
 const SKILL_ROUTING_TERMS = ['suggest', 'detect', 'install', 'meta'];
@@ -78,6 +115,7 @@ const SKILL_ROUTING_VERBS = new Set([
 ]);
 
 const MIN_USEFUL_SCORE = 2;
+const LEXICAL_WEIGHT = 100;
 const LOW_SIGNAL_TAG_TERMS = new Set(['web', 'frontend']);
 
 function fold(term) {
@@ -101,7 +139,10 @@ function expandedTerms(query) {
   for (const t of tokens) {
     if (STOP.has(t)) continue;
     set.add(t);
-    for (const syn of SYNONYMS[t] || []) set.add(syn);
+    // Do not read inherited Object.prototype values (for example a query
+    // containing "constructor"). They are functions, not synonym arrays.
+    const synonyms = Object.hasOwn(SYNONYMS, t) ? SYNONYMS[t] : [];
+    for (const syn of synonyms) set.add(syn);
   }
   if (hasSkillNoun && hasSkillRoutingVerb) {
     for (const term of SKILL_ROUTING_TERMS) set.add(term);
@@ -109,48 +150,40 @@ function expandedTerms(query) {
   return [...set];
 }
 
+export async function createRanker(manifest) {
+  const corpus = buildTextCorpus(manifest.skills);
+
+  return {
+    rank(query) {
+      const terms = expandedTerms(query);
+      if (!terms.length) return [];
+      const exact = scoreRows(manifest.skills, terms);
+      const exactById = new Map(exact.map((row) => [row.id, row.score]));
+      // Synonyms feed the statistical ranker as well as the exact scorer. This
+      // preserves Spanish/Catalan intent mapping while TF-IDF handles lexical
+      // variants and description-wide relevance.
+      const lexical = rankText(corpus, `${query} ${terms.join(' ')}`);
+      const lexicalById = new Map(lexical.map((row) => [row.id, row.score]));
+      const maxExact = Math.max(0, ...exact.map((row) => row.score));
+      const maxLexical = lexical[0]?.score || 0;
+      if (maxExact < MIN_USEFUL_SCORE && maxLexical < 0.08) return [];
+
+      const ids = new Set([...exactById.keys(), ...lexicalById.keys()]);
+      return [...ids].map((id) => ({
+        id,
+        score: (exactById.get(id) || 0) + (lexicalById.get(id) || 0) * LEXICAL_WEIGHT,
+      })).sort(byScore);
+    },
+    close() {},
+  };
+}
+
 export async function rank(manifest, query) {
-  const terms = expandedTerms(query);
-  if (!terms.length) return [];
-  const scored = scoreRows(manifest.skills, terms);
-  if (!scored.length || Math.max(...scored.map((r) => r.score)) < MIN_USEFUL_SCORE) return [];
-  const SQL = await initSqlJs();
-  const db = new SQL.Database();
-
-  const rows = manifest.skills.map((sk) => [
-    sk.id,
-    ` ${sk.id} ${sk.description} ${(sk.tags || []).join(' ')} `.toLowerCase(),
-  ]);
-
-  // Prefer FTS5 for fidelity with ECC; fall back to scored whole-word LIKE if
-  // the sql.js wasm build was compiled without the FTS5 module.
+  const ranker = await createRanker(manifest);
   try {
-    db.run('CREATE VIRTUAL TABLE s USING fts5(id, doc);');
-    const stmt = db.prepare('INSERT INTO s (id, doc) VALUES (?, ?)');
-    for (const r of rows) stmt.run(r);
-    stmt.free();
-    const match = terms.map((t) => `"${t}"*`).join(' OR ');
-    const res = db.exec('SELECT id FROM s WHERE s MATCH ? ORDER BY rank', [match]);
-    db.close();
-    if (!res.length) return [];
-    const ids = new Set(res[0].values.map(([id]) => id));
-    return scored.filter((r) => ids.has(r.id)).sort(byScore);
-  } catch {
-    db.run('CREATE TABLE s (id TEXT, doc TEXT);');
-    const stmt = db.prepare('INSERT INTO s (id, doc) VALUES (?, ?)');
-    for (const r of rows) stmt.run(r);
-    stmt.free();
-    // Whole-word match: pad doc with spaces and look for "% term %".
-    const score = terms.map(() => '(doc LIKE ?)').join(' + ');
-    const params = terms.map((t) => `% ${t} %`);
-    const res = db.exec(
-      `SELECT id, (${score}) AS score FROM s WHERE score > 0 ORDER BY score DESC, id`,
-      params,
-    );
-    db.close();
-    if (!res.length) return [];
-    const ids = new Set(res[0].values.map(([id]) => id));
-    return scored.filter((r) => ids.has(r.id)).sort(byScore);
+    return ranker.rank(query);
+  } finally {
+    ranker.close();
   }
 }
 

package/scripts/lib/default-skill-floor.js

@@ -0,0 +1,11 @@
+// Skills every installation path equips, even when the user picks a profile,
+// adds one skill directly, or browses the catalog by hand.
+//
+// `orient` and `suggest` are runtime always-on. `bro` is installed by default
+// but remains conditionally loaded: its description routes human-language asks
+// without paying for its body on unrelated turns.
+export const DEFAULT_SKILL_FLOOR = Object.freeze(['orient', 'suggest', 'bro']);
+
+export function withDefaultSkillFloor(skillIds = []) {
+  return [...new Set([...DEFAULT_SKILL_FLOOR, ...skillIds])];
+}

package/scripts/lib/domains.js

@@ -4,8 +4,8 @@
 // catalog grows deliberately, never silently.
 
 export const DOMAINS = [
-  { title: 'Core & control plane', ids: ['init', 'harness', 'orient', 'suggest', 'author-skill', 'sdd-init'] },
-  { title: 'Spec-Driven Development', ids: ['sdd', 'constitution', 'specify', 'clarify', 'plan', 'tasks', 'analyze', 'implement', 'verify', 'review', 'ship', 'debug', 'worktrees', 'parallel'] },
+  { title: 'Core & control plane', ids: ['init', 'harness', 'orient', 'suggest', 'bro', 'author-skill', 'sdd-init'] },
+  { title: 'Spec-Driven Development', ids: ['sdd', 'constitution', 'idea-refinement', 'specify', 'clarify', 'plan', 'tasks', 'analyze', 'decision-challenge', 'implement', 'source-grounded-development', 'verify', 'review', 'simplify-code', 'ship', 'debug', 'worktrees', 'parallel'] },
   { title: 'Run a business', ids: ['finance-ops', 'invoicing', 'bookkeeping', 'pricing', 'sales-pipeline', 'lead-gen', 'cold-outreach', 'proposals', 'contracts', 'customer-support', 'client-onboarding', 'retention', 'hiring', 'people-ops', 'inventory', 'logistics-ops', 'procurement', 'meeting-notes', 'sop-builder', 'project-ops'] },
   { title: 'Raise & model money', ids: ['pitch-deck', 'investor-materials', 'financial-model', 'fundraising', 'unit-economics', 'grants'] },
   { title: 'Legal, privacy & compliance', ids: ['gdpr-privacy', 'terms-conditions', 'compliance', 'data-policy', 'ip-trademark'] },
@@ -22,7 +22,7 @@ export const DOMAINS = [
   { title: 'Game development', ids: ['godot', 'unity', 'unreal', 'game-design', 'game-storytelling', 'level-design', 'gamedev-shaders', 'gamedev-multiplayer', 'gamedev-physics', 'gamedev-pathing', 'gamedev-shipping'] },
   { title: 'Databases & data layer', ids: ['postgresdb', 'mysql', 'mongodb', 'redis', 'supabase', 'neon', 'planetscale', 'sqlite-turso', 'prisma-orm', 'drizzle-orm', 'firebase', 'dynamodb', 'vector-db', 'clickhouse-analytics', 'duckdb', 'db-migrations', 'backups'] },
   { title: 'Ship & operate — platforms', ids: ['vercel', 'netlify', 'cloudflare', 'railway', 'render', 'fly-io', 'coolify', 'hetzner', 'digitalocean', 'aws-essentials', 'gcp-essentials'] },
-  { title: 'Ship & operate — devops', ids: ['docker', 'github-actions', 'git-workflow', 'domains-dns', 'monitoring', 'email-deliverability', 'scaling', 'deployment'] },
+  { title: 'Ship & operate — devops', ids: ['docker', 'github-actions', 'git-workflow', 'domains-dns', 'monitoring', 'email-deliverability', 'scaling', 'deployment', 'deprecation'] },
   { title: 'Ship & operate — quality & security', ids: ['code-review', 'security-scan', 'secure-coding', 'testing-py', 'testing-web', 'testing-go', 'e2e-testing', 'accessibility', 'performance', 'error-handling', 'observability'] },
   { title: 'Design & content craft', ids: ['design', 'presentations', 'course-storytelling', 'course-builder', 'technical-writing', 'translation-l10n'] },
   { title: 'Knowledge & meta', ids: ['knowledge-ops', 'codebase-onboarding', 'research-ops', 'decision-records', 'continuous-learning', 'skill-scout', 'context-budget', 'roast-me', 'fable-operator'] },

package/scripts/lib/recommend.js

@@ -1,6 +1,7 @@
 import { skillById } from './manifest.js';
 
 const OUTCOMES = {
+  bro: 'Writing that sounds natural and human',
   suggest: 'An assistant that proposes what you need as you go',
   harness: 'A tidy workspace: connect and document your company',
   init: 'Guided project bootstrap',

package/scripts/lib/text-rank.js

@@ -0,0 +1,112 @@
+const STOP = new Set([
+  'a', 'an', 'and', 'any', 'are', 'as', 'at', 'be', 'before', 'by', 'for', 'from',
+  'in', 'into', 'is', 'it', 'its', 'my', 'need', 'needs', 'of', 'on', 'or', 'our',
+  'so', 'that', 'the', 'them', 'this', 'to', 'use', 'want', 'we', 'when', 'with',
+  'you', 'your', 'help', 'me', 'i',
+  'un', 'una', 'unos', 'unas', 'con', 'de', 'del', 'la', 'el', 'los', 'las',
+  'para', 'que', 'porque', 'en', 'mi', 'mis', 'quiero', 'hacer', 'como',
+  'amb', 'aquest', 'aquesta', 'els', 'les', 'per', 'vull', 'vols',
+]);
+
+function fold(text) {
+  return text.normalize('NFD').replace(/\p{M}/gu, '');
+}
+
+function stem(token) {
+  // Deliberately light: enough to join "simplify/simplified" and
+  // "conflicts/conflict" without pretending to be a language model.
+  for (const suffix of ['ally', 'ing', 'ed', 'es', 'al']) {
+    if (token.length > suffix.length + 3 && token.endsWith(suffix)) {
+      token = token.slice(0, -suffix.length);
+      break;
+    }
+  }
+  if (token.length > 3 && token.endsWith('s') && !token.endsWith('ss')) token = token.slice(0, -1);
+  if (token.length > 4 && token.endsWith('e')) token = token.slice(0, -1);
+  if (
+    token.length > 4
+    && token[token.length - 1] === token[token.length - 2]
+    && !'aeiou'.includes(token[token.length - 1])
+  ) token = token.slice(0, -1);
+  if (token.length > 3 && token.endsWith('y')) token = `${token.slice(0, -1)}i`;
+  return token;
+}
+
+export function tokenize(text) {
+  return fold(text.toLowerCase())
+    .replace(/[^\p{L}\p{N}\s-]/gu, ' ')
+    .split(/[\s-]+/)
+    .filter((token) => token.length > 2 && !STOP.has(token))
+    .map(stem);
+}
+
+function frequencies(tokens) {
+  const result = new Map();
+  for (const token of tokens) result.set(token, (result.get(token) || 0) + 1);
+  return result;
+}
+
+function vector(frequency, idf) {
+  const result = new Map();
+  for (const [term, count] of frequency) result.set(term, count * idf(term));
+  return result;
+}
+
+export function cosine(left, right) {
+  let dot = 0;
+  let leftNorm = 0;
+  let rightNorm = 0;
+  for (const [term, weight] of left) {
+    leftNorm += weight * weight;
+    const other = right.get(term);
+    if (other) dot += weight * other;
+  }
+  for (const weight of right.values()) rightNorm += weight * weight;
+  if (!leftNorm || !rightNorm) return 0;
+  return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
+}
+
+export function buildTextCorpus(skills) {
+  const frequenciesById = new Map();
+  for (const skill of skills) {
+    const idTokens = tokenize(skill.id.replace(/-/g, ' '));
+    const tagTokens = tokenize((skill.tags || []).join(' '));
+    frequenciesById.set(skill.id, frequencies([
+      ...idTokens, ...idTokens, ...idTokens,
+      ...tagTokens, ...tagTokens,
+      ...tokenize(skill.description),
+    ]));
+  }
+
+  const documentFrequency = new Map();
+  for (const terms of frequenciesById.values()) {
+    for (const term of terms.keys()) {
+      documentFrequency.set(term, (documentFrequency.get(term) || 0) + 1);
+    }
+  }
+  const size = frequenciesById.size;
+  const idf = (term) => Math.log(1 + size / (1 + (documentFrequency.get(term) || 0)));
+  const vectors = new Map();
+  for (const [id, terms] of frequenciesById) vectors.set(id, vector(terms, idf));
+  return { idf, vectors };
+}
+
+export function rankText(corpus, prompt) {
+  const query = vector(frequencies(tokenize(prompt)), corpus.idf);
+  return [...corpus.vectors]
+    .map(([id, skillVector]) => ({ id, score: cosine(query, skillVector) }))
+    .filter((row) => row.score > 0)
+    .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}
+
+export function descriptionCollisions(corpus, minimum = 0.5) {
+  const rows = [...corpus.vectors];
+  const collisions = [];
+  for (let left = 0; left < rows.length; left += 1) {
+    for (let right = left + 1; right < rows.length; right += 1) {
+      const score = cosine(rows[left][1], rows[right][1]);
+      if (score >= minimum) collisions.push({ left: rows[left][0], right: rows[right][0], score });
+    }
+  }
+  return collisions.sort((a, b) => b.score - a.score || a.left.localeCompare(b.left));
+}

package/scripts/lib/ui.js

@@ -92,11 +92,11 @@ function frame(phase, cols, sparks, white) {
 }
 
 // Animated ASCII wordmark — the exaggerated "WOW". Static plain text when not a TTY.
-export async function banner() {
+export async function banner(skillCount = 'all') {
   if (!stdout.isTTY) {
     say('');
     for (const l of ART) say(l);
-    say('  231 skills · one CLI · zero bloat');
+    say(`  ${skillCount} skills · one CLI · zero bloat`);
     return;
   }
   const rows = ART.length;
@@ -133,7 +133,7 @@ export async function banner() {
   // settle on a final rainbow snapshot
   stdout.write(`\x1b[${rows}A`);
   stdout.write(frame(15, W));
-  say(C.dim('  231 skills · one CLI · zero bloat'));
+  say(C.dim(`  ${skillCount} skills · one CLI · zero bloat`));
   stdout.write('\x1b[?25h'); // show cursor
 }