skilldrop-cli 0.2.0 → 0.4.0

package/README.md

@@ -1,10 +1,18 @@
 # skilldrop
 
-A collection of portable **Claude Skills** you can drop into any IDE — for the deliverables knowledge workers actually ship: diagrams, design docs, ADRs, runbooks, decks, decision logs, comparison matrices, and exec summaries.
+[![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)
+
+**48 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**, 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,
+npx skilldrop-cli list                               #     sre-oncall, stakeholder-comms, ai-engineering
+```
 
 Originally scoped to solution architects, now broadly useful to PMs, founders, consultants, engineering leaders, exec assistants — anyone who turns ideas into stakeholder-ready artifacts.
 
-Each skill is a plain directory of `SKILL.md` + supporting files + `manifest.json`. Works in **Claude Code** natively, and ports cleanly to **Cursor**, **Kiro**, **Continue**, **Cline**, **Aider**, and any other AI coding tool that accepts custom instructions or rules.
+**Why skilldrop over heavier agent platforms:** every skill is a plain folder (`SKILL.md` + `manifest.json` + supporting files) and installs by *copy, never transformation* — what runs in your IDE is byte-identical to what's reviewed in this repo. The flat layout doubles as an open catalog contract: [any repo shaped like this one](#third-party-catalogs--publish-your-own-skills-through-the-same-cli) is installable through the same CLI. Skills are *opinionated* — each ships a quality bar, anti-patterns, and acceptance evals, so the output is an artifact, not a vibe.
 
 ## How skilldrop works
 
@@ -130,6 +138,16 @@ Skills for the direction-setting layer above any single feature — testing whet
 | [`data-contract`](skills/data-contract/SKILL.md) | Draft a data contract for a dataset, table, or event stream others depend on — the data-engineering counterpart to `api-contract-draft`. Schema specified with **per-field semantics and units** (the cents-vs-dollars, UTC-vs-local, gross-vs-net firewall), measurable quality SLAs across freshness / completeness / validity / uniqueness / distribution — each with a threshold, a check, and a **breach action** — a schema-evolution policy that names the silent killer (changing a field's *meaning* under a stable name/type is breaking, and no validator catches it), enumerated consumers (so "breaking" is defined and notices have an address), a named owner, and per-field PII classification. Marks aspirational-vs-met SLAs honestly on existing assets. |
 | [`tech-comparison-matrix`](skills/tech-comparison-matrix/SKILL.md) | Produce a weighted comparison matrix for a tech-selection question (e.g. "Postgres vs DynamoDB") with criteria, weights, scores, and a recommendation. |
 
+### Agent engineering
+
+Designing the agentic systems themselves — the loops, orchestrations, and budgets that turn "prompting an agent" into infrastructure a team can run unattended. (`feature-implement-loop` under Dev workflow is the in-repo worked example of a supervised loop; `llm-eval-harness` below builds the verifier's quality gate.)
+
+| Skill | What it does |
+|---|---|
+| [`agent-loop-design`](skills/agent-loop-design/SKILL.md) | Design a supervised agent loop as an implementable **loop spec**: a strict generate→verify→gate state machine (no mushy "reflect" states), an **observable done-condition** (never "output looks good"), verifier structurally ≠ generator (self-grading inflates), **both caps as numbers** (revision cap defaulting to 3, budget cap per run), human gates at every irreversible action with **decision-shaped digests** (never transcripts), findings flowing into the next round (else it's retry, not iteration), three specified failure routes (cap-hit / can't-judge / systemic early-stop), and a telemetry row so the loop's degradation shows up before its output does. |
+| [`subagent-design`](skills/subagent-design/SKILL.md) | Decompose a task into orchestrator + subagents — starting from **"the default answer is one agent"**: fan-out must earn itself via context separation, independence, or role conflict, or the plan says so. One-mission **role cards** (typed output contracts, explicit context-isolation lines, least-privilege tools, structured failure behavior), topology chosen with the reason attached (pipeline default; barriers only for named cross-item dependencies; judge panels with a vote rule), depth capped at one level, an **adversarial verification stage that is never a generator**, and a budget line per fleet. |
+| [`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. |
+
 ### AI adoption & observability
 
 | Skill | What it does |
@@ -209,7 +227,7 @@ Categories (above) say what a skill *is*; packs say *who needs it*. [`packs.json
 | `dev-team` | 11 | Build-and-ship loop: implementation with adversarial review, test plans, triage, migrations, release notes, quality gates |
 | `stakeholder-comms` | 8 | Non-technical audiences: audience profiling, deck outlines and real `.pptx` decks, exec summaries, decision logs, guides |
 | `sre-oncall` | 5 | Operate the service: runbooks, observability design, incident comms, postmortems, capacity/cost models |
-| `ai-engineering` | 3 | Ship and measure AI features: eval harnesses, AI-usage reporting, data contracts |
+| `ai-engineering` | 6 | Build and run AI systems: agent loop design, subagent orchestration, spend budgets, eval harnesses, usage reporting, data contracts |
 
 ```bash
 python3 pack.py                                  # list packs
@@ -236,7 +254,18 @@ npx skilldrop-cli outdated && npx skilldrop-cli update  # skills improve; cp -R
 npx skilldrop-cli list | skilldrop info <skill> | skilldrop packs | skilldrop uninstall <skill>
 ```
 
-`--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 [`skilldrop-cli-design/`](skilldrop-cli-design/skilldrop-cli-design.md).
+`--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).
+
+### 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.
+
+```bash
+npx skilldrop-cli install devils-advocate --with-hooks --project
+# → appends a marker-fenced reminder to .git/hooks/pre-commit: "run /devils-advocate on staged changes"
+```
+
+The CLI emits per target and **degrades gracefully** — a `pre-commit-review` hook becomes an IDE-agnostic git hook (needs a git repo); a `session-start` hook becomes a Claude Code `settings.json` entry, and is cleanly skipped where the target has no equivalent (Cursor, Kiro, plain `--dest`), printing what it did and where. Hooks are reminders/context, not autonomous execution — skilldrop skills are agent instructions, so the hook prompts *you* to run the review, it doesn't silently run an AI pass. `skilldrop uninstall` removes any hook artifacts it wrote. Vocabulary and the per-target mapping are in the RFC.
 
 ### Third-party catalogs — publish your own skills through the same CLI
 

package/bin/skilldrop.js

@@ -15,6 +15,8 @@ const { execFileSync } = require("child_process");
 const ROOT = path.resolve(__dirname, "..");
 const LEDGER = ".skilldrop.json";
 const BUNDLED = "bundled";
+// Neutral hook vocabulary (RFC-0006). Kept in sync with validate.py's HOOK_EVENTS.
+const HOOK_EVENTS = ["session-start", "pre-commit-review", "on-demand"];
 
 const HELP = `skilldrop — portable AI-agent skills for Claude Code, Cursor, Kiro, and more
 
@@ -44,6 +46,10 @@ Install/update/uninstall targets (pick one):
 
 Options:
   --with-related     also install each skill's related companions (one level)
+  --with-hooks       also wire any hooks a skill declares (RFC-0006) — git pre-commit
+                     reminders and Claude Code session-start context; degrades where the
+                     target has no hook mechanism. Off by default so installs never touch
+                     your git repo or settings unasked.
 `;
 
 function die(msg) { console.error("error: " + msg); process.exit(1); }
@@ -163,6 +169,106 @@ function writeWiring(ide, dest, s, desc) {
     fs.writeFileSync(p, `When the user requests the following, defer to the instructions in .kiro/skills/${s}/SKILL.md:\n\n${desc}\n`);
 }
 
+/* ---------- hooks (RFC-0006: emit per target, degrade where unsupported) ---------- */
+
+function gitRoot(startDir) {
+  let d = path.resolve(startDir);
+  for (;;) {
+    if (fs.existsSync(path.join(d, ".git"))) return d;
+    const up = path.dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+// Append an idempotent, marker-fenced reminder to .git/hooks/pre-commit. IDE-agnostic.
+function writeGitPreCommitHook(root, skill, hook) {
+  const p = path.join(root, ".git", "hooks", "pre-commit");
+  const marker = `skilldrop-hook:${skill}:pre-commit-review`;
+  let body = fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  if (!body.startsWith("#!")) body = "#!/bin/sh\n" + body;
+  if (body.includes(marker)) return p; // already wired
+  const line = `echo "skilldrop: run /${hook.action} on your staged changes before committing — ${hook.description}"`;
+  body += `\n# >>> ${marker} >>>\n${line}\n# <<< ${marker} <<<\n`;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, body);
+  fs.chmodSync(p, 0o755);
+  return p;
+}
+
+// Merge a SessionStart command into Claude Code settings.json. Returns the path,
+// or null if the file exists but is malformed (we never clobber unparseable JSON).
+function writeClaudeSessionHook(settingsPath, skill, hook) {
+  let data = {};
+  if (fs.existsSync(settingsPath)) {
+    try { data = JSON.parse(fs.readFileSync(settingsPath, "utf8")); }
+    catch (e) { return null; }
+  }
+  data.hooks = data.hooks || {};
+  data.hooks.SessionStart = data.hooks.SessionStart || [];
+  const marker = `skilldrop-hook:${skill}:session-start`;
+  if (!JSON.stringify(data.hooks.SessionStart).includes(marker)) {
+    const cmd = `echo "skilldrop: /${hook.action} is available — ${hook.description}" # ${marker}`;
+    data.hooks.SessionStart.push({ hooks: [{ type: "command", command: cmd }] });
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2) + "\n");
+  }
+  return settingsPath;
+}
+
+// Wire one skill's declared hooks; returns human-readable status lines.
+function emitHooks(cat, skill, dest, ide) {
+  let hooks = [];
+  try { hooks = manifestOf(cat, skill).hooks || []; } catch (e) { return []; }
+  const lines = [];
+  for (const h of hooks) {
+    if (h.event === "pre-commit-review") {
+      const root = gitRoot(process.cwd());
+      if (root) lines.push(`  ${skill}: pre-commit reminder -> ${path.join(root, ".git/hooks/pre-commit")}`);
+      else lines.push(`  ${skill}: pre-commit-review skipped — no git repo at ${process.cwd()}`);
+      if (root) writeGitPreCommitHook(root, skill, h);
+    } else if (h.event === "session-start") {
+      if (ide === "claude") {
+        const sp = path.join(path.dirname(dest), "settings.json");
+        const written = writeClaudeSessionHook(sp, skill, h);
+        lines.push(written ? `  ${skill}: session-start context -> ${sp}`
+                           : `  ${skill}: session-start skipped — ${sp} is not valid JSON`);
+      } else {
+        lines.push(`  ${skill}: session-start skipped — no hook mechanism for ${ide}`);
+      }
+    } else if (h.event === "on-demand") {
+      lines.push(`  ${skill}: on-demand — invoke /${h.action} manually (no artifact needed)`);
+    }
+  }
+  return lines;
+}
+
+function removeHooksFor(skill, dest, ide) {
+  const root = gitRoot(process.cwd());
+  if (root) {
+    const p = path.join(root, ".git", "hooks", "pre-commit");
+    if (fs.existsSync(p)) {
+      const body = fs.readFileSync(p, "utf8");
+      const re = new RegExp(`\\n?# >>> skilldrop-hook:${skill}:[^\\n]* >>>[\\s\\S]*?# <<< skilldrop-hook:${skill}:[^\\n]* <<<\\n?`, "g");
+      const next = body.replace(re, "\n");
+      if (next !== body) fs.writeFileSync(p, next);
+    }
+  }
+  if (ide === "claude") {
+    const sp = path.join(path.dirname(dest), "settings.json");
+    if (fs.existsSync(sp)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(sp, "utf8"));
+        const arr = data.hooks && data.hooks.SessionStart;
+        if (Array.isArray(arr)) {
+          const kept = arr.filter((e) => !JSON.stringify(e).includes(`skilldrop-hook:${skill}:`));
+          if (kept.length !== arr.length) { data.hooks.SessionStart = kept; fs.writeFileSync(sp, JSON.stringify(data, null, 2) + "\n"); }
+        }
+      } catch (e) { /* leave malformed settings untouched */ }
+    }
+  }
+}
+
 /* ---------- commands ---------- */
 
 function expandNames(args, cat) {
@@ -211,6 +317,18 @@ function install(args) {
   }
   saveLedger(l);
   console.log(`\n${names.length} skill(s) installed (${ide}).`);
+
+  const withHooks = names.filter((s) => { try { return (manifestOf(cat, s).hooks || []).length; } catch (e) { return false; } });
+  if (withHooks.length && args.flags["with-hooks"]) {
+    const lines = withHooks.flatMap((s) => emitHooks(cat, s, dest, ide));
+    console.log(`\nHooks wired (RFC-0006):\n${lines.join("\n")}`);
+    if (cat.source !== BUNDLED)
+      console.log(`  NOTE: these hooks run commands from third-party catalog '${cat.source}' — read them before trusting them.`);
+    console.log(`  Undo any of these with: skilldrop uninstall <skill> ${ide === "claude" ? "" : "--ide " + ide}`.trimEnd());
+  } else if (withHooks.length) {
+    console.log(`\n${withHooks.join(", ")} declare hooks — re-run with --with-hooks to wire them (git pre-commit reminders / session-start context).`);
+  }
+
   if (cat.source !== BUNDLED)
     console.log(`\nWARNING: third-party catalog '${cat.source}'. Skills are instructions your AI agent will follow — review each installed SKILL.md under ${dest} before first use. Install copied files only; nothing was executed.`);
   if (ide === "generic")
@@ -269,6 +387,7 @@ function uninstall(args) {
     fs.rmSync(path.join(dest, s), { recursive: true, force: true });
     const w = wiringPath(ide, dest, s);
     if (w) fs.rmSync(w, { force: true });
+    removeHooksFor(s, dest, ide);
     delete l.data[s];
     console.log(`removed ${s} from ${dest}`);
   }

package/model-routing.json

@@ -142,6 +142,9 @@
     "prfaq": { "tier": "standard", "rationale": "Synthesizes a press release and FAQs from a product concept against a fixed format. The specificity discipline needs care but the template bounds it; escalate via ambiguous-input when the concept itself is contested." },
     "okr-cascade": { "tier": "standard", "rationale": "Structured derivation against a fixed roll-up discipline; the causal-sentence and gap judgments need care but the template bounds them. Escalate via ambiguous-input when the company objectives themselves are contested." },
     "user-journey-map": { "tier": "standard", "rationale": "Structured synthesis into a fixed four-row stage model plus bounded ranking judgment. Escalate via ambiguous-input when the persona or outcome is contested or research inputs conflict." },
-    "strategy-analysis": { "tier": "heavy", "rationale": "Framework selection plus evidenced multi-factor judgment ending in a ranked, committal verdict. Cheaper models fill cells with generic filler, skip the TOWS crossings, and refuse to take a side. Never downgrade." }
+    "strategy-analysis": { "tier": "heavy", "rationale": "Framework selection plus evidenced multi-factor judgment ending in a ranked, committal verdict. Cheaper models fill cells with generic filler, skip the TOWS crossings, and refuse to take a side. Never downgrade." },
+    "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." }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship — diagrams, ADRs, PRDs, runbooks, decks, reviews — installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "bin": {
     "skilldrop": "bin/skilldrop.js"
@@ -32,5 +32,6 @@
     "type": "git",
     "url": "git+https://github.com/sananthanarayan/skilldrop.git"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "homepage": "https://github.com/sananthanarayan/skilldrop#readme"
 }

package/packs.json

@@ -79,8 +79,11 @@
       ]
     },
     "ai-engineering": {
-      "description": "Ship and measure AI features: eval harness design, AI-usage reporting, and the data contracts AI pipelines depend on.",
+      "description": "Build and run AI systems: agent loop design, subagent orchestration, spend budgets, eval harnesses, AI-usage reporting, and the data contracts AI pipelines depend on.",
       "skills": [
+        "agent-loop-design",
+        "subagent-design",
+        "agent-budget",
         "llm-eval-harness",
         "ai-usage-report",
         "data-contract"

package/skills/agent-budget/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: agent-budget
+description: Write the spend spec for an agentic workflow — per-stage model tiers, token caps with hard abort rules, a graceful-degradation order, and cost-per-outcome as the governing metric. Use when the user asks what an agent loop or multi-agent workflow should be allowed to spend, wants token/cost budgets and caps for AI automation, or got a surprise bill from an agent fleet.
+---
+
+# agent-budget
+
+An unbudgeted agent loop is a runaway-cost incident with an architecture diagram. This skill produces the **budget spec** that governs an agentic workflow: what each stage may spend, on which tier of model, what happens at the cap, and — the number that actually matters — what one *outcome* costs. Pairs with `agent-loop-design` (the caps land in its loop spec) and `subagent-design` (the fleet line lands in its role cards); the tier vocabulary is this repo's own light/standard/heavy routing abstraction, so the spec ports across providers. Infra spend (compute, storage, egress) is `capacity-cost-model`'s domain — this skill budgets the tokens.
+
+## How to respond
+
+1. **Pin the outcome unit and the workflow's stages.** Ask at most 2 questions, spent on: *"what is one successful outcome?"* (a merged PR, a triaged ticket, a verified report — the denominator every cost divides by) and *"what does a typical run look like today?"* (stages, rounds, models — or "not built yet", which makes this a design-time budget, the cheap time to write one). Non-interactive run (no user to ask): derive both from the input and tag `[assumption]`; no outcome unit derivable → emit `BLOCKED: need the workflow and its outcome unit`.
+
+2. **Assign each stage the cheapest adequate tier** — light / standard / heavy, per the routing rule of thumb: **light** for mechanical extraction and formatting, **standard** for most generation, **heavy** only where the hard thinking *is* the value (adversarial verification, weighted judgment) — and heavy stages are never downgraded to save money; they're where the money buys correctness. Every tier assignment carries a one-line rationale. The classic misallocation runs both directions: frontier models formatting JSON, and — worse — the cheap model doing the verify pass that exists to catch the cheap mistakes.
+
+3. **Set three numbers per stage** in [`templates/budget-spec.md`](templates/budget-spec.md): **expected** spend per run (estimate honestly, tag `[assumption]` until measured), **cap** (the hard stop — 3–5× expected, tighter for unattended loops), and **on-cap action** (abort-and-escalate, or degrade — never "continue and warn"; a warning nobody is watching is a continue). State each as tokens **and** approximate money — tokens are what the harness enforces, but money is the only unit that sums across tiers, so **all cap comparisons happen in currency**. A stage that fans out per item carries two caps: a per-item cap (that item fails to the report's needs-human list; the rest continue) and a stage-wide cap. Then the **run-level cap** for the whole workflow — in currency, *less* than the sum of stage caps: every stage simultaneously hitting its cap is not a run to finish, it's an anomaly to stop.
+
+4. **Write the degradation ladder** — what gives, in order, when spend pressure hits: first **narrow scope** (fewer items per run), then **reduce parallelism** (smaller fleet, slower wall-clock), then **cut non-verification stages** (skip the polish pass), and **last — never — verification**. Skipping verify to save tokens converts a cost problem into a correctness problem at the exact moment quality is already under pressure; a workflow that can't afford its verifier can't afford to run. State each rung's trigger and who flips it.
+
+5. **Make cost-per-outcome the governing metric.** Total tokens is noise; **spend ÷ successful outcomes** is the number with meaning — a loop that gets cheaper per run but passes fewer runs got more expensive. Give it a target and a review threshold, and put beside it the **comparison line**: what the same outcome costs today (an hour of an engineer's time, the manual process) — a $4 triaged ticket is expensive against 60 seconds of a human's glance and cheap against twenty minutes of one; without the line, nobody can say which.
+
+6. **Add measurement and emit.** Spend logged per run per stage (tagged by stage name, feeding the loop spec's telemetry row); weekly review of cost-per-outcome and cap-hit counts by a named role; alert on cap-hit rate rising (the leading indicator of drift — inputs grew, a prompt regressed, or a model changed under you) and on any run breaching the run-level cap (that's an incident, not a line item). Emit the spec in one message: stage table, run cap, degradation ladder, cost-per-outcome with comparison line, measurement plan. Flag every `[assumption]` estimate as the calibration backlog — after ~20 real runs, expected values stop being guesses. Hand off: the caps → `agent-loop-design`'s loop spec; per-agent tiers → `subagent-design`'s role cards; the verifier's quality gate → `llm-eval-harness`.
+
+## Useful references in this skill
+
+- [`templates/budget-spec.md`](templates/budget-spec.md) — stage table, degradation ladder, cost-per-outcome, and measurement skeleton
+
+## Quality bar
+
+- **The outcome unit is named** and every cost in the doc divides by it.
+- **Every stage has tier + rationale + three numbers** (expected, cap, on-cap action). No stage rides free.
+- **Heavy tiers survive.** No verification or judgment stage was downgraded to make the total look better.
+- **Caps are hard.** Every on-cap action is abort or degrade — "warn and continue" appears nowhere.
+- **The run cap is less than the sum of stage caps**, and the doc says why.
+- **Verification is last on the degradation ladder**, explicitly.
+- **The comparison line exists** — cost-per-outcome sits next to what the outcome costs without the agents.
+- **Estimates are tagged.** `[assumption]` until measured; the calibration step is scheduled, not implied.
+
+## When to use this skill
+
+- ✅ "What should this agent workflow be allowed to spend?" — at design time, the cheap time
+- ✅ A surprise token bill arrived — retrofit caps and a degradation ladder
+- ✅ An `agent-loop-design` or `subagent-design` spec needs its budget line filled in
+- ✅ "Is this automation actually cheaper than doing it by hand?" — build the comparison line
+
+## When NOT to use this skill
+
+- ❌ Infra/cloud cost modeling (compute, storage, egress) — `capacity-cost-model`
+- ❌ Choosing a model tier for a single skilldrop skill — that's `model-routing.json`'s table, already decided
+- ❌ Designing the loop or the fan-out itself — `agent-loop-design` / `subagent-design`; this skill prices what they draw
+- ❌ Negotiating provider contracts or rate limits — procurement, not a spec
+
+## Anti-patterns to avoid
+
+- ❌ **Budget-free loops.** "We'll see what it costs" means the invoice is the monitoring system.
+- ❌ **Warn-and-continue caps.** A cap whose breach action is a log line is a number, not a cap.
+- ❌ **Skimping the verifier.** Downgrading or skipping verification under spend pressure — the false economy that ships fleet-speed garbage precisely when scrutiny dropped.
+- ❌ **Token vanity metrics.** Celebrating "20% fewer tokens" while cost-per-successful-outcome rose because pass rates fell.
+- ❌ **Frontier-everything.** The orchestrator's model formatting JSON at heavy-tier prices because nobody assigned tiers per stage.
+- ❌ **Missing comparison line.** A cost-per-outcome with nothing beside it can justify anything or condemn anything.
+- ❌ **Estimates that never graduate.** `[assumption]` numbers still governing caps six months and a thousand runs later.

package/skills/agent-budget/evals/eval_queries.json

@@ -0,0 +1,11 @@
+[
+  { "query": "What should our agent workflow be allowed to spend in tokens?", "should_trigger": true },
+  { "query": "We got a surprise LLM bill from our automation — put budgets and caps on it", "should_trigger": true },
+  { "query": "Is this agent pipeline actually cheaper than doing the work manually?", "should_trigger": true },
+  { "query": "Add a budget line to this loop spec", "should_trigger": true },
+
+  { "query": "Model our service's cloud infrastructure costs at 10x scale", "should_trigger": false },
+  { "query": "Which model tier should the adr-generator skill run on?", "should_trigger": false },
+  { "query": "Design the loop with exit criteria for this automation", "should_trigger": false },
+  { "query": "Design the eval golden set for our LLM judge", "should_trigger": false }
+]

package/skills/agent-budget/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill_name": "agent-budget",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Budget our nightly agent workflow: it reviews the day's merged PRs for security issues. Stages: collect diffs, one reviewer agent per PR (typically 15 PRs), an adversarial verifier on each finding, and a summary report. One outcome = a verified finding report delivered by 8am. We got a $900 bill last week and nobody can say if that's bad.",
+      "assertions": [
+        "The outcome unit is the verified report (or per-PR-reviewed), and every cost divides by it",
+        "Every stage has a tier with a one-line rationale — collection is light, review standard/heavy, verification heavy and explicitly never downgraded",
+        "Every stage has expected spend, a hard cap (roughly 3-5x expected), and an on-cap action that is abort or degrade — no warn-and-continue",
+        "A run-level cap exists and is less than the sum of stage caps, with the reason stated",
+        "The degradation ladder is ordered scope -> parallelism -> non-verification stages, with verification explicitly last/never",
+        "Cost-per-outcome gets a target and a comparison line against the manual alternative (e.g. engineer review time), addressing whether $900/week is bad",
+        "Estimates are tagged [assumption] with a calibration step after ~20 runs",
+        "Measurement includes per-stage spend logging, a review cadence, and an alert on rising cap-hit rate",
+        "Hand-offs route caps to agent-loop-design and per-agent tiers to subagent-design"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "[Non-interactive run — no user available to answer questions] Set a token budget.",
+      "assertions": [
+        "No budget is fabricated — the output is BLOCKED: need the workflow and its outcome unit",
+        "No stage table or caps appear"
+      ]
+    }
+  ]
+}

package/skills/agent-budget/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "agent-budget",
+  "version": "0.1.0",
+  "description": "Write the spend spec for an agentic workflow — per-stage model tiers, token caps with hard abort rules, a graceful-degradation order, and cost-per-outcome as the governing metric. Use when the user asks what an agent loop or multi-agent workflow should be allowed to spend, wants token/cost budgets and caps for AI automation, or got a surprise bill from an agent fleet.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["agent-loop-design", "capacity-cost-model", "llm-eval-harness", "subagent-design"],
+  "tags": ["agent-budget", "token-budget", "cost-control", "agentic", "caps", "cost-per-outcome"],
+  "model": { "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." }
+}

package/skills/agent-budget/templates/budget-spec.md

@@ -0,0 +1,30 @@
+# Agent budget: {workflow name}
+
+> Outcome unit: {one successful …} · Status: {design-time [assumption] | calibrated on {N} runs} · Owner: {role}
+
+## Stage budgets
+
+| Stage | Tier | Why this tier | Expected / run | Cap (hard) | On cap |
+|---|---|---|---|---|---|
+| {stage} | light / standard / heavy | {one line} | {tokens ≈ ${…} `[assumption]`?} | {3–5× expected, tokens ≈ $; per-item + stage-wide for fan-out stages} | abort→escalate / degrade rung {n} / per-item: fail item to needs-human, continue rest |
+
+**Run-level cap:** ${number, < sum of stage caps in currency — the only unit that sums across tiers} — all stages capping at once is an anomaly to stop, not a run to finish.
+
+## Degradation ladder (in order; trigger and owner per rung)
+
+1. Narrow scope — {fewer items per run} · trigger: {…} · flipped by: {role}
+2. Reduce parallelism — {smaller fleet} · trigger: {…}
+3. Cut non-verification stages — {which} · trigger: {…}
+4. **Verification is never cut.** A workflow that can't afford its verifier can't afford to run.
+
+## Cost per outcome
+
+- **Target:** {spend ÷ successful outcomes} · review threshold: {value that triggers investigation}
+- **Comparison line:** the same outcome today costs {manual process, time × rate} — the number that says whether this is cheap.
+
+## Measurement
+
+- Spend logged per run, per stage (stage-tagged; feeds the loop spec's telemetry row)
+- {cadence} review of cost-per-outcome + cap-hit counts by {role}
+- Alerts: cap-hit rate rising ({threshold}) → drift investigation · run-level cap breached → incident, not a line item
+- Calibration: replace `[assumption]` expecteds after {~20} real runs · date: {…}

package/skills/agent-loop-design/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: agent-loop-design
+description: Design a supervised agent loop — the generate→verify→gate cycle, observable exit criteria, hard iteration cap, human gates at irreversible steps, and failure routes — as a loop spec a team can implement in any agent harness. Use when the user wants to automate a recurring task with an AI agent loop, design a work loop / review loop / research loop, or asks "how do I stop my agent from running forever or shipping junk".
+---
+
+# agent-loop-design
+
+You shouldn't be prompting agents; you should be designing the loops that prompt them — and a loop is only as good as its exits. This skill produces a **loop spec**: the states, gates, caps, and failure routes that turn "run the agent again until it looks right" into a system a team can trust unattended. `feature-implement-loop` is this repo's worked example of the pattern (generate → adversarial review → gate, capped at 3 rounds); this skill designs *new* loops for the user's own tasks. Fan-out inside a stage is `subagent-design`'s job; what the loop may spend is `agent-budget`'s.
+
+## How to respond
+
+1. **Pin the loop's job and its "done".** Ask at most 2 questions, spent on: *"what artifact does one successful run produce?"* and *"how would a human verify it's right without watching the run?"* The done-condition must be **observable** — tests pass, checklist satisfied, reviewer-agent returns zero blockers — never "output looks good". No observable done-condition derivable → the task isn't loop-ready; say what needs defining first. Non-interactive run (no user to ask): derive both from the input and tag `[assumption]`; no artifact derivable → emit `BLOCKED: need the task and its done-condition`.
+
+2. **Draw the state machine — generate, verify, gate, and nothing mushier.**
+   - **Generate**: produces or revises the artifact. Must consume the verifier's findings from the previous round as explicit input — a generate step that can't see why it failed is retry, not iteration.
+   - **Verify**: judges the artifact against the done-condition. **The verifier is never the generator** — same model grading its own homework inflates; use a different persona, prompt, or agent (`devils-advocate`-style adversarial framing where quality is the risk, or programmatic checks where they exist — cheapest adequate check wins, per `llm-eval-harness`'s grading ladder).
+   - **Gate**: routes on the verdict — pass → exit/handoff; fail → generate with findings; fail at cap → escalate. Every loop has exactly these three state types; "polish", "reflect", and "improve" states with no verdict are where loops go to wander.
+
+3. **Set the caps — both of them, as numbers.**
+   - **Revision cap**: max verify-fail rounds before escalation. Default 3 (`feature-implement-loop`'s cap); justify anything higher with what new information later rounds could possibly have.
+   - **Budget cap**: max spend per run, referencing an `agent-budget` line (or a stated token/cost number when no budget spec exists yet, tagged `[assumption]`). A loop without numeric caps is a runaway incident scheduled for later.
+
+4. **Place the human gates.** Every **irreversible or outward-facing action** — merge, deploy, send, publish, delete — sits behind a human gate: the loop stops and presents; it never proceeds on its own verdict. Reversible internal work (drafts, branches, scratch files) runs unattended; that's the point of the loop. Name each gate's presenter format: what the human sees must be a **decision-shaped digest** (the artifact + the verifier's verdict + what changed since the last gate), not a transcript.
+
+5. **Design the failure routes.** Three exits, each specified:
+   - **Cap hit** → escalate to a named role with a digest: rounds used, last findings, the diff of attempts. Raw logs are not an escalation.
+   - **Verifier can't judge** (input outside the done-condition's domain) → route out with `BLOCKED: <what's missing>`, don't loop on it.
+   - **Systemic failure** (same finding class every round) → stop early — identical findings twice means the generate step can't fix it; more rounds spend budget to relearn that.
+
+6. **Add the telemetry row and emit** with [`templates/loop-spec.md`](templates/loop-spec.md): per-run log of rounds-used, spend, verdict, and escalations — the numbers that tell you the loop is degrading before its output does (rounds-to-pass creeping up is the leading indicator). Emit the spec in one message: state machine (Mermaid `stateDiagram-v2`), caps, gates, failure routes, telemetry. Hand off: stage fan-out → `subagent-design`; the spend model → `agent-budget`; the verifier's golden set → `llm-eval-harness`.
+
+## Useful references in this skill
+
+- [`templates/loop-spec.md`](templates/loop-spec.md) — state machine, caps, gates, failure-route, and telemetry skeleton
+
+## Quality bar
+
+- **The done-condition is observable** — a person who didn't watch the run can check it in minutes.
+- **Verifier ≠ generator**, structurally: different persona, prompt, or program — stated in the spec, not implied.
+- **Both caps are numbers.** "Reasonable number of iterations" is not a cap; 3 is.
+- **Every irreversible action has a human gate**, and every gate has a decision-shaped digest format.
+- **Generate consumes findings.** The spec shows the findings flowing into the next round's input.
+- **All three failure routes are specified** — cap-hit, can't-judge, systemic — each with a destination.
+- **The Mermaid renders** and contains only generate/verify/gate states plus the human-gate and escalate exits — no "polish"/"reflect" states without a verdict.
+
+## When to use this skill
+
+- ✅ "I want an agent to keep our runbooks up to date / triage inbound bugs / draft weekly reports — design the loop"
+- ✅ "My agent keeps running forever / declaring victory on garbage" — retrofit exits onto an existing loop
+- ✅ Turning a one-shot prompt that "usually works" into something a team can run unattended
+- ✅ Reviewing a proposed automation for missing gates before it touches production
+
+## When NOT to use this skill
+
+- ❌ Implementing one feature right now — run `feature-implement-loop`; it *is* the loop
+- ❌ Splitting one task across parallel agents — `subagent-design`
+- ❌ Deciding what the loop may spend — `agent-budget`
+- ❌ One-off tasks — a loop for something that runs once is ceremony
+
+## Anti-patterns to avoid
+
+- ❌ **Self-grading.** The generator's model praising the generator's output is how confident garbage ships. The verifier is a different pass with an adversarial job description.
+- ❌ **Cap-free loops.** "It'll converge" is a hypothesis; the cap is what makes it a safe one to be wrong about.
+- ❌ **Vibes exits.** "Loop until the output is good" defers the definition of good to the loop's most tired moment.
+- ❌ **Retry cosplay.** If round N's generate can't see round N-1's findings, you built retry with extra steps — findings flow forward or the loop learns nothing.
+- ❌ **Transcript escalations.** Escalating a 40-page log teaches humans to ignore escalations. Digest: rounds, findings, attempts, the ask.
+- ❌ **Gating the reversible, freeing the irreversible.** Human approval for a draft file but auto-send on the customer email is the exact wrong way around — gate placement follows blast radius, not effort.
+- ❌ **Loops without telemetry.** A loop that doesn't log rounds-and-spend per run degrades silently until the quarter's token bill or a shipped defect announces it.

package/skills/agent-loop-design/evals/eval_queries.json

@@ -0,0 +1,11 @@
+[
+  { "query": "Design an agent loop to keep our runbooks up to date", "should_trigger": true },
+  { "query": "My agent keeps iterating forever — how do I add proper exit criteria?", "should_trigger": true },
+  { "query": "Turn this prompt we run by hand every week into a supervised automation loop", "should_trigger": true },
+  { "query": "Review this proposed agent automation for missing human gates", "should_trigger": true },
+
+  { "query": "Implement this user story with tests", "should_trigger": false },
+  { "query": "Split this task across parallel subagents", "should_trigger": false },
+  { "query": "How many tokens should this workflow be allowed to spend?", "should_trigger": false },
+  { "query": "Design the eval set for our LLM feature", "should_trigger": false }
+]

package/skills/agent-loop-design/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill_name": "agent-loop-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Design an agent loop that keeps our API reference docs in sync with the codebase: when endpoints change, the agent should update the docs, and we want to review before anything is published to the public docs site.",
+      "assertions": [
+        "One run's artifact and an observable done-condition are named (not 'docs look correct')",
+        "The state machine has exactly generate/verify/gate(/escalate) states, rendered as valid Mermaid stateDiagram-v2",
+        "The verifier is structurally different from the generator, with the independence stated",
+        "Both caps are numbers: a revision cap and a per-run budget line",
+        "Publishing to the public docs site sits behind a human gate with a decision-shaped digest format described",
+        "Findings from a failed verify flow into the next generate round explicitly",
+        "All three failure routes are specified: cap-hit escalation with digest, can't-judge BLOCKED route, systemic early-stop",
+        "A telemetry row logs rounds/spend/verdict per run with a review cadence",
+        "Hand-offs point to subagent-design for fan-out and agent-budget for the spend model"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "[Non-interactive run — no user available to answer questions] Design an agent loop.",
+      "assertions": [
+        "No loop is designed — the output is BLOCKED: need the task and its done-condition",
+        "No state machine or caps are fabricated"
+      ]
+    }
+  ]
+}

package/skills/agent-loop-design/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "agent-loop-design",
+  "version": "0.1.0",
+  "description": "Design a supervised agent loop — the generate→verify→gate cycle, observable exit criteria, hard iteration cap, human gates at irreversible steps, and failure routes — as a loop spec a team can implement in any agent harness. Use when the user wants to automate a recurring task with an AI agent loop, design a work loop / review loop / research loop, or asks \"how do I stop my agent from running forever or shipping junk\".",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["agent-budget", "devils-advocate", "feature-implement-loop", "llm-eval-harness", "subagent-design"],
+  "tags": ["agent-loop", "loop-engineering", "automation", "supervised-loop", "agentic", "guardrails"],
+  "model": { "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." }
+}

package/skills/agent-loop-design/templates/loop-spec.md

@@ -0,0 +1,46 @@
+# Loop spec: {loop name — the task, not the tech}
+
+> One run produces: {artifact} · Done when: {observable condition} · Owner: {role}
+
+## State machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Generate: {trigger}
+    Generate --> Verify: artifact + round log
+    Verify --> Gate: verdict + findings
+    Gate --> Generate: fail (findings feed next round)
+    Gate --> HumanGate: pass
+    Gate --> Escalate: fail at cap {N}
+    HumanGate --> [*]: approved → {irreversible action}
+    Escalate --> [*]: digest → {role}
+```
+
+## Caps
+
+| Cap | Value | Rationale |
+|---|---|---|
+| Revision cap | {N, default 3} | {what could later rounds know that round 3 didn't?} |
+| Budget per run | {tokens or currency; cite the `agent-budget` line, or a stated number tagged [assumption] until that spec exists} | {…} |
+
+## Verification (never the generator)
+
+- Verifier: {persona/prompt/program, and why it's independent of the generator}
+- Judges against: {the done-condition, itemized}
+- Cheapest adequate check: {programmatic where possible → structured assertions → LLM judge last}
+
+## Human gates
+
+| Gate | Guards (irreversible action) | Digest the human sees |
+|---|---|---|
+| {name} | {merge / send / deploy / delete} | {artifact + verdict + delta since last gate} |
+
+## Failure routes
+
+- **Cap hit** → {role} with digest: rounds used, last findings, attempt diffs
+- **Verifier can't judge** → `BLOCKED: {what's missing}` to {destination}
+- **Systemic** (same finding class twice) → stop early, route to {role}
+
+## Telemetry (per run)
+
+rounds-used · spend · verdict · escalated? — reviewed {cadence} by {role}; alert when rounds-to-pass trends up {threshold}.

package/skills/ai-usage-report/SKILL.md

@@ -95,7 +95,7 @@ The skill has **no magic classifier**. It exposes a set of signals the user inte
 
 ## When NOT to use this skill
 
-- ❌ You don't have usage telemetry yet — the skill consumes data, doesn't collect it. See [[ai-usage-telemetry-design]] for the collection side.
+- ❌ You don't have usage telemetry yet — the skill consumes data, doesn't collect it. The collection-side spec (event schema, MCP server) lives in the skilldrop repo at `docs/designs/ai-usage-telemetry-design.md`.
 - ❌ You want to *judge* specific named people. The skill surfaces patterns; performance judgments based on AI usage are a different (and harder) decision.
 - ❌ The input lacks every effectiveness field. You can still produce a volume report, but call out the limitation explicitly — don't ship a report that looks like effectiveness analysis when it isn't.
 - ❌ Your team is < 5 people *and* the view is team-rollup. Aggregate views aren't anonymous at that size.

package/skills/devils-advocate/manifest.json

@@ -6,6 +6,9 @@
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["design-doc", "doc-critique"],
+  "hooks": [
+    { "event": "pre-commit-review", "action": "devils-advocate", "description": "adversarially review staged changes before they land" }
+  ],
   "tags": ["review", "code-review", "adversarial", "edge-cases", "future-proofing", "test-coverage", "dev-workflow"],
   "model": { "tier": "heavy", "rationale": "Adversarial code review across four lenses. Cheaper models miss edge cases and under-call severity. Never downgrade." }
 }

package/skills/subagent-design/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: subagent-design
+description: Decompose a task into an orchestrator and subagents — one-mission role cards with typed output contracts, a topology (pipeline / parallel / judge panel) chosen with a reason, context-isolation rationale, and a verification stage that is never a generator. Use when the user wants to fan work out across multiple agents, design a multi-agent workflow or orchestration, or asks "should this be one agent or several".
+---
+
+# subagent-design
+
+Produces an **orchestration plan**: which subagents exist, what each one alone is for, how their outputs compose, and who checks the result. The default answer to "should this be several agents?" is **no** — one context that fits is always simpler; fan out only when a plan survives step 1. Two skilldrop skills are ready-made instances of the patterns worth copying — `council-review` (a judge panel of independent perspectives) and `devils-advocate` (an adversarial verifier that isn't the generator) — cite them as patterns even where they aren't installed. Loop mechanics around the fan-out belong to `agent-loop-design`; what the fleet may spend belongs to `agent-budget`.
+
+## How to respond
+
+1. **Justify the fan-out or refuse it.** Exactly three reasons earn multiple agents — name which applies, or recommend a single agent and stop:
+   - **Context separation**: the task spans more material than one context holds well, and it partitions cleanly (per-module audit, per-source research).
+   - **Independence**: judgments must not contaminate each other — reviewers, estimators, hypothesis-testers whose value is that they haven't seen each other's answers.
+   - **Role conflict**: one agent can't hold both jobs honestly — the generator must not grade itself; the negotiator must not also be the auditor.
+
+   "It would be faster" alone is not on the list — parallelism is a consequence of separation, not a reason to manufacture it. Non-interactive run (no user to ask): derive the task from the input, tag assumptions `[assumption]`; no task derivable → emit `BLOCKED: need the task being decomposed`.
+
+2. **Write one role card per agent** — the plan's core, using [`templates/orchestration-plan.md`](templates/orchestration-plan.md). Each card: **mission** (one sentence, one job — an agent with "and" in its mission is two agents or one agent over-split; a mission repeated across items is one card with a ×N multiplier, and splitting one item's work into separate per-check cards is worth the extra invocations only when the isolation or tier difference pays for it), **inputs** (exactly what it's given — and, as important, what it's *denied*: the context-isolation line states what this agent must not see, e.g. a judge never sees the other judges' verdicts), **output contract** (a typed schema — fields and types, not "a summary"; prose outputs make aggregation a second AI task you didn't budget), **tools/permissions** (least privilege: a research agent gets read, never write), and **failure behavior** (what it returns when it can't do the job — a structured `BLOCKED`/empty result, never improvisation).
+
+3. **Pick the topology, with the reason attached:**
+   - **Pipeline** — stages feed forward; item B needn't wait for item A's later stages. The default for multi-stage work.
+   - **Parallel + barrier** — only when a stage genuinely needs *all* prior results at once (dedup across findings, a zero-count early exit). A barrier "because the stages feel separate" burns wall-clock for tidiness.
+   - **Judge panel** — N independent attempts or verdicts, then score/merge (`council-review`'s shape). For wide solution spaces and contested judgments; specify the vote rule (majority, unanimous-to-kill) up front.
+   - **Depth cap: one level.** Subagents spawning subagents needs a written justification; two levels of delegation is where accountability and budgets go to disappear.
+
+4. **Design the aggregation and verification stage.** Aggregation is code-shaped where possible (merge schemas, dedup by key) — an "aggregator agent" summarizing prose is a smell that the output contracts were too loose. Verification is a **separate stage with an adversarial job description** (`devils-advocate` framing): it tries to refute, and its verdict gates the result. The orchestrator trusts contracts, not content — a subagent's confident prose is not evidence; count only schema-valid outputs, and route contract violations to the failure path, never into the merge.
+
+5. **Attach the budget line and emit.** Per-agent tier (light/standard/heavy — the repo's routing abstraction; most fan-out workers are one tier below the orchestrator's instinct) and the fleet's cap per run, referencing an `agent-budget` spec or tagging the numbers `[assumption]`. Emit in one message: fan-out justification, role cards, topology (Mermaid `flowchart`) with the reason, aggregation + verification, budget line. Hand off: the loop around this fan-out → `agent-loop-design`; the full spend model → `agent-budget`; implementing a coding task through it → `feature-implement-loop`.
+
+## Useful references in this skill
+
+- [`templates/orchestration-plan.md`](templates/orchestration-plan.md) — role cards, topology diagram, aggregation/verification, budget line
+
+## Quality bar
+
+- **The fan-out is justified by one of the three reasons, by name** — or the plan says "one agent" and means it.
+- **Every mission is one sentence with no "and".** Two jobs, two cards.
+- **Every output contract is typed.** A reader could write the JSON schema from the card.
+- **Isolation lines are explicit** — each card says what the agent is denied and why.
+- **The topology has its reason attached**, and any barrier names the cross-item dependency that earns it.
+- **Verification is adversarial and separate** — never the generator, never "the orchestrator double-checks".
+- **The budget line exists** — per-agent tier + fleet cap, sourced or tagged.
+
+## When to use this skill
+
+- ✅ "Should this be one agent or several?" — including when the honest answer is one
+- ✅ Designing a multi-agent review, audit, research sweep, or migration
+- ✅ A fan-out exists but produces mush — retrofit contracts, isolation, and verification
+- ✅ Choosing between pipeline, barrier, and judge-panel shapes for a workflow
+
+## When NOT to use this skill
+
+- ❌ Designing the loop that wraps the fan-out (caps, gates, exits) — `agent-loop-design`
+- ❌ Setting the spend policy — `agent-budget`
+- ❌ Running a multi-perspective review right now — `council-review` is the panel, ready-made
+- ❌ Implementing one story — `feature-implement-loop`
+
+## Anti-patterns to avoid
+
+- ❌ **Fan-out as a lifestyle.** Five agents doing what one context does well is five times the cost for a coordination tax. The burden of proof is on splitting.
+- ❌ **Prose contracts.** "Each agent reports its findings" guarantees an unmergeable pile and a surprise summarization stage. Schemas or it didn't happen.
+- ❌ **Contaminated judges.** A panel that sees each other's verdicts is one opinion with extra steps — independence is the entire value.
+- ❌ **The trusting orchestrator.** Merging whatever comes back because it arrived confidently. Contract-invalid output goes to the failure route, not the report.
+- ❌ **Unbounded depth.** Subagents spawning subagents until nobody can say who decided what or spent which tokens.
+- ❌ **Barrier by aesthetics.** Synchronizing stages because the diagram looks cleaner — pay wall-clock only for a named cross-item dependency.
+- ❌ **Verifier-free fleets.** Ten generators and no refuter ships ten agents' worth of plausible-but-wrong at fleet speed.

package/skills/subagent-design/evals/eval_queries.json

@@ -0,0 +1,11 @@
+[
+  { "query": "Should this task be one agent or several?", "should_trigger": true },
+  { "query": "Design a multi-agent workflow to audit all our repos", "should_trigger": true },
+  { "query": "My agent fan-out produces mush — help me add contracts and verification", "should_trigger": true },
+  { "query": "Pipeline or parallel for this multi-stage agent job?", "should_trigger": true },
+
+  { "query": "Design the loop with exit criteria and human gates for this automation", "should_trigger": false },
+  { "query": "Set a token budget for our agent workflows", "should_trigger": false },
+  { "query": "Run a council review on this architecture decision", "should_trigger": false },
+  { "query": "Implement this feature with tests", "should_trigger": false }
+]

package/skills/subagent-design/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "subagent-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Design a multi-agent workflow to audit our 40-repo GitHub org for secrets committed to git history, hardcoded credentials, and misconfigured CI permissions. Results should end up as one prioritized report.",
+      "assertions": [
+        "The fan-out is justified by name (context separation across 40 repos) rather than assumed",
+        "Every role card has a one-sentence single mission with no 'and'",
+        "Every output contract is a typed schema, not 'reports its findings'",
+        "Each card states what the agent is denied seeing (isolation) and least-privilege tools (read-only for auditors)",
+        "The topology is named with its reason; any barrier names the cross-item dependency (e.g. dedup before prioritization)",
+        "A separate adversarial verification stage gates findings before the report — verifier is not a generator",
+        "Contract-invalid subagent output routes to a failure path, not the merged report",
+        "Depth is capped at one level",
+        "A budget line gives per-agent tiers and a fleet cap, sourced or tagged [assumption]",
+        "A Mermaid flowchart of the topology is emitted with valid syntax"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Should I use multiple agents to write a single 500-word blog post from an outline I already have?",
+      "assertions": [
+        "The skill recommends a single agent — the task fits one context and no fan-out reason applies",
+        "The three-reasons test is applied explicitly rather than a fan-out being designed anyway"
+      ]
+    }
+  ]
+}

package/skills/subagent-design/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "subagent-design",
+  "version": "0.1.0",
+  "description": "Decompose a task into an orchestrator and subagents — one-mission role cards with typed output contracts, a topology (pipeline / parallel / judge panel) chosen with a reason, context-isolation rationale, and a verification stage that is never a generator. Use when the user wants to fan work out across multiple agents, design a multi-agent workflow or orchestration, or asks \"should this be one agent or several\".",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["agent-budget", "agent-loop-design", "council-review", "devils-advocate", "feature-implement-loop"],
+  "tags": ["subagents", "orchestration", "multi-agent", "fan-out", "agentic", "role-cards"],
+  "model": { "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." }
+}

package/skills/subagent-design/templates/orchestration-plan.md

@@ -0,0 +1,47 @@
+# Orchestration plan: {task}
+
+> Fan-out justification: {context separation | independence | role conflict} — {one line why}. If none applies, this document should instead say: use one agent.
+
+## Role cards
+
+### {agent-name}
+- **Mission:** {one sentence, one job, no "and"}
+- **Inputs:** {exactly what it receives}
+- **Denied (isolation):** {what it must not see, and why}
+- **Output contract:** `{ field: type, field: type }` — schema, not prose
+- **Tools/permissions:** {least privilege}
+- **On failure:** {structured BLOCKED/empty return — never improvisation}
+- **Tier:** {light | standard | heavy} — {why this tier suffices}
+
+<!-- one card per agent role (use ×N in the name for a mission repeated per item), and always include a card for the orchestrator itself -->
+
+## Topology
+
+**Shape:** {pipeline | parallel+barrier | judge panel} — **because** {the named dependency or independence requirement}.
+{If barrier: the cross-item dependency that earns it. If judge panel: the vote rule.}
+**Depth:** one level. {Justification here if any agent spawns agents.}
+
+```mermaid
+flowchart LR
+    O[orchestrator] --> A[{agent}]
+    O --> B[{agent}]
+    A --> V{verify}
+    B --> V
+    V -->|pass| OUT[{artifact}]
+    V -->|refuted| F[failure route]
+```
+
+## Aggregation & verification
+
+- **Aggregation:** {code-shaped merge — dedup key, schema union}; contract-invalid output → failure route, never the merge
+- **Verification:** {adversarial verifier — persona/prompt, independent of all generators}; verdict gates the result
+- **Vote rule:** {panels: e.g. finding survives unless 2 of 3 refute · single verifier: "ships unless refuted"}
+
+## Budget line
+
+Fleet cap per run: {tokens/currency} `[source: agent-budget spec | assumption]` · Worker tiers as carded above · On cap: {stop and escalate — see the loop spec}
+
+## Hand-offs
+
+- Loop wrapping this fan-out (caps, gates, exits) → `agent-loop-design`
+- Full spend model → `agent-budget`