@kaddo/cli 3.7.1 → 3.8.0

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { createRequire } from "module";
 import { Command } from "commander";
 
 // src/commands/init.ts
@@ -1374,6 +1375,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
 
@@ -1633,6 +1848,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.
@@ -1959,23 +2177,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
+## Handoff
 
-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.**
-
-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
 
@@ -1983,8 +2190,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
 
@@ -2497,6 +2705,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 },
@@ -2512,8 +2796,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 = {
@@ -2528,7 +2815,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);
@@ -2550,20 +2842,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) {
@@ -5695,7 +5990,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"]
   };
@@ -8435,8 +8732,10 @@ async function runBootstrap(dir = cwd()) {
 }
 
 // src/index.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
 var program = new Command();
-program.name("kaddo").description("Knowledge Driven Development toolkit").version("3.6.0");
+program.name("kaddo").description("Knowledge Driven Development toolkit").version(version);
 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.7.1",
+  "version": "3.8.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {