@kaddo/mcp 3.45.0 → 3.46.0

package/dist/index.js

@@ -7947,7 +7947,8 @@ function buildUnderstandPlan(dir, config) {
       name: config.project.name,
       state,
       teamSize: config.team.size,
-      structure: config.project.structure
+      structure: config.project.structure,
+      language: "English"
     },
     scanAvailable: exists(join(dir, ".kaddo", "scan.json")),
     contextPackPath: ".kaddo/context-pack.md",
@@ -7966,42 +7967,140 @@ function agentName(file) {
 }
 function renderUnderstand(plan) {
   const { project, steps } = plan;
+  const rec = plan.nextStepRecommendation;
+  const ds = plan.deliveryState;
   const parts = [];
   parts.push("# Kaddo Understand Handoff\n");
   parts.push(
     "> Generated by `kaddo understand`. Kaddo does not call an LLM \u2014 you stay in control of the interpretation.\n"
   );
   parts.push("## Project\n");
-  parts.push(
-    [
-      `- Name: ${project.name}`,
-      `- State: ${project.state}`,
-      `- Team: ${project.teamSize}`,
-      `- Structure: ${project.structure}`
-    ].join("\n") + "\n"
-  );
-  parts.push("## Recommended Agent Flow\n");
-  parts.push(`Recommended order for a ${stateLabel2(project.state)} project:
+  const projectLines = [
+    `- Name: ${project.name}`,
+    `- State: ${project.state}`,
+    `- Team: ${project.teamSize}`,
+    `- Structure: ${project.structure}`
+  ];
+  if (project.language) projectLines.push(`- Language: ${project.language}`);
+  parts.push(projectLines.join("\n") + "\n");
+  if (plan.phase && rec) {
+    parts.push("## Current Phase\n");
+    const phaseLines = [`- Phase: ${plan.phase}`];
+    if (rec.agent) phaseLines.push(`- Recommended agent: ${agentName(rec.agent)}`);
+    if (rec.skill) phaseLines.push(`- Recommended skill: ${rec.skill}`);
+    phaseLines.push(`- Next step: ${rec.label}`);
+    if (rec.reason) phaseLines.push(`- Reason: ${rec.reason}`);
+    parts.push(phaseLines.join("\n") + "\n");
+  }
+  if (ds && ds.total_work_items > 0) {
+    parts.push("## Delivery State\n");
+    parts.push(
+      [
+        `- Draft Work Items: ${ds.draft_work_items}`,
+        `- Ready Work Items: ${ds.ready_work_items}`,
+        `- In-progress Work Items: ${ds.in_progress_work_items}`,
+        `- Blocked Work Items: ${ds.blocked_work_items}`,
+        `- Ownership coverage: ${ds.ownership_coverage}`,
+        `- Remaining Work Item candidates: ${ds.remaining_work_item_candidates}`,
+        `- Technical decision candidates: ${ds.decision_candidates}`,
+        `- Accepted ADRs: ${ds.accepted_adrs}`,
+        `- Installed adapters: ${ds.adapters_installed}`
+      ].join("\n") + "\n"
+    );
+  }
+  if (steps.length > 0) {
+    parts.push("## Recommended Agent Flow\n");
+    parts.push(`Recommended order for a ${stateLabel2(project.state)} project:
 `);
-  parts.push(
-    steps.map((s, i) => {
-      const flag = s.installed ? "" : "  _(not installed \u2014 run `kaddo add agents`)_";
-      return `${i + 1}. ${agentName(s.agent)} \u2192 \`${s.output}\`${flag}`;
-    }).join("\n") + "\n"
-  );
+    parts.push(
+      steps.map((s, i) => {
+        const flag = s.installed ? "" : "  _(not installed \u2014 run `kaddo add agents`)_";
+        return `${i + 1}. ${agentName(s.agent)} \u2192 \`${s.output}\`${flag}`;
+      }).join("\n") + "\n"
+    );
+  } else if (rec) {
+    parts.push("## Recommended Agent Flow\n");
+    const flowSteps = [];
+    if (rec.agent) flowSteps.push(agentName(rec.agent));
+    if (rec.secondary) {
+      for (const s of rec.secondary) {
+        if (s.agent) flowSteps.push(agentName(s.agent));
+        else if (s.skill) flowSteps.push(`${s.skill} skill`);
+        else if (s.command) flowSteps.push(`\`${s.command}\``);
+      }
+    }
+    if (flowSteps.length > 0) {
+      parts.push(flowSteps.map((f, i) => `${i + 1}. ${f}`).join("\n") + "\n");
+    }
+  }
+  if (rec) {
+    parts.push("## Primary Recommendation\n");
+    const recLines = [`- id: ${rec.id}`];
+    if (rec.agent) recLines.push(`- agent: ${agentName(rec.agent)}`);
+    if (rec.skill) recLines.push(`- skill: ${rec.skill}`);
+    if (rec.command) recLines.push(`- command: \`${rec.command}\``);
+    recLines.push(`- reason: ${rec.reason}`);
+    parts.push(recLines.join("\n") + "\n");
+  }
+  if (rec?.secondary && rec.secondary.length > 0) {
+    parts.push("## Secondary Recommendations\n");
+    parts.push(rec.secondary.map((s, i) => `${i + 1}. ${s.label}`).join("\n") + "\n");
+  }
+  if (plan.activeWorkItems && plan.activeWorkItems.length > 0) {
+    parts.push("## Active Work Items\n");
+    parts.push(
+      plan.activeWorkItems.map((w) => `- ${w.id} [${w.type}] ${w.lifecycle} \u2014 ${w.title}`).join("\n") + "\n"
+    );
+  }
   parts.push("## Context Pack\n");
   const scanNote = plan.scanAvailable ? "" : " (incomplete \u2014 run `kaddo scan` first for a richer baseline)";
   parts.push(`Use \`${plan.contextPackPath}\` as the primary input${scanNote}.
 `);
+  const agentPaths = [];
+  if (plan.recommendedPaths && plan.recommendedPaths.length > 0) {
+    agentPaths.push(...plan.recommendedPaths);
+  } else if (steps.length > 0) {
+    agentPaths.push(...steps.map((s) => agentInstallPath(s.agent)));
+  }
+  if (plan.recommendedSkillPaths && plan.recommendedSkillPaths.length > 0) {
+    agentPaths.push(...plan.recommendedSkillPaths);
+  }
+  agentPaths.push(plan.contextPackPath);
   parts.push("## Agent Prompts\n");
-  parts.push(
-    steps.map((s) => `- \`${agentInstallPath(s.agent)}\``).join("\n") + "\n"
-  );
-  parts.push("## Expected Outputs\n");
-  parts.push(steps.map((s) => `- \`${s.output}\``).join("\n") + "\n");
+  if (agentPaths.length > 1) {
+    parts.push("Use:\n");
+    parts.push(agentPaths.map((p) => `- \`${p}\``).join("\n") + "\n");
+  } else {
+    parts.push(`- \`${plan.contextPackPath}\`
+`);
+  }
+  if (steps.length > 0) {
+    parts.push("## Expected Outputs\n");
+    parts.push(steps.map((s) => `- \`${s.output}\``).join("\n") + "\n");
+  } else if (rec) {
+    parts.push("## Expected Outputs\n");
+    const outputs = [];
+    if (rec.target) outputs.push(`- \`${rec.target}\``);
+    if (rec.id === "refine-work-item" || rec.id === "resolve-blocker")
+      outputs.push("- Refined Work Item content.");
+    if (rec.id === "create-work-item")
+      outputs.push("- A new Work Item under `knowledge/delivery/work-items/`.");
+    if (rec.id === "implement")
+      outputs.push("- Implementation plan or code changes guided by the Work Item.");
+    if (rec.id === "guard")
+      outputs.push("- Updated knowledge artifacts reflecting recent code changes.");
+    if (rec.id === "install-adapter")
+      outputs.push("- An adapter configured and injected (`kaddo adapters list`).");
+    if (outputs.length > 0) {
+      parts.push("The LLM should produce:\n");
+      parts.push(outputs.join("\n") + "\n");
+    } else {
+      parts.push("_See the primary recommendation above._\n");
+    }
+  }
   parts.push("## Copy/Paste Instructions\n");
-  const first2 = steps[0];
-  if (first2) {
+  if (steps.length > 0) {
+    const first2 = steps[0];
     parts.push(
       [
         `Start with **${agentName(first2.agent)}**:`,
@@ -8013,9 +8112,31 @@ function renderUnderstand(plan) {
         `5. Save the result in: \`${first2.output}\``
       ].join("\n") + "\n"
     );
+  } else if (agentPaths.length > 1) {
+    parts.push("Paste the following into your LLM chat:\n");
+    parts.push(agentPaths.map((p, i) => `${i + 1}. \`${p}\``).join("\n") + "\n");
+    if (rec?.agent) {
+      parts.push(`Ask the LLM to follow the ${agentName(rec.agent)} instructions.
+`);
+    }
+  } else {
+    parts.push(`Paste \`${plan.contextPackPath}\` into your LLM chat.
+`);
   }
   parts.push("## Next Steps\n");
-  if (steps.length > 1) {
+  if (rec) {
+    const nextLines = [];
+    nextLines.push(`1. ${rec.label}`);
+    let n = 2;
+    if (rec.secondary) {
+      for (const s of rec.secondary) {
+        nextLines.push(`${n}. ${s.label}`);
+        n++;
+      }
+    }
+    nextLines.push(`${n}. Re-run \`kaddo explain\`.`);
+    parts.push(nextLines.join("\n") + "\n");
+  } else if (steps.length > 1) {
     parts.push(
       `After saving \`${steps[0].output}\`, continue with **${agentName(steps[1].agent)}** (feed it the context pack plus the artifacts you already produced). Re-run \`kaddo understand\` any time to see this plan again.
 `

package/package.json

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