@kaddo/cli 3.20.0 → 3.22.0

package/README.md

@@ -505,6 +505,10 @@ create --from roadmap → owners → guard → explain`.
 | v3.16 | Knowledge Capsules: `kaddo capsule export/add`, External Knowledge in context/explain, new `capsule-agent` |
 | v3.17 | Knowledge Graph Export: `kaddo graph export` (`.kaddo/graph.json` + `.mmd`, `--scope`/`--format`); graph summary in context/explain |
 | v3.18 | Graph relationship quality & metadata hints: `graph-hints.md`/`.json`, quality levels, `graph-agent`; hints in context/explain/understand |
+| v3.19 | Read-only MCP server `@kaddo/mcp` (resources, tools, prompts over stdio) |
+| v3.20 | MCP derived tools: safe regeneration of context/explain/understand/graph/capsule-draft under `.kaddo/` |
+| v3.21 | Reusable Skills layer (`kaddo add skills`); skills in context/explain/understand, agent prompts and MCP |
+| v3.22 | Guard & graph scope semantics: graph scope metadata, contextual-empty messaging, Guard ownership scope (active + completed; `--include-archived`) |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -1487,6 +1487,386 @@ var guardAdvancedModule = {
   ]
 };
 
+// src/skills/skills.ts
+function skill(id, title, group, appliesTo, body) {
+  const frontMatter2 = [
+    "---",
+    "type: skill",
+    `id: ${id}`,
+    `title: ${title}`,
+    "version: 1",
+    `group: ${group}`,
+    "applies_to:",
+    ...appliesTo.map((a) => `  - ${a}`),
+    "---",
+    ""
+  ].join("\n");
+  return { id, title, group, appliesTo, content: frontMatter2 + body.trimStart() };
+}
+var ADR_WRITING = skill(
+  "adr-writing",
+  "ADR Writing Skill",
+  "tech",
+  ["decision-agent", "architecture-agent", "implementation-agent"],
+  `
+# ADR Writing Skill
+
+## Purpose
+
+Standardize how Architecture Decision Records are written so every decision is captured the same
+way and stays auditable.
+
+## When to use
+
+When a real, consequential technical decision is being made or recognized \u2014 and only then.
+
+## Inputs
+
+The context pack, the relevant Work Item or architecture note, and the decision being made.
+
+## Output
+
+A single ADR containing: context, the decision, alternatives considered, consequences, the code
+paths it governs (\`code:\` globs when known) and the decision status (proposed / accepted /
+superseded).
+
+## Rules
+
+- One ADR = one decision. Never mix unrelated decisions.
+- Never invent decisions; never write an ADR without a clear reason.
+- Record alternatives honestly, including the one chosen and why.
+- Prefer narrow governed \`code:\` globs over broad ones.
+
+## Quality checklist
+
+- Context explains why the decision was needed.
+- The decision and its alternatives are explicit.
+- Consequences (positive and negative) are stated.
+- Status and governed paths are present.
+
+## Example output
+
+\`\`\`md
+# ADR-0007 \u2014 Use SQLite for local persistence
+Status: accepted
+## Context
+...
+## Decision
+...
+## Alternatives considered
+...
+## Consequences
+...
+\`\`\`
+`
+);
+var WORK_ITEM_REFINEMENT = skill(
+  "work-item-refinement",
+  "Work Item Refinement Skill",
+  "delivery",
+  ["work-item-agent", "backlog-agent", "roadmap-agent"],
+  `
+# Work Item Refinement Skill
+
+## Purpose
+
+Standardize how a Work Item is sharpened from a rough idea into a ready, implementable item.
+
+## When to use
+
+When improving a draft Work Item, or turning a backlog idea / roadmap candidate into a ready item.
+
+## Inputs
+
+The context pack and the Work Item (draft or candidate).
+
+## Output
+
+An improved Work Item with: problem, expected result, scope, out of scope, acceptance criteria,
+validation (how to test it), definition of done, open questions and dependencies.
+
+## Rules
+
+- Do not implement code.
+- Do not expand scope without explicit confirmation.
+- Do not create mega Work Items \u2014 split when it covers multiple outcomes.
+- Keep acceptance criteria testable.
+
+## Quality checklist
+
+- Problem and expected result are unambiguous.
+- Scope and out-of-scope are explicit.
+- Acceptance criteria and validation are present and testable.
+- Open questions and dependencies are surfaced, not hidden.
+
+## Example output
+
+A Work Item markdown with the sections above filled in, ready for the implementation-agent.
+`
+);
+var OWNERSHIP_SUGGESTION = skill(
+  "ownership-suggestion",
+  "Ownership Suggestion Skill",
+  "tech",
+  ["ownership-agent", "work-item-agent", "graph-agent", "implementation-agent"],
+  `
+# Ownership Suggestion Skill
+
+## Purpose
+
+Standardize how precise \`code:\` ownership globs are proposed so Guard can relate code changes to
+the right knowledge.
+
+## When to use
+
+When a Work Item or artifact is missing ownership, or its ownership is too broad/inaccurate.
+
+## Inputs
+
+The context pack, the Work Item, and the technical inventory / codebase notes.
+
+## Output
+
+A \`code:\` glob proposal, e.g.
+
+\`\`\`yaml
+code:
+  - src/database/**
+  - src/cli/**
+\`\`\`
+
+## Rules
+
+- Prefer small, specific globs; avoid \`src/**\`.
+- Use only real paths; validate intent against the Work Item.
+- Explain uncertainty instead of guessing.
+- Propose only \u2014 the human applies with \`kaddo owners suggest\`.
+
+## Quality checklist
+
+- Every glob maps to a real path relevant to the item.
+- No catch-all globs.
+- Uncertainty is marked.
+
+## Example output
+
+The YAML \`code:\` block above plus a one-line rationale per glob.
+`
+);
+var GRAPH_METADATA_REVIEW = skill(
+  "graph-metadata-review",
+  "Graph Metadata Review Skill",
+  "tech",
+  ["graph-agent", "ownership-agent", "work-item-agent"],
+  `
+# Graph Metadata Review Skill
+
+## Purpose
+
+Standardize how \`kaddo graph export\` hints become precise relationship front matter.
+
+## When to use
+
+When relationship quality is partial/sparse/empty, or when reviewing \`.kaddo/graph-hints.md\`.
+
+## Inputs
+
+The context pack, \`.kaddo/graph.json\` and \`.kaddo/graph-hints.md\`, plus the affected artifacts.
+
+## Output
+
+Front matter proposals, e.g.
+
+\`\`\`yaml
+capabilities:
+  - local-persistence
+decisions:
+  - ADR-0001
+code:
+  - src/database/**
+capsules:
+  - orders-service
+\`\`\`
+
+## Rules
+
+- Never invent relationships, paths or IDs.
+- Do not try to resolve every hint at once \u2014 propose what is justified.
+- Do not modify artifacts; the human applies and re-runs \`kaddo graph export\`.
+
+## Quality checklist
+
+- Each proposal maps to a real artifact/path/capability/ADR/capsule.
+- Globs are narrow; uncertainty is marked.
+
+## Example output
+
+The YAML proposal above, grouped per artifact, with a short reason each.
+`
+);
+var CAPSULE_WRITING = skill(
+  "capsule-writing",
+  "Capsule Writing Skill",
+  "integration",
+  ["capsule-agent", "architecture-agent", "product-agent"],
+  `
+# Capsule Writing Skill
+
+## Purpose
+
+Standardize how a Knowledge Capsule is written/reviewed so external consumers get safe, useful
+context.
+
+## When to use
+
+When creating or refining a Knowledge Capsule for sharing with another project.
+
+## Inputs
+
+The context pack, capabilities, current-state, decisions and any public contracts.
+
+## Output
+
+A capsule with: purpose, responsibilities, capabilities, contracts, dependencies, risks, owners,
+out of scope and usage notes.
+
+## Rules
+
+- Never include secrets, tokens, credentials, source code, PII or unnecessary internal detail.
+- Never invent contracts; mark unknowns.
+- Summarize boundaries; prefer "unknown" over guessing.
+
+## Quality checklist
+
+- Purpose and boundaries are clear.
+- Contracts are real, not invented.
+- No secrets/source/PII included.
+
+## Example output
+
+A \`*.capsule.md\` with the sections above.
+`
+);
+var LEARNING_CAPTURE = skill(
+  "learning-capture",
+  "Learning Capture Skill",
+  "delivery",
+  ["implementation-agent", "guard-agent", "architecture-agent", "work-item-agent"],
+  `
+# Learning Capture Skill
+
+## Purpose
+
+Standardize how a Work Item's learning is captured when it closes.
+
+## When to use
+
+When finishing a Work Item, after implementation and verification.
+
+## Inputs
+
+The Work Item, the diff/result, and any decisions or surprises that came up.
+
+## Output
+
+A learning record: what was implemented, what changed, what was learned, what decision emerged,
+which knowledge must be updated, and what remains pending.
+
+## Rules
+
+- Do not close a Work Item without validation.
+- Do not hide failures; record them honestly.
+- Do not assume everything is done if errors remain.
+
+## Quality checklist
+
+- Implemented vs changed vs learned are distinct.
+- Knowledge to update is named (ADR / capabilities / current-state).
+- Pending items are listed.
+
+## Example output
+
+A short learning section appended to the Work Item or a learning note.
+`
+);
+var IMPLEMENTATION_PLANNING = skill(
+  "implementation-planning",
+  "Implementation Planning Skill",
+  "delivery",
+  ["implementation-agent", "work-item-agent"],
+  `
+# Implementation Planning Skill
+
+## Purpose
+
+Standardize the plan produced before implementation starts.
+
+## When to use
+
+Before writing code for a ready Work Item.
+
+## Inputs
+
+The context pack and the ready Work Item.
+
+## Output
+
+A plan with: technical scope, expected files, risks, validations, out of scope, implementation
+steps, and stop criteria (when to pause and ask).
+
+## Rules
+
+- Do not start coding without confirmation.
+- Do not expand scope.
+- Never make commits or push \u2014 suggest only.
+
+## Quality checklist
+
+- Scope and expected files are explicit.
+- Risks and validations are listed.
+- Stop criteria are defined.
+
+## Example output
+
+A numbered plan covering the sections above, ending with a request to confirm before coding.
+`
+);
+var SKILLS = [
+  ADR_WRITING,
+  WORK_ITEM_REFINEMENT,
+  OWNERSHIP_SUGGESTION,
+  GRAPH_METADATA_REVIEW,
+  CAPSULE_WRITING,
+  LEARNING_CAPTURE,
+  IMPLEMENTATION_PLANNING
+];
+var SKILL_GROUPS = {
+  delivery: ["work-item-refinement", "implementation-planning", "learning-capture"],
+  tech: ["adr-writing", "ownership-suggestion", "graph-metadata-review"],
+  integration: ["capsule-writing"]
+};
+var SKILL_GROUP_NAMES = Object.keys(SKILL_GROUPS);
+var RECOMMENDED_SKILLS = [...SKILL_GROUPS.delivery, ...SKILL_GROUPS.tech];
+function skillInstallPath(id) {
+  return `knowledge/skills/${id}/skill.md`;
+}
+function selectSkills(opts) {
+  if (opts.all) {
+    return { ids: SKILLS.map((s) => s.id), label: "all skills" };
+  }
+  if (opts.group) {
+    const group = opts.group;
+    const ids = SKILL_GROUPS[group];
+    if (!ids) {
+      throw new Error(
+        `Unknown skill group "${opts.group}". Valid groups: ${SKILL_GROUP_NAMES.join(", ")}.`
+      );
+    }
+    return { ids, label: `group: ${group}` };
+  }
+  return { ids: RECOMMENDED_SKILLS, label: "recommended skills" };
+}
+
 // src/agents/responsibility.ts
 var RESPONSIBILITY_MATRIX = {
   "business-agent": {
@@ -1758,14 +2138,30 @@ function renderLanguageRule() {
     ""
   ].join("\n");
 }
+function renderSkillsSection(agent) {
+  const applicable = SKILLS.filter((s) => s.appliesTo.includes(agent));
+  if (applicable.length === 0) return "";
+  return [
+    "## Reusable Skills",
+    "",
+    "Apply these reusable skills when relevant (install with `kaddo add skills`; read them in",
+    "`knowledge/skills/` or via the Kaddo MCP server):",
+    "",
+    ...applicable.map((s) => `- **${s.id}** \u2014 ${s.title}.`),
+    ""
+  ].join("\n");
+}
 function withResponsibilityTrace(fileName, content) {
   const agent = fileName.replace(/\.md$/, "");
   if (!RESPONSIBILITY_MATRIX[agent]) return content;
+  const skills = renderSkillsSection(agent);
+  const skillsBlock = skills ? `${skills}
+` : "";
   return `${content.trimEnd()}
 
 ${renderLanguageRule()}
 ${renderAgentBoundaries(agent)}
-${renderAgentTrace(agent)}`;
+${skillsBlock}${renderAgentTrace(agent)}`;
 }
 
 // src/agents/prompts.ts
@@ -3532,74 +3928,40 @@ var agentsModule = {
 };
 
 // src/modules/skills.ts
+var skillsReadme = {
+  path: "knowledge/skills/README.md",
+  content: [
+    "# Skills",
+    "",
+    "Reusable **skill** definitions \u2014 capabilities shared across agents. A skill does not decide",
+    "WHAT to do (that is the agent); it defines HOW to do one thing well. Agents orchestrate;",
+    "skills standardize; knowledge grounds; MCP exposes.",
+    "",
+    "Skills never execute anything \u2014 they are reusable instructions, not tools. They never run",
+    "git, never call an LLM and never modify files.",
+    "",
+    "## Installed skills",
+    "",
+    ...SKILLS.map((s) => `- \`${s.id}\` (${s.group}) \u2014 ${s.title}. Applies to: ${s.appliesTo.join(", ")}.`),
+    "",
+    "## Groups",
+    "",
+    ...Object.entries(SKILL_GROUPS).map(([g, ids]) => `- **${g}**: ${ids.join(", ")}`),
+    "",
+    "Install: `kaddo add skills` (recommended), `--all`, or `--group <delivery|tech|integration>`."
+  ].join("\n")
+};
+var skillFiles = SKILLS.map((s) => ({
+  path: skillInstallPath(s.id),
+  content: s.content
+}));
 var skillsModule = {
   name: "skills",
-  description: "Reusable skills \u2014 capabilities shared across agents, teams, or projects",
+  description: "Reusable skills \u2014 capabilities shared across agents (adr-writing, work-item-refinement, \u2026)",
   configKey: "module_skills",
   dirs: ["knowledge/skills"],
-  files: [
-    {
-      path: "knowledge/skills/.gitkeep",
-      content: ""
-    },
-    {
-      path: "knowledge/skills/README.md",
-      content: [
-        "# Skills",
-        "",
-        "This directory contains skill definitions \u2014 reusable capabilities that agents",
-        "or team members can invoke.",
-        "",
-        "A skill is a well-defined, repeatable capability with:",
-        "- Clear inputs and outputs",
-        "- A defined trigger (when to use it)",
-        "- Known preconditions",
-        "",
-        "Skills differ from agents: a skill is a single capability,",
-        "an agent is an orchestrator that uses skills."
-      ].join("\n")
-    }
-  ],
-  workItemTypes: [
-    {
-      name: "skill",
-      knowledgeLevel: "K3",
-      description: "Skill \u2014 a reusable capability shared across agents, teams, or projects.",
-      questions: [
-        {
-          id: "what_it_does",
-          prompt: "What does this skill do?",
-          placeholder: "e.g. Reads the artifact front matters and returns ownership gaps",
-          frontMatterField: "what_it_does",
-          required: true
-        },
-        {
-          id: "trigger",
-          prompt: "When should this skill be invoked?",
-          placeholder: "e.g. When a guard FYI has no matching artifact with code globs",
-          frontMatterField: "trigger",
-          required: true
-        },
-        {
-          id: "inputs_outputs",
-          prompt: "What are the inputs and outputs?",
-          placeholder: "e.g. Input: list of touched files. Output: suggested artifact IDs to update",
-          frontMatterField: "inputs_outputs",
-          required: true
-        }
-      ],
-      qualityGate: [
-        "Skill is scoped to a single, reusable capability.",
-        "Trigger condition is explicit.",
-        "Inputs and outputs are defined."
-      ],
-      extraFrontMatter: {
-        skill_type: "analysis",
-        reusable_by: [],
-        code: []
-      }
-    }
-  ]
+  files: [skillsReadme, ...skillFiles],
+  workItemTypes: []
 };
 
 // src/modules/global-docs.ts
@@ -5162,10 +5524,14 @@ async function offerIgnore(dir, match) {
   log2.success(`${id} added to .kaddo/ignores.yml`);
   return true;
 }
-function printCIJson(dir, touchedFiles, activeMatches, ignoredCount, pluginSignals, affectedOwners, workspace) {
+function printCIJson(dir, touchedFiles, activeMatches, ignoredCount, pluginSignals, affectedOwners, workspace, includeArchived) {
   const output = {
     kaddo_guard: true,
     ci: true,
+    ownership_scope: {
+      included: includeArchived ? ["draft", "ready", "in-progress", "blocked", "completed", "archived"] : ["draft", "ready", "in-progress", "blocked", "completed"],
+      excluded: includeArchived ? [] : ["archived"]
+    },
     touched_files: touchedFiles.length,
     fyi_count: activeMatches.length,
     ignored_count: ignoredCount,
@@ -5194,6 +5560,12 @@ function printCIJson(dir, touchedFiles, activeMatches, ignoredCount, pluginSigna
   }
   console.log(JSON.stringify(output, null, 2));
 }
+function printOwnershipScope(includeArchived) {
+  console.log("Ownership scope:");
+  console.log("- Active and completed Work Items");
+  console.log(includeArchived ? "- Archived Work Items included (--include-archived)" : "- Archived Work Items excluded");
+  console.log("");
+}
 async function runGuard(opts = {}) {
   const dir = cwd();
   const interactive = opts.interactive !== false && !opts.ci && !opts.json;
@@ -5235,7 +5607,10 @@ async function runGuard(opts = {}) {
     console.log("kaddo guard: no knowledge/ directory found. Run `kaddo init` first.");
     return;
   }
-  const artifacts = discoverKnowledge(dir);
+  const includeArchived = opts.includeArchived === true;
+  const artifacts = discoverKnowledge(dir).filter(
+    (a) => !(a.isWorkItem && a.lifecycle === "archived" && !includeArchived)
+  );
   const result = analyzeGuard(touchedFiles, artifacts, silentWithoutOwnership);
   const pluginSignals = runPlugins(plugins, currentFiles, (filePath) => {
     const abs = join(dir, filePath);
@@ -5256,7 +5631,7 @@ async function runGuard(opts = {}) {
     const ownerMapCI = loadOwners(dir);
     const matchedDomainsCI = collectMatchedDomains(activeMatches.map((m) => m.artifact.domains));
     const affectedOwnersCI = resolveAffectedOwners(matchedDomainsCI, ownerMapCI);
-    printCIJson(dir, touchedFiles, activeMatches, alreadyIgnoredMatches.length, pluginSignals, affectedOwnersCI, workspaceScan);
+    printCIJson(dir, touchedFiles, activeMatches, alreadyIgnoredMatches.length, pluginSignals, affectedOwnersCI, workspaceScan, includeArchived);
     return;
   }
   if (result.silenced && pluginSignals.length === 0) {
@@ -5266,12 +5641,18 @@ async function runGuard(opts = {}) {
   if (result.matches.length === 0 && pluginSignals.length === 0) {
     if (workspaceScan) printWorkspaceHeader(workspaceScan);
     printHeader(touchedFiles);
+    printOwnershipScope(includeArchived);
     console.log("  No artifact ownership matches found.");
+    console.log("");
+    console.log("Note:");
+    console.log("Guard checks ownership from active and completed Work Items.");
+    console.log("Run `kaddo explain` to inspect ownership coverage.");
     printUntracked();
     return;
   }
   if (workspaceScan) printWorkspaceHeader(workspaceScan);
   printHeader(touchedFiles);
+  printOwnershipScope(includeArchived);
   printUntracked();
   for (const match of activeMatches) {
     printFYI(match, dir);
@@ -5346,7 +5727,7 @@ function runIgnoreRemove(artifactId) {
 }
 
 // src/commands/explain.ts
-import matter3 from "gray-matter";
+import matter4 from "gray-matter";
 import { parse as parseYaml9 } from "yaml";
 
 // src/core/delivery-phase.ts
@@ -5678,6 +6059,11 @@ function loadExternalCapsules(dir) {
 
 // src/core/graph.ts
 var KNOWLEDGE2 = "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 toPosix2(p2) {
   return p2.replace(/\\/g, "/");
 }
@@ -5720,7 +6106,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}`;
@@ -5790,6 +6179,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: {
@@ -5797,6 +6187,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
   };
@@ -5844,8 +6238,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
@@ -5997,6 +6396,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,
@@ -6032,13 +6433,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");
   }
@@ -6074,6 +6485,8 @@ function loadGraphHints(dir) {
     const report = JSON.parse(readFile(p2));
     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,
@@ -6084,6 +6497,42 @@ function loadGraphHints(dir) {
   }
 }
 
+// src/services/installed-skills.ts
+import matter3 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 } = matter3(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;
+}
+function skillsForAgents(skills, agents) {
+  const set = new Set(agents.map((a) => a.replace(/\.md$/, "")));
+  return skills.filter((s) => s.appliesTo.some((a) => set.has(a))).map((s) => s.id);
+}
+
 // src/core/knowledge-discovery.ts
 var KNOWLEDGE4 = "knowledge";
 var CONSOLIDATED_TYPE = {
@@ -6416,6 +6865,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,
@@ -6557,13 +7010,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) {
@@ -6609,7 +7076,7 @@ function readKnowledge(dir) {
   if (!exists(knowledgePath)) return null;
   try {
     const raw = readFile(knowledgePath);
-    const { data, content } = matter3(raw);
+    const { data, content } = matter4(raw);
     return { content, data };
   } catch {
     return null;
@@ -6620,7 +7087,7 @@ function readRoadmap(dir) {
   if (!exists(roadmapPath)) return null;
   try {
     const raw = readFile(roadmapPath);
-    const { content } = matter3(raw);
+    const { content } = matter4(raw);
     return content.trim();
   } catch {
     return null;
@@ -6789,7 +7256,7 @@ function runExplain(opts) {
 }
 
 // src/core/context-pack.ts
-import matter4 from "gray-matter";
+import matter5 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR6 = "knowledge";
 function readScanJson(dir) {
@@ -6802,7 +7269,7 @@ function readScanJson(dir) {
   }
 }
 function firstParagraph2(markdown) {
-  const body = matter4(markdown).content.trim();
+  const body = matter5(markdown).content.trim();
   const para = body.split("\n\n").map((p2) => p2.trim()).find((p2) => p2 && !p2.startsWith("#"));
   return para ?? "";
 }
@@ -6975,6 +7442,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
@@ -7145,9 +7613,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");
@@ -7168,6 +7639,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");
@@ -7489,6 +7966,14 @@ function runUnderstand() {
   if (assessment.nextStep) {
     console.log(`Next step: ${assessment.nextStep}`);
   }
+  const installedSkills = discoverInstalledSkills(dir);
+  if (installedSkills.length > 0 && assessment.recommendedAgents.length > 0) {
+    const recSkills = skillsForAgents(installedSkills, assessment.recommendedAgents);
+    if (recSkills.length > 0) {
+      console.log("Recommended skills:");
+      for (const s of recSkills) console.log(`  - ${s}`);
+    }
+  }
   if (exp.externalCapsules.length > 0) {
     console.log("");
     console.log("External knowledge:");
@@ -7803,7 +8288,7 @@ function runStatus() {
 }
 
 // src/commands/learn.ts
-import matter5 from "gray-matter";
+import matter6 from "gray-matter";
 var ARCH_DIR9 = "knowledge";
 var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
 function findWorkItemFile(dir, id) {
@@ -7815,7 +8300,7 @@ function findWorkItemFile(dir, id) {
 }
 function updateWorkItemFile(filePath, learning) {
   const raw = readFile(filePath);
-  const { data, content } = matter5(raw);
+  const { data, content } = matter6(raw);
   data.status = "done";
   data.completed_at = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   let updatedContent = content;
@@ -7840,7 +8325,7 @@ ${learning.trim()}
 ${learning.trim()}
 `;
   }
-  const newRaw = matter5.stringify(updatedContent, data);
+  const newRaw = matter6.stringify(updatedContent, data);
   writeFile(filePath, newRaw);
 }
 async function runLearn(artifactId) {
@@ -7968,6 +8453,12 @@ function selectAgentModuleFiles(files, opts, state) {
   );
   return { files: selected, label };
 }
+function selectSkillModuleFiles(files, opts) {
+  const { ids, label } = selectSkills({ all: opts.all, group: opts.group });
+  const wanted = new Set(ids.map((id) => skillInstallPath(id)));
+  const selected = files.filter((f) => f.path.endsWith("README.md") || wanted.has(f.path));
+  return { files: selected, label };
+}
 function markModuleInstalled(dir, configKey, moduleName) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return;
@@ -8028,6 +8519,15 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
       console.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
+  } else if (mod.name === "skills") {
+    try {
+      const sel = selectSkillModuleFiles(mod.files, opts);
+      filesToInstall = sel.files;
+      log2.info(`Installing skills (${sel.label}).`);
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
   }
   const written = [];
   const skipped = [];
@@ -8058,6 +8558,13 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
     outro2("Agents installed. Kaddo prepares context \u2014 your LLM does the interpretation.");
     return;
   }
+  if (mod.name === "skills") {
+    log2.info("Skills are reusable capabilities agents apply \u2014 they never run anything.");
+    log2.info("More skills: `kaddo add skills --all` or `--group <delivery|tech|integration>`.");
+    log2.info("Read them in `knowledge/skills/` or via the Kaddo MCP server (`kaddo://skills`).");
+    outro2("Skills installed. Agents orchestrate; skills standardize.");
+    return;
+  }
   if (mod.workItemTypes.length > 0) {
     log2.info(`New work item types available:`);
     for (const t of mod.workItemTypes) {
@@ -8068,7 +8575,7 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
 }
 
 // src/core/ownership-suggest.ts
-import matter6 from "gray-matter";
+import matter7 from "gray-matter";
 var SCAN_PATH = ".kaddo/scan.json";
 function normalizeGlob(input) {
   let g = input.trim().replace(/\\/g, "/");
@@ -8190,11 +8697,11 @@ function suggestGlobs(artifact, signals) {
   return [...new Set(out)];
 }
 function applyOwnership(raw, globs, mode = "replace") {
-  const parsed = matter6(raw);
+  const parsed = matter7(raw);
   const existing = toStringArray3(parsed.data.code);
   const next = mode === "append" ? [.../* @__PURE__ */ new Set([...existing, ...globs])] : [...new Set(globs)];
   const data = { ...parsed.data, code: next };
-  return matter6.stringify(parsed.content, data);
+  return matter7.stringify(parsed.content, data);
 }
 
 // src/commands/owners.ts
@@ -10349,9 +10856,15 @@ function runGraphExport(opts = {}) {
   writeFile(join(dir, ".kaddo", "graph-hints.md"), renderGraphHintsMarkdown(hints));
   writeFile(join(dir, ".kaddo", "graph-hints.json"), serializeGraphHintsJson(hints));
   written.push(".kaddo/graph-hints.md", ".kaddo/graph-hints.json");
-  log2.success("Knowledge graph exported.");
+  log2.success(`Knowledge graph exported with ${scope} scope.`);
   log2.info(`Scope: ${scope} \xB7 Nodes: ${graph.nodes.length} \xB7 Edges: ${graph.edges.length}`);
   log2.info(`Relationship quality: ${hints.quality}`);
+  const hasWorkItemNodes = graph.nodes.some((n) => n.type === "work-item");
+  if (scope === "active" && !hasWorkItemNodes) {
+    log2.warn("No active Work Items found.");
+    log2.info("The active graph only includes knowledge layers.");
+    log2.info("Run `kaddo graph export --scope all` to include completed Work Items.");
+  }
   if (hints.hints.length > 0) {
     const shown = hints.hints.slice(0, 5);
     log2.warn(`${hints.hints.length} metadata hint(s) available:`);
@@ -10393,7 +10906,7 @@ var graphCmd = program.command("graph").description("Export the lightweight, fil
 graphCmd.command("export").description("Write the knowledge graph to .kaddo/graph.json and .kaddo/graph.mmd").option("--scope <scope>", "Graph scope: active (default) or all").option("--format <format>", "Output format: json, mermaid (default: both)").action((opts) => {
   runGraphExport(opts);
 });
-program.command("guard").description("Check if modified code has related artifacts that were not updated").option("--staged", "Check only staged files").option("--no-interactive", "Disable interactive ignore prompts").option("--ci", "CI mode: output JSON, no prompts, non-blocking").option("--json", "Output JSON (alias for --ci)").option("--workspace", "Also check local mapped module repos from .kaddo/modules.yml (opt-in)").action(async (opts) => {
+program.command("guard").description("Check if modified code has related artifacts that were not updated").option("--staged", "Check only staged files").option("--no-interactive", "Disable interactive ignore prompts").option("--ci", "CI mode: output JSON, no prompts, non-blocking").option("--json", "Output JSON (alias for --ci)").option("--workspace", "Also check local mapped module repos from .kaddo/modules.yml (opt-in)").option("--include-archived", "Include archived Work Items in ownership matching (excluded by default)").action(async (opts) => {
   await runGuard(opts);
 });
 var ignoreCmd = program.command("ignore").description("Manage guard ignore list");
@@ -10444,7 +10957,7 @@ modulesCmd.command("map").description("Register a secondary repository as a modu
 modulesCmd.command("list").description("List mapped modules").action(() => {
   runModulesList();
 });
-program.command("add [module]").description("Install an optional Kaddo module (adr, incident, rfc, migration, legacy, agents, standards, security, stack, git-strategy)").option("--all", "For `add agents`: install every agent (not just the recommended set)").option("--group <name>", "For `add agents`: install one layer group (business, product, tech, delivery, utilities)").action((moduleName, opts) => {
+program.command("add [module]").description("Install an optional Kaddo module (adr, incident, rfc, migration, legacy, agents, skills, standards, security, stack, git-strategy)").option("--all", "For `add agents` / `add skills`: install every item (not just the recommended set)").option("--group <name>", "For `add agents`: business|product|tech|delivery|utilities. For `add skills`: delivery|tech|integration").action((moduleName, opts) => {
   runAdd(moduleName ?? "", { all: opts.all, group: opts.group });
 });
 program.parseAsync(process.argv).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/cli",
-  "version": "3.20.0",
+  "version": "3.22.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {