@kaddo/mcp 3.20.0 → 3.22.0

package/README.md

@@ -49,7 +49,8 @@ directory set via the `KADDO_PROJECT_DIR` environment variable).
 | `kaddo://roadmap` | `knowledge/delivery/roadmap.md` | delivery roadmap |
 | `kaddo://capsules` | `.kaddo/external.yml` + `external/` | external Knowledge Capsules |
 | `kaddo://agents` | `knowledge/agents/` | installed agent prompts |
-| `kaddo://skills` | `knowledge/skills/` | installed skills (empty if none) |
+| `kaddo://skills` | `knowledge/skills/` | installed reusable skills (empty if none) |
+| `kaddo://skills/<id>` | `knowledge/skills/<id>/skill.md` | one reusable skill |
 
 ## Tools (read-only)
 
@@ -58,6 +59,7 @@ directory set via the `KADDO_PROJECT_DIR` environment variable).
 - `kaddo_get_work_item` — a Work Item by `id` (summary + full markdown).
 - `kaddo_list_capsules` / `kaddo_get_capsule` — external Knowledge Capsules.
 - `kaddo_list_agents` / `kaddo_get_agent_prompt` — installed agent prompts.
+- `kaddo_list_skills` / `kaddo_get_skill` — installed reusable skills.
 - `kaddo_list_graph_hints` — graph hints, filter by `artifact_type` / `severity` / `active_only`.
 
 ## Derived tools (write only under `.kaddo/`)

package/dist/index.js

@@ -207,8 +207,50 @@ function getAgentPrompt(root, name) {
   return { ...info, content };
 }
 
-// src/workitems.ts
+// src/skills.ts
 import matter2 from "gray-matter";
+function firstHeadingOrLine2(md) {
+  for (const line of md.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#") || t.startsWith("---")) continue;
+    return t.replace(/\s+/g, " ").slice(0, 200);
+  }
+  return "";
+}
+function listSkills(root) {
+  const files = listFiles(root, "knowledge/skills", "skill.md");
+  const out = [];
+  for (const rel of files) {
+    const raw = readText(root, rel);
+    if (raw === null) continue;
+    let data = {};
+    try {
+      data = matter2(raw).data;
+    } catch {
+    }
+    if (data.type && String(data.type) !== "skill") continue;
+    const folder = rel.split("/").slice(-2)[0];
+    out.push({
+      id: String(data.id ?? folder),
+      title: String(data.title ?? folder),
+      group: String(data.group ?? "unknown"),
+      applies_to: Array.isArray(data.applies_to) ? data.applies_to.map(String).filter(Boolean) : [],
+      path: rel
+    });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function getSkill(root, id) {
+  const want = id.replace(/\.md$/, "");
+  const info = listSkills(root).find((s) => s.id === want);
+  if (!info) return null;
+  const content = readText(root, info.path);
+  if (content === null) return null;
+  return { ...info, content, description: firstHeadingOrLine2(content) || info.title };
+}
+
+// src/workitems.ts
+import matter3 from "gray-matter";
 var ACTIVE_STATES = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
 function strArray(v) {
   return Array.isArray(v) ? v.map((x) => String(x)).filter(Boolean) : [];
@@ -235,7 +277,7 @@ function listWorkItems(root) {
     if (raw === null) continue;
     let parsed;
     try {
-      parsed = matter2(raw);
+      parsed = matter3(raw);
     } catch {
       continue;
     }
@@ -396,18 +438,15 @@ var RESOURCES = [
   {
     uri: "kaddo://skills",
     name: "Kaddo skills",
-    description: "Installed skills from knowledge/skills/ (empty if none).",
+    description: "Installed reusable skills from knowledge/skills/ (empty if none).",
     mimeType: "application/json",
-    read: (root) => {
-      const files = listFiles(root, "knowledge/skills", ".md");
-      return [
-        {
-          uri: "kaddo://skills",
-          text: JSON.stringify({ skills: files }, null, 2),
-          mimeType: "application/json"
-        }
-      ];
-    }
+    read: (root) => [
+      {
+        uri: "kaddo://skills",
+        text: JSON.stringify({ skills: listSkills(root) }, null, 2),
+        mimeType: "application/json"
+      }
+    ]
   }
 ];
 
@@ -465,8 +504,12 @@ function projectStatus(root) {
       withOwnership: explain.ownership?.workItemsWithOwnership ?? 0,
       total: explain.ownership?.workItemsTotal ?? 0
     },
-    graphQuality: hints?.quality ?? "unknown (run `kaddo graph export`)",
-    graphHints: hints?.summary?.hints ?? 0,
+    graph: {
+      scope: hints?.scope ?? "unknown (run `kaddo graph export`)",
+      scope_reason: hints?.scope_reason ?? "",
+      quality: hints?.quality ?? "unknown (run `kaddo graph export`)",
+      hints: hints?.summary?.hints ?? 0
+    },
     capsules: capsules.length
   });
 }
@@ -499,6 +542,14 @@ function getAgentPromptTool(root, name) {
   if (!agent) return fail(`Agent "${name}" is not installed. Run \`kaddo add agents\` first.`);
   return ok(agent);
 }
+function listSkillsTool(root) {
+  return ok(listSkills(root));
+}
+function getSkillTool(root, id) {
+  const skill = getSkill(root, id);
+  if (!skill) return fail(`Skill "${id}" is not installed. Run \`kaddo add skills\` first.`);
+  return ok(skill);
+}
 function listGraphHints(root, filter = {}) {
   const report = readJson(root, ".kaddo/graph-hints.json");
   if (!report) return fail("Graph hints not found. Run `kaddo graph export` first.");
@@ -506,7 +557,13 @@ function listGraphHints(root, filter = {}) {
   if (filter.artifact_type) hints = hints.filter((h) => h.artifact_type === filter.artifact_type);
   if (filter.severity) hints = hints.filter((h) => h.severity === filter.severity);
   if (filter.active_only) hints = hints.filter((h) => h.artifact_type === "work-item");
-  return ok({ quality: report.quality ?? "unknown", count: hints.length, hints });
+  return ok({
+    scope: report.scope ?? "active",
+    scope_reason: report.scope_reason ?? "",
+    quality: report.quality ?? "unknown",
+    count: hints.length,
+    hints
+  });
 }
 
 // ../cli/src/core/config.ts
@@ -528,6 +585,9 @@ function readDir(dirPath) {
 function isFile(p) {
   return exists(p) && fs2.statSync(p).isFile();
 }
+function isDir(p) {
+  return exists(p) && fs2.statSync(p).isDirectory();
+}
 function join(...parts) {
   return path2.join(...parts);
 }
@@ -619,13 +679,13 @@ ${issues}`);
 }
 
 // ../cli/src/core/context-pack.ts
-import matter5 from "gray-matter";
+import matter7 from "gray-matter";
 
 // ../cli/src/services/artifact-reader.ts
-import matter3 from "gray-matter";
+import matter4 from "gray-matter";
 function parseArtifact(filePath, raw) {
   try {
-    const { data } = matter3(raw);
+    const { data } = matter4(raw);
     const globs = Array.isArray(data.code) ? data.code.filter(Boolean) : [];
     return {
       filePath,
@@ -1283,7 +1343,7 @@ function assessPhase(input) {
 }
 
 // ../cli/src/core/capsule.ts
-import matter4 from "gray-matter";
+import matter5 from "gray-matter";
 import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
 
 // ../cli/src/services/owners.ts
@@ -1436,7 +1496,7 @@ function sectionParagraph2(md, title) {
   return "";
 }
 function parseCapsule(id, path3, md) {
-  const { data } = matter4(md);
+  const { data } = matter5(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
   if (updatedAt) {
@@ -1471,6 +1531,11 @@ function loadExternalCapsules(dir) {
 
 // ../cli/src/core/graph.ts
 var KNOWLEDGE3 = "knowledge";
+var ACTIVE_STATUSES = ["draft", "ready", "in-progress", "blocked"];
+var ALL_STATUSES = ["draft", "ready", "in-progress", "blocked", "completed"];
+function scopeStatuses(scope) {
+  return scope === "all" ? { included: ALL_STATUSES, excluded: ["archived"] } : { included: ACTIVE_STATUSES, excluded: ["completed", "archived"] };
+}
 function toPosix3(p) {
   return p.replace(/\\/g, "/");
 }
@@ -1513,7 +1578,10 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   }
   const all = discoverKnowledge(dir);
   const workItems = all.filter((a) => a.isWorkItem);
-  const selectedWIs = scope === "active" ? workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle)) : workItems;
+  const { included, excluded } = scopeStatuses(scope);
+  const includedSet = new Set(included);
+  const activeWICount = workItems.filter((a) => a.lifecycle && isActiveState(a.lifecycle)).length;
+  const selectedWIs = workItems.filter((a) => a.lifecycle && includedSet.has(a.lifecycle));
   for (const wi of selectedWIs) {
     const id = wi.id || wi.title;
     const wiNodeId = `wi:${id}`;
@@ -1583,6 +1651,7 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       }
     }
   }
+  const scopeReason = scope === "all" ? "All supported Work Item statuses are included." : activeWICount === 0 ? "No active Work Items found. Completed Work Items are excluded from active scope." : "Active Work Items only; completed and archived are excluded.";
   return {
     generated_at: now.toISOString(),
     project: {
@@ -1590,6 +1659,10 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
       state: config.project.state,
       structure: config.project.structure
     },
+    scope,
+    scope_reason: scopeReason,
+    included_statuses: included,
+    excluded_statuses: excluded,
     nodes: [...nodes.values()],
     edges
   };
@@ -1637,8 +1710,13 @@ function loadGraphSummary(dir) {
     const connected = new Set(
       edges.filter((e) => e.type === "owns" && activeWiIds.has(e.from)).map((e) => e.from)
     );
+    const scope = graph.scope === "all" ? "all" : "active";
     return {
       generatedAt: String(graph.generated_at ?? ""),
+      scope,
+      scopeReason: String(graph.scope_reason ?? ""),
+      includedStatuses: Array.isArray(graph.included_statuses) ? graph.included_statuses : [],
+      excludedStatuses: Array.isArray(graph.excluded_statuses) ? graph.excluded_statuses : [],
       nodes: nodes.length,
       edges: edges.length,
       activeWorkItemsConnectedToCode: connected.size
@@ -1790,6 +1868,8 @@ function buildGraphHints(dir, graph, now = /* @__PURE__ */ new Date()) {
   const quality = assessQuality(nodes, relationshipEdges, hints.length);
   return {
     generated_at: now.toISOString(),
+    scope: graph.scope,
+    scope_reason: graph.scope_reason,
     quality,
     summary: { nodes, edges: graph.edges.length, hints: hints.length },
     metrics,
@@ -1825,13 +1905,23 @@ function renderGraphHintsMarkdown(report) {
   lines.push("");
   lines.push("## Summary");
   lines.push("");
+  lines.push(`- Scope: ${report.scope} \u2014 ${report.scope_reason}`);
   lines.push(`- Relationship quality: ${report.quality} \u2014 ${QUALITY_NOTE[report.quality]}`);
   lines.push(`- Nodes: ${report.summary.nodes}`);
   lines.push(`- Edges: ${report.summary.edges}`);
   lines.push(`- Hints: ${report.summary.hints}`);
   lines.push("");
   if (report.hints.length === 0) {
-    lines.push("No hints \u2014 the declared relationships look healthy. \u{1F389}");
+    if (report.quality === "empty") {
+      lines.push("No active relationship hints were generated.");
+      lines.push("");
+      lines.push(`The graph is ${report.quality} for the **${report.scope}** scope \u2014 ${report.scope_reason}`);
+      if (report.scope !== "all") {
+        lines.push("Run `kaddo graph export --scope all` to inspect completed Work Items and historical relationships.");
+      }
+    } else {
+      lines.push("No hints \u2014 the declared relationships look healthy. \u{1F389}");
+    }
     lines.push("");
     return lines.join("\n");
   }
@@ -1867,6 +1957,8 @@ function loadGraphHints(dir) {
     const report = JSON.parse(readFile(p));
     const hints = Array.isArray(report.hints) ? report.hints : [];
     return {
+      scope: String(report.scope ?? "active"),
+      scopeReason: String(report.scope_reason ?? ""),
       quality: report.quality ?? "empty",
       totalHints: hints.length,
       activeWorkItemHints: hints.filter((h) => h.artifact_type === "work-item").length,
@@ -1877,6 +1969,38 @@ function loadGraphHints(dir) {
   }
 }
 
+// ../cli/src/services/installed-skills.ts
+import matter6 from "gray-matter";
+var SKILLS_DIR = join("knowledge", "skills");
+function discoverInstalledSkills(dir) {
+  const base = join(dir, SKILLS_DIR);
+  if (!exists(base) || !isDir(base)) return [];
+  const out = [];
+  for (const entry of readDir(base)) {
+    const skillFile = join(base, entry, "skill.md");
+    if (!isFile(skillFile)) continue;
+    try {
+      const { data } = matter6(readFile(skillFile));
+      if (data.type && String(data.type) !== "skill") continue;
+      const id = String(data.id ?? entry);
+      out.push({
+        id,
+        title: String(data.title ?? id),
+        group: String(data.group ?? "unknown"),
+        appliesTo: Array.isArray(data.applies_to) ? data.applies_to.map(String).filter(Boolean) : [],
+        relPath: `${SKILLS_DIR.replace(/\\/g, "/")}/${entry}/skill.md`
+      });
+    } catch {
+    }
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function skillGroupCounts(skills) {
+  const counts = {};
+  for (const s of skills) counts[s.group] = (counts[s.group] ?? 0) + 1;
+  return counts;
+}
+
 // ../cli/src/core/context-pack.ts
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR2 = "knowledge";
@@ -1890,7 +2014,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph3(markdown) {
-  const body = matter5(markdown).content.trim();
+  const body = matter7(markdown).content.trim();
   const para = body.split("\n\n").map((p) => p.trim()).find((p) => p && !p.startsWith("#"));
   return para ?? "";
 }
@@ -2063,6 +2187,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     external: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
     graphHints: loadGraphHints(dir),
+    skills: discoverInstalledSkills(dir).map((s) => s.id),
     mappedModules,
     missing,
     // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
@@ -2233,9 +2358,12 @@ function renderContextPack(pack) {
     parts.push(
       [
         "- Available: yes",
+        `- Scope: ${pack.graph.scope}`,
         `- Nodes: ${pack.graph.nodes}`,
         `- Edges: ${pack.graph.edges}`,
-        `- Active Work Items connected to code: ${pack.graph.activeWorkItemsConnectedToCode}`
+        ...pack.graphHints ? [`- Quality: ${pack.graphHints.quality}`] : [],
+        `- Active Work Items connected to code: ${pack.graph.activeWorkItemsConnectedToCode}`,
+        ...pack.graph.scopeReason ? [`- Reason: ${pack.graph.scopeReason}`] : []
       ].join("\n") + "\n"
     );
     parts.push("Full graph: `.kaddo/graph.json` / `.kaddo/graph.mmd` (run `kaddo graph export` to refresh).\n");
@@ -2256,6 +2384,12 @@ function renderContextPack(pack) {
 `);
     }
   }
+  if (pack.skills.length > 0) {
+    parts.push("## Skills\n");
+    parts.push("Available reusable skills (agents apply these; content is not inlined):\n");
+    parts.push(pack.skills.map((s) => `- ${s}`).join("\n") + "\n");
+    parts.push("Read full skill definitions in `knowledge/skills/` or via the Kaddo MCP server (`kaddo://skills`).\n");
+  }
   parts.push("## Missing Context\n");
   if (missing.length > 0) {
     parts.push(missing.map((m) => `- ${m}`).join("\n") + "\n");
@@ -2475,6 +2609,10 @@ function buildProjectExplanation(dir) {
     externalCapsules: loadExternalCapsules(dir),
     graph: loadGraphSummary(dir),
     graphHints: loadGraphHints(dir),
+    skills: (() => {
+      const installed = discoverInstalledSkills(dir);
+      return { total: installed.length, byGroup: skillGroupCounts(installed) };
+    })(),
     layers,
     roadmap,
     mappedModules,
@@ -2616,13 +2754,27 @@ function renderExplanationHuman(exp) {
   }
   if (exp.graph) {
     lines.push("## Knowledge Graph");
+    lines.push(`- Scope: ${exp.graph.scope}`);
     lines.push(`- Nodes: ${exp.graph.nodes}`);
     lines.push(`- Edges: ${exp.graph.edges}`);
     if (exp.graphHints) {
       lines.push(`- Quality: ${exp.graphHints.quality}`);
       lines.push(`- Hints: ${exp.graphHints.totalHints}`);
     }
+    if (exp.graph.scopeReason) lines.push(`- Reason: ${exp.graph.scopeReason}`);
     if (exp.graph.generatedAt) lines.push(`- Last exported: ${exp.graph.generatedAt}`);
+    if (exp.graph.scope === "active" && exp.graphHints?.quality === "empty") {
+      lines.push("- Tip: Run `kaddo graph export --scope all` to include completed Work Items");
+    }
+    lines.push("");
+  }
+  if (exp.skills.total > 0) {
+    lines.push(`## Skills installed: ${exp.skills.total}`);
+    const groups = Object.entries(exp.skills.byGroup).sort((a, b) => a[0].localeCompare(b[0]));
+    if (groups.length > 0) {
+      lines.push("Groups:");
+      for (const [g, n] of groups) lines.push(`- ${g}: ${n}`);
+    }
     lines.push("");
   }
   if (exp.missingKnowledge.length > 0) {
@@ -2871,10 +3023,10 @@ function generateUnderstand(root) {
     next_suggested_resources: ["kaddo://understand"]
   };
 }
-function generateGraph(root) {
+function generateGraph(root, scope = "active") {
   const config = requireConfig(root);
   requireKnowledge(root);
-  const graph = buildGraph(root, config, { scope: "active" });
+  const graph = buildGraph(root, config, { scope });
   const hints = buildGraphHints(root, graph);
   writeDerived(root, ".kaddo/graph.json", serializeGraphJson(graph));
   writeDerived(root, ".kaddo/graph.mmd", renderGraphMermaid(graph));
@@ -2889,7 +3041,7 @@ function generateGraph(root) {
       ".kaddo/graph-hints.md",
       ".kaddo/graph-hints.json"
     ],
-    summary: "Knowledge graph and hints generated successfully.",
+    summary: `Knowledge graph and hints generated successfully (${scope} scope).`,
     warnings,
     next_suggested_resources: ["kaddo://graph", "kaddo://graph-hints"]
   };
@@ -3021,6 +3173,38 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => listGraphHints(root, args)))
   );
+  server.registerTool(
+    "kaddo_list_skills",
+    { title: "List skills", description: "List installed reusable skills.", inputSchema: {} },
+    async () => toolText(guarded(root, () => listSkillsTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_skill",
+    { title: "Get skill", description: "Get an installed reusable skill by id.", inputSchema: { id: z2.string() } },
+    async (args) => toolText(guarded(root, () => getSkillTool(root, args.id)))
+  );
+  let installedSkills = [];
+  try {
+    assertKaddoProject(root);
+    installedSkills = listSkills(root);
+  } catch {
+    installedSkills = [];
+  }
+  for (const s of installedSkills) {
+    server.registerResource(
+      `skill: ${s.id}`,
+      `kaddo://skills/${s.id}`,
+      { title: s.title, description: `Reusable skill "${s.id}" (${s.group}).`, mimeType: "text/markdown" },
+      async (uri) => {
+        const full = getSkill(root, s.id);
+        return {
+          contents: [
+            { uri: uri.href, text: full?.content ?? `Skill "${s.id}" not found.`, mimeType: "text/markdown" }
+          ]
+        };
+      }
+    );
+  }
   server.registerTool(
     "kaddo_generate_context",
     { title: "Generate context pack", description: `Regenerate .kaddo/context-pack.md + .json. ${DERIVED_NOTE}`, inputSchema: {} },
@@ -3038,8 +3222,12 @@ function createServer(root) {
   );
   server.registerTool(
     "kaddo_generate_graph",
-    { title: "Generate knowledge graph", description: `Regenerate .kaddo/graph.json/.mmd + graph-hints.md/.json. ${DERIVED_NOTE}`, inputSchema: {} },
-    async () => generated(root, "generate knowledge graph", () => generateGraph(root))
+    {
+      title: "Generate knowledge graph",
+      description: `Regenerate .kaddo/graph.json/.mmd + graph-hints.md/.json. scope: active (default) or all. ${DERIVED_NOTE}`,
+      inputSchema: { scope: z2.enum(["active", "all"]).optional() }
+    },
+    async (args) => generated(root, "generate knowledge graph", () => generateGraph(root, args.scope ?? "active"))
   );
   server.registerTool(
     "kaddo_generate_capsule_draft",
@@ -3064,6 +3252,17 @@ function createServer(root) {
       }
     );
   }
+  for (const s of installedSkills) {
+    server.registerPrompt(
+      `skill-${s.id}`,
+      { title: s.title, description: `Reusable skill "${s.id}" (${s.group}).` },
+      async () => {
+        const full = getSkill(root, s.id);
+        const content = full?.content ?? `Skill "${s.id}" is not installed.`;
+        return { messages: [{ role: "user", content: { type: "text", text: content } }] };
+      }
+    );
+  }
   return server;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.20.0",
+  "version": "3.22.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {