@kaddo/cli 3.1.0 → 3.3.0

package/README.md

@@ -433,6 +433,8 @@ 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) |
+| v3.3 | Work Item delivery lifecycle: `understand` shows branch → scan → ownership → guard → knowledge → commit for active Work Items (suggestions only; Kaddo never runs git) |
 
 **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,67 +5185,64 @@ 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"];
+// src/core/delivery.ts
+function slugify2(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function selectAgentFiles(opts) {
-  if (opts.all) {
-    const all = AGENT_GROUP_NAMES.flatMap((g) => AGENT_GROUPS[g]);
-    return { files: all, label: "all agents" };
+function isWorkItem(a) {
+  return a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type);
+}
+function activeWorkItems(dir) {
+  const archDir = join(dir, "knowledge");
+  if (!exists(archDir)) return [];
+  return readArtifacts(archDir).filter((a) => isWorkItem(a) && a.status === "in-progress").map((a) => {
+    const id = a.id || a.title || "WI";
+    return { id, title: a.title || id, type: a.type, slug: slugify2(a.title || id) };
+  });
+}
+function branchPrefix(type) {
+  switch (type) {
+    case "bugfix":
+      return "bugfix";
+    case "hotfix":
+      return "hotfix";
+    case "spike":
+      return "spike";
+    default:
+      return "feature";
   }
-  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}` };
+}
+function commitPrefix(type) {
+  switch (type) {
+    case "bugfix":
+    case "hotfix":
+      return "fix";
+    case "spike":
+      return "chore";
+    default:
+      return "feat";
   }
-  return {
-    files: recommendedAgents(opts.state),
-    label: `recommended for state: ${opts.state ?? "pre-ai"}`
-  };
+}
+function suggestedBranch(wi) {
+  return `${branchPrefix(wi.type)}/${wi.id}-${wi.slug}`;
+}
+function suggestedCommit(wi) {
+  return `${commitPrefix(wi.type)}: ${wi.title.toLowerCase()}`;
+}
+function renderDeliveryLifecycle(wi) {
+  return [
+    `Active work item: ${wi.id} \u2014 ${wi.title}`,
+    "",
+    "Delivery lifecycle (Kaddo never runs git for you):",
+    `  1. Create a branch          e.g. ${suggestedBranch(wi)}`,
+    "  2. Implement the work item",
+    "  3. Run `kaddo scan`         (after new modules/migrations/contracts)",
+    "  4. Run `kaddo owners suggest`  \u2192 confirm code: globs",
+    "  5. Run `kaddo guard`        before committing (detect knowledge drift)",
+    "  6. Update knowledge         ADR / capabilities.md / current-state.md as needed",
+    "  7. Review (human)",
+    `  8. Commit                   e.g. ${suggestedCommit(wi)}`
+  ];
 }
 
 // src/commands/understand.ts
@@ -5193,11 +5280,41 @@ 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(`Agents for this phase: ${groupAgents.join(", ")}`);
+  }
+  const active = activeWorkItems(dir);
+  if (active.length > 0) {
     console.log("");
-    console.log(`Current phase: ${phase}`);
-    console.log("Recommended agents for this phase:");
-    for (const a of groupAgents) console.log(`  - ${a}`);
+    for (const line of renderDeliveryLifecycle(active[0])) console.log(line);
+    if (active.length > 1) {
+      console.log("");
+      console.log(`Other active work items: ${active.slice(1).map((w) => w.id).join(", ")}`);
+    }
   }
   writeFile(join(dir, ".kaddo", "understand.md"), renderUnderstand(plan));
   log2.success("Wrote .kaddo/understand.md");
@@ -7590,7 +7707,7 @@ var MODULE_TYPES = [
   "data",
   "unknown"
 ];
-function slugify2(name) {
+function slugify3(name) {
   return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function readModulesDescriptor(dir) {
@@ -7610,7 +7727,7 @@ function moduleDir(id) {
   return `knowledge/tech/modules/${id}`;
 }
 function buildModule(input) {
-  const id = slugify2(input.name);
+  const id = slugify3(input.name);
   const base = moduleDir(id);
   return {
     id,
@@ -7877,7 +7994,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.3.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.3.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {