skilldrop-cli 0.16.29 → 0.16.30

package/bin/skilldrop.js

@@ -71,8 +71,10 @@ Usage:
                                           in SKILL.md before you trust a catalog (RFC-0022)
   skilldrop new-skill <name> --pack <p>   scaffold a skill in the catalog you're in (for catalog authors;
                                           --tier light|standard|heavy, default standard)
-  skilldrop loop-stats [<file>] [--days N]  summarise the opt-in loop run log (SKILLDROP_LOOP_LOG):
-                                          which gates pass first time, loop back, or block. Local only.
+  skilldrop loop-stats [<file>...] [--days N] [--json | --html <out>]  summarise the opt-in loop
+                                          run log (SKILLDROP_LOOP_LOG): which gates pass first time, loop
+                                          back, or block. Several files (logs or others' --json) combine
+                                          into one view; --html writes a page that loads nothing. Local only.
   skilldrop init-catalogue <dir> [--pack <name>]  start a private catalogue for your team's skills
   skilldrop package <dir> [--pack a,b] [--skills x,y] [--agents]  copy a vetted subset of a catalogue
                                           into a standalone one to host internally (writes MIRROR.json)
@@ -147,7 +149,7 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--pack" || a === "--ide" || a === "--dest" || a === "--from" || a === "--panel" || a === "--profile" || a === "--tier" || a === "--skills" || a === "--days" ||
-        a === "--policy" || a === "--merge" || a === "--label" || a === "--last") out.flags[a.slice(2)] = argv[++i];
+        a === "--policy" || a === "--merge" || a === "--label" || a === "--last" || a === "--html") out.flags[a.slice(2)] = argv[++i];
     else if (a.startsWith("--")) out.flags[a.slice(2)] = true;
     else out._.push(a);
   }
@@ -1789,47 +1791,172 @@ function newSkill(args) {
 
 /* loop-stats: summarise the opt-in run log loops append to when SKILLDROP_LOOP_LOG is set.
    Local only — the file is the user's, nothing is sent anywhere. Answers the questions a team
-   asks of its loops: which gates pass first time, which keep looping back, which block. */
+   asks of its loops: which gates pass first time, which keep looping back, which block.
+   Several inputs are combined: each is a run log (JSONL) or another person's `--json` summary,
+   so a team can pool its numbers by passing files around, never through a service. */
+const LOOP_CLASSES = ["pass", "conditional", "revise", "redirect", "blocked", "unknown"];
+
+function isoWeek(ts) {
+  const d = new Date(ts);
+  if (isNaN(d)) return null;
+  const t = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  t.setUTCDate(t.getUTCDate() + 4 - (t.getUTCDay() || 7));            // the week's Thursday
+  const y = t.getUTCFullYear();
+  const wk = Math.ceil(((t - Date.UTC(y, 0, 1)) / 864e5 + 1) / 7);
+  return `${y}-W${String(wk).padStart(2, "0")}`;
+}
+
 function loopStats(args) {
-  const file = args._[0] || process.env.SKILLDROP_LOOP_LOG || path.join(".skilldrop", "loop-log.jsonl");
-  const raw = readIfPresent(file, null);
-  if (raw === null)
-    die(`no run log at ${file}.\n       Turn it on: export SKILLDROP_LOOP_LOG="$PWD/.skilldrop/loop-log.jsonl" — each loop then appends one line per gate verdict.`);
+  const inputs = args._.length ? args._ : [process.env.SKILLDROP_LOOP_LOG || path.join(".skilldrop", "loop-log.jsonl")];
   const days = Number(args.flags.days) || 0;
   const since = days ? Date.now() - days * 864e5 : 0;
-  const rows = [], bad = [];
-  raw.split(/\r?\n/).forEach((line, i) => {
-    if (!line.trim()) return;
-    try {
-      const r = JSON.parse(line);
-      if (!r.loop || !r.verdict) throw new Error("missing loop or verdict");
-      if (since && Date.parse(r.ts) < since) return;
-      rows.push(r);
-    } catch (e) { bad.push(i + 1); }
-  });
   const terms = (() => { try { return readJSON(path.join(ROOT, "contracts", "terminals.json")); } catch (e) { return {}; } })();
   // Verdict classes come from the shared vocabulary (RFC-0028), so a new verdict word is
   // classified the same way here as in the loops.
   const classOf = (v) => ((terms.verdicts || {})[v] || {}).class || (/BLOCK/.test(v) ? "blocked" : "unknown");
   const by = {};
-  for (const r of rows) {
-    const k = `${r.loop}  ${r.gate || "-"} (${r.stage || "?"})`;
-    const g = by[k] = by[k] || { n: 0, verdicts: {}, firstPass: 0, firsts: 0, blocked: 0, rounds: [] };
-    g.n++; g.verdicts[r.verdict] = (g.verdicts[r.verdict] || 0) + 1;
-    const cls = classOf(r.verdict);
-    if (Number(r.round) === 1) { g.firsts++; if (cls === "pass" || cls === "conditional") g.firstPass++; }
-    if (cls === "blocked") g.blocked++;
-    if (r.round) g.rounds.push(Number(r.round));
-  }
-  if (args.flags.json) return emitJSON({ file, entries: rows.length, skipped: bad.length, gates: by });
-  console.log(`${rows.length} gate verdict(s) in ${file}${days ? ` from the last ${days} days` : ""}\n`);
+  let entries = 0, skipped = 0, summaries = 0;
+  const gateOf = (k, r) => by[k] = by[k] || { loop: r.loop, gate: r.gate || null, stage: r.stage || null, n: 0,
+    verdicts: {}, firstPass: 0, firsts: 0, blocked: 0, maxRound: 0, rounds: {}, weeks: {} };
+  const keyOf = (r) => `${r.loop}  ${r.gate || "-"} (${r.stage || "?"})`;
+
+  for (const file of inputs) {
+    const raw = readIfPresent(file, null);
+    if (raw === null)
+      die(`no run log at ${file}.\n       Turn it on: export SKILLDROP_LOOP_LOG="$PWD/.skilldrop/loop-log.jsonl" — each loop then appends one line per gate verdict.`);
+    let summary = null;
+    try { const o = JSON.parse(raw); if (o && typeof o === "object" && o.gates) summary = o; } catch (e) { /* a run log */ }
+    if (summary) {
+      // Someone else's `loop-stats --json`: add its counts in. Its own --days already applied.
+      summaries++;
+      entries += Number(summary.entries) || 0; skipped += Number(summary.skipped) || 0;
+      for (const [k, s] of Object.entries(summary.gates)) {
+        const m = /^(\S+)\s+(\S+)\s+\((.*)\)$/.exec(k) || [];
+        const g = gateOf(k, { loop: s.loop || m[1] || k, gate: s.gate || (m[2] !== "-" ? m[2] : null), stage: s.stage || m[3] });
+        g.n += Number(s.n) || 0; g.firstPass += Number(s.firstPass) || 0; g.firsts += Number(s.firsts) || 0;
+        g.blocked += Number(s.blocked) || 0;
+        for (const [v, n] of Object.entries(s.verdicts || {})) g.verdicts[v] = (g.verdicts[v] || 0) + Number(n);
+        // 0.16.29 and earlier wrote `rounds` as a list of round numbers; later, as counts.
+        const rounds = Array.isArray(s.rounds) ? s.rounds.reduce((a, r) => (a[r] = (a[r] || 0) + 1, a), {}) : s.rounds || {};
+        for (const [r, n] of Object.entries(rounds)) g.rounds[r] = (g.rounds[r] || 0) + Number(n);
+        g.maxRound = Math.max(g.maxRound, Number(s.maxRound) || 0, ...Object.keys(rounds).map(Number));
+        for (const [w, cls] of Object.entries(s.weeks || {})) {
+          const into = g.weeks[w] = g.weeks[w] || {};
+          for (const [c, n] of Object.entries(cls)) into[c] = (into[c] || 0) + Number(n);
+        }
+      }
+      continue;
+    }
+    raw.split(/\r?\n/).forEach((line) => {
+      if (!line.trim()) return;
+      let r;
+      try {
+        r = JSON.parse(line);
+        if (!r.loop || !r.verdict) throw new Error("missing loop or verdict");
+      } catch (e) { skipped++; return; }
+      if (since && Date.parse(r.ts) < since) return;
+      entries++;
+      const g = gateOf(keyOf(r), r);
+      g.n++; g.verdicts[r.verdict] = (g.verdicts[r.verdict] || 0) + 1;
+      const cls = classOf(r.verdict);
+      if (Number(r.round) === 1) { g.firsts++; if (cls === "pass" || cls === "conditional") g.firstPass++; }
+      if (cls === "blocked") g.blocked++;
+      if (r.round) { g.rounds[r.round] = (g.rounds[r.round] || 0) + 1; g.maxRound = Math.max(g.maxRound, Number(r.round)); }
+      const w = isoWeek(r.ts);
+      if (w) { const into = g.weeks[w] = g.weeks[w] || {}; into[cls] = (into[cls] || 0) + 1; }
+    });
+  }
+  const sources = inputs.length;
+  if (args.flags.json)
+    return emitJSON({ sources, entries, skipped, ...(days ? { days } : {}), gates: by });
+  if (args.flags.html) {
+    const out = typeof args.flags.html === "string" ? args.flags.html : "loop-stats.html";
+    fs.writeFileSync(out, loopStatsHtml(by, { sources, entries, days, classOf }));
+    console.log(`wrote ${out}: ${entries} gate verdict(s) from ${sources} file(s). It loads nothing from the network; open it in any browser.`);
+    return;
+  }
+  const from = sources === 1 ? inputs[0] : `${sources} files`;
+  console.log(`${entries} gate verdict(s) in ${from}${days ? ` from the last ${days} days` : ""}\n`);
   for (const [k, g] of Object.entries(by).sort()) {
     const mix = Object.entries(g.verdicts).sort((a, b) => b[1] - a[1]).map(([v, n]) => `${v} ${n}`).join(", ");
     const fp = g.firsts ? `${Math.round(100 * g.firstPass / g.firsts)}% pass first time` : "no first-round entries";
-    const maxRound = g.rounds.length ? Math.max(...g.rounds) : 0;
-    console.log(`${k}\n  ${g.n} verdict(s): ${mix}\n  ${fp} · ${g.blocked} blocked · longest run ${maxRound} round(s)`);
-  }
-  if (bad.length) console.log(`\n${bad.length} line(s) skipped as unreadable: ${bad.slice(0, 10).join(", ")}${bad.length > 10 ? "…" : ""}`);
+    console.log(`${k}\n  ${g.n} verdict(s): ${mix}\n  ${fp} · ${g.blocked} blocked · longest run ${g.maxRound} round(s)`);
+  }
+  if (summaries && days) console.log(`\n--days applies to run logs only; the ${summaries} summary file(s) were counted as written.`);
+  if (skipped) console.log(`\n${skipped} line(s) skipped as unreadable.`);
+}
+
+/* The dashboard: one self-contained page, no script, and a policy that lets it load nothing,
+   so it can be opened from an email or a shared drive and sent on without leaking anything. */
+function loopStatsHtml(by, { sources, entries, days, classOf }) {
+  const esc = (x) => String(x).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  const label = { pass: "passed", conditional: "passed with conditions", revise: "sent back",
+                  redirect: "redirected", blocked: "blocked", unknown: "other" };
+  const allWeeks = [...new Set(Object.values(by).flatMap((g) => Object.keys(g.weeks)))].sort().slice(-12);
+  const bar = (counts, total) => LOOP_CLASSES.filter((c) => counts[c]).map((c) =>
+    `<span class="seg ${c}" style="width:${(100 * counts[c] / total).toFixed(2)}%" title="${esc(`${counts[c]} ${label[c]}`)}"></span>`).join("");
+  const loops = {};
+  for (const [k, g] of Object.entries(by)) (loops[g.loop] = loops[g.loop] || []).push([k, g]);
+  const sections = Object.keys(loops).sort().map((loop) => {
+    const rows = loops[loop].sort((a, b) => String(a[1].gate).localeCompare(String(b[1].gate))).map(([, g]) => {
+      const byClass = {};
+      for (const [v, n] of Object.entries(g.verdicts)) byClass[classOf(v)] = (byClass[classOf(v)] || 0) + n;
+      const fp = g.firsts ? Math.round(100 * g.firstPass / g.firsts) : null;
+      const mix = Object.entries(g.verdicts).sort((a, b) => b[1] - a[1]).map(([v, n]) => `${esc(v)} ${n}`).join(", ");
+      const peak = Math.max(1, ...allWeeks.map((w) => Object.values(g.weeks[w] || {}).reduce((a, b) => a + b, 0)));
+      const spark = allWeeks.map((w) => {
+        const c = g.weeks[w] || {}, t = Object.values(c).reduce((a, b) => a + b, 0);
+        return `<span class="wk" title="${esc(`${w}: ${t} verdict(s)`)}"><span class="col" style="height:${(100 * t / peak).toFixed(0)}%">${t ? bar(c, t).replace(/width:/g, "height:") : ""}</span></span>`;
+      }).join("");
+      return `<tr><th scope="row">${esc(g.gate || "-")}<small>${esc(g.stage || "")}</small></th><td class="num">${g.n}</td>` +
+        `<td class="num">${fp === null ? "–" : fp + "%"}</td><td class="num">${g.blocked}</td><td class="num">${g.maxRound}</td>` +
+        `<td><div class="mix" role="img" aria-label="${esc(mix)}">${bar(byClass, g.n)}</div><small>${mix}</small></td>` +
+        `<td><div class="spark" role="img" aria-label="verdicts per week">${spark}</div></td></tr>`;
+    }).join("\n");
+    return `<section><h2>${esc(loop)}</h2><table><thead><tr><th>Gate</th><th>Verdicts</th><th>Pass first time</th>` +
+      `<th>Blocked</th><th>Longest run</th><th>Mix</th><th>Per week</th></tr></thead><tbody>\n${rows}\n</tbody></table></section>`;
+  }).join("\n");
+  const legend = LOOP_CLASSES.filter((c) => c !== "unknown").map((c) => `<span><i class="seg ${c}"></i>${label[c]}</span>`).join("");
+  const weeks = allWeeks.length ? `${allWeeks[0]} to ${allWeeks[allWeeks.length - 1]}` : "no dated entries";
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Loop gates: where work gets stuck</title>
+<style>
+:root{color-scheme:light dark;--bg:#fafaf9;--fg:#17171a;--muted:#5c5c58;--line:#e4e4e0;--card:#fff}
+@media (prefers-color-scheme:dark){:root{--bg:#16161b;--fg:#ececf1;--muted:#a3a3ad;--line:#2f2f38;--card:#1d1d23}}
+body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif}
+main{max-width:1100px;margin:0 auto;padding:2rem 1.2rem}
+h1{font-size:1.6rem;margin:0 0 .3rem}p.sub{color:var(--muted);margin:0 0 1.2rem}
+section{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:1rem 1.2rem;margin:0 0 1rem;overflow-x:auto}
+h2{font-size:1.1rem;margin:0 0 .6rem;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+table{border-collapse:collapse;width:100%;table-layout:fixed;min-width:820px}
+thead th:nth-child(1){width:9%}thead th:nth-child(2),thead th:nth-child(4),thead th:nth-child(5){width:9%}thead th:nth-child(3){width:11%}thead th:nth-child(7){width:17%}th,td{text-align:left;padding:.45rem .5rem;border-top:1px solid var(--line);vertical-align:top}
+thead th{border-top:0;font-size:.78rem;color:var(--muted);font-weight:600}
+th small,td small{display:block;color:var(--muted);font-size:.78rem;font-weight:400}
+td.num{text-align:right;font-variant-numeric:tabular-nums;white-space:nowrap}
+.mix{display:flex;height:14px;border-radius:7px;overflow:hidden;background:var(--line)}
+.seg{display:block}.pass{background:#15803d}.conditional{background:#65a30d}.revise{background:#d97706}
+.redirect{background:#7c3aed}.blocked{background:#b91c1c}.unknown{background:#78716c}
+.spark{display:flex;align-items:flex-end;gap:2px;height:36px;}
+.wk{flex:1;height:100%;display:flex;align-items:flex-end}.col{display:flex;flex-direction:column-reverse;width:100%;min-height:1px;background:var(--line)}
+.legend{display:flex;flex-wrap:wrap;gap:.4rem 1rem;margin:0 0 1rem;color:var(--muted);font-size:.85rem}
+.legend i{display:inline-block;width:.8rem;height:.8rem;border-radius:2px;margin-right:.35rem;vertical-align:-1px}
+ul{margin:.3rem 0 0;padding-left:1.2rem}
+</style></head><body><main>
+<h1>Loop gates: where work gets stuck</h1>
+<p class="sub">${entries} gate verdict(s) from ${sources} file(s)${days ? `, the last ${days} days` : ""} · weeks shown: ${esc(weeks)} · generated ${esc(new Date().toISOString().slice(0, 10))} by skilldrop loop-stats. Nothing here came from or goes to a server.</p>
+<div class="legend">${legend}</div>
+${sections || "<section><p>No gate verdicts yet.</p></section>"}
+<section><h2>Reading it</h2><ul>
+<li><b>A gate that rarely passes first time</b> usually points upstream: look at what the stage before it hands over.</li>
+<li><b>Frequent blocked</b> means a missing input. The loop's output names what was missing.</li>
+<li><b>A gate that always passes</b> may not be checking anything. Read a few of its reviews.</li>
+<li>Don't rank people by these numbers. A hard change loops more than an easy one.</li>
+</ul></section>
+</main></body></html>
+`;
 }
 
 /* init-catalogue <dir>: start a private catalogue (an internal mirror or a team's own skills)

package/catalogue.json

@@ -17,7 +17,8 @@
         "nfr-spec",
         "success-metrics",
         "user-story-splitter",
-        "user-journey-map"
+        "user-journey-map",
+        "feedback-synthesis"
       ]
     },
     "design-the-system": {
@@ -38,7 +39,8 @@
         "agent-loop-design",
         "subagent-design",
         "agent-budget",
-        "terraform-module"
+        "terraform-module",
+        "mcp-pairing"
       ]
     },
     "build-and-review-software": {
@@ -60,7 +62,9 @@
         "llm-eval-harness",
         "eval-harness-generator",
         "backlog-triage",
-        "tracker-brief-sync"
+        "tracker-brief-sync",
+        "dependency-upgrade-review",
+        "codebase-tour"
       ]
     },
     "build-on-the-claude-api": {

package/model-routing.json

@@ -190,6 +190,10 @@
       "tier": "standard",
       "rationale": "A stdlib script does the aggregation; the model maps columns, checks evidence and computes savings with shown arithmetic against a fixed category checklist, which is bounded judgment."
     },
+    "codebase-tour": {
+      "tier": "standard",
+      "rationale": "Reading a repo and citing what it finds is generation over evidence; every claim is checked against a file, so a mid tier is enough."
+    },
     "content-design": {
       "tier": "standard",
       "rationale": "Rewrites source text from user needs under fixed plain-language rules, with a script for the readability numbers. Prioritising questions needs judgment, but facts come from the source."
@@ -222,6 +226,10 @@
       "tier": "standard",
       "rationale": "A stdlib script computes every number; the model maps columns, checks data quality and interprets weekly trends against fixed DORA definitions, which is bounded judgment."
     },
+    "dependency-upgrade-review": {
+      "tier": "standard",
+      "rationale": "Reads a version diff, changelogs and CI evidence against a fixed checklist; the merge verdict follows from what is verified, not open-ended judgment."
+    },
     "design-doc": {
       "tier": "standard",
       "rationale": "Synthesizes a design doc from a brief. Escalate to heavy via large-input or ambiguous-input when alternatives are genuinely contested."
@@ -254,6 +262,10 @@
       "tier": "standard",
       "rationale": "Code + test generation against acceptance criteria. The adversarial pass delegates to devils-advocate (heavy) where available; the loop itself is generation."
     },
+    "feedback-synthesis": {
+      "tier": "standard",
+      "rationale": "Coding feedback into themes is bounded judgment; the counts by distinct person and segment come from its script."
+    },
     "figma-diagrams": {
       "tier": "standard",
       "rationale": "API calls + spec generation. Bounded transformation."
@@ -298,6 +310,10 @@
       "tier": "standard",
       "rationale": "Writes short copy to fit and fills a spec for a deterministic builder. Bounded generation."
     },
+    "mcp-pairing": {
+      "tier": "standard",
+      "rationale": "Matching a loop's stages to the context each needs and the narrowest access that provides it is bounded judgment over a short checklist."
+    },
     "md-to-docx": {
       "tier": "standard",
       "rationale": "A stdlib script does the conversion; the model restructures the Markdown so it converts cleanly (heading levels, footnotes, HTML), reads each warning and explains the losses. Bounded editing, no open-ended generation."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.29",
+  "version": "0.16.30",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, 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",

package/packs/ai-engineering/skills/mcp-pairing/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: mcp-pairing
+description: Recommend which MCP servers to connect for a loop, workflow or task, stage by stage, with the narrowest access that works — what outside context or action each stage needs, the server that provides it (only ones the user named or the vendor officially publishes), the scopes to grant (read-only by default, never write on a review or gate stage), what it must not be able to do, the export-file fallback that keeps the stage running without it, and which stages need no server at all. Use when the user asks "which MCP servers should we hook up for this loop", "what should our agent connect to", "what token scopes does this stage need", "is this MCP setup too broad", or wants to wire GitHub, GitLab, Jira, Linear, Slack, Sentry, Grafana or a database into an agent workflow.
+---
+
+# mcp-pairing
+
+Turns a loop, workflow or task into a per-stage connection plan: which stages get an MCP
+server, which get none, and the exact access each one holds. An MCP server is a capability
+handed to the agent with someone's credentials, so the default answer for every stage is
+**fewer servers, read-only, scoped to one project**, and every grant beyond that is argued
+from the stage's output. The plan stays honest about names: it never invents a server,
+package or URL.
+
+Complements `agent-threat-model`, which audits a finished capability surface for data
+exfiltration paths. This skill decides what the surface should be in the first place;
+that one attacks it.
+
+## How to respond
+
+**Four rules come before the steps and outrank them:**
+
+- **Answer what was asked, first.** Open with the plan in plain words: how many servers, which ones, read or write, and which stages need none. The table comes after.
+- **Use only what you were given.** Name only the tools, servers, stages and scopes the input contains, plus vendors' own official servers under the naming rule in step 3. Never invent a package, endpoint, URL or version. What the plan needs and doesn't have is listed once at the end under "To confirm".
+- **Deliver from what you have.** When the request names a loop, workflow or task, state the assumptions in a line and produce the plan. When it names nothing to pair, ask for it in one or two plain sentences and say what the plan will contain once it arrives.
+- **Write for someone who has never heard of this skill.** No skill names, no paths from this folder, no internal terms, nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
+
+1. **List the stages and what each one produces.** From a named skilldrop loop, use its stage list and the stage types in [`reference.md`](reference.md) (generate, verify, gate). From a described workflow, write the stages as verbs with one output each — ✅ *"triage: one ticket labelled with severity"* — ❌ *"handle tickets"*. Mark each stage's **type** and its **cadence** (per change, daily, weekly, monthly). Ask at most 2 questions, spent on the tools in use and who can write into them; everything else is tagged `[assumption]`.
+
+2. **Name the outside context or action each stage needs, by category.** Categories: tracker issues, repo / merge request / diff, CI status, docs and wiki, logs / metrics / traces, error events, design files, chat history, database read, cloud billing, web. A stage that works from the previous stage's output needs nothing outside — write **None** and move on. ✅ *"implement — None: works from the shaped story and the local checkout"*.
+
+3. **Pick the server for each need, or write the category.** Name a server only when (a) the user named it, or (b) it is the vendor's own server for a tool the user named — then say how to confirm it: publisher is the vendor, source or docs live on the vendor's domain or organization, and a version or commit is pinned for a local server. Never write a URL, package name or install command the user did not give. ✅ *"GitLab's own MCP server — confirm GitLab publishes it in GitLab's docs before installing"* — ❌ *"`npx @gitlab/mcp-server`"*. When no official server is known, write the category and the five vetting checks from [`reference.md`](reference.md): publisher, source available, pinned version, tools exposed, and whether it can run code or reach the network beyond its own API.
+
+4. **Grant read-only by default, per stage, not per session.** The scope is the narrowest token scope, one repository or project, one database role on a replica — ✅ *"GitLab token, `read_api`, project `payments-web` only"* — ❌ *"GitLab token with `api`"*. Write access goes **only** to the stage whose output is that write (posting the release, opening the draft merge request), on a **separate credential** from the read one, and is the user's choice to grant; otherwise a person does the write. When the vendor offers no scope narrower than full API access for that write, a person does it. Never grant write to a **verify** or **gate** stage: a review that can merge, approve, close or comment is no longer a review. No admin, owner, org-wide or `*` scopes, ever.
+
+5. **Write what each server must not be able to do.** Name the concrete actions to exclude — merge, approve, push to the default branch, transition or close issues, post to channels, run SQL writes, delete, change settings. "Read-only" alone is not enough when the vendor's read-only mode still exposes a tool the stage doesn't need; list the toolsets to turn off.
+
+6. **Split untrusted reading from write or exec.** Issue text, merge request and PR comments, tickets, chat messages, web pages, log lines and design-file comments are **untrusted input**: anyone who can write there can write instructions. A stage that reads untrusted content and also holds a write tool, a shell, or a network tool is the dangerous combination. Fix it by splitting the stage (one reader that returns a file, one actor that reads only that file), dropping the write to a person, or dropping the server. ✅ *"implement runs tests (exec), so it gets no tracker server; it reads the story file shape wrote, which a person skims first"*.
+
+7. **Cut every server that doesn't earn its attack surface.** A server earns its place when the input is too large, too structured or too live to paste at the stage's cadence: dozens of items (a release's 40 merge requests), fields that matter (a cycle's issues with status and owner), or data that changes by the minute (a live incident). A handful of items fetched weekly or less, or a step that saves a single copy-paste, gets the export file instead. Say which servers were cut and why.
+
+8. **Give every stage its export-file fallback.** Name the file a person produces without a server — the diff saved to a file, the tracker filter exported as CSV, the dashboard panel's data downloaded, the query result saved as CSV — so the loop still runs where no server is allowed.
+
+9. **Place the secrets.** Tokens live in environment variables or the tool's secret store; a committed config file holds variable names, never values. A project-scoped config that contains a token stays out of git. Read and write credentials are separate variables. Point at OAuth where the vendor offers it, so no long-lived token exists.
+
+10. **Emit with [`templates/mcp-pairing.md`](templates/mcp-pairing.md)**: the plan in two or three sentences, the per-stage pairing table (stage, needs, server, grant, must not, fallback, risk), the credential list, servers cut, vetting checks for anything not confirmed official, and "To confirm". When the plan still puts private data, untrusted content and any way to send data out in one session, end with one sentence recommending an exfiltration-path review of the finished setup.
+
+**Non-interactive runs** (subagent, CI, headless): unnamed tools become categories tagged `[assumption]`, unknown cadence is assumed weekly, and unknown writers into a source make it untrusted. If no loop, workflow or task is given at all, emit `BLOCKED: need the loop, workflow or task the servers are for`, then say in plain words that the plan needs its stages and the tools the team uses — a pairing for invented stages pairs nothing.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — stage types and their access ceiling, needs by category with the usual export fallback, the vetting checklist, known vendor read-only controls, the cut rule, and the skilldrop loops' stages
+- [`templates/mcp-pairing.md`](templates/mcp-pairing.md) — output skeleton
+- [`examples/build-loop-github-jira-datadog.md`](examples/build-loop-github-jira-datadog.md) — worked example: the build loop for a team on GitHub, Jira and Datadog; two read-only servers, one optional write credential, Datadog cut
+
+## Quality bar
+
+- **Every stage has a row,** including the ones that get **None**. A plan that lists only servers hides which stages hold nothing.
+- **No verify or gate stage holds a write scope.** Not comment, not approve, not label.
+- **Every write grant names the stage whose output it is** and sits on its own credential.
+- **No invented names.** Every server, package, URL and scope in the plan came from the user or is a vendor's own server with the confirm step written beside it.
+- **Every grant is narrower than "read-only":** a scope, a project or repository, a role.
+- **Every stage that reads untrusted content is checked** against write, exec and network tools in the same session, and the combination is split or dropped.
+- **Every stage has an export-file fallback** a person can produce today.
+- **At least one server is argued against** or the plan says why each one earns its place.
+- **No token value appears anywhere,** and the config placement keeps tokens out of git.
+
+## When to use this skill
+
+- ✅ "Which MCP servers should we hook up for our release loop?"
+- ✅ Wiring a tracker, repo host, chat, observability tool or database into a loop or recurring agent workflow
+- ✅ Deciding token scopes, project limits and database roles for an agent's servers, stage by stage
+- ✅ Tightening an existing MCP config that grew one server and one wide token at a time
+
+## When NOT to use this skill
+
+- ❌ Threat-modelling a finished agent's tools and data for exfiltration paths — `agent-threat-model`
+- ❌ Designing the loop itself: stages, exit criteria, caps, human gates — `agent-loop-design`
+- ❌ Deciding how to split work across subagents and what each one is told — `subagent-design`
+- ❌ Writing the organization's rules for which AI tools and data are allowed — `ai-usage-policy`
+- ❌ Setting up one tracker step by step (Jira, Linear, GitHub Projects) — that is the per-tracker integration guide in the skilldrop docs, not a plan
+
+## Anti-patterns to avoid
+
+- ❌ **One session-wide token for the whole loop.** The verify stage then holds the implement stage's write scope.
+- ❌ **A review stage that posts its own comments or merges.** The verdict goes to a person or to CI; the reviewer holds read only.
+- ❌ **Inventing the server.** `@vendor/mcp-server` written from memory is how a typosquatted package gets installed with a production token.
+- ❌ **"Read-only, so safe."** Read-only stops writes to the vendor; it does nothing about untrusted text steering a stage that has a shell.
+- ❌ **Connecting everything the team uses.** A monthly report does not need a live Slack server with history across every channel.
+- ❌ **A token in `.mcp.json`.** Committed files hold `${VAR}` references, never values.
+- ❌ **Admin scope "to get it working".** A 403 means the scope is wrong for that tool; widen to the one permission named in the error, on that stage's credential only.
+- ❌ **Showing the machinery.** Don't mention this skill, its files or its steps in the reply.
+- ❌ **A bare `BLOCKED` line.** Keep it, then say in plain words what is missing and what the plan will contain.

package/packs/ai-engineering/skills/mcp-pairing/evals/eval_queries.json

@@ -0,0 +1,13 @@
+[
+  { "query": "Which MCP servers should we hook up for our release loop? We use GitLab, Linear and Grafana", "should_trigger": true },
+  { "query": "What token scopes does each stage of our build loop need for the GitHub MCP server?", "should_trigger": true },
+  { "query": "Here's our .mcp.json — is this too much access for a weekly status report?", "should_trigger": true },
+  { "query": "We want the on-call agent to read Sentry and Slack. What should we connect and with what permissions?", "should_trigger": true },
+  { "query": "Should our research workflow get a web browsing server and write access to Notion?", "should_trigger": true },
+
+  { "query": "Threat-model this agent: it reads support tickets, queries our customer DB and can send email", "should_trigger": false },
+  { "query": "Design an agent loop that keeps our runbooks up to date, with exit criteria and a human gate", "should_trigger": false },
+  { "query": "How should I split this code migration across parallel subagents?", "should_trigger": false },
+  { "query": "Write our company's policy on which AI tools staff may use with client data", "should_trigger": false },
+  { "query": "Walk me through connecting Jira to Claude Code step by step", "should_trigger": false }
+]

package/packs/ai-engineering/skills/mcp-pairing/evals/evals.json

@@ -0,0 +1,76 @@
+{
+  "skill_name": "mcp-pairing",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Which MCP servers should we hook up for our release loop? We use GitLab, Linear and Grafana. The loop is plan the rollout, check launch readiness, write the release notes, then a go/no-go call. We release about every two weeks.",
+      "assertions": [
+        "It opens with the plan in plain words — how many servers, which ones, read or write, and which stages need none — before any table",
+        "Every one of the four stages (plan, readiness, release notes, go/no-go) has its own row, including any that get no server",
+        "No write scope is granted to the readiness check or the go/no-go stage; the go/no-go decision stays with a person",
+        "Every grant is narrower than 'read-only': a named scope such as GitLab read_api, one project or team, or a Grafana Viewer role, with no admin or api-wide scope",
+        "Any write (publishing the release or notes) sits on a separate credential used only by the release-notes stage, or is handed to a person",
+        "It does not invent server names, packages, install commands or URLs the user didn't give; vendor servers are named only as the vendor's own, with how to confirm the publisher",
+        "Merge request text, comments or Linear issue text are called untrusted, and no stage that reads them is left holding write, exec or network tools",
+        "Every stage gets an export-file fallback, and at least one server is cut or argued for against the fortnightly cadence"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our on-call agent uses the config in mcp.json for two steps: drafting incident updates for the #inc channel, and writing the postmortem afterwards from the timeline, the Jira tickets and some database queries. A teammate set it up and it works, but I'm nervous. Tighten it — tell me what each step should actually be connected to.",
+      "assertions": [
+        "It flags the token values written into the config file and says to move them to environment variables or the tool's secret store, with the committed file holding variable names only",
+        "It drops the admin scopes (admin:org, Slack admin) and the broad repo and workflow scopes, naming the narrower scope each step needs",
+        "It flags the unpinned community packages (@harbourline/jira-mcp, @harbourline/pg-mcp@latest, @harbourline/slack-mcp) and gives the vetting checks: publisher, source available, pinned version, tools exposed, code or network reach",
+        "It replaces the app_owner connection to the primary database with a read-only role on a replica, scoped to what the postmortem needs, or with an exported query result",
+        "It says the Slack posting is the one write the incident-update step's output justifies, on a separate credential from history reading, or hands posting to a person, and the postmortem step gets no write",
+        "It calls Slack messages and Jira ticket text untrusted and does not leave a step that reads them holding the write or database tools it doesn't need",
+        "It does not invent replacement package names, URLs or install commands the user didn't give",
+        "Each step has an export-file fallback, such as the incident channel's thread exported to a file or the query result saved as CSV"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Once a month we research one competitor: plan the question, gather and summarise sources, then weigh the explanations for what they're doing. We want to give the agent a web browsing MCP server, Notion's MCP with write access so it can file the summary in our research space, and Google Drive so it can read our past reports. Good idea?",
+      "assertions": [
+        "It answers the question directly in the opening lines, with a clear verdict on the setup as proposed",
+        "Web pages are called untrusted input, and the stage that browses is not given Notion write or any other write or exec tool in the same session",
+        "The weigh-the-explanations stage is treated as a verify stage and gets read-only access or none",
+        "Notion write, if kept at all, goes only to the stage whose output is filing the summary, scoped to the one research space on its own credential; otherwise a person files it",
+        "Google Drive access is narrowed to the folder of past reports, read-only, or replaced by exported files",
+        "Given the monthly cadence, at least one server is cut in favour of an export file or saved pages, with the reason stated",
+        "It does not invent server names, packages or URLs the user didn't give, and names Notion's or Google's server only with how to confirm the publisher"
+      ]
+    },
+    {
+      "id": 4,
+      "held_out": "2026-10-20",
+      "prompt": "Our team runs a coding agent through the PR loop in docs/pr-loop.md. Someone set up the .mcp.json in the repo root a few months ago and it's committed so everyone gets the same tools. Before we roll this out to two more teams, can you check it? I want to know if it's too broad, what each stage actually needs, and what you'd change. Don't rewrite the loop itself, just the MCP side.",
+      "assertions": [
+        "Flags the GitHub token (and the Jira/Slack/DB secrets) pasted in plain text in a committed .mcp.json as an immediate problem: says to treat the tokens as exposed and rotate them, and to move secrets out of the file (environment variables or a secret store, referenced instead of stored inline).",
+        "Flags the classic PAT with admin:org and delete_repo (and workflow) as far too broad, and recommends a narrowly scoped token instead (e.g. a fine-grained token or app limited to example-org/orders-service with only the repository permissions the implement stage needs: contents and pull requests write, plus read for actions/checks).",
+        "Says the review stage must be read-only: the 'github-reviewer' entry with all toolsets and the ability to approve/merge contradicts the loop's own rule that only a human merges, and should become a read-only connection (diff, CI results, ticket) with no merge, approve, push or write tools.",
+        "Identifies the Jira server 'jira-mcp-plus-unofficial@latest' and the community Slack/Postgres packages as unknown-origin, unpinned third-party code that gets credentials, and recommends replacing them with the vendor's official server or the user's vetted one (or at minimum pinning and reviewing them), not trusting them as-is.",
+        "Recommends removing the Postgres connection entirely (or replacing it with a schema-only/read-only path such as a schema dump or migration files), since no stage in the loop needs a database and the current config gives the agent the prod owner role on the orders database.",
+        "Narrows Slack to what the announce stage actually needs: posting to the single #team-orders-dev channel (chat:write, invited to that channel), dropping history-reading scopes, users:read.email, chat:write.public and admin; and notes that the merge gate stage needs no MCP server at all.",
+        "Gives a per-stage breakdown (pick up, implement, review, merge gate, announce) stating for each what access it needs, what it must not be able to do, and a fallback if the server is unavailable (e.g. pasted or exported ticket text for pick-up, gh CLI or a saved diff/CI log for review, a human posting the Slack line).",
+        "Does not invent server package names, registry URLs, image names or MCP tool names that weren't in the user's files; where it recommends an official server it either names one the user already referenced (ghcr.io/github/github-mcp-server) or describes it generically and tells the user to confirm the vendor-published source."
+      ]
+    },
+    {
+      "id": 5,
+      "held_out": "2026-10-20",
+      "prompt": "I'm the platform lead for the payments group. We want an agent to do first-pass on-call triage, roughly the flow in docs/oncall-triage.md. Nothing is wired up yet. We use self-hosted Sentry, Grafana Cloud, GitLab, Linear and Postgres. Which MCP servers should we connect for this, with what token scopes / roles, and is there anything you'd keep it away from? Security is going to review whatever you propose, so be specific.",
+      "assertions": [
+        "Organises the answer by the five stages (gather, correlate, check data, ticket, postmortem draft) and, for each, states what outside data or action the stage needs and which of the user's named systems supplies it.",
+        "Recommends read-only access for Sentry, Grafana and GitLab: e.g. Sentry token limited to reading events/issues/projects for payments-api (no project write/admin, no resolving issues), a Grafana service account with Viewer role, and a GitLab token with read-only scopes (read_api / read_repository) rather than the full 'api' scope.",
+        "For the database stage, recommends connecting only to the read replica (never the primary) with a dedicated read-only role, and calls out that the PCI card-data columns (pan_last4, card_token, billing_address) must be excluded, e.g. via a restricted view or column-level grants, rather than trusting the agent to avoid them; may also suggest statement timeouts/row limits.",
+        "Treats the ticket stage as the only stage that genuinely needs write access, and limits it to creating/updating issues in the PAY team in Linear (no admin, no access to other teams, no deletion), possibly noting a human could approve or the ticket could be created by a person from the agent's draft.",
+        "States that the postmortem draft stage needs no MCP server, since it writes markdown from what earlier stages already gathered.",
+        "Gives a no-server fallback per stage that keeps the loop working, e.g. exported Sentry event JSON, Grafana panel CSV/screenshot, a pasted git log or MR diff, psql output pasted by the on-call, and a markdown ticket draft the on-call files by hand.",
+        "Explicitly lists what each connection must not be able to do (e.g. no deploys, rollbacks or pipeline triggers from GitLab, no alert silencing or dashboard edits in Grafana, no writes or DDL on Postgres, no reading card data), in a form a security reviewer could check.",
+        "Does not invent MCP server package names, repository URLs or tool names for Sentry, Grafana, GitLab, Linear or Postgres; it either says to use the vendor's officially published server (to be confirmed by the user) or describes the capability generically, and notes that self-hosted Sentry may need verification that the official server supports a custom host."
+      ]
+    }
+  ]
+}

package/packs/ai-engineering/skills/mcp-pairing/evals/files/2/mcp.json

@@ -0,0 +1,32 @@
+{
+  "mcpServers": {
+    "github": {
+      "type": "http",
+      "url": "https://github-mcp.example.invalid/mcp",
+      "headers": { "Authorization": "Bearer tok_FAKE_9f3c_example_not_real" },
+      "note": "classic token, scopes: repo, admin:org, workflow"
+    },
+    "jira": {
+      "command": "npx",
+      "args": ["-y", "@harbourline/jira-mcp"],
+      "env": {
+        "JIRA_URL": "https://brightwell.atlassian.example.invalid",
+        "JIRA_TOKEN": "tok_FAKE_41aa_example_not_real"
+      },
+      "note": "found on a blog post, does create/update/transition/comment"
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@harbourline/pg-mcp@latest"],
+      "env": {
+        "DATABASE_URL": "postgres://app_owner:FAKE_PASSWORD@orders-primary.internal.example.invalid:5432/orders"
+      }
+    },
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "@harbourline/slack-mcp"],
+      "env": { "SLACK_TOKEN": "tok_FAKE_77de_example_not_real" },
+      "note": "bot scopes: channels:history, groups:history, im:history, chat:write, admin"
+    }
+  }
+}

package/packs/ai-engineering/skills/mcp-pairing/evals/files/4/.mcp.json

@@ -0,0 +1,47 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_EXAMPLEEXAMPLEEXAMPLEEXAMPLE0001"
+      },
+      "_comment": "classic PAT, scopes: repo, workflow, admin:org, delete_repo -- easiest to just give it everything"
+    },
+    "github-reviewer": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_EXAMPLEEXAMPLEEXAMPLEEXAMPLE0001",
+        "GITHUB_TOOLSETS": "all"
+      },
+      "_comment": "used by the review stage so it can approve + merge when it's happy"
+    },
+    "jira": {
+      "command": "npx",
+      "args": ["-y", "jira-mcp-plus-unofficial@latest"],
+      "env": {
+        "JIRA_URL": "https://example-team.atlassian.net",
+        "JIRA_EMAIL": "build-bot@example.com",
+        "JIRA_API_TOKEN": "EXAMPLE-JIRA-TOKEN-DO-NOT-USE"
+      },
+      "_comment": "found this on a forum thread, works better than the official one"
+    },
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "slack-mcp-server-community"],
+      "env": {
+        "SLACK_BOT_TOKEN": "xoxb-EXAMPLE-EXAMPLE-EXAMPLE",
+        "_scopes": "chat:write, chat:write.public, channels:history, groups:history, im:history, users:read.email, admin"
+      }
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "some-postgres-mcp"],
+      "env": {
+        "DATABASE_URL": "postgresql://app_owner:EXAMPLEPASSWORD@prod-db.internal.example:5432/orders"
+      },
+      "_comment": "handy for the implement stage to check schemas"
+    }
+  }
+}

package/packs/ai-engineering/skills/mcp-pairing/evals/files/4/docs/pr-loop.md

@@ -0,0 +1,12 @@
+# Our agent PR loop
+
+The coding agent runs this loop for every ticket in the "Agent-ready" Jira column.
+
+1. **Pick up** - read the Jira ticket (description, acceptance criteria, linked tickets). Move it to "In Progress".
+2. **Implement** - branch off `main`, write the change and tests, push the branch, open a draft PR on GitHub.
+3. **Review** - a second agent session reads the PR diff, the CI results and the ticket, and decides if it meets the acceptance criteria.
+4. **Merge gate** - a human tech lead approves and merges. Nothing merges without a human.
+5. **Announce** - post a one-line summary with the PR link to `#team-orders-dev` in Slack.
+
+Repo: one GitHub repo, `example-org/orders-service`. CI is GitHub Actions.
+The `.mcp.json` lives in the repo root and is committed so everyone gets the same setup.