@kaddo/cli 3.1.0 → 3.2.0

package/README.md

@@ -433,6 +433,7 @@ create --from roadmap → owners → guard → explain`.
 | v2.8 | `kaddo bootstrap` for new projects (Business → Product → Tech → Delivery); business templates + bootstrap agents |
 | v3.0 | Knowledge-centric realignment: `architecture/` → `knowledge/` with layers Business → Product → Tech → Delivery; context/explain by layer (breaking) |
 | v3.1 | Minimum Sufficient Knowledge: bootstrap one consolidated file per layer; progressive `add agents` by group (state default, `--all`, `--group`) |
+| v3.2 | New-project flow hardening: agents in per-layer folders; `new` recommends capability+architecture agents; explain Work Item parser fix; intent vs reality (codebase vs current-state) |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -2487,6 +2487,81 @@ var AGENT_PROMPTS = [
   { fileName: "codebase-agent.md", content: CODEBASE_FOUNDATION_AGENT }
 ];
 
+// src/agents/groups.ts
+var AGENT_GROUPS = {
+  business: ["business-agent.md"],
+  product: ["bootstrap-agent.md", "capability-agent.md"],
+  tech: [
+    "architecture-agent.md",
+    "codebase-agent.md",
+    "stack-agent.md",
+    "security-agent.md",
+    "standards-agent.md",
+    "module-design-agent.md",
+    "adr-agent.md"
+  ],
+  delivery: ["roadmap-agent.md", "work-item-agent.md", "git-strategy-agent.md"],
+  utilities: ["legacy-agent.md"]
+};
+var AGENT_GROUP_NAMES = Object.keys(AGENT_GROUPS);
+function agentGroupOf(fileName) {
+  for (const g of AGENT_GROUP_NAMES) {
+    if (AGENT_GROUPS[g].includes(fileName)) return g;
+  }
+  return "utilities";
+}
+function agentInstallPath(fileName) {
+  return `knowledge/agents/${agentGroupOf(fileName)}/${fileName}`;
+}
+var RECOMMENDED_BY_STATE = {
+  new: [
+    "business-agent.md",
+    "bootstrap-agent.md",
+    "capability-agent.md",
+    "architecture-agent.md",
+    "codebase-agent.md",
+    "roadmap-agent.md",
+    "work-item-agent.md",
+    "adr-agent.md"
+  ],
+  "pre-ai": [
+    "capability-agent.md",
+    "architecture-agent.md",
+    "roadmap-agent.md",
+    "work-item-agent.md"
+  ],
+  legacy: [
+    "legacy-agent.md",
+    "architecture-agent.md",
+    "capability-agent.md",
+    "roadmap-agent.md",
+    "work-item-agent.md"
+  ]
+};
+function recommendedAgents(state) {
+  return RECOMMENDED_BY_STATE[state ?? "pre-ai"] ?? RECOMMENDED_BY_STATE["pre-ai"];
+}
+function selectAgentFiles(opts) {
+  if (opts.all) {
+    const all = AGENT_GROUP_NAMES.flatMap((g) => AGENT_GROUPS[g]);
+    return { files: all, label: "all agents" };
+  }
+  if (opts.group) {
+    const group = opts.group;
+    const files = AGENT_GROUPS[group];
+    if (!files) {
+      throw new Error(
+        `Unknown agent group "${opts.group}". Valid groups: ${AGENT_GROUP_NAMES.join(", ")}.`
+      );
+    }
+    return { files, label: `group: ${group}` };
+  }
+  return {
+    files: recommendedAgents(opts.state),
+    label: `recommended for state: ${opts.state ?? "pre-ai"}`
+  };
+}
+
 // src/modules/agents.ts
 var agentReadme = {
   path: "knowledge/agents/README.md",
@@ -2538,7 +2613,7 @@ var agentReadme = {
   ].join("\n")
 };
 var agentFiles = AGENT_PROMPTS.map((a) => ({
-  path: `knowledge/agents/${a.fileName}`,
+  path: agentInstallPath(a.fileName),
   content: a.content
 }));
 var agentsModule = {
@@ -4261,7 +4336,18 @@ function loadScan(dir) {
 function hasAgents(dir) {
   const agentsDir = join(dir, ARCH_DIR3, "agents");
   if (!exists(agentsDir)) return false;
-  return readDir(agentsDir).some((e) => e.endsWith(".md") && isFile(join(agentsDir, e)));
+  function hasAgentMd(d) {
+    for (const e of readDir(d)) {
+      const full = join(d, e);
+      if (isFile(full)) {
+        if (e.endsWith("-agent.md")) return true;
+      } else if (hasAgentMd(full)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  return hasAgentMd(agentsDir);
 }
 function buildProjectExplanation(dir) {
   const config = loadConfig(dir);
@@ -4293,9 +4379,10 @@ function buildProjectExplanation(dir) {
   };
   const archDir = join(dir, ARCH_DIR3);
   const allArtifacts = exists(archDir) ? readArtifacts(archDir) : [];
-  const workItemArtifacts = allArtifacts.filter(
-    (a) => a.type !== "current-state" && a.type !== "roadmap"
-  );
+  const workItemArtifacts = allArtifacts.filter((a) => {
+    const p2 = a.filePath.replace(/\\/g, "/");
+    return p2.includes("/delivery/work-items/") && Boolean(a.type);
+  });
   const items = workItemArtifacts.map((a) => ({
     id: a.id || a.title,
     title: a.title,
@@ -4525,7 +4612,7 @@ function explainForHuman(dir, artifacts, opts) {
     console.log("");
   }
   const workItems = artifacts.filter(
-    (a) => a.type !== "current-state" && a.type !== "roadmap" && a.status === "in-progress"
+    (a) => a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type) && a.status === "in-progress"
   );
   if (workItems.length > 0) {
     console.log("## Active work items");
@@ -4945,6 +5032,9 @@ function runContext(opts = {}) {
 }
 
 // src/core/understand.ts
+function agentIsInstalled(dir, fileName) {
+  return exists(join(dir, agentInstallPath(fileName))) || exists(join(dir, "knowledge", "agents", fileName));
+}
 function flowForState(state) {
   switch (state) {
     case "new":
@@ -4972,7 +5062,7 @@ function buildUnderstandPlan(dir, config) {
   const state = config.project.state;
   const flow = flowForState(state);
   const steps = flow.map((s) => {
-    const installed = exists(join(dir, "knowledge", "agents", s.agent));
+    const installed = agentIsInstalled(dir, s.agent);
     return { agent: s.agent, output: s.output, installed };
   });
   const missingAgents = steps.filter((s) => !s.installed).map((s) => s.agent);
@@ -5095,69 +5185,6 @@ function renderUnderstandTerminal(plan) {
   return lines.join("\n");
 }
 
-// src/agents/groups.ts
-var AGENT_GROUPS = {
-  business: ["business-agent.md"],
-  product: ["bootstrap-agent.md", "capability-agent.md"],
-  tech: [
-    "architecture-agent.md",
-    "codebase-agent.md",
-    "stack-agent.md",
-    "security-agent.md",
-    "standards-agent.md",
-    "module-design-agent.md",
-    "adr-agent.md"
-  ],
-  delivery: ["roadmap-agent.md", "work-item-agent.md", "git-strategy-agent.md"],
-  utilities: ["legacy-agent.md"]
-};
-var AGENT_GROUP_NAMES = Object.keys(AGENT_GROUPS);
-var RECOMMENDED_BY_STATE = {
-  new: [
-    "business-agent.md",
-    "bootstrap-agent.md",
-    "codebase-agent.md",
-    "roadmap-agent.md",
-    "work-item-agent.md"
-  ],
-  "pre-ai": [
-    "capability-agent.md",
-    "architecture-agent.md",
-    "roadmap-agent.md",
-    "work-item-agent.md"
-  ],
-  legacy: [
-    "legacy-agent.md",
-    "architecture-agent.md",
-    "capability-agent.md",
-    "roadmap-agent.md",
-    "work-item-agent.md"
-  ]
-};
-function recommendedAgents(state) {
-  return RECOMMENDED_BY_STATE[state ?? "pre-ai"] ?? RECOMMENDED_BY_STATE["pre-ai"];
-}
-function selectAgentFiles(opts) {
-  if (opts.all) {
-    const all = AGENT_GROUP_NAMES.flatMap((g) => AGENT_GROUPS[g]);
-    return { files: all, label: "all agents" };
-  }
-  if (opts.group) {
-    const group = opts.group;
-    const files = AGENT_GROUPS[group];
-    if (!files) {
-      throw new Error(
-        `Unknown agent group "${opts.group}". Valid groups: ${AGENT_GROUP_NAMES.join(", ")}.`
-      );
-    }
-    return { files, label: `group: ${group}` };
-  }
-  return {
-    files: recommendedAgents(opts.state),
-    label: `recommended for state: ${opts.state ?? "pre-ai"}`
-  };
-}
-
 // src/commands/understand.ts
 function runUnderstand() {
   const dir = cwd();
@@ -5193,11 +5220,32 @@ function runUnderstand() {
   const phase = currentPhase(knowledgeLayers(dir));
   const group = phase.toLowerCase();
   const groupAgents = (AGENT_GROUPS[group] ?? []).map((a) => a.replace(/\.md$/, ""));
+  const NEXT_STEPS = {
+    business: ["Use business-agent \u2192 refine knowledge/business/business.md"],
+    product: [
+      "Use bootstrap-agent \u2192 refine knowledge/product/product.md",
+      "Use capability-agent \u2192 knowledge/product/capabilities.md"
+    ],
+    tech: [
+      "Use architecture-agent \u2192 knowledge/tech/current-state.md (reality)",
+      "Use codebase-agent \u2192 knowledge/tech/codebase.md (intent)",
+      "Record decisions as ADRs in knowledge/tech/decisions/"
+    ],
+    delivery: [
+      "Use roadmap-agent \u2192 knowledge/delivery/roadmap.md",
+      "Run `kaddo create --from roadmap`, then `kaddo owners suggest`"
+    ],
+    utilities: ["Use legacy-agent to surface risks and unknowns"]
+  };
+  console.log("");
+  console.log(`Current phase: ${phase}`);
+  console.log("Recommended next steps:");
+  console.log("  1. Run `kaddo scan`   (technical signals \u2192 knowledge/inventory.md)");
+  console.log("  2. Run `kaddo context`  (package knowledge for your LLM)");
+  let n = 3;
+  for (const step of NEXT_STEPS[group] ?? []) console.log(`  ${n++}. ${step}`);
   if (groupAgents.length > 0) {
-    console.log("");
-    console.log(`Current phase: ${phase}`);
-    console.log("Recommended agents for this phase:");
-    for (const a of groupAgents) console.log(`  - ${a}`);
+    console.log(`Agents for this phase: ${groupAgents.join(", ")}`);
   }
   writeFile(join(dir, ".kaddo", "understand.md"), renderUnderstand(plan));
   log2.success("Wrote .kaddo/understand.md");
@@ -7877,7 +7925,7 @@ async function runBootstrap(dir = cwd()) {
 
 // src/index.ts
 var program = new Command();
-program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.1.0");
+program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.2.0");
 program.command("init").description("Initialize Kaddo in the current project").action(async () => {
   await runInit();
 });

package/package.json

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