skilldrop-cli 0.8.1 → 0.8.2

package/README.md

@@ -3,9 +3,9 @@
 [![npm](https://img.shields.io/npm/v/skilldrop-cli)](https://www.npmjs.com/package/skilldrop-cli)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 49 skills, filterable by pack, tag, and model tier.
+**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 50 skills, filterable by pack, tag, and model tier.
 
-**49 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, **Codex**, **GitHub Copilot**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:
+**50 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, **Codex**, **GitHub Copilot**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:
 
 ```bash
 npx skilldrop-cli install --pack product-manager     # or: solution-architect, dev-team,
@@ -264,6 +264,17 @@ npx skilldrop-cli list | skilldrop info <skill> | skilldrop packs | skilldrop un
 
 `--with-related` also pulls each skill's companions. From a clone (or before the package is published): `node bin/skilldrop.js <same args>`. Scope and design: [RFC-0002](docs/rfcs/0002-skilldrop-cli.md), full command surface in [`docs/designs/skilldrop-cli-design.md`](docs/designs/skilldrop-cli-design.md).
 
+### Or: the Claude Code plugin marketplace
+
+skilldrop is also a **Claude Code plugin marketplace** — install the whole catalogue as one plugin, no npm step:
+
+```text
+/plugin marketplace add sananthanarayan/skilldrop
+/plugin install skilldrop@skilldrop
+```
+
+Every skill then invokes as `/skilldrop:<name>` (e.g. `/skilldrop:prfaq`), and the reviewer subagents come with it. The marketplace ships the flat `skills/` and `agents/` trees at the repo root unchanged — same copy-install premise, expressed in Claude's own plugin format. `.claude-plugin/{marketplace,plugin}.json` are generated from `package.json` by [`build_marketplace.py`](build_marketplace.py) (`--check` guards drift in CI). Use the CLI above when you want per-pack or per-skill granularity, another IDE, or hooks; use the marketplace when you're in Claude Code and want everything in two lines. Rationale and the deferred per-pack-plugin step: [RFC-0014](docs/rfcs/0014-agentbundle-interop.md).
+
 ### Hooks (opt-in) — wire a skill to an event
 
 Some loop-shaped skills declare **hooks** — event-triggered nudges the CLI wires into your environment when you pass `--with-hooks` ([RFC-0006](docs/rfcs/0006-per-ide-hooks.md)). It's off by default, so a plain install never touches your git repo or editor settings.
@@ -315,6 +326,13 @@ npx skilldrop-cli install --pack starter --from ../local-catalog
 npx skilldrop-cli update      # updates bundled and third-party skills side by side — the ledger remembers each skill's source
 ```
 
+The CLI also reads **agentbundle-shaped catalogs** ([agent-ready-repo](https://github.com/eugenelim/agent-ready-repo)) — `packs/<pack>/.apm/skills/<name>/SKILL.md` with a `pack.toml` per pack — so you can install *its* packs through the same command ([RFC-0014](docs/rfcs/0014-agentbundle-interop.md)). Both shapes share the agentskills.io `SKILL.md`, so the reader just maps his packs onto the accessors above:
+
+```bash
+npx skilldrop-cli packs --from https://github.com/eugenelim/agent-ready-repo
+npx skilldrop-cli install --pack contracts --from https://github.com/eugenelim/agent-ready-repo --dest .agents/skills
+```
+
 Safety model: installs **copy files only — nothing from a catalog is ever executed**; every skill passes a structural check before copying (broken folders are refused with reasons); and third-party installs print a review-before-use warning, because skills are instructions your AI agent will follow — read a stranger's `SKILL.md` before letting your agent obey it.
 
 **Authoring a catalog:** mirror the layout above, then check it with `npx skilldrop-cli validate --from <your-repo-or-path>` before publishing. `related`, `packs.json`, and `requirements.txt` all work in third-party catalogs exactly as they do here.

package/bin/skilldrop.js

@@ -3,8 +3,10 @@
  * or any directory, from the bundled catalog or any third-party catalog
  * (--from <path | git-url[#ref]>). Zero dependencies; copy-only, never executes
  * catalog content at install time.
+ * Reads two catalog shapes: skilldrop (flat skills/) and agentbundle (packs/<p>/.apm/skills).
  * Design: skilldrop-cli-design/skilldrop-cli-design.md
- * Scope:  docs/rfcs/0002-skilldrop-cli.md, docs/rfcs/0003-third-party-catalogs.md
+ * Scope:  docs/rfcs/0002-skilldrop-cli.md, docs/rfcs/0003-third-party-catalogs.md,
+ *         docs/rfcs/0014-agentbundle-interop.md (the agentbundle reader)
  */
 "use strict";
 const fs = require("fs");
@@ -37,8 +39,9 @@ Usage:
 
 Catalogs:
   (default)          the catalog bundled with this package
-  --from <dir>       any local directory shaped like skills/<name>/{SKILL.md,manifest.json}
-  --from <git-url>   any git repo with that shape; append #<branch-or-tag> to pin
+  --from <dir|url>   a skilldrop catalog (skills/<name>/{SKILL.md,manifest.json}) OR an
+                     agentbundle one (packs/<pack>/.apm/skills/<name>/SKILL.md); a git URL
+                     works for either — append #<branch-or-tag> to pin
 
 Install/update/uninstall targets (pick one):
   (default)          ~/.claude/skills           Claude Code, user scope
@@ -78,7 +81,16 @@ function parseArgs(argv) {
   return out;
 }
 
-/* ---------- catalogs ---------- */
+/* ---------- catalogs ----------
+   Two on-disk shapes are read (RFC-0003, RFC-0014):
+     "skilldrop" — flat skills/<name>/{SKILL.md,manifest.json} + optional packs.json
+     "apm"       — agentbundle (agent-ready-repo): packs/<pack>/{pack.toml,
+                   .apm/skills/<name>/SKILL.md, .apm/agents/<name>.md}
+   The apm reader normalizes into the same accessors the native path uses — skills keyed by
+   folder name, a per-skill manifest synthesized from the SKILL.md frontmatter + the pack.toml
+   version, each pack.toml's [pack] table a virtual pack — so `--from git+https://…/agent-ready-repo`
+   installs his packs through this same CLI. Skill accessors: skillsIn / skillDir / skillExists /
+   manifestOf; never touch cat.skillsDir directly (it exists only on the skilldrop shape). */
 
 const catalogCache = {};
 function resolveCatalog(source) {
@@ -96,23 +108,101 @@ function resolveCatalog(source) {
       die(`could not fetch catalog '${source}' — not a local path, and git clone failed`);
     }
   }
-  const skillsDir = path.join(dir, "skills");
-  if (!fs.existsSync(skillsDir)) die(`'${source || dir}' is not a skilldrop catalog — no skills/ directory`);
-  return (catalogCache[key] = { dir, skillsDir, source: source || BUNDLED });
+  const src = source || BUNDLED;
+  if (fs.existsSync(path.join(dir, "skills")))
+    return (catalogCache[key] = { dir, source: src, shape: "skilldrop", skillsDir: path.join(dir, "skills") });
+  if (fs.existsSync(path.join(dir, "packs")))
+    return (catalogCache[key] = readApmCatalog(dir, src));
+  die(`'${src}' is not a catalog — expected a skills/ (skilldrop) or packs/ (agentbundle) directory`);
+}
+
+/* Minimal TOML read — the [pack] table's basic-string scalars (name, version, description).
+   pack.toml is small and regular; a full TOML parser would be dead weight in a zero-dep CLI. */
+function packMeta(tomlText) {
+  const out = {};
+  let inPack = false;
+  for (const raw of tomlText.split(/\r?\n/)) {
+    const t = raw.trim();
+    if (t.startsWith("[")) { inPack = t === "[pack]"; continue; }
+    if (!inPack || !t || t.startsWith("#")) continue;
+    const m = t.match(/^([A-Za-z0-9_.-]+)\s*=\s*"((?:[^"\\]|\\.)*)"/);
+    if (m) out[m[1]] = m[2].replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+  }
+  return out;
+}
+
+/* SKILL.md frontmatter (agentskills.io: name optional, description carries the trigger). */
+function frontmatter(mdPath) {
+  let fm = "";
+  try { fm = fs.readFileSync(mdPath, "utf8").split("---")[1] || ""; } catch (e) { return {}; }
+  const get = (k) => { const m = fm.match(new RegExp("^" + k + ":\\s*(.+)$", "m")); return m ? m[1].trim() : ""; };
+  return { name: get("name"), description: get("description") };
+}
+
+/* Read an agentbundle catalog into the native accessor shape. First-wins on a skill name
+   (skilldrop's own generated catalogue duplicates a multi-pack skill into each pack — the
+   flat skill list dedups, while packsData still lists it under every pack it belongs to). */
+function readApmCatalog(dir, source) {
+  const packsDir = path.join(dir, "packs");
+  const skillIndex = {}, agentIndex = {}, packsData = {};
+  for (const pack of fs.readdirSync(packsDir)) {
+    const pdir = path.join(packsDir, pack);
+    if (!fs.statSync(pdir).isDirectory()) continue;
+    const ptoml = path.join(pdir, "pack.toml");
+    const pm = fs.existsSync(ptoml) ? packMeta(fs.readFileSync(ptoml, "utf8")) : {};
+    const version = pm.version || "0.0.0";
+    const skills = [];
+    const skillsRoot = path.join(pdir, ".apm", "skills");
+    if (fs.existsSync(skillsRoot))
+      for (const s of fs.readdirSync(skillsRoot)) {
+        const sdir = path.join(skillsRoot, s);
+        if (!fs.statSync(sdir).isDirectory()) continue;
+        skills.push(s);
+        if (!skillIndex[s])
+          skillIndex[s] = { dir: sdir, manifest: {
+            name: s, description: frontmatter(path.join(sdir, "SKILL.md")).description || "",
+            version, related: [], tags: [],
+            deps: { pip: [], npm: [] }, env: { required: [], optional: [] },
+          } };
+      }
+    const agentsRoot = path.join(pdir, ".apm", "agents");
+    if (fs.existsSync(agentsRoot))
+      for (const f of fs.readdirSync(agentsRoot))
+        if (f.endsWith(".md") && f !== "README.md") agentIndex[f.slice(0, -3)] = path.join(agentsRoot, f);
+    packsData[pack] = { description: pm.description || "", skills };
+  }
+  return { dir, source, shape: "apm", skillIndex, agentIndex, packsData };
 }
+
 function skillsIn(cat) {
+  if (cat.shape === "apm") return Object.keys(cat.skillIndex).sort();
   return fs.readdirSync(cat.skillsDir).filter((d) => fs.statSync(path.join(cat.skillsDir, d)).isDirectory()).sort();
 }
-function manifestOf(cat, s) { return readJSON(path.join(cat.skillsDir, s, "manifest.json")); }
+function skillDir(cat, s) {
+  if (cat.shape === "apm") return cat.skillIndex[s] && cat.skillIndex[s].dir;
+  return path.join(cat.skillsDir, s);
+}
+function skillExists(cat, s) { const d = skillDir(cat, s); return !!d && fs.existsSync(d); }
+function manifestOf(cat, s) {
+  if (cat.shape === "apm") {
+    if (!cat.skillIndex[s]) throw new Error(`no such skill '${s}'`);
+    return cat.skillIndex[s].manifest;
+  }
+  return readJSON(path.join(cat.skillsDir, s, "manifest.json"));
+}
 
 /* Agents (RFC-0012): single markdown files, frontmatter is already Claude Code's format.
-   Optional in a catalog — a third-party catalog with no agents/ is still valid. */
+   Optional in a catalog — a third-party catalog with no agents is still valid. */
 function agentsIn(cat) {
+  if (cat.shape === "apm") return Object.keys(cat.agentIndex).sort();
   const d = path.join(cat.dir, "agents");
   if (!fs.existsSync(d)) return [];
   return fs.readdirSync(d).filter((f) => f.endsWith(".md") && f !== "README.md").map((f) => f.slice(0, -3)).sort();
 }
-function agentPath(cat, a) { return path.join(cat.dir, "agents", `${a}.md`); }
+function agentPath(cat, a) {
+  if (cat.shape === "apm") return cat.agentIndex[a];
+  return path.join(cat.dir, "agents", `${a}.md`);
+}
 function agentMeta(cat, a) {
   const fm = (fs.readFileSync(agentPath(cat, a), "utf8").split("---")[1] || "");
   const get = (k) => { const m = fm.match(new RegExp("^" + k + ":\\s*(.+)$", "m")); return m ? m[1].trim() : ""; };
@@ -122,13 +212,15 @@ function agentMeta(cat, a) {
 /* Same gate the skills get, applied to agents before anything is copied. */
 function checkAgent(cat, a) {
   const problems = [];
-  if (!fs.existsSync(agentPath(cat, a))) return [`agents/${a}.md missing`];
+  const p = agentPath(cat, a);
+  if (!p || !fs.existsSync(p)) return [`agent '${a}' missing`];
   const m = agentMeta(cat, a);
   if (m.name !== a) problems.push(`frontmatter name '${m.name}' != filename '${a}'`);
   if (!m.description) problems.push("frontmatter missing description");
   return problems;
 }
 function packsOf(cat) {
+  if (cat.shape === "apm") return Object.keys(cat.packsData).length ? cat.packsData : null;
   const p = path.join(cat.dir, "packs.json");
   return fs.existsSync(p) ? readJSON(p).packs : null;
 }
@@ -136,8 +228,14 @@ function packsOf(cat) {
 /* Structural gate (RFC-0003): a skill must pass before it is copied anywhere. */
 function checkSkill(cat, s) {
   const problems = [];
-  const dir = path.join(cat.skillsDir, s);
-  if (!fs.existsSync(path.join(dir, "SKILL.md"))) problems.push("SKILL.md missing");
+  const dir = skillDir(cat, s);
+  if (!dir || !fs.existsSync(path.join(dir, "SKILL.md"))) problems.push("SKILL.md missing");
+  if (cat.shape === "apm") {
+    // agentbundle skills carry name/description in SKILL.md frontmatter (agentskills.io);
+    // version lives in pack.toml and there is no model tier — gate only the portable fields.
+    if (!problems.length && !manifestOf(cat, s).description) problems.push("SKILL.md frontmatter missing description");
+    return problems;
+  }
   let m = null;
   try { m = manifestOf(cat, s); } catch (e) { problems.push("manifest.json missing or invalid JSON"); }
   if (m) {
@@ -456,13 +554,13 @@ function expandNames(args, cat) {
     return p.skills.slice();
   }
   if (!args._.length) die("nothing to install — pass skill names, --pack <name>, or --all");
-  for (const s of args._) if (!fs.existsSync(path.join(cat.skillsDir, s))) die(`unknown skill '${s}' in catalog '${cat.source}'`);
+  for (const s of args._) if (!skillExists(cat, s)) die(`unknown skill '${s}' in catalog '${cat.source}'`);
   return args._.slice();
 }
 
 function copyOne(cat, s, dest, ide, l, notes) {
   const m = manifestOf(cat, s);
-  fs.cpSync(path.join(cat.skillsDir, s), path.join(dest, s), { recursive: true });
+  fs.cpSync(skillDir(cat, s), path.join(dest, s), { recursive: true });
   const note = writeWiring(ide, dest, s, m.description);
   if (note && notes) notes.push(note);
   l.data[s] = { version: m.version, source: cat.source };
@@ -478,7 +576,7 @@ function install(args) {
     for (const s of names.slice()) {
       let related = [];
       try { related = manifestOf(cat, s).related || []; } catch (e) { /* gated below */ }
-      for (const r of related) if (!seen.has(r) && fs.existsSync(path.join(cat.skillsDir, r))) { seen.add(r); names.push(r); }
+      for (const r of related) if (!seen.has(r) && skillExists(cat, r)) { seen.add(r); names.push(r); }
     }
   }
   gate(cat, names);
@@ -488,7 +586,7 @@ function install(args) {
   const pipDeps = [], suggestions = new Set(), notes = [];
   for (const s of names) {
     const m = copyOne(cat, s, dest, ide, l, notes);
-    if (fs.existsSync(path.join(cat.skillsDir, s, "requirements.txt"))) pipDeps.push(s);
+    if (fs.existsSync(path.join(skillDir(cat, s), "requirements.txt"))) pipDeps.push(s);
     for (const r of m.related || []) if (!names.includes(r) && !l.data[r]) suggestions.add(r);
     console.log(`installed ${s}@${m.version} -> ${dest}`);
   }
@@ -525,7 +623,7 @@ function installedRows(flags) {
     let current = null, cat = null;
     try {
       cat = resolveCatalog(src === BUNDLED ? undefined : src);
-      if (fs.existsSync(path.join(cat.skillsDir, s))) current = manifestOf(cat, s).version;
+      if (skillExists(cat, s)) current = manifestOf(cat, s).version;
     } catch (e) { /* unreachable source: current stays null */ }
     return { s, src, cat, installed: lver(l.data[s]), current };
   });
@@ -651,15 +749,15 @@ function list(args) {
 function info(args) {
   const cat = resolveCatalog(args.flags.from);
   const s = args._[0] || die("pass a skill name");
-  if (!fs.existsSync(path.join(cat.skillsDir, s))) die(`unknown skill '${s}' in catalog '${cat.source}'`);
+  if (!skillExists(cat, s)) die(`unknown skill '${s}' in catalog '${cat.source}'`);
   const m = manifestOf(cat, s);
   const ps = packsOf(cat) || {};
   const inPacks = Object.entries(ps).filter(([, p]) => p.skills.includes(s)).map(([n]) => n);
-  console.log(`${m.name}@${m.version}  (tier: ${m.model && m.model.tier})\n\n${m.description}\n`);
+  console.log(`${m.name}@${m.version}  (tier: ${(m.model && m.model.tier) || "n/a"})\n\n${m.description}\n`);
   console.log(`catalog: ${cat.source}`);
   console.log(`packs:   ${inPacks.join(", ") || "-"}`);
   console.log(`related: ${(m.related || []).join(", ") || "-"}`);
-  if (((m.deps || {}).pip || []).length || fs.existsSync(path.join(cat.skillsDir, s, "requirements.txt")))
+  if (((m.deps || {}).pip || []).length || fs.existsSync(path.join(skillDir(cat, s), "requirements.txt")))
     console.log("deps:    python (requirements.txt)");
   if (((m.env || {}).required || []).length) console.log(`env:     ${m.env.required.join(", ")} (required)`);
 }

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship \u2014 diagrams, ADRs, PRDs, runbooks, decks, reviews \u2014 installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
+  "author": {
+    "name": "Sanjay Ananthanarayan",
+    "url": "https://github.com/sananthanarayan"
+  },
   "bin": {
     "skilldrop": "bin/skilldrop.js"
   },

package/skills/business-case/examples/build-vs-buy-flags.md

@@ -0,0 +1,42 @@
+# Worked example — build vs. buy a feature-flag system
+
+Input → output oracle for `business-case`. Shows the ask first (< 40 words), Option 0
+costed, benefits as re-runnable calculations with confidence tags, all three cost
+layers, ranges, the flip-assumption, and a singular recommendation that states the
+runner-up's best argument fairly.
+
+## Input
+
+> "Should [Acme] build an in-house feature-flag system or buy a SaaS one? ~30
+> engineers, currently gating releases with config files and redeploys."
+
+## Output
+
+### The ask
+**Buy the SaaS feature-flag service (~$18–30k/yr).** It pays back in < 3 months against ~$140k of first-year build cost and recurring toil, and frees roadmap capacity now. Decision needed before next quarter's release-velocity commitments.
+
+### Options (Option 0 is costed)
+
+| Option | Build (one-time) | Run (yr 1) | Opportunity cost |
+|---|--:|--:|--:|
+| **0 — Status quo** (config + redeploy) | $0 | ~$60–90k/yr toil | Slow releases → est. 1–2 delayed launches/yr |
+| **1 — Build in-house** | ~$110–160k | ~$25–40k/yr (on-call, maint.) | 2 eng × 3–4 mo off roadmap |
+| **2 — Buy SaaS** | ~$5k (integrate) | ~$18–30k/yr license | ~1 eng-week integration |
+
+### Benefits (re-runnable calculations, sourced, confidence-tagged)
+
+- **Toil removed vs. Option 0:** each gated release currently costs ~1 eng-hr of redeploy coordination × ~15 releases/mo × $120 loaded/hr = **~$22k/yr** recovered. *(confidence: medium — release count from deploy logs; hourly is loaded-cost estimate.)*
+- **Incident reduction:** flag-based instant rollback vs. redeploy shortens mean remediation from ~40 min to ~5 min; at ~6 rollback-worthy incidents/yr that's ~3.5 hrs × team = **~$8–15k/yr** avoided. *(confidence: low — incident count is small-sample; range reflects it.)*
+- **Release velocity:** decoupling deploy from release plausibly removes 1–2 launch slips/yr; value is real but **not costed here** (depends on launch revenue) — flagged for the decision owner.
+
+Totals are ranges; the **lower end is likelier** for the hard-dollar items (toil is the solid number; incident/velocity are directional).
+
+### The flip-assumption
+The case flips to **Build** only if **flag evaluation must run in a data plane the SaaS can't reach** (e.g. strict data-residency or sub-ms in-process evaluation at scale). Confidence that this *doesn't* apply is medium. **De-risking step before committing to Buy:** a 1-week spike confirming the SaaS SDK meets latency + residency requirements — cheap insurance against the one assumption that would reverse the decision.
+
+### Recommendation
+**Buy (Option 2).** Lowest first-year cost, fastest payback, and it returns ~2 engineers to the roadmap that Build would consume. **The runner-up's best argument, stated fairly:** Build is genuinely better *if* flag evaluation becomes a core differentiator or a hard data-residency constraint emerges — in that world the SaaS boundary bites and owning the system is worth the cost. The spike above is what tells us which world we're in.
+
+## Why this passes the quality bar
+
+The ask leads in under 40 words; Option 0 is present and costed; every benefit is a calculation with sourced inputs and a confidence tag; outputs are ranges naming the likelier end; all three cost layers appear per option; the flip-assumption is identified with a de-risking step; and the recommendation is singular while stating the runner-up's strongest case honestly.

package/skills/council-review/SKILL.md

@@ -33,7 +33,7 @@ Five **standing seats** — each a distinct mandate with a lane it stays in. Rea
 | ⚖️ **Pragmatist** | Is this the simplest thing that works? Over-engineered? Do we even need it? | [`seats/pragmatist.md`](seats/pragmatist.md) |
 | 👤 **User-Advocate** | Is it correct for the people who use it? Edge cases, errors, contracts, compat? | [`seats/user-advocate.md`](seats/user-advocate.md) |
 
-Plus a **bench** of optional seats (Performance, Cost/FinOps, Data & Migration, Accessibility, Compliance) — seat them only when the change warrants. See [`seats/bench.md`](seats/bench.md).
+Plus a **bench** of optional seats (Performance, Cost/FinOps, Data & Migration, Accessibility, Compliance) — seat them only when the change warrants. See [`seats/bench.md`](seats/bench.md). Chairing and roster-choice guidance that doesn't fit here lives in [`reference.md`](reference.md).
 
 The **Chair** is not a sixth opinion. The Chair facilitates, finds the cruxes, and decides.
 

package/skills/devils-advocate/examples/rate-limiter-review.md

@@ -0,0 +1,46 @@
+# Worked example — adversarial review of a just-written rate limiter
+
+Input → output oracle for `devils-advocate`. Shows the four-lens sweep producing
+severity-calibrated findings with `file:line` evidence and paste-able fixes — not a
+generic "looks good, consider tests" pass.
+
+## Input (the "done" implementation)
+
+> "Implemented the per-user rate limiter, tests pass, ready for review."
+
+```python
+# ratelimit.py
+_buckets: dict[str, tuple[float, float]] = {}   # user_id -> (tokens, last_refill)
+
+def allow(user_id: str, rate: float, burst: float) -> bool:
+    now = time.time()
+    tokens, last = _buckets.get(user_id, (burst, now))
+    tokens = min(burst, tokens + (now - last) * rate)
+    if tokens >= 1:
+        _buckets[user_id] = (tokens - 1, now)
+        return True
+    _buckets[user_id] = (tokens, now)
+    return False
+```
+
+## Output (the review)
+
+**Verdict: not ready — 1 blocker, 1 major.** Four lenses swept; happy path is fine, the concurrency and growth paths are not.
+
+🟥 **Blocker — race on the shared dict (assumptions lens).** `ratelimit.py:6-11` reads then writes `_buckets[user_id]` with no lock. Two concurrent requests for the same user both read `tokens=1.0`, both pass, both write back `0.0` — the limiter leaks one token per race, so a burst of N parallel requests admits ~2× the intended rate. The "tests pass" because they're single-threaded. *Fix:* guard the read-modify-write with a per-user lock, or move to an atomic backend (Redis `INCR`+TTL). A dict-of-locks keyed by `user_id` is the minimal change.
+
+🟧 **Major — unbounded memory growth (edge-case lens).** `_buckets` never evicts (`:1`). Every distinct `user_id` ever seen stays forever; a service facing the open internet (or spoofable user ids) OOMs over time. *Fix:* cap with an LRU (`functools.lru_cache` won't fit the mutable value — use `cachetools.TTLCache(maxsize=…, ttl=…)`), evicting idle buckets.
+
+🟨 **Minor — first call gets a free full burst (edge-case lens).** A never-seen `user_id` starts at `(burst, now)` (`:6`), so a brand-new user can immediately spend the whole burst. If the intent is "warm up", seed at `min(burst, rate*window)` instead — flag for product, don't silently change.
+
+⚪ **Nit — `rate`/`burst` unvalidated (staff-engineer lens).** `rate<=0` freezes every user out; `burst<1` makes `allow` always false. Assert `rate>0 and burst>=1` at the boundary.
+
+**Test-coverage gaps (the "tests pass" were happy-path only):**
+- Concurrency: two threads hammering one `user_id` must not exceed `burst + rate*elapsed` admits.
+- Refill: after exhausting tokens, `allow` returns True again only after `1/rate` seconds.
+- Eviction: memory stays bounded under 10k distinct ids.
+- Boundary: `tokens` sitting at exactly `1.0` admits; at `0.999…` denies.
+
+## Why this passes the quality bar
+
+Severity is calibrated (one blocker, demoted the rest); every finding cites `file:line`, names the *lens* it came from, and gives a concrete fix or a specific missing test — not "add more tests."

package/skills/doc-critique/examples/design-doc-critique.md

@@ -0,0 +1,34 @@
+# Worked example — critique of a design-doc excerpt
+
+Input → output oracle for `doc-critique`. Shows local, doc-quoting findings with
+paste-able fixes — reviewing whether the doc *made its case*, not re-debating the topic.
+
+## Input (excerpt of a design doc under review)
+
+> ## TL;DR
+> We will build an innovative, scalable notification service to leverage our
+> existing infrastructure and deliver best-in-class user engagement.
+>
+> ## Approach
+> The service consumes events and sends notifications. It will be highly
+> available and performant. We considered several options and chose a
+> queue-based design because it is the industry standard.
+>
+> ## Rollout
+> We will roll it out to all users.
+
+## Output (the critique)
+
+**Verdict: not ready to circulate — 1 blocker, 2 major, 1 minor.** The doc asserts conclusions it never earns; a reader can't tell what's being built or why this shape.
+
+🟥 **Blocker — the decision has no rationale (§ Approach).** Quoted: *"chose a queue-based design because it is the industry standard."* "Industry standard" is not a reason; it hides the actual tradeoff. *Fix:* replace with the decision's real driver — e.g. "chose a queue so a downstream outage buffers events instead of dropping them; the alternative (synchronous fan-out) loses notifications when a provider is down." Name the alternative and why it lost.
+
+🟧 **Major — TL;DR is adjectives, not content (§ TL;DR).** Quoted: *"innovative, scalable … leverage … best-in-class user engagement."* Five value-words, zero facts — a reader learns nothing about scope. *Fix:* state what it does and the one number that matters: "A queue-backed service that delivers email/push notifications from domain events, targeting < 5s p95 delivery for 1M events/day."
+
+🟧 **Major — unfalsifiable quality claims (§ Approach).** Quoted: *"highly available and performant."* No SLO, so nothing can be reviewed or later checked. *Fix:* commit numbers — availability target (e.g. 99.9%), p95 latency, throughput — or move them to an explicit "Open questions" list if unknown.
+
+🟨 **Minor — rollout has no stages or guardrail (§ Rollout).** Quoted: *"roll it out to all users."* No canary, no rollback trigger. *Fix:* a 2–3 line staged plan (1% → 10% → 100%) and the metric that halts it (delivery-failure rate > X%).
+
+## Why this passes the quality bar
+
+Severity is calibrated (one blocker). Every finding is **local** and **quotes the doc verbatim** (the audit trail that it was actually read), the fixes are paste-able, and it critiques the *doc's* case-making — it does not re-argue whether a queue is the right architecture.

package/skills/strategy-analysis/examples/market-entry-tows.md

@@ -0,0 +1,42 @@
+# Worked example — SWOT arriving as TOWS for a market-entry decision
+
+Input → output oracle for `strategy-analysis`. Shows the framework justified in one
+line, evidenced/consequential cells, the mandatory SWOT→TOWS crossings, ranked
+action-shaped implications tied to the decision, and a verdict that takes a side.
+
+## Input
+
+> "Should [Acme], a mid-market B2B analytics vendor, enter the SMB self-serve
+> segment next year? Decision owner wants a go / no-go with conditions."
+
+## Framework fit (one line)
+
+**SWOT→TOWS**, not Five Forces: the question is about *our* fit to a new segment (internal capabilities vs. external openings), not the structural attractiveness of the industry.
+
+## SWOT (every cell specific · evidenced · consequential)
+
+| | Helpful | Harmful |
+|---|---|---|
+| **Internal** | **S1** Self-serve onboarding already built for mid-market trials (evidence: 40% of trials activate with zero sales touch) → *marginal cost to serve SMB is low.* | **W1** Pricing starts at $2k/mo (evidence: current floor plan) → *5–10× above SMB willingness-to-pay; no viable entry SKU.* |
+| **External** | **O1** No incumbent owns SMB self-serve analytics in this niche (evidence: top 3 competitors are all sales-led, $10k+ ACV) → *an unserved segment with a wedge.* | **T1** Two horizontal BI tools added SMB free tiers this year (evidence: their changelogs) → *the window is closing; a free tier resets price expectations.* |
+
+## TOWS crossings (the strategy — inventory becomes moves)
+
+- **S1 × O1 (invest):** Package the existing zero-touch onboarding as a low-price self-serve SKU to claim the unserved niche before it's contested.
+- **W1 × T1 (defend/decide):** The $2k floor collides head-on with free tiers — a new SMB SKU is a *prerequisite*, not an option; without it, don't enter.
+- **S1 × T1 (hedge):** Low cost-to-serve means an SMB tier can be near-free to run, so a defensive free/low tier is affordable if a competitor forces it.
+- **W1 × O1 (fix-first):** The opportunity is real but unreachable until pricing is solved — so pricing is the gating workstream, not marketing.
+
+## Ranked implications (action-shaped, tied to the go/no-go)
+
+1. **Gate the decision on a validated SMB SKU** (target ≤ $99/mo, positive unit economics at self-serve volume). No SKU → no-go. *(from W1×T1, W1×O1)*
+2. **Run a 60-day self-serve pilot** on the existing onboarding to test activation without sales. *(S1×O1)*
+3. **Pre-commit a free-tier response** so a competitor's move doesn't catch us flat. *(S1×T1)*
+
+## Verdict (takes a side + what would change it)
+
+**Conditional GO** — enter *only* after a sub-$100 SKU clears a unit-economics test in a 60-day pilot; the low cost-to-serve and the open niche make the upside real, but the pricing gap is disqualifying until fixed. **What flips it to no-go:** the pilot shows self-serve activation < 20% (the zero-touch advantage doesn't transfer), or a horizontal BI tool ships a *vertical* SMB tier first (the wedge closes).
+
+## Why this passes the quality bar
+
+The framework choice is justified; every cell is specific, evidenced, and carries a "→ so what"; SWOT is delivered *as TOWS* with real crossings; implications are ranked and tied to the named decision; and the verdict commits with a falsifiable flip-condition instead of "it depends."

package/skills/tech-comparison-matrix/examples/queue-selection.md

@@ -0,0 +1,41 @@
+# Worked example — weighted comparison of message queues
+
+Input → output oracle for `tech-comparison-matrix`. Shows shown weights, a one-line
+justification per score, honest "rough" markers, and a one-sentence recommendation.
+
+## Input
+
+> "We need a message queue for an order-processing pipeline: ~5k msg/s, must not
+> lose messages, small team, already on AWS. Compare [managed-broker-A],
+> [self-hosted-broker-B], and [cloud-queue-C]."
+
+## Output
+
+**Weights** (sum to 100, set by the stated constraints — durability and ops-load dominate because the team is small and messages can't be lost):
+
+| Criterion | Weight | Why this weight |
+|---|--:|---|
+| Durability / no message loss | 30 | Hard requirement — order data. |
+| Operational load | 25 | Small team; running a broker is a tax. |
+| Throughput headroom | 15 | 5k/s is modest; all three clear it, so it's not decisive. |
+| Delivery semantics / ordering | 15 | Orders need per-key ordering. |
+| Ecosystem fit (AWS) | 15 | Already on AWS; native integration saves glue. |
+
+**Scores** (1–5, each justified; ties kept where real):
+
+| Criterion | Wt | [managed-broker-A] | [self-hosted-broker-B] | [cloud-queue-C] |
+|---|--:|--:|--:|--:|
+| Durability | 30 | 5 — replicated, managed | 5 — replicated *if* configured right | 5 — replicated, managed |
+| Ops load | 25 | 4 — managed, some tuning | 2 — you patch/scale/monitor it | 5 — fully serverless |
+| Throughput (rough) | 15 | 4 — ~tens of k/s | 5 — highest ceiling | 4 — ample for 5k/s |
+| Semantics/ordering | 15 | 4 — ordered per partition | 5 — most flexible | 3 — FIFO variant, lower quotas |
+| AWS fit | 15 | 3 — runs on AWS, not native | 2 — self-run on EC2/EKS | 5 — native service |
+| **Weighted total** | | **4.15** | **3.55** | **4.45** |
+
+**Recommendation:** Pick **[cloud-queue-C]** — its serverless ops profile decisively fits a small team with a modest, durability-critical load, and the only real gap (ordering quotas) is manageable at 5k/s.
+
+*Directional note:* throughput scores are rough (order-of-magnitude, not benchmarked); if load is likely to 10× within a year, re-weight throughput up and re-score — [self-hosted-broker-B]'s ceiling starts to matter.
+
+## Why this passes the quality bar
+
+Weights are shown and tied to the question; every score carries a one-line justification; ties (durability 5/5/5) are left as ties; the guessed throughput numbers are flagged "rough"/"directional"; and the recommendation is one decisive sentence, not hedged.