@kaddo/cli 3.44.0 → 3.46.0

package/README.md

@@ -543,6 +543,7 @@ create --from roadmap → owners → guard → explain`.
 | v3.42 | Agent & skill version metadata: installed agents/skills carry a `version:`; `kaddo agents status` / `kaddo skills status` classify up-to-date/outdated/unknown-version/modified/missing; `agents update` / `skills update` refresh outdated safely (never overwrite edits without `--force`); MCP `kaddo://installed-assets` |
 | v3.43 | Capability-grounded roadmap: each `RM-xxx` candidate is graded on related domain / capability / source signals; `roadmap_quality` surfaced in `explain`/`context`/`understand`; `create --from roadmap` preserves `source_roadmap_candidate` + related metadata into the Work Item; roadmap-agent emits grounded fields (never materializes Work Items); MCP `kaddo://roadmap-quality` |
 | v3.44 | Roadmap counting alignment + materialization quality: `explain`/`context` separate **Roadmap initiatives** from **Work Item candidates** (`## Roadmap Status`); two-level `roadmapQuality` (initiatives + work_item_candidates); `create --from roadmap` normalizes metadata — fills `domains` from `related_domain`, splits comma-joined `related_capabilities` into a real list, carries `source_roadmap_initiative`/`source_work_item_candidate`/`source_signals`/`decision_candidates`, improved Source + Context-From-Roadmap body + ADR warning; MCP `kaddo://work-item-candidates` |
+| v3.45 | State-aware next step: `resolveNextStep` decides from the real delivery state (draft/ready/in-progress, ownership, ADRs, adapters) instead of always suggesting `create --from roadmap` — draft → work-item-agent, ready → adapter/implementation-agent, in-progress → guard; parallel **secondary** recommendations (ownership, ADRs, remaining candidates); `deliveryState` + recommendation in `explain`/`context`; MCP `kaddo://next-step` |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -8113,7 +8113,124 @@ function buildSharedFileStatuses(statuses) {
   }));
 }
 
+// src/core/decisions.ts
+var CANDIDATES_DISCOVERY = "knowledge/tech/discovery/decision-candidates.md";
+var CANDIDATES_LEGACY = "knowledge/tech/decision-candidates.md";
+var DECISIONS_DIR = "knowledge/tech/decisions";
+function resolveCandidatesPath(dir) {
+  const discovery = exists(join(dir, CANDIDATES_DISCOVERY));
+  const legacy = exists(join(dir, CANDIDATES_LEGACY));
+  if (discovery) return { path: CANDIDATES_DISCOVERY, legacy: false, bothExist: legacy };
+  if (legacy) return { path: CANDIDATES_LEGACY, legacy: true, bothExist: false };
+  return { path: null, legacy: false, bothExist: false };
+}
+function cleanCandidateTitle(title) {
+  return title.replace(/^\s*#{1,6}\s+/, "").replace(/^\s*[-*]\s+/, "").replace(/^\s*\(?\d+\)?[.):]\s+/, "").trim();
+}
+function slugify2(s) {
+  return cleanCandidateTitle(s).toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 70).replace(/-+$/g, "");
+}
+function parseDecisionCandidates(md) {
+  const out = [];
+  for (const line of md.split(/\r?\n/)) {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      const raw = m[1].trim();
+      if (!raw || /^_.*_$/.test(raw)) continue;
+      const t = cleanCandidateTitle(raw);
+      if (t) out.push(t);
+    }
+  }
+  return out;
+}
+function countAdrs(dir) {
+  const base = join(dir, DECISIONS_DIR);
+  if (!exists(base)) return { total: 0, draft: 0, accepted: 0 };
+  let total = 0;
+  let draft = 0;
+  let accepted = 0;
+  for (const entry of readDir(base)) {
+    if (!entry.endsWith(".md") || entry === ".gitkeep") continue;
+    const full = join(base, entry);
+    if (!isFile(full)) continue;
+    total += 1;
+    let content = "";
+    try {
+      content = readFile(full);
+    } catch {
+      continue;
+    }
+    const status = content.match(/^\s*status:\s*([a-z-]+)/im)?.[1]?.toLowerCase();
+    if (status === "accepted") accepted += 1;
+    else draft += 1;
+  }
+  return { total, draft, accepted };
+}
+function buildTechDecisions(dir) {
+  const resolved = resolveCandidatesPath(dir);
+  let titles = [];
+  if (resolved.path) {
+    try {
+      titles = parseDecisionCandidates(readFile(join(dir, resolved.path)));
+    } catch {
+      titles = [];
+    }
+  }
+  const { total, draft, accepted } = countAdrs(dir);
+  const candidate_list = titles.map((title, i) => {
+    const n = String(total + i + 1).padStart(3, "0");
+    return { title, source: resolved.path, suggestedAdrFile: `${DECISIONS_DIR}/ADR-${n}-${slugify2(title)}.md` };
+  });
+  let status;
+  if (accepted > 0) status = "accepted-adrs";
+  else if (total > 0) status = "draft-adrs";
+  else if (titles.length > 0) status = "candidates";
+  else status = "none";
+  return {
+    status,
+    candidates: titles.length,
+    adrs: total,
+    draft_adrs: draft,
+    accepted_adrs: accepted,
+    candidate_list,
+    candidates_source: resolved.path,
+    candidates_legacy_location: resolved.legacy,
+    candidates_both_exist: resolved.bothExist
+  };
+}
+
 // src/core/next-step.ts
+function buildDeliveryState(dir) {
+  const wis = discoverWorkItems(dir);
+  const byState = (s) => wis.filter((w) => w.lifecycle === s).length;
+  const total = wis.length;
+  const withOwnership = wis.filter((w) => w.codeGlobs.length > 0).length;
+  const td = buildTechDecisions(dir);
+  const roadmapPath = join(dir, "knowledge/delivery/roadmap.md");
+  const roadmapMd = exists(roadmapPath) ? safeRead(roadmapPath) : null;
+  const stats = roadmapStats(roadmapMd, total);
+  const adapters = installedAdapters(dir);
+  return {
+    phase: "",
+    draft_work_items: byState("draft"),
+    ready_work_items: byState("ready"),
+    in_progress_work_items: byState("in-progress"),
+    blocked_work_items: byState("blocked"),
+    total_work_items: total,
+    ownership_coverage: `${withOwnership}/${total}`,
+    remaining_work_item_candidates: stats.remaining_work_item_candidates,
+    decision_candidates: td.candidates,
+    accepted_adrs: td.accepted_adrs,
+    adapters_installed: adapters.length
+  };
+}
+function safeRead(p2) {
+  try {
+    return readFile(p2);
+  } catch {
+    return null;
+  }
+}
 function roadmapSignal(dir) {
   const p2 = join(dir, "knowledge/delivery/roadmap.md");
   if (!exists(p2)) return "missing";
@@ -8210,15 +8327,117 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   if (roadmap !== "has-candidates") {
     return { id: "roadmap", phase: "Planning", label: "Use roadmap-agent to define roadmap candidates (`kaddo roadmap`).", command: "kaddo roadmap", agent: "roadmap-agent", target: "knowledge/delivery/roadmap.md", reason: "The roadmap has no candidates yet." };
   }
-  const wi = workItemsSignal(dir);
-  if (wi === "none" || wi === "none-ready") {
-    return { id: "create-work-item", phase: "Delivery Preparation", label: "Run `kaddo create --from roadmap` to materialize the first Work Item.", command: "kaddo create --from roadmap", reason: "The roadmap has candidates but no Work Item is ready." };
+  const st = buildDeliveryState(dir);
+  const secondary = buildSecondaryRecommendations(st);
+  if (st.total_work_items === 0) {
+    return {
+      id: "create-work-item",
+      phase: "Delivery Preparation",
+      label: "Run `kaddo create --from roadmap` to materialize the first Work Item.",
+      command: "kaddo create --from roadmap",
+      reason: "The roadmap has candidates but no Work Item exists yet.",
+      ...secondary.length ? { secondary } : {}
+    };
   }
-  const adapters = installedAdapters(dir);
-  if (adapters.length === 0) {
-    return { id: "install-adapter", phase: "Active Delivery", label: "Run `kaddo adapters list` and install the adapter for your preferred agent.", command: "kaddo adapters list", reason: "A Work Item is ready but no adapter is installed." };
+  const adapters = st.adapters_installed;
+  if (st.ready_work_items > 0) {
+    if (adapters === 0) {
+      return {
+        id: "install-adapter",
+        phase: "Active Delivery",
+        label: "Install or configure an adapter before implementation (`kaddo adapters list`).",
+        command: "kaddo adapters list",
+        reason: `${st.ready_work_items} Work Item(s) are ready but no adapter is installed.`,
+        ...secondary.length ? { secondary } : {}
+      };
+    }
+    return {
+      id: "implement",
+      phase: "Active Delivery",
+      label: "Use the implementation-agent or your installed adapter to plan implementation.",
+      agent: "implementation-agent",
+      reason: `${st.ready_work_items} Work Item(s) are ready and an adapter is installed.`,
+      ...secondary.length ? { secondary } : {}
+    };
+  }
+  if (st.in_progress_work_items > 0) {
+    return {
+      id: "guard",
+      phase: "Active Delivery",
+      label: "Run `kaddo guard` and update affected knowledge after significant changes.",
+      command: "kaddo guard",
+      reason: `${st.in_progress_work_items} Work Item(s) are in progress.`,
+      ...secondary.length ? { secondary } : {}
+    };
+  }
+  if (st.draft_work_items > 0) {
+    return {
+      id: "refine-work-item",
+      phase: "Active Delivery",
+      label: "Refine the existing draft Work Item with the work-item-agent.",
+      agent: "work-item-agent",
+      skill: "work-item-refinement",
+      reason: `There ${st.draft_work_items === 1 ? "is" : "are"} ${st.draft_work_items} draft Work Item${st.draft_work_items === 1 ? "" : "s"} and no Work Item is ready.`,
+      ...secondary.length ? { secondary } : {}
+    };
+  }
+  if (st.blocked_work_items > 0) {
+    return {
+      id: "resolve-blocker",
+      phase: "Active Delivery",
+      label: "Resolve the blocker on the blocked Work Item with the work-item-agent.",
+      agent: "work-item-agent",
+      reason: `${st.blocked_work_items} Work Item(s) are blocked.`,
+      ...secondary.length ? { secondary } : {}
+    };
+  }
+  if (st.remaining_work_item_candidates > 0) {
+    return {
+      id: "materialize-more-work-items",
+      phase: "Maintenance",
+      label: `Materialize the remaining ${st.remaining_work_item_candidates} Work Item candidate(s) with \`kaddo create --from roadmap\`.`,
+      command: "kaddo create --from roadmap",
+      reason: "No active Work Items remain; roadmap candidates are still pending.",
+      ...secondary.length ? { secondary } : {}
+    };
+  }
+  return {
+    id: "plan-next",
+    phase: "Maintenance",
+    label: "Use the roadmap-agent to plan the next initiative.",
+    agent: "roadmap-agent",
+    reason: "No active Work Items and no remaining roadmap candidates."
+  };
+}
+function buildSecondaryRecommendations(st) {
+  const out = [];
+  const [withOwnership] = st.ownership_coverage.split("/").map(Number);
+  if (st.total_work_items > 0 && withOwnership < st.total_work_items) {
+    out.push({
+      id: "suggest-ownership",
+      label: "Run `kaddo owners suggest` for Work Items without code ownership.",
+      command: "kaddo owners suggest",
+      reason: `Ownership coverage is ${st.ownership_coverage}.`
+    });
   }
-  return { id: "implement", phase: "Active Delivery", label: "Implement the ready Work Item and run `kaddo guard`.", reason: "A Work Item is ready and an adapter is installed." };
+  if (st.total_work_items > 0 && st.decision_candidates > 0 && st.accepted_adrs === 0) {
+    out.push({
+      id: "materialize-adrs",
+      label: "Use the adr-writing skill (`kaddo adr`) to materialize decision candidates into ADRs before implementing related technical Work Items.",
+      command: "kaddo adr",
+      skill: "adr-writing",
+      reason: `There are ${st.decision_candidates} technical decision candidate(s) and ${st.accepted_adrs} accepted ADR(s).`
+    });
+  }
+  if (st.total_work_items > 0 && st.remaining_work_item_candidates > 0) {
+    out.push({
+      id: "materialize-more-work-items",
+      label: `Later, materialize the remaining ${st.remaining_work_item_candidates} Work Item candidate(s) with \`kaddo create --from roadmap\`.`,
+      command: "kaddo create --from roadmap",
+      reason: `There are ${st.remaining_work_item_candidates} remaining Work Item candidate(s).`
+    });
+  }
+  return out;
 }
 
 // src/core/readiness.ts
@@ -8313,92 +8532,6 @@ function buildReadinessReport(dir, now = /* @__PURE__ */ new Date()) {
   };
 }
 
-// src/core/decisions.ts
-var CANDIDATES_DISCOVERY = "knowledge/tech/discovery/decision-candidates.md";
-var CANDIDATES_LEGACY = "knowledge/tech/decision-candidates.md";
-var DECISIONS_DIR = "knowledge/tech/decisions";
-function resolveCandidatesPath(dir) {
-  const discovery = exists(join(dir, CANDIDATES_DISCOVERY));
-  const legacy = exists(join(dir, CANDIDATES_LEGACY));
-  if (discovery) return { path: CANDIDATES_DISCOVERY, legacy: false, bothExist: legacy };
-  if (legacy) return { path: CANDIDATES_LEGACY, legacy: true, bothExist: false };
-  return { path: null, legacy: false, bothExist: false };
-}
-function cleanCandidateTitle(title) {
-  return title.replace(/^\s*#{1,6}\s+/, "").replace(/^\s*[-*]\s+/, "").replace(/^\s*\(?\d+\)?[.):]\s+/, "").trim();
-}
-function slugify2(s) {
-  return cleanCandidateTitle(s).toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 70).replace(/-+$/g, "");
-}
-function parseDecisionCandidates(md) {
-  const out = [];
-  for (const line of md.split(/\r?\n/)) {
-    const m = line.match(/^##\s+(.+?)\s*$/);
-    if (m) {
-      const raw = m[1].trim();
-      if (!raw || /^_.*_$/.test(raw)) continue;
-      const t = cleanCandidateTitle(raw);
-      if (t) out.push(t);
-    }
-  }
-  return out;
-}
-function countAdrs(dir) {
-  const base = join(dir, DECISIONS_DIR);
-  if (!exists(base)) return { total: 0, draft: 0, accepted: 0 };
-  let total = 0;
-  let draft = 0;
-  let accepted = 0;
-  for (const entry of readDir(base)) {
-    if (!entry.endsWith(".md") || entry === ".gitkeep") continue;
-    const full = join(base, entry);
-    if (!isFile(full)) continue;
-    total += 1;
-    let content = "";
-    try {
-      content = readFile(full);
-    } catch {
-      continue;
-    }
-    const status = content.match(/^\s*status:\s*([a-z-]+)/im)?.[1]?.toLowerCase();
-    if (status === "accepted") accepted += 1;
-    else draft += 1;
-  }
-  return { total, draft, accepted };
-}
-function buildTechDecisions(dir) {
-  const resolved = resolveCandidatesPath(dir);
-  let titles = [];
-  if (resolved.path) {
-    try {
-      titles = parseDecisionCandidates(readFile(join(dir, resolved.path)));
-    } catch {
-      titles = [];
-    }
-  }
-  const { total, draft, accepted } = countAdrs(dir);
-  const candidate_list = titles.map((title, i) => {
-    const n = String(total + i + 1).padStart(3, "0");
-    return { title, source: resolved.path, suggestedAdrFile: `${DECISIONS_DIR}/ADR-${n}-${slugify2(title)}.md` };
-  });
-  let status;
-  if (accepted > 0) status = "accepted-adrs";
-  else if (total > 0) status = "draft-adrs";
-  else if (titles.length > 0) status = "candidates";
-  else status = "none";
-  return {
-    status,
-    candidates: titles.length,
-    adrs: total,
-    draft_adrs: draft,
-    accepted_adrs: accepted,
-    candidate_list,
-    candidates_source: resolved.path,
-    candidates_legacy_location: resolved.legacy,
-    candidates_both_exist: resolved.bothExist
-  };
-}
-
 // src/core/assets.ts
 import matter4 from "gray-matter";
 function canonicalAgents() {
@@ -8956,9 +9089,12 @@ function renderExplanationHuman(exp) {
   }
   lines.push(`- Next step: ${exp.readiness.recommended_next_step.label}`);
   lines.push("");
-  if (exp.suggestedNextSteps.length > 0) {
+  const rec = exp.nextStepRecommendation;
+  const secondary = rec.secondary ?? [];
+  const steps = secondary.length > 0 || /Delivery|Active|Maintenance/.test(rec.phase) ? [rec.label, ...secondary.map((s2) => s2.label)] : exp.suggestedNextSteps;
+  if (steps.length > 0) {
     lines.push("## Suggested Next Steps");
-    exp.suggestedNextSteps.forEach((s2, i) => lines.push(`${i + 1}. ${s2}`));
+    steps.forEach((s2, i) => lines.push(`${i + 1}. ${s2}`));
     lines.push("");
   }
   const r = exp.readiness;
@@ -9431,6 +9567,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     nextStep: nextStepRecommendation.label,
     recommendedAgents: nextStepRecommendation.agent ? [nextStepRecommendation.agent] : phase.recommendedAgents
   };
+  const deliveryState = { ...buildDeliveryState(dir), phase: nextStepRecommendation.phase };
   return {
     version: CONTEXT_PACK_VERSION,
     generatedAt: now.toISOString(),
@@ -9463,6 +9600,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     roadmap,
     phase: unifiedPhase,
     nextStepRecommendation,
+    deliveryState,
     techDecisions,
     techKnowledge,
     roadmapQuality: buildRoadmapQuality(dir),
@@ -9527,6 +9665,31 @@ function renderContextPack(pack) {
     parts.push(`Next step: ${pack.phase.nextStep}
 `);
   }
+  const ds = pack.deliveryState;
+  const rec = pack.nextStepRecommendation;
+  if (ds.total_work_items > 0 || rec.phase !== "Setup") {
+    parts.push("## Delivery State\n");
+    parts.push(
+      [
+        `- Phase: ${ds.phase}`,
+        `- Draft Work Items: ${ds.draft_work_items}`,
+        `- Ready Work Items: ${ds.ready_work_items}`,
+        `- In-progress Work Items: ${ds.in_progress_work_items}`,
+        `- Ownership coverage: ${ds.ownership_coverage}`,
+        `- Remaining Work Item candidates: ${ds.remaining_work_item_candidates}`
+      ].join("\n") + "\n"
+    );
+    parts.push("## Next Step Recommendation\n");
+    const recLines = [`- ${rec.label}`, `  - id: ${rec.id}`, `  - reason: ${rec.reason}`];
+    if (rec.agent) recLines.push(`  - agent: ${rec.agent}`);
+    if (rec.skill) recLines.push(`  - skill: ${rec.skill}`);
+    if (rec.command) recLines.push(`  - command: \`${rec.command}\``);
+    parts.push(recLines.join("\n") + "\n");
+    if (rec.secondary && rec.secondary.length > 0) {
+      parts.push("Also (secondary):\n");
+      parts.push(rec.secondary.map((s) => `- ${s.label}`).join("\n") + "\n");
+    }
+  }
   parts.push("## Knowledge Layers\n");
   parts.push(
     "Project knowledge is organized in four layers: **Business \u2192 Product \u2192 Tech \u2192 Delivery**.\n"
@@ -9812,7 +9975,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",
@@ -9821,6 +9985,18 @@ function buildUnderstandPlan(dir, config) {
     steps
   };
 }
+function enrichUnderstandPlan(plan, opts) {
+  return {
+    ...plan,
+    project: { ...plan.project, language: opts.language },
+    phase: opts.phase,
+    nextStepRecommendation: opts.nextStepRecommendation,
+    deliveryState: opts.deliveryState,
+    activeWorkItems: opts.activeWorkItems,
+    recommendedPaths: opts.recommendedPaths,
+    recommendedSkillPaths: opts.recommendedSkillPaths
+  };
+}
 
 // src/templates/understand-template.ts
 function stateLabel2(state) {
@@ -9831,42 +10007,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((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");
-  const first2 = steps[0];
-  if (first2) {
+  if (steps.length > 0) {
+    const first2 = steps[0];
     parts.push(
       [
         `Start with **${agentName(first2.agent)}**:`,
@@ -9878,9 +10152,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((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");
-  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.
 `
@@ -10030,8 +10326,13 @@ function runUnderstand() {
     for (const r of assessment.reasons) console.log(`  - ${r}`);
   }
   if (rec.agent) console.log(`Recommended: ${rec.agent}`);
+  if (rec.skill) console.log(`Recommended skill: ${rec.skill}`);
   console.log(`Next step: ${rec.label}`);
   if (rec.reason) console.log(`Why: ${rec.reason}`);
+  if (rec.secondary && rec.secondary.length > 0) {
+    console.log("Also:");
+    for (const s of rec.secondary) console.log(`  - ${s.label}`);
+  }
   const installedSkills = discoverInstalledSkills(dir);
   if (installedSkills.length > 0 && assessment.recommendedAgents.length > 0) {
     const recSkills = skillsForAgents(installedSkills, assessment.recommendedAgents);
@@ -10053,7 +10354,7 @@ function runUnderstand() {
     console.log(`Roadmap quality: ${rqi.grounded}/${rqi.total} initiatives grounded.`);
     console.log("  \u2192 Use roadmap-agent to ground roadmap initiatives in capability domains, gaps and source signals");
     console.log("    before `kaddo create --from roadmap`.");
-  } else if (rqi.total > 0 && rqi.grounded === rqi.total) {
+  } else if (rqi.total > 0 && rqi.grounded === rqi.total && exp.roadmap.materialized_work_items === 0) {
     console.log("");
     console.log("Roadmap initiatives are grounded. \u2192 Run `kaddo create --from roadmap` to materialize the first Work Item.");
   }
@@ -10100,7 +10401,41 @@ function runUnderstand() {
       console.log(`Other active work items: ${active.slice(1).map((w) => w.id).join(", ")}`);
     }
   }
-  writeFile(join(dir, ".kaddo", "understand.md"), renderUnderstand(plan));
+  const ds = buildDeliveryState(dir);
+  ds.phase = assessment.phase;
+  const wis = discoverWorkItems(dir);
+  const activeWis = wis.filter((w) => w.lifecycle && ["draft", "ready", "in-progress", "blocked"].includes(w.lifecycle)).map((w) => ({
+    id: w.id,
+    title: w.title,
+    type: w.type,
+    lifecycle: w.lifecycle ?? "draft",
+    knowledgeLevel: w.knowledgeLevel,
+    hasOwnership: w.codeGlobs.length > 0
+  }));
+  const recommendedPaths = [];
+  if (rec.agent) {
+    const agentFile = rec.agent.endsWith(".md") ? rec.agent : `${rec.agent}.md`;
+    if (agentIsInstalled(dir, agentFile)) {
+      recommendedPaths.push(agentInstallPath(agentFile));
+    }
+  }
+  const recommendedSkillPaths = [];
+  if (rec.skill) {
+    const sp = skillInstallPath(rec.skill);
+    if (exists(join(dir, sp))) {
+      recommendedSkillPaths.push(sp);
+    }
+  }
+  const enrichedPlan = enrichUnderstandPlan(plan, {
+    phase: assessment.phase,
+    nextStepRecommendation: rec,
+    deliveryState: ds,
+    activeWorkItems: activeWis,
+    recommendedPaths,
+    recommendedSkillPaths,
+    language: languageLabel(projectLanguage(config))
+  });
+  writeFile(join(dir, ".kaddo", "understand.md"), renderUnderstand(enrichedPlan));
   log2.success("Wrote .kaddo/understand.md");
   printCommandFooter("understand");
   outro2("Handoff ready. CLI prepares context \u2014 your LLM creates the understanding.");

package/package.json

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