@kaddo/cli 3.51.0 → 3.53.0

package/dist/index.js

@@ -4643,6 +4643,7 @@ var RECOMMENDED_BY_STATE = {
     "adr-agent.md"
   ],
   "pre-ai": [
+    "business-agent.md",
     "capability-agent.md",
     "architecture-agent.md",
     "roadmap-agent.md",
@@ -8856,23 +8857,33 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   if (!exists(join(dir, ".kaddo", "context-pack.md"))) {
     return { id: "context", phase: "Discovery", label: "Run `kaddo context` to prepare the LLM context pack.", command: "kaddo context", reason: "No context pack has been generated yet." };
   }
-  if (!exists(join(dir, ".kaddo", "understand.md"))) {
-    return { id: "understand", phase: "Discovery", label: "Run `kaddo understand` to summarize the project context.", command: "kaddo understand", reason: "No understand handoff has been generated yet." };
-  }
   const discovery = state === "pre-ai" || state === "legacy";
-  const refine = (id, agent, target, quality, verb = "complete") => ({
-    id,
-    phase: "Knowledge Refinement",
-    label: `Use ${agent} to ${verb} \`${target}\`.`,
-    agent,
-    target,
-    reason: `${target} is ${quality === "missing" ? "missing" : "still a bootstrap placeholder or too thin"}.`,
-    instructions: [
-      "The baseline file exists but does not yet hold real, project-specific knowledge.",
-      `Use the ${agent} to replace the placeholders with real knowledge.`,
-      "Do not write code."
-    ]
-  });
+  const resolveAgent = (agent) => {
+    const file = agent.endsWith(".md") ? agent : `${agent}.md`;
+    const path6 = agentInstallPath(file);
+    const installed = isFile(join(dir, path6));
+    const group = agentGroupOf(file);
+    return { agentPath: path6, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+  };
+  const refine = (id, agent, target, quality, verb = "complete") => {
+    const ar = resolveAgent(agent);
+    return {
+      id,
+      phase: "Knowledge Refinement",
+      label: `Use ${agent} to ${verb} \`${target}\`.`,
+      agent,
+      target,
+      agentPath: ar.agentPath,
+      agentInstalled: ar.agentInstalled,
+      installCommand: ar.installCommand,
+      reason: `${target} is ${quality === "missing" ? "missing" : "still a bootstrap placeholder or too thin"}.`,
+      instructions: [
+        "The baseline file exists but does not yet hold real, project-specific knowledge.",
+        `Use the ${agent} to replace the placeholders with real knowledge.`,
+        "Do not write code."
+      ]
+    };
+  };
   if (qBusiness !== "useful") return refine("refine-business", "business-agent", B, qBusiness);
   if (qProduct !== "useful" || qCap !== "useful") {
     if (qCap !== "useful") {
@@ -8885,6 +8896,9 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     const agent = ctx.agents.includes("codebase-agent") ? "codebase-agent" : "architecture-agent";
     return refine("refine-codebase", agent, CB, qCodebase);
   }
+  if (!exists(join(dir, ".kaddo", "understand.md"))) {
+    return { id: "understand", phase: "Discovery", label: "Run `kaddo understand` to summarize the project context.", command: "kaddo understand", reason: "No understand handoff has been generated yet." };
+  }
   const oq = buildOpenQuestionsReport(dir, now);
   if (oq.summary.blocking_open > 0) {
     return { id: "questions", phase: "Knowledge Refinement", label: "Run `kaddo questions` to see source locations and resolution guidance, then resolve, assume or defer the blocking open questions.", command: "kaddo questions", reason: `${oq.summary.blocking_open} blocking open question(s) remain.` };
@@ -9665,7 +9679,11 @@ function mapNextStepId(id) {
     "add-skills": "enable-kaddo",
     scan: "scan-repository",
     context: "scan-repository",
-    understand: "scan-repository"
+    "refine-business": "define-business",
+    "refine-product": "define-product",
+    "refine-capabilities": "discover-capabilities",
+    "refine-current-state": "describe-architecture",
+    "refine-codebase": "describe-architecture"
   };
   return MAP[id] ?? id;
 }
@@ -11034,9 +11052,22 @@ function renderContextPack(pack) {
   if (isBootstrapIncomplete) {
     parts.push("No agent handoff yet.\n");
     parts.push("Run `kaddo bootstrap` first to create the baseline files.\n");
+  } else if (rec.agent && rec.agentInstalled === false) {
+    parts.push(`Recommended agent: ${rec.agent.replace(/\.md$/, "")}
+`);
+    parts.push("**Agent is not installed.**\n");
+    if (rec.installCommand) {
+      parts.push(`Run \`${rec.installCommand}\` to install it.
+`);
+    }
+    parts.push("Then run `kaddo context` and `kaddo understand`.\n");
   } else {
     parts.push(`Recommended next for the **${pack.phase.phase}** phase:
 `);
+    if (rec.agentPath) {
+      parts.push(`Agent prompt: \`${rec.agentPath}\`
+`);
+    }
     parts.push(handoff.recommendedAgents.map((a, i) => `${i + 1}. ${a}`).join("\n") + "\n");
     if (handoff.nextSteps.length > 0) {
       parts.push("Next step:\n");
@@ -11264,72 +11295,85 @@ function renderUnderstand(plan) {
   parts.push(`Use \`${plan.contextPackPath}\` as the primary input${scanNote}.
 `);
   if (!isBootstrap) {
-    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");
-    if (agentPaths.length > 1) {
-      parts.push("Use:\n");
-      parts.push(agentPaths.map((p2) => `- \`${p2}\``).join("\n") + "\n");
-    } else {
-      parts.push(`- \`${plan.contextPackPath}\`
+    const agentMissing = rec && rec.agent && rec.agentInstalled === false;
+    if (agentMissing) {
+      parts.push("## Missing Agent\n");
+      parts.push(`${agentName(rec.agent)} is not installed.
 `);
-    }
-    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");
-    if (steps.length > 0) {
-      const first2 = steps[0];
-      parts.push(
-        [
-          `Start with **${agentName(first2.agent)}**:`,
-          "",
-          "1. Open your preferred LLM chat (Claude, ChatGPT, Cursor, Copilot, Windsurf\u2026).",
-          `2. Paste the context pack: \`${plan.contextPackPath}\``,
-          `3. Paste the agent prompt: \`${agentInstallPath(first2.agent)}\``,
-          `4. Ask the LLM to produce: \`${first2.output}\``,
-          `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((p2, i) => `${i + 1}. \`${p2}\``).join("\n") + "\n");
-      if (rec?.agent) {
-        parts.push(`Ask the LLM to follow the ${agentName(rec.agent)} instructions.
+      if (rec.installCommand) {
+        parts.push(`Run \`${rec.installCommand}\` to install it.
 `);
       }
+      parts.push("Then run:\n");
+      parts.push("1. `kaddo context`\n2. `kaddo understand`\n");
     } else {
-      parts.push(`Paste \`${plan.contextPackPath}\` into your LLM chat.
+      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");
+      if (agentPaths.length > 1) {
+        parts.push("Use:\n");
+        parts.push(agentPaths.map((p2) => `- \`${p2}\``).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");
+      if (steps.length > 0) {
+        const first2 = steps[0];
+        parts.push(
+          [
+            `Start with **${agentName(first2.agent)}**:`,
+            "",
+            "1. Open your preferred LLM chat (Claude, ChatGPT, Cursor, Copilot, Windsurf\u2026).",
+            `2. Paste the context pack: \`${plan.contextPackPath}\``,
+            `3. Paste the agent prompt: \`${agentInstallPath(first2.agent)}\``,
+            `4. Ask the LLM to produce: \`${first2.output}\``,
+            `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((p2, i) => `${i + 1}. \`${p2}\``).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");
@@ -11391,25 +11435,36 @@ function renderUnderstandTerminal(plan) {
     lines.push("  3. kaddo context");
     lines.push("  4. kaddo understand");
   } else {
-    const first2 = steps[0];
-    if (first2) {
-      lines.push("Foundational knowledge still needed:");
-      steps.forEach((s, i) => {
-        const flag = s.installed ? "" : "  (not installed)";
-        lines.push(`  ${i + 1}. ${agentName(s.agent)} \u2192 ${s.output}${flag}`);
-      });
-      lines.push("");
-      lines.push(`First step: use ${agentName(first2.agent)}.`);
-      lines.push("");
-      lines.push(`  Context:         ${plan.contextPackPath}`);
-      lines.push(`  Agent prompt:    ${agentInstallPath(first2.agent)}`);
-      lines.push(`  Expected output: ${first2.output}`);
-      lines.push("");
-      lines.push("Instructions:");
-      lines.push("  Open your preferred LLM chat, paste the context pack, then paste the agent");
-      lines.push("  prompt. Ask the LLM to generate the expected output and save it in the target file.");
+    const agentMissing = rec && rec.agent && rec.agentInstalled === false;
+    if (agentMissing) {
+      lines.push(`Missing agent: ${agentName(rec.agent)}`);
+      if (rec.installCommand) {
+        lines.push(`Run: ${rec.installCommand}`);
+      }
+      lines.push("Then run:");
+      lines.push("  1. kaddo context");
+      lines.push("  2. kaddo understand");
     } else {
-      lines.push("Foundational knowledge looks complete \u2014 see the phase recommendation below.");
+      const first2 = steps[0];
+      if (first2) {
+        lines.push("Foundational knowledge still needed:");
+        steps.forEach((s, i) => {
+          const flag = s.installed ? "" : "  (not installed)";
+          lines.push(`  ${i + 1}. ${agentName(s.agent)} \u2192 ${s.output}${flag}`);
+        });
+        lines.push("");
+        lines.push(`First step: use ${agentName(first2.agent)}.`);
+        lines.push("");
+        lines.push(`  Context:         ${plan.contextPackPath}`);
+        lines.push(`  Agent prompt:    ${agentInstallPath(first2.agent)}`);
+        lines.push(`  Expected output: ${first2.output}`);
+        lines.push("");
+        lines.push("Instructions:");
+        lines.push("  Open your preferred LLM chat, paste the context pack, then paste the agent");
+        lines.push("  prompt. Ask the LLM to generate the expected output and save it in the target file.");
+      } else {
+        lines.push("Foundational knowledge looks complete \u2014 see the phase recommendation below.");
+      }
     }
   }
   lines.push("");
@@ -11524,6 +11579,11 @@ function runUnderstand() {
       for (const r of assessment.reasons) console.log(`  - ${r}`);
     }
     if (rec.agent) console.log(`Recommended: ${rec.agent}`);
+    if (rec.agent && rec.agentInstalled === false) {
+      console.log(`  \u26A0 Agent not installed. Run: ${rec.installCommand ?? "kaddo add agents"}`);
+    } else if (rec.agentPath) {
+      console.log(`  Agent prompt: ${rec.agentPath}`);
+    }
     if (rec.skill) console.log(`Recommended skill: ${rec.skill}`);
     console.log(`Next step: ${rec.label}`);
     if (rec.reason) console.log(`Why: ${rec.reason}`);

package/package.json

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