@kaddo/cli 3.7.2 → 3.9.0

package/dist/index.js

@@ -725,6 +725,17 @@ async function runScan() {
 }
 
 // src/core/knowledge-levels.ts
+var WORK_ITEM_TYPES = ["feature", "bugfix", "hotfix", "spike", "chore"];
+var TYPE_ALIASES = {
+  setup: "chore",
+  maintenance: "chore",
+  tooling: "chore",
+  infrastructure: "chore",
+  infra: "chore",
+  config: "chore",
+  configuration: "chore",
+  refactor: "chore"
+};
 var LEVELS = {
   K0: {
     level: "K0",
@@ -879,7 +890,9 @@ var TYPE_TO_LEVEL = {
   hotfix: "K1",
   bugfix: "K2",
   feature: "K2",
-  spike: "K3"
+  spike: "K3",
+  // Chores are maintenance/config/tooling work — low ceremony (problem + expected result).
+  chore: "K1"
 };
 function getLevel(level) {
   return LEVELS[level];
@@ -888,7 +901,13 @@ function getLevelForType(type) {
   return TYPE_TO_LEVEL[type];
 }
 function isValidType(type) {
-  return ["feature", "bugfix", "hotfix", "spike"].includes(type);
+  return WORK_ITEM_TYPES.includes(type);
+}
+function normalizeType(raw) {
+  if (!raw) return null;
+  const t = raw.trim().toLowerCase();
+  if (isValidType(t)) return t;
+  return TYPE_ALIASES[t] ?? null;
 }
 
 // src/modules/adr.ts
@@ -1375,6 +1394,220 @@ var guardAdvancedModule = {
   ]
 };
 
+// src/agents/responsibility.ts
+var RESPONSIBILITY_MATRIX = {
+  "business-agent": {
+    agent: "business-agent",
+    responsibleFor: ["Problem", "Users", "Rules", "Constraints"],
+    produces: ["knowledge/business/business.md"],
+    canSuggest: ["product-agent"],
+    cannotSuggest: ["Git", "branches", "commits", "code"],
+    next: ["product-agent"]
+  },
+  "product-agent": {
+    agent: "product-agent",
+    responsibleFor: ["Product", "Capabilities", "Scope"],
+    produces: ["knowledge/product/product.md", "knowledge/product/capabilities.md"],
+    canSuggest: ["roadmap-agent"],
+    cannotSuggest: ["Git", "implementation", "branches", "code"],
+    next: ["roadmap-agent"]
+  },
+  "capability-agent": {
+    agent: "capability-agent",
+    responsibleFor: ["Capabilities"],
+    produces: ["knowledge/product/capabilities.md"],
+    canSuggest: ["roadmap-agent"],
+    cannotSuggest: ["Git", "implementation", "branches", "code"],
+    next: ["roadmap-agent"]
+  },
+  "bootstrap-agent": {
+    agent: "bootstrap-agent",
+    responsibleFor: ["Initial direction", "Capabilities", "Quality attributes", "Roadmap seed"],
+    produces: [
+      "knowledge/bootstrap-summary.md",
+      "knowledge/product/capabilities.md",
+      "knowledge/delivery/roadmap.md"
+    ],
+    canSuggest: ["capability-agent", "architecture-agent", "roadmap-agent"],
+    cannotSuggest: ["Git", "branches", "commits", "code"],
+    next: ["capability-agent", "architecture-agent"]
+  },
+  "codebase-agent": {
+    agent: "codebase-agent",
+    responsibleFor: ["Stack", "Structure", "Standards"],
+    produces: ["knowledge/tech/codebase.md"],
+    canSuggest: ["architecture-agent", "decision-agent"],
+    cannotSuggest: ["Git", "branches", "commits", "production code"],
+    next: ["architecture-agent"]
+  },
+  "stack-agent": {
+    agent: "stack-agent",
+    responsibleFor: ["Technologies", "Stack classification"],
+    produces: ["knowledge/tech/stack.md"],
+    canSuggest: ["architecture-agent", "standards-agent"],
+    cannotSuggest: ["Git", "branches", "code"],
+    next: ["architecture-agent"]
+  },
+  "standards-agent": {
+    agent: "standards-agent",
+    responsibleFor: ["Coding/doc/testing standards"],
+    produces: ["knowledge/tech/standards.md"],
+    canSuggest: ["architecture-agent"],
+    cannotSuggest: ["Git", "branches", "code"],
+    next: ["architecture-agent"]
+  },
+  "security-agent": {
+    agent: "security-agent",
+    responsibleFor: ["Security considerations"],
+    produces: ["knowledge/tech/security.md"],
+    canSuggest: ["architecture-agent", "decision-agent"],
+    cannotSuggest: ["Git", "branches", "code", "vulnerability scanning"],
+    next: ["architecture-agent"]
+  },
+  "module-design-agent": {
+    agent: "module-design-agent",
+    responsibleFor: ["Module design", "Boundaries"],
+    produces: ["knowledge/tech/modules/<module>/module-design.md"],
+    canSuggest: ["architecture-agent", "decision-agent"],
+    cannotSuggest: ["Git", "branches", "code"],
+    next: ["architecture-agent"]
+  },
+  "architecture-agent": {
+    agent: "architecture-agent",
+    responsibleFor: ["Architecture", "Technical state", "Risks"],
+    produces: ["knowledge/tech/current-state.md"],
+    canSuggest: ["decision-agent", "roadmap-agent"],
+    cannotSuggest: ["Git", "branches", "commits", "code"],
+    next: ["decision-agent", "roadmap-agent"]
+  },
+  "decision-agent": {
+    agent: "decision-agent",
+    responsibleFor: ["ADRs"],
+    produces: ["knowledge/tech/decisions/"],
+    canSuggest: ["implementation-agent"],
+    cannotSuggest: ["Git", "branches", "commits", "code"],
+    next: ["implementation-agent"]
+  },
+  // The shipped prompt file is `adr-agent.md`; it plays the decision-agent role.
+  "adr-agent": {
+    agent: "adr-agent",
+    responsibleFor: ["ADRs", "Decision candidates"],
+    produces: ["knowledge/tech/decision-candidates.md", "knowledge/tech/decisions/"],
+    canSuggest: ["implementation-agent"],
+    cannotSuggest: ["Git", "branches", "commits", "code"],
+    next: ["implementation-agent"]
+  },
+  "roadmap-agent": {
+    agent: "roadmap-agent",
+    responsibleFor: ["Roadmap", "Initiatives", "Work Item candidates"],
+    produces: ["knowledge/delivery/roadmap.md"],
+    canSuggest: ["kaddo create --from roadmap", "work-item-agent"],
+    cannotSuggest: ["branches", "commits", "pull requests", "code"],
+    next: ["kaddo create --from roadmap", "work-item-agent"]
+  },
+  "work-item-agent": {
+    agent: "work-item-agent",
+    responsibleFor: ["Work Item refinement"],
+    produces: ["knowledge/delivery/work-items/"],
+    canSuggest: ["implementation-agent"],
+    cannotSuggest: ["branches", "commits", "pull requests", "code"],
+    next: ["implementation-agent"]
+  },
+  "implementation-agent": {
+    agent: "implementation-agent",
+    responsibleFor: ["Implementation"],
+    produces: ["Code", "Tests", "Migrations"],
+    // The ONLY agent allowed to suggest branches — and only respecting the Git strategy.
+    canSuggest: [
+      "a branch (per knowledge/tech/git-strategy.md / .kaddo/git.yml)",
+      "kaddo scan",
+      "kaddo owners suggest",
+      "kaddo guard"
+    ],
+    cannotSuggest: [
+      "running git itself",
+      "committing without human confirmation",
+      "pushing or merging"
+    ],
+    next: ["kaddo scan", "kaddo owners suggest", "kaddo guard", "kaddo explain"]
+  },
+  "guard-agent": {
+    agent: "guard-agent",
+    responsibleFor: ["Knowledge drift"],
+    produces: ["Findings", "Warnings"],
+    canSuggest: ["update knowledge", "update ownership"],
+    cannotSuggest: ["branches", "commits", "code"],
+    next: ["update knowledge", "kaddo owners suggest"]
+  },
+  "git-strategy-agent": {
+    agent: "git-strategy-agent",
+    responsibleFor: ["Branch/commit/tag/release strategy (documentation)"],
+    produces: ["knowledge/tech/git-strategy.md"],
+    canSuggest: ["implementation-agent"],
+    // It documents a strategy; it never creates branches/commits itself.
+    cannotSuggest: ["creating branches", "creating commits", "creating tags"],
+    next: ["implementation-agent"]
+  },
+  "legacy-agent": {
+    agent: "legacy-agent",
+    responsibleFor: ["Risks", "Unknowns", "Safe first steps"],
+    produces: ["knowledge/legacy/risks.md", "knowledge/legacy/unknowns.md"],
+    canSuggest: ["architecture-agent", "capability-agent"],
+    cannotSuggest: ["Git", "branches", "code", "large rewrites"],
+    next: ["architecture-agent"]
+  }
+};
+function list(items) {
+  return items.length > 0 ? items.join(", ") : "\u2014";
+}
+function renderAgentBoundaries(agent) {
+  const r = RESPONSIBILITY_MATRIX[agent];
+  if (!r) return "";
+  return [
+    "## Responsibility & Boundaries",
+    "",
+    `**Responsible for:** ${list(r.responsibleFor)}`,
+    `**Produces:** ${list(r.produces)}`,
+    `**May suggest:** ${list(r.canSuggest)}`,
+    `**Must NOT suggest:** ${list(r.cannotSuggest)}`,
+    "",
+    "This agent produces **knowledge only**. It never runs Git, never runs code and never runs commands. It may only suggest actions inside its own responsibility.",
+    ""
+  ].join("\n");
+}
+function renderAgentTrace(agent) {
+  const r = RESPONSIBILITY_MATRIX[agent];
+  if (!r) return "";
+  const produced = r.produces.length > 0 ? r.produces.join("\n") : "(none)";
+  const next = r.next.length > 0 ? r.next.join("\n") : "(end of flow)";
+  return [
+    "## Agent Trace",
+    "",
+    "End **every** response with this trace block so the flow stays auditable:",
+    "",
+    "```text",
+    "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    `Agent: ${r.agent}`,
+    "",
+    "Produced:",
+    produced,
+    "",
+    "Next:",
+    next,
+    "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500",
+    "```",
+    ""
+  ].join("\n");
+}
+function withResponsibilityTrace(fileName, content) {
+  const agent = fileName.replace(/\.md$/, "");
+  if (!RESPONSIBILITY_MATRIX[agent]) return content;
+  return `${content.trimEnd()}
+
+${renderAgentBoundaries(agent)}
+${renderAgentTrace(agent)}`;
+}
+
 // src/agents/prompts.ts
 var CAPABILITY_AGENT = `# Capability Agent
 
@@ -1618,6 +1851,9 @@ Produce a roadmap where each initiative includes:
 7. Dependencies.
 8. Why this comes now.
 9. Candidate work items (each with type, suggested knowledge level, expected value, notes).
+   Use only the official Work Item types: \`feature\`, \`bugfix\`, \`hotfix\`, \`spike\`, \`chore\`.
+   Use \`chore\` for technical/maintenance/tooling/config/infra work (e.g. "Initialize
+   TypeScript project", "Configure Vitest", "Setup CI") \u2014 do not label such work \`feature\`.
 10. Open questions.
 
 Then add a suggested execution order, risks and constraints, a "Not Now" list, and the
@@ -1634,6 +1870,9 @@ Adapt priorities to the project state from the context pack:
 
 - Do not invent business priorities or business facts \u2014 mark them as assumptions when inferred.
 - Do not write code or implementation details.
+- **Do not suggest branches, commits or pull requests.** Git and implementation belong to the
+  implementation-agent, and only after Work Items are materialized. Your handoff is
+  \`kaddo create --from roadmap\` \u2192 work-item-agent.
 - Do not create the work items themselves; only propose candidates.
 - Make clear that initiatives and work items are **candidates**, not final decisions.
 - Mark any uncertain information as an assumption or open question.
@@ -1916,12 +2155,14 @@ A refined Work Item intended to be saved under the lifecycle workspace:
 
 1. Restate the problem in one clear sentence.
 2. Split the candidate if it is too large for a single Work Item.
-3. Validate the Knowledge Level (K0\u2013K4) and propose a different one if needed.
-4. Propose acceptance criteria.
-5. Propose Out of scope and Validation sections.
-6. Propose a Definition of Done.
-7. Identify open questions and assumptions.
-8. Suggest ownership candidates (code globs) if evident.
+3. Preserve the candidate's type (\`feature\`, \`bugfix\`, \`hotfix\`, \`spike\`, \`chore\`).
+   Keep \`chore\` for maintenance/tooling/config/infra work \u2014 never upgrade a chore to a feature.
+4. Validate the Knowledge Level (K0\u2013K4) and propose a different one if needed.
+5. Propose acceptance criteria.
+6. Propose Out of scope and Validation sections.
+7. Propose a Definition of Done.
+8. Identify open questions and assumptions.
+9. Suggest ownership candidates (code globs) if evident.
 
 ## Constraints
 
@@ -1960,23 +2201,12 @@ Save new output as a draft under \`knowledge/delivery/work-items/draft/\` unless
 explicitly asks for another lifecycle state. Treat only \`draft\`, \`ready\`, \`in-progress\`
 and \`blocked\` as active work; \`completed\` and \`archived\` are historical knowledge.
 
-## Delivery workflow
-
-When this Work Item is **implemented** (by you or the coding agent), follow the project's
-delivery protocol. **Never run git mutating commands without the human's confirmation.**
+## Handoff
 
-1. **Branch first.** Before changing any code, create a branch following the project's Git
-   strategy (\`.kaddo/git.yml\` \u2192 \`branchNaming.pattern\`, default
-   \`feature/<work-item-id>-<slug>\`; also \`bugfix/\`, \`hotfix/\`, \`spike/\`). This keeps work
-   off the default branch so nothing lands on \`main\` by accident.
-2. Implement the change.
-3. Run \`kaddo scan\` after adding modules, migrations, contracts or significant structure.
-4. Run \`kaddo owners suggest\` and confirm the \`code:\` globs.
-5. Run \`kaddo guard\` before committing to detect possible knowledge drift.
-6. Update the affected knowledge (ADR / capabilities.md / current-state.md).
-7. **Commit only with explicit human confirmation.** Never commit, push or merge on your
-   own \u2014 suggest a Conventional Commit message and wait for the human. The Kaddo CLI itself
-   never touches git.
+When the Work Item is refined and ready to build, **hand off to the implementation-agent**.
+You do **not** suggest branches, commits or pull requests \u2014 implementation (including any Git
+branch suggestion) is the implementation-agent's responsibility, and only by respecting the
+project Git strategy. Your job ends at a clear, traceable Work Item.
 
 ## Quality Checklist
 
@@ -1984,8 +2214,9 @@ delivery protocol. **Never run git mutating commands without the human's confirm
 - Large candidates are split.
 - Knowledge Level is justified.
 - Acceptance criteria are testable.
+- Out of scope and Validation are stated.
 - Open questions are explicit.
-- Delivery: branch first, commit only with human confirmation.
+- Handoff: next step is the implementation-agent (never a branch or commit).
 `;
 var GIT_STRATEGY_AGENT = `# Git Strategy Agent
 
@@ -2498,6 +2729,82 @@ Save as \`knowledge/tech/codebase.md\`.
 - Minimum criteria to start development are explicit.
 - Assumptions and open questions are listed.
 `;
+var IMPLEMENTATION_AGENT = `# Implementation Agent
+
+## Role
+
+You are the Kaddo Implementation Agent. Your job is to implement a refined Work Item \u2014 code,
+tests and migrations \u2014 and keep the project knowledge in sync. You are the **only** agent that
+may suggest a Git branch, and only by respecting the project's Git strategy.
+
+You never run Git yourself. The Kaddo CLI never runs Git either. Every git action is the
+human's, and commits/pushes/merges happen only with explicit human confirmation.
+
+## When to Use
+
+Use this agent after the work-item-agent has produced a clear, traceable Work Item under
+\`knowledge/delivery/work-items/\` (typically in \`ready/\`).
+
+## Input Required
+
+Provide \`.kaddo/context-pack.md\`, the Work Item to implement, and the Git strategy
+(\`knowledge/tech/git-strategy.md\` / \`.kaddo/git.yml\`) if it exists.
+
+## Expected Output
+
+Working code, tests and migrations, plus updated knowledge (ADR / capabilities / current-state)
+when the change affects them. You also produce a suggested branch name and a suggested
+Conventional Commit message \u2014 as suggestions, never executed.
+
+## Instructions
+
+1. **Suggest a branch first** (do not run it). Follow the Git strategy
+   (\`.kaddo/git.yml\` \u2192 \`branchNaming.pattern\`, default \`feature/<work-item-id>-<slug>\`;
+   also \`bugfix/\`, \`hotfix/\`, \`spike/\`). If no strategy exists, suggest the default and say so.
+2. Implement the change with tests.
+3. Suggest running \`kaddo scan\` after adding modules, migrations, contracts or significant
+   structure.
+4. Suggest running \`kaddo owners suggest\` and confirm the \`code:\` globs.
+5. Suggest running \`kaddo guard\` before committing to detect knowledge drift.
+6. Update affected knowledge (ADR / capabilities.md / current-state.md).
+7. Suggest a Conventional Commit message and **wait for explicit human confirmation**. Never
+   commit, push or merge on your own.
+
+## Constraints
+
+- Never run Git. Never commit, push or merge \u2014 suggest and wait for the human.
+- Respect \`knowledge/tech/git-strategy.md\` when it exists.
+- Keep knowledge in sync with the code you change.
+- Do not invent business facts.
+
+## Output Format
+
+\`\`\`markdown
+# Implementation Plan \u2014 <Work Item id>
+
+## Suggested branch
+
+## Changes
+
+## Tests
+
+## Knowledge to update
+
+## Suggested commit (await human confirmation)
+\`\`\`
+
+## Where to Save the Result
+
+Code, tests and migrations live in the repository. Knowledge updates go under \`knowledge/\`.
+
+## Quality Checklist
+
+- A branch is suggested per the Git strategy (never executed).
+- Tests accompany the change.
+- \`kaddo scan\` / \`owners suggest\` / \`guard\` are suggested at the right moments.
+- Affected knowledge is updated.
+- Commit is suggested and awaits human confirmation \u2014 never run automatically.
+`;
 var AGENT_PROMPTS = [
   { fileName: "capability-agent.md", content: CAPABILITY_AGENT },
   { fileName: "architecture-agent.md", content: ARCHITECTURE_AGENT },
@@ -2513,8 +2820,11 @@ var AGENT_PROMPTS = [
   // Bootstrap agents (new projects)
   { fileName: "business-agent.md", content: BUSINESS_AGENT },
   { fileName: "bootstrap-agent.md", content: BOOTSTRAP_AGENT },
-  { fileName: "codebase-agent.md", content: CODEBASE_FOUNDATION_AGENT }
-];
+  { fileName: "codebase-agent.md", content: CODEBASE_FOUNDATION_AGENT },
+  // Implementation (the only agent that may suggest a branch — VS-044)
+  { fileName: "implementation-agent.md", content: IMPLEMENTATION_AGENT }
+  // Every official prompt ends with its responsibility boundaries + Agent Trace footer.
+].map((p2) => ({ fileName: p2.fileName, content: withResponsibilityTrace(p2.fileName, p2.content) }));
 
 // src/agents/groups.ts
 var AGENT_GROUPS = {
@@ -2529,7 +2839,12 @@ var AGENT_GROUPS = {
     "module-design-agent.md",
     "adr-agent.md"
   ],
-  delivery: ["roadmap-agent.md", "work-item-agent.md", "git-strategy-agent.md"],
+  delivery: [
+    "roadmap-agent.md",
+    "work-item-agent.md",
+    "implementation-agent.md",
+    "git-strategy-agent.md"
+  ],
   utilities: ["legacy-agent.md"]
 };
 var AGENT_GROUP_NAMES = Object.keys(AGENT_GROUPS);
@@ -2551,20 +2866,23 @@ var RECOMMENDED_BY_STATE = {
     "codebase-agent.md",
     "roadmap-agent.md",
     "work-item-agent.md",
+    "implementation-agent.md",
     "adr-agent.md"
   ],
   "pre-ai": [
     "capability-agent.md",
     "architecture-agent.md",
     "roadmap-agent.md",
-    "work-item-agent.md"
+    "work-item-agent.md",
+    "implementation-agent.md"
   ],
   legacy: [
     "legacy-agent.md",
     "architecture-agent.md",
     "capability-agent.md",
     "roadmap-agent.md",
-    "work-item-agent.md"
+    "work-item-agent.md",
+    "implementation-agent.md"
   ]
 };
 function recommendedAgents(state) {
@@ -3381,20 +3699,21 @@ async function runCreate(type, opts = {}) {
   }
   if (!type) {
     console.error("Missing work item type.");
-    console.error("Usage: kaddo create <feature|bugfix|hotfix|spike> [--from roadmap]");
+    console.error("Usage: kaddo create <feature|bugfix|hotfix|spike|chore> [--from roadmap]");
     process.exit(1);
   }
   const modWorkItemType = findWorkItemType(type);
   if (modWorkItemType) {
     return runCreateModule(dir, modWorkItemType);
   }
-  if (!isValidType(type)) {
+  const workItemType = normalizeType(type);
+  if (!workItemType) {
     console.error(`Unknown work item type: "${type}"`);
-    console.error("Valid types: feature, bugfix, hotfix, spike");
+    console.error("Valid types: feature, bugfix, hotfix, spike, chore");
+    console.error("Aliases: setup, maintenance, tooling, infrastructure, refactor \u2192 chore");
     console.error("Module types: adr, incident, rfc, migration, legacy (run `kaddo add <module>` first)");
     process.exit(1);
   }
-  const workItemType = type;
   const level = getLevelForType(workItemType);
   const levelDef = getLevel(level);
   intro2(`kaddo create ${workItemType}`);
@@ -3402,7 +3721,7 @@ async function runCreate(type, opts = {}) {
   printStateGuidance(dir);
   const title = await text2({
     message: "Title for this work item",
-    placeholder: `e.g. ${workItemType === "feature" ? "Add email verification to checkout" : workItemType === "hotfix" ? "Fix null pointer in payment handler" : workItemType === "bugfix" ? "Fix broken pagination on orders list" : "Explore caching strategies for API responses"}`,
+    placeholder: `e.g. ${workItemType === "feature" ? "Add email verification to checkout" : workItemType === "hotfix" ? "Fix null pointer in payment handler" : workItemType === "bugfix" ? "Fix broken pagination on orders list" : workItemType === "chore" ? "Configure Vitest and CI pipeline" : "Explore caching strategies for API responses"}`,
     validate: (v) => v.trim().length === 0 ? "Title is required." : void 0
   });
   const answers = {};
@@ -3471,9 +3790,7 @@ ${body}`;
 }
 var K_LEVEL_RE = /^K[0-4]$/;
 function resolveCandidateType(candidate, cliType) {
-  if (candidate.type && isValidType(candidate.type)) return candidate.type;
-  if (cliType && isValidType(cliType)) return cliType;
-  return null;
+  return normalizeType(candidate.type) ?? normalizeType(cliType);
 }
 function resolveCandidateLevel(candidate, type) {
   const suggested = candidate.suggestedKnowledgeLevel?.trim().toUpperCase();
@@ -3635,7 +3952,8 @@ async function runCreateFromRoadmap(dir, cliType) {
         { value: "feature", label: "feature" },
         { value: "bugfix", label: "bugfix" },
         { value: "hotfix", label: "hotfix" },
-        { value: "spike", label: "spike" }
+        { value: "spike", label: "spike" },
+        { value: "chore", label: "chore" }
       ]
     });
   }
@@ -4431,7 +4749,7 @@ var STRUCTURED_TYPES = {
   ]),
   Delivery: /* @__PURE__ */ new Set([])
 };
-var WORK_ITEM_TYPES = /* @__PURE__ */ new Set([
+var WORK_ITEM_TYPES2 = /* @__PURE__ */ new Set([
   "work-item",
   "feature",
   "bugfix",
@@ -4444,7 +4762,7 @@ function layerForType(type) {
   if (type === CONSOLIDATED_TYPE.Product || STRUCTURED_TYPES.Product.has(type)) return "Product";
   if (type === CONSOLIDATED_TYPE.Tech || STRUCTURED_TYPES.Tech.has(type) || type === "knowledge")
     return "Tech";
-  if (type === "roadmap" || WORK_ITEM_TYPES.has(type)) return "Delivery";
+  if (type === "roadmap" || WORK_ITEM_TYPES2.has(type)) return "Delivery";
   return null;
 }
 function layerFromPath(filePath) {
@@ -4475,7 +4793,7 @@ function discoverLayers(dir) {
     slot.detected.add(basename(a.filePath));
     if (layer === "Delivery") {
       if (type === "roadmap" || basename(a.filePath) === "roadmap.md") slot.hasRoadmap = true;
-      if (WORK_ITEM_TYPES.has(type) || a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) {
+      if (WORK_ITEM_TYPES2.has(type) || a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) {
         if (a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/")) slot.hasWorkItem = true;
       }
       continue;
@@ -4695,6 +5013,7 @@ function buildProjectExplanation(dir) {
   const items = workItemArtifacts.map((a) => ({
     id: a.id || a.title,
     title: a.title,
+    type: a.type,
     status: a.status,
     lifecycle: lifecycleStateOf({ status: a.status, filePath: a.filePath }),
     initiative: a.initiative,
@@ -4703,6 +5022,11 @@ function buildProjectExplanation(dir) {
     domains: a.domains
   }));
   const byState = lifecycleCounts(items.map((i) => i.lifecycle));
+  const byType = {};
+  for (const i of items) {
+    const t = i.type || "unknown";
+    byType[t] = (byType[t] ?? 0) + 1;
+  }
   const initiativeMap = /* @__PURE__ */ new Map();
   for (const i of items) {
     const name = i.initiative || "Unassigned";
@@ -4716,6 +5040,7 @@ function buildProjectExplanation(dir) {
     done: items.filter((i) => i.status === "done").length,
     cancelled: items.filter((i) => i.status === "cancelled").length,
     byState,
+    byType,
     initiatives,
     items
   };
@@ -4785,6 +5110,10 @@ function buildProjectExplanation(dir) {
 function stateLabel(state) {
   return state === "pre-ai" ? "pre-ai" : state;
 }
+function typeLabel(type) {
+  const cap = type.charAt(0).toUpperCase() + type.slice(1);
+  return cap.endsWith("s") ? cap : `${cap}s`;
+}
 var LIFECYCLE_LABEL = {
   draft: "Draft",
   ready: "Ready",
@@ -4846,6 +5175,12 @@ function renderExplanationHuman(exp) {
       lines.push(`- ${LIFECYCLE_LABEL[s]}: ${exp.workItems.byState[s]}`);
     }
     lines.push("");
+    const typeEntries = Object.entries(exp.workItems.byType).sort((a, b) => b[1] - a[1]);
+    if (typeEntries.length > 0) {
+      lines.push("## Work Items by Type");
+      for (const [t, n] of typeEntries) lines.push(`- ${typeLabel(t)}: ${n}`);
+      lines.push("");
+    }
     const grouped = exp.workItems.initiatives.filter(
       (g) => LIFECYCLE_STATES.some((s) => g.states[s] > 0)
     );
@@ -5218,6 +5553,13 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     (a) => a.filePath.replace(/\\/g, "/").includes("/delivery/work-items/") && Boolean(a.type)
   ).length;
   const roadmap = roadmapStats(exists(roadmapPath) ? readFile(roadmapPath) : null, materialized);
+  const deliveryMix = {};
+  for (const a of allArtifacts) {
+    const p2 = a.filePath.replace(/\\/g, "/");
+    if (!a.type || !p2.includes("/delivery/work-items/")) continue;
+    if (!isActiveState(lifecycleStateOf({ status: a.status, filePath: a.filePath }))) continue;
+    deliveryMix[a.type] = (deliveryMix[a.type] ?? 0) + 1;
+  }
   const mappedModules = loadMappedModules(dir);
   const layers = knowledgeLayers(dir);
   return {
@@ -5248,6 +5590,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     },
     layers,
     roadmap,
+    deliveryMix,
     mappedModules,
     missing,
     handoff: {
@@ -5349,6 +5692,16 @@ function renderContextPack(pack) {
   } else {
     parts.push("No active work items found.\n");
   }
+  const mixEntries = Object.entries(pack.deliveryMix).sort((a, b) => b[1] - a[1]);
+  if (mixEntries.length > 0) {
+    parts.push("## Delivery Mix\n");
+    parts.push("Active Work Items by type:\n");
+    const label = (t) => {
+      const c = t.charAt(0).toUpperCase() + t.slice(1);
+      return c.endsWith("s") ? c : `${c}s`;
+    };
+    parts.push(mixEntries.map(([t, n]) => `- ${label(t)}: ${n}`).join("\n") + "\n");
+  }
   parts.push("## Artifacts and Ownership\n");
   if (knowledge.artifacts.length > 0) {
     const lines = knowledge.artifacts.map(
@@ -5696,7 +6049,9 @@ function runUnderstand() {
     ],
     delivery: [
       "Use roadmap-agent \u2192 knowledge/delivery/roadmap.md",
-      "Run `kaddo create --from roadmap`, then `kaddo owners suggest`"
+      "Run `kaddo create --from roadmap` (candidates \u2192 Work Items)",
+      "Use work-item-agent \u2192 refine into knowledge/delivery/work-items/",
+      "Use implementation-agent \u2192 implement, then `kaddo scan`, `kaddo owners suggest`, `kaddo guard`"
     ],
     utilities: ["Use legacy-agent to surface risks and unknowns"]
   };
@@ -8449,7 +8804,7 @@ program.command("scan").description("Detect project stack and suggest domains").
 program.command("bootstrap").description("Build the initial knowledge base for a new project (Business \u2192 Product \u2192 Tech \u2192 Delivery)").action(async () => {
   await runBootstrap();
 });
-program.command("create [type]").description("Create a work item (feature, bugfix, hotfix, spike). Use --from roadmap to create from a roadmap candidate.").option("--from <source>", "Create from a source artifact (currently: roadmap)").action(async (type, opts) => {
+program.command("create [type]").description("Create a work item (feature, bugfix, hotfix, spike, chore). Use --from roadmap to create from a roadmap candidate.").option("--from <source>", "Create from a source artifact (currently: roadmap)").action(async (type, opts) => {
   await runCreate(type ?? "", opts);
 });
 program.command("guard").description("Check if modified code has related artifacts that were not updated").option("--staged", "Check only staged files").option("--no-interactive", "Disable interactive ignore prompts").option("--ci", "CI mode: output JSON, no prompts, non-blocking").option("--json", "Output JSON (alias for --ci)").option("--workspace", "Also check local mapped module repos from .kaddo/modules.yml (opt-in)").action(async (opts) => {

package/package.json

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