skilldrop-cli 0.8.0 → 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,
@@ -151,6 +151,8 @@ Designing the agentic systems themselves — the loops, orchestrations, and budg
 | [`agent-budget`](skills/agent-budget/SKILL.md) | The spend spec for an agentic workflow: cheapest-adequate **tier per stage** (light/standard/heavy — heavy verification is never downgraded to save money), three numbers per stage (expected, hard cap, on-cap action — "warn and continue" banned), a run-level cap *below* the sum of stage caps, a **degradation ladder where verification is last and never cut**, and **cost-per-outcome** as the governing metric with a comparison line against the manual alternative — so "$900/week" becomes answerable. Estimates tagged `[assumption]` until calibrated on real runs. |
 | [`agent-threat-model`](skills/agent-threat-model/SKILL.md) | Security review of an agent's **capability surface** against the lethal trifecta — private data, untrusted content, an exfiltration vector. Inventories data reach *transitively* (the filesystem tool reaches every secret in `.env`), applies a writer-authorization test that classifies almost every content source untrusted, and sweeps egress past the obvious network tool (rendered markdown images, CI logs, error text, DNS). Scores **paths, not tools** — `fetch` is fine alone and lethal beside a secrets file — then names the architectural fix that breaks a leg, with a verification step. Structurally refuses the two answers teams reach for first: a system prompt telling the model to ignore injected instructions is not a control, and an injection classifier is defense in depth, never a broken leg. |
 
+| [`agents-md-generator`](skills/agents-md-generator/SKILL.md) | Generate or audit the `AGENTS.md` that Claude Code, Codex, Cursor, Copilot, Kiro and Antigravity all read before your prompt. Built around one rule: **every command traces to evidence in the repo** — a CI step, a Makefile target, a `package.json` script — or it appears as `[missing: no test command in CI or manifests]` rather than a guess, because an invented command is a fault the agent will trust over the filesystem. Convention lines must pass a **counterfactual test** (without this line, would a competent agent do the wrong thing?); virtue instructions — "clean", "best practice", "thorough" — are *stripped, not softened*, since they spend context and change no behaviour. Names forbidden actions explicitly, the section most files omit. Hard ~150-line cap when generating, a warning when auditing, because an existing file may be long for good reason. Audit mode emits a diff, never a silent rewrite. Satellites (`CLAUDE.md`, `.github/copilot-instructions.md`) are opt-in and **delta-only** — a satellite that repeats `AGENTS.md` is guaranteed drift. |
+
 ### AI adoption & observability
 
 | Skill | What it does |
@@ -262,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.
@@ -313,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/model-routing.json

@@ -146,6 +146,7 @@
     "agent-loop-design": { "tier": "standard", "rationale": "Design synthesis against a fixed state-machine pattern and exit-criteria catalog. The gate-placement judgment is bounded by the blast-radius rule; escalate via ambiguous-input when the task itself is contested." },
     "subagent-design": { "tier": "standard", "rationale": "Design synthesis against a fixed topology catalog and role-card template. The fan-out-or-refuse judgment is bounded by the three-reasons rule; escalate via ambiguous-input on genuinely novel workflow shapes." },
     "agent-budget": { "tier": "standard", "rationale": "Quantitative spec synthesis against a fixed tier vocabulary and degradation ladder. Cap-setting judgment is bounded by the 3-5x rule; escalate via ambiguous-input when the workflow itself is undefined." },
+    "agents-md-generator": { "tier": "standard", "rationale": "Repo inspection plus synthesis against a fixed section order and line budget — the same shape as reverse-architecture. The judgment is the counterfactual test on each convention line, which is bounded; escalate via large-input on monorepos." },
     "agent-threat-model": { "tier": "heavy", "rationale": "Adversarial reasoning over a capability graph — the judgment is which mitigations are architectural versus theatrical, and that call is exactly where a weaker model produces a confident wrong answer. Never downgraded." }
   }
 }

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.8.0",
+  "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/packs.json

@@ -14,6 +14,7 @@
         "tech-comparison-matrix",
         "threat-model",
         "agent-threat-model",
+        "agents-md-generator",
         "api-contract-draft",
         "data-contract",
         "db-schema-design",
@@ -41,8 +42,9 @@
       ]
     },
     "dev-team": {
-      "description": "Build-and-ship loop: story implementation with adversarial review, test plans, triage, migrations, release notes, and code-quality gates.",
+      "description": "Build-and-ship loop: story implementation with adversarial review, test plans, triage, migrations, release notes, agent-policy files, and code-quality gates.",
       "skills": [
+        "agents-md-generator",
         "user-story-splitter",
         "feature-implement-loop",
         "devils-advocate",

package/skills/agents-md-generator/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: agents-md-generator
+description: Generate or audit a repository's AGENTS.md — the agent-policy file Claude Code, Codex, Cursor, Copilot, Kiro and Antigravity read — with every command traced to real evidence in the repo, generic virtue instructions stripped, and forbidden actions named. Use when a repo has no AGENTS.md, when an existing one is stale or ignored, when onboarding a codebase to agentic coding, or when an agent keeps running commands that don't exist.
+---
+
+# agents-md-generator
+
+Produces the file agents read *before* the user's prompt. An `AGENTS.md` is not documentation — it is the context an agent spends on every turn, so a line that changes no decision is a line stolen from the task.
+
+The failure that makes these files worse than useless is an **invented command**. `npm test` in a repo with no test script sends every agent down a path that fails, and the agent trusts the file over the filesystem. So the rule this skill is built around: **every command traces to evidence in the repo, or it does not appear.**
+
+Two modes, chosen by what's already there:
+- **Generate** — no `AGENTS.md` exists. Produce one under the line cap.
+- **Audit** — one exists. Score it, name what can't be verified, emit a diff. Never silently rewrite a hand-tuned file.
+
+## How to respond
+
+1. **Inventory the real command surface before writing anything.** Read, in this order: `package.json` (`scripts`), `Makefile`, `pyproject.toml` / `setup.cfg`, `Cargo.toml`, `go.mod`, `composer.json`, `.github/workflows/*.yml`, `justfile`, `Taskfile.yml`, and any `CONTRIBUTING.md`. CI workflows are the highest-value source: they contain the commands that actually have to pass.
+
+   For each command record its **provenance** — the file and key it came from. Provenance is what makes audit mode possible later.
+
+2. **Apply the evidence rule without exception.** A command appears only if it traces to a file in the repo. Never infer from ecosystem convention: a Python repo does not necessarily run `pytest`, and a repo with `jest` in `devDependencies` may still have no test script.
+
+   When a section needs a command that doesn't exist, write the marker, not a guess: ✅ *"Test: `[missing: no test script in package.json or CI]`"* — ❌ *"Test: `npm test`"*. The marker is useful; the guess is a trap.
+
+3. **Derive file placement from the actual tree**, not from what the framework usually does. Name the directories that exist and what belongs in each. Two or three rows beat a full tree dump.
+
+4. **Extract only conventions an agent would otherwise get wrong.** The test is counterfactual: *would a competent agent, without this line, do the wrong thing?* Naming rules that are enforced somewhere, invariants that look arbitrary but aren't, a generated file that must never be hand-edited. If the answer is no, cut the line.
+
+   Generic virtue instructions — "write clean code", "be thorough", "follow best practices", "use good naming" — are **stripped, not softened.** They consume context and change no behaviour.
+
+5. **Name forbidden actions explicitly.** This is the section most files omit and the one that prevents the most damage: paths that must not be touched, commands that must never run unattended, files that are generated, secrets that must never be committed. Concrete and few.
+
+6. **Assemble under ~150 lines.** In generate mode this is a **hard cap** — go over and cut, lowest value first (background prose, then examples, then convention lines that failed the counterfactual test). In audit mode it is a **warning**: report the overage and name the sections you would cut, because an existing file may be long for good reason.
+
+7. **Satellites only on request, and only as a delta.** If asked to wire a specific tool, emit a satellite (`CLAUDE.md`, `.github/copilot-instructions.md`, `GEMINI.md`) that contains **only what is specific to that tool**, plus one line pointing at `AGENTS.md` for everything shared. **Refuse to copy shared content into a satellite** — four copies of a command list is four chances to be wrong, and the drift is invisible. See [`reference.md`](reference.md) for the per-tool shapes.
+
+8. **Emit.** Generate mode: the file, plus a provenance table showing where each command came from and what was marked `[missing]`. Audit mode: verdict, the unverifiable lines quoted, the virtue instructions to cut, the line-count position, and a concrete diff.
+
+**Non-interactive runs:** unstated conventions are simply omitted — an `AGENTS.md` is allowed to be short. If the repo cannot be read at all, emit `BLOCKED: need repo access — every command must trace to a file`. Never produce an `AGENTS.md` from a description of a repo; the whole artifact is a claim about what is in the tree.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — where each tool looks, the evidence-source table, the satellite shapes, and the strip-list of virtue phrasings
+- [`templates/agents-md.md`](templates/agents-md.md) — the output skeleton with the section order and the line budget per section
+
+## Quality bar
+
+- **Zero unverified commands.** Every one traces to a file and key, or carries a `[missing: …]` marker. This is the bar; a file that fails it is worse than no file.
+- **A newcomer agent could build and test from this file alone** — or can see plainly that the repo has no such command.
+- **Forbidden actions are named**, not implied.
+- **Every convention line passes the counterfactual test.** If an agent would do the right thing without it, it is padding.
+- **≤150 lines generated.** Over the cap means something was kept that should have been cut.
+- **No virtue instructions survive.** Search the output for "clean", "best practice", "thorough", "appropriate", "as needed" — each hit is a line that changes nothing.
+- **It does not restate the README.** Different reader, different job: the README sells and explains, `AGENTS.md` constrains.
+
+## When to use this skill
+
+- ✅ A repo is adopting agentic coding and has no `AGENTS.md`
+- ✅ An existing `AGENTS.md` is stale, ignored, or full of advice rather than facts
+- ✅ Agents keep running commands that don't exist in the repo
+- ✅ Onboarding a legacy codebase where the real commands live only in CI
+- ✅ After `reverse-architecture` — its extraction is good input for the conventions section
+
+## When NOT to use this skill
+
+- ❌ Writing human contributor docs — that's `CONTRIBUTING.md`, a different reader
+- ❌ Explaining what the project *is* — that's the README
+- ❌ Operating a running service — that's `runbook-generator`
+- ❌ Reviewing an existing document's prose quality — that's `doc-critique`, which takes documents; this one takes a repository
+
+## Anti-patterns to avoid
+
+- ❌ **Inventing a command that "should" exist.** The single most damaging thing this artifact can do. A `[missing]` marker is a finding; a guess is a fault the agent will trust.
+- ❌ **Virtue instructions.** "Write clean, maintainable code" is context spent on nothing. Agents already try.
+- ❌ **Dumping the file tree.** Placement rules earn their space; a directory listing does not — the agent can run `ls`.
+- ❌ **Restating the README.** If it's already there, link it.
+- ❌ **A satellite that duplicates `AGENTS.md`.** Guaranteed drift, invisible until an agent acts on the stale copy.
+- ❌ **Silently rewriting a hand-tuned file.** Audit mode emits a diff and lets a human choose; the file may encode decisions the repo can't show you.
+- ❌ **Writing to the cap.** 150 lines is a ceiling, not a target. Most repos need far less.

package/skills/agents-md-generator/evals/eval_queries.json

@@ -0,0 +1,15 @@
+[
+  { "query": "Write an AGENTS.md for this repo", "should_trigger": true },
+  { "query": "Our AGENTS.md is stale — review it", "should_trigger": true },
+  { "query": "The agent keeps running commands that don't exist in our project", "should_trigger": true },
+  { "query": "Set this codebase up for agentic coding", "should_trigger": true },
+  { "query": "Create a CLAUDE.md for this project", "should_trigger": true },
+  { "query": "What should go in an agent instructions file?", "should_trigger": true },
+
+  { "query": "Write a CONTRIBUTING.md for this repo", "should_trigger": false },
+  { "query": "Document what this service does for new hires", "should_trigger": false },
+  { "query": "Reverse-engineer the architecture of this codebase", "should_trigger": false },
+  { "query": "Write a runbook for this service", "should_trigger": false },
+  { "query": "Review this design doc for gaps", "should_trigger": false },
+  { "query": "Design a supervised agent loop", "should_trigger": false }
+]

package/skills/agents-md-generator/evals/evals.json

@@ -0,0 +1,50 @@
+{
+  "skill_name": "agents-md-generator",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write an AGENTS.md for this repo. It's a Python service: pyproject.toml declares pytest and ruff in dev dependencies, there's a Makefile with `run` and `migrate` targets, and .github/workflows/ci.yml runs `ruff check .` then `pytest -q`. No test script anywhere else. Migrations are in alembic/versions/.",
+      "assertions": [
+        "Commands are traced to their source — CI for ruff/pytest, Makefile for run/migrate — not inferred from the dependency list",
+        "The test command is `pytest -q` as CI runs it, not a guessed `pytest` or `make test` that does not exist",
+        "No command appears that cannot be traced to pyproject.toml, the Makefile, or the workflow",
+        "Alembic migrations produce a convention or forbidden-action line (append-only / never edit a committed migration)",
+        "A `Do not` section exists with concrete entries, not implied caution",
+        "Output is at or under ~150 lines",
+        "No virtue instructions appear — no 'clean', 'best practice', 'thorough', 'maintainable'",
+        "Conventions included would each change agent behaviour if removed"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Here's our AGENTS.md — audit it. It says: 'Run `npm test` to test. Write clean, maintainable code and follow best practices. Be thorough in reviews.' Our package.json has scripts for build and lint only, no test.",
+      "assertions": [
+        "Audit mode is used — a verdict and diff, not a silent rewrite",
+        "`npm test` is flagged as unverifiable: package.json has no test script",
+        "The three virtue instructions are named for removal, with the reason that they change no behaviour",
+        "What the file is missing is stated — real commands (build, lint), file placement, forbidden actions",
+        "The line-count position is reported rather than the file being failed for length",
+        "A concrete replacement or diff is offered, not just criticism"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Also wire it up for Claude Code and Copilot.",
+      "assertions": [
+        "Satellites are emitted as deltas only — each points at AGENTS.md for shared content",
+        "No satellite repeats the command table, file placement, or conventions",
+        "CLAUDE.md carries only Claude-Code-specific content; .github/copilot-instructions.md only Copilot-specific content",
+        "If there is no genuinely tool-specific content, that is said rather than a file padded to justify itself"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "[Non-interactive run — no repo access] Generate an AGENTS.md for a typical Node microservice.",
+      "assertions": [
+        "No AGENTS.md is produced — the output is BLOCKED: need repo access",
+        "No commands are invented from ecosystem convention",
+        "The reason given is that every command must trace to a file in the tree"
+      ]
+    }
+  ]
+}

package/skills/agents-md-generator/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "agents-md-generator",
+  "version": "0.1.0",
+  "description": "Generate or audit a repository's AGENTS.md — the agent-policy file Claude Code, Codex, Cursor, Copilot, Kiro and Antigravity read — with every command traced to real evidence in the repo, generic virtue instructions stripped, and forbidden actions named. Use when a repo has no AGENTS.md, when an existing one is stale or ignored, when onboarding a codebase to agentic coding, or when an agent keeps running commands that don't exist.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["doc-critique", "reverse-architecture", "runbook-generator"],
+  "tags": ["agents-md", "agent-policy", "repo-onboarding", "context-engineering", "agentic", "conventions"],
+  "model": { "tier": "standard", "rationale": "Repo inspection plus synthesis against a fixed section order and line budget — the same shape as reverse-architecture. The judgment is the counterfactual test on each convention line, which is bounded; escalate via large-input on monorepos." }
+}

package/skills/agents-md-generator/reference.md

@@ -0,0 +1,89 @@
+# agents-md-generator — reference
+
+## Who reads what
+
+Confirmed in the July 2026 survey ([`docs/designs/ide-primitive-coverage.md`](../../docs/designs/ide-primitive-coverage.md)). A root `AGENTS.md` is the broadest single file; satellites are a reach fix for specific tools, not the norm.
+
+| Tool | Reads |
+|---|---|
+| Codex | root `AGENTS.md` |
+| GitHub Copilot | root `AGENTS.md`, `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, and also root `CLAUDE.md` / `GEMINI.md` |
+| Claude Code | `CLAUDE.md` (auto-loaded) |
+| Cursor | root `AGENTS.md`, plus `.cursor/rules/*.mdc` for rules |
+| Kiro | root `AGENTS.md`, plus `.kiro/steering/` for always-on context |
+| Antigravity | root `AGENTS.md` |
+
+**Precedence matters more than reach.** Several of these load on every turn regardless of relevance. A file that is always in context should carry only what earns its place there — the same reason an always-included steering file is a poor home for a persona.
+
+## Evidence sources, in priority order
+
+Every command must trace to one of these. Record the file and key as provenance.
+
+| Source | What it proves |
+|---|---|
+| `.github/workflows/*.yml` (and other CI) | **Strongest.** These commands must pass or the build fails |
+| `Makefile` / `justfile` / `Taskfile.yml` | Named entry points the team actually uses |
+| `package.json` `scripts` | Node entry points; check the script body, not just the key |
+| `pyproject.toml` / `setup.cfg` / `tox.ini` | Python entry points and runners |
+| `Cargo.toml`, `go.mod`, `composer.json`, `Gemfile` | Ecosystem defaults *only if* the file confirms them |
+| `CONTRIBUTING.md`, `README.md` | Human-facing; **verify against the above before trusting** — docs go stale faster than CI |
+| Dev container / Dockerfile | Setup steps and version pins |
+
+**A dependency is not a command.** `jest` in `devDependencies` does not mean `npm test` exists. Check for the script.
+
+## What earns a line — the counterfactual test
+
+Ask: *without this line, would a competent agent do the wrong thing?*
+
+| ✅ Earns its place | ❌ Cut |
+|---|---|
+| "Generated — never hand-edit `src/api/types.ts`; run `make codegen`" | "Keep the codebase clean and well organised" |
+| "Migrations are append-only; never edit a committed migration" | "Follow database best practices" |
+| "Tests live beside the source as `*_test.go`, not in `tests/`" | "Write comprehensive tests" |
+| "`main` is protected; open a PR" | "Follow good git hygiene" |
+| "Do not run `terraform apply` — plan only, a human applies" | "Be careful with infrastructure" |
+
+## Strip list
+
+Search generated output for these; each hit is a line that changes no behaviour:
+
+`clean` · `best practice` · `thorough` · `appropriate` · `as needed` · `where possible` · `make sure to` · `try to` · `robust` · `maintainable` · `readable` · `well-structured` · `properly` · `high-quality` · `idiomatic` (unless a specific idiom is named)
+
+## Satellite shapes — delta only
+
+A satellite carries what is specific to its tool **and nothing else**. Every shared fact stays in `AGENTS.md` and is pointed at.
+
+**`CLAUDE.md`** — Claude Code auto-loads it:
+
+```markdown
+# CLAUDE.md
+
+The substantive guidance lives in [AGENTS.md](AGENTS.md). Read it first.
+
+This file exists because Claude Code auto-loads `CLAUDE.md`. Everything below is
+Claude-Code-specific and does not belong in the cross-IDE file.
+
+## <tool-specific section>
+…e.g. `${CLAUDE_SKILL_DIR}` semantics, `.claude/settings.json`, subagent delegation…
+```
+
+**`.github/copilot-instructions.md`** — same shape, Copilot-specific content only (custom agents in `.github/agents/`, `.github/hooks/*.json`).
+
+**`GEMINI.md`** — same shape, for Gemini/Antigravity specifics.
+
+**Refuse** to emit a satellite containing the command table, file placement, or conventions that already live in `AGENTS.md`. If a tool needs those, it reads `AGENTS.md` — and if it genuinely cannot, say so plainly rather than duplicating.
+
+## Line budget
+
+150 lines total. A workable split:
+
+| Section | Lines |
+|---|---|
+| Repo in one paragraph | 3–5 |
+| Commands (with provenance verified) | 15–30 |
+| File placement | 10–20 |
+| Conventions that pass the counterfactual test | 20–40 |
+| Forbidden actions | 5–15 |
+| Pointers to deeper docs | 3–5 |
+
+Over budget: cut background prose first, then examples, then convention lines that only *probably* pass the test.

package/skills/agents-md-generator/templates/agents-md.md

@@ -0,0 +1,48 @@
+# AGENTS.md — {project name}
+
+> {One line: what an agent needs to know it is working on.}
+
+## Repo in one paragraph
+
+{What this is, what it produces, and the one structural fact an agent must hold. 3–5 lines.}
+
+## Commands
+
+<!-- Every row traces to a file. No row may be inferred from ecosystem convention. -->
+
+| Task | Command | Source |
+|---|---|---|
+| Install | `{cmd}` | `{file}` → `{key}` |
+| Build | `{cmd}` | `{file}` → `{key}` |
+| Test | `{cmd}` *or* `[missing: no test command in CI or manifests]` | `{file}` → `{key}` |
+| Lint | `{cmd}` | `{file}` → `{key}` |
+| Run locally | `{cmd}` | `{file}` → `{key}` |
+
+{Drop the Source column from the final file if it crowds the budget — but only after every row has been verified with it present.}
+
+## File placement
+
+| Kind | Where |
+|---|---|
+| {thing} | `{path}` |
+
+## Conventions
+
+<!-- Each line must pass: without it, would a competent agent do the wrong thing? -->
+
+- **{Rule stated as a rule.}** {One clause of why, only if the why changes how it is applied.}
+
+## Do not
+
+- {Path, command, or action that must never happen unattended — concrete.}
+- {Generated artifacts that must not be hand-edited, and the command that regenerates them.}
+
+## Pointers
+
+- {Deeper doc}: `{path}`
+- {Architecture / design}: `{path}`
+
+<!--
+Line budget: 150. Provenance for every command was verified at generation time.
+Commands marked [missing] are findings, not omissions — the repo has no such command.
+-->

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.