@kaddo/cli 3.11.2 → 3.13.0

package/dist/index.js

@@ -1546,6 +1546,20 @@ var RESPONSIBILITY_MATRIX = {
     cannotSuggest: ["branches", "commits", "pull requests", "code"],
     next: ["kaddo create --from roadmap", "work-item-agent"]
   },
+  "backlog-agent": {
+    agent: "backlog-agent",
+    responsibleFor: ["Capturing ideas", "Structuring new work"],
+    produces: ["knowledge/delivery/work-items/draft/", "roadmap candidates"],
+    canSuggest: ["work-item-agent", "roadmap-agent"],
+    cannotSuggest: [
+      "code",
+      "branches",
+      "commits",
+      "editing the roadmap automatically",
+      "auto-executing other agents"
+    ],
+    next: ["human decision (refine / add candidate / split / keep draft)"]
+  },
   "work-item-agent": {
     agent: "work-item-agent",
     responsibleFor: ["Work Item refinement"],
@@ -2249,6 +2263,12 @@ You do **not** suggest branches, commits or pull requests \u2014 implementation
 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.
 
+## Git boundaries
+
+Never run Git. Do not create or switch branches, create worktrees, stash, commit, push or merge.
+Work only inside the currently selected workspace. If a workspace or branch change is required,
+stop and ask the human.
+
 ## Quality Checklist
 
 - The problem is one clear sentence.
@@ -2814,6 +2834,10 @@ Conventional Commit message \u2014 as suggestions, never executed.
 ## Constraints
 
 - Never run Git. Never commit, push or merge \u2014 suggest and wait for the human.
+- **Do not create branches, switch branches, create worktrees, or stash changes.** You may
+  *suggest* a branch name; the human creates the branch and selects the workspace.
+- **Work only inside the currently selected workspace** (repository root or the active Git
+  worktree). If a branch or workspace change is required, stop and ask 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.
@@ -2846,6 +2870,98 @@ Code, tests and migrations live in the repository. Knowledge updates go under \`
 - Affected knowledge is updated.
 - Commit is suggested and awaits human confirmation \u2014 never run automatically.
 `;
+var BACKLOG_AGENT = `# Backlog Agent
+
+## Role
+
+You are the Kaddo Backlog Agent. Your job is to capture raw ideas, requests, meeting notes,
+conversations and transcripts and turn them into **structured backlog** compatible with Kaddo \u2014
+either a Work Item draft or a roadmap candidate.
+
+You answer one question: **"where should this idea live?"** \u2014 not "how is it implemented?". You do
+not write code, you do not refine Work Items fully, and you never trigger the next step.
+
+## When to Use
+
+Use this agent whenever new work appears outside the roadmap: a one-line idea, a bullet list, a
+meeting transcript, a Slack/Teams/email thread. It sits before the work-item-agent:
+
+\`Idea \u2192 backlog-agent \u2192 draft / roadmap candidate \u2192 (human decides) \u2192 work-item-agent\`
+
+## Input Required
+
+Provide \`.kaddo/context-pack.md\` as the primary input, plus the raw idea/notes/transcript. Use
+\`knowledge/business/business.md\`, \`knowledge/product/product.md\`, \`knowledge/product/capabilities.md\`,
+\`knowledge/tech/codebase.md\` and \`knowledge/delivery/roadmap.md\` when they exist to place the idea
+in the right initiative and avoid duplicates.
+
+## Expected Output
+
+One of:
+
+1. A **Work Item draft** under \`knowledge/delivery/work-items/draft/\` when the scope is clear and
+   small.
+2. A **roadmap candidate** (\`WI-CANDIDATE-XXX\`) to add later when the scope is too large.
+3. **Multiple** backlog items when the input contains several distinct ideas (split them).
+
+## Instructions
+
+1. Read the idea and the available knowledge.
+2. Decide: clear & small \u2192 Work Item draft; large \u2192 roadmap candidate; multiple ideas \u2192 split.
+3. For each item infer: initiative, domains, suggested type (feature/bugfix/hotfix/spike/chore),
+   suggested Knowledge Level (K1\u2013K4) and a suggested priority.
+4. Detect duplicates, overlaps and obvious dependencies with existing knowledge.
+5. Place each item under the most appropriate initiative.
+6. End with the mandatory handoff (below) \u2014 the human decides the next step.
+
+## Constraints
+
+- Do not write code.
+- Do not fully refine Work Items (that is the work-item-agent).
+- Do not modify \`knowledge/delivery/roadmap.md\` automatically \u2014 propose the candidate.
+- Never run Git (no branches, commits, pushes, merges).
+- **Never auto-execute the next step.** Do not run the work-item-agent or implementation-agent.
+- Always require a human decision before anything continues.
+
+## Output Format
+
+\`\`\`markdown
+# Backlog capture
+
+## Item 1 \u2014 <title>
+- Output: Work Item draft | Roadmap candidate
+- Suggested type: feature | bugfix | hotfix | spike | chore
+- Suggested Knowledge Level: K1 / K2 / K3 / K4
+- Initiative:
+- Domains:
+- Suggested priority:
+- Duplicates / overlaps / dependencies:
+- Summary:
+
+## Handoff
+Created: WI-023 (draft)   \xB7or\xB7   Roadmap candidate: WI-CANDIDATE-014
+
+Suggested next actions (human decides \u2014 nothing runs automatically):
+1. Refine with the work-item-agent
+2. Add as a roadmap candidate
+3. Split into multiple items
+4. Keep as a draft
+\`\`\`
+
+## Where to Save the Result
+
+Save a Work Item draft under \`knowledge/delivery/work-items/draft/\`. For a roadmap candidate,
+propose the \`WI-CANDIDATE-XXX\` text for a human to add to \`knowledge/delivery/roadmap.md\` (do not
+edit the roadmap yourself).
+
+## Quality Checklist
+
+- The idea is captured without being implemented or fully refined.
+- Output is clearly a draft or a roadmap candidate.
+- Multiple ideas are split into separate items.
+- Duplicates, overlaps and dependencies are flagged.
+- The response ends with a human-decision handoff \u2014 no agent is auto-executed.
+`;
 var AGENT_PROMPTS = [
   { fileName: "capability-agent.md", content: CAPABILITY_AGENT },
   { fileName: "architecture-agent.md", content: ARCHITECTURE_AGENT },
@@ -2863,7 +2979,9 @@ var AGENT_PROMPTS = [
   { fileName: "bootstrap-agent.md", content: BOOTSTRAP_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 }
+  { fileName: "implementation-agent.md", content: IMPLEMENTATION_AGENT },
+  // Backlog capture (idea → draft / roadmap candidate — VS-050)
+  { fileName: "backlog-agent.md", content: BACKLOG_AGENT }
   // Every official prompt ends with its responsibility boundaries + Agent Trace footer.
 ].map((p2) => ({ fileName: p2.fileName, content: withResponsibilityTrace(p2.fileName, p2.content) }));
 
@@ -2881,6 +2999,7 @@ var AGENT_GROUPS = {
     "adr-agent.md"
   ],
   delivery: [
+    "backlog-agent.md",
     "roadmap-agent.md",
     "work-item-agent.md",
     "implementation-agent.md",
@@ -2906,6 +3025,7 @@ var RECOMMENDED_BY_STATE = {
     "architecture-agent.md",
     "codebase-agent.md",
     "roadmap-agent.md",
+    "backlog-agent.md",
     "work-item-agent.md",
     "implementation-agent.md",
     "adr-agent.md"
@@ -2914,6 +3034,7 @@ var RECOMMENDED_BY_STATE = {
     "capability-agent.md",
     "architecture-agent.md",
     "roadmap-agent.md",
+    "backlog-agent.md",
     "work-item-agent.md",
     "implementation-agent.md"
   ],
@@ -2922,6 +3043,7 @@ var RECOMMENDED_BY_STATE = {
     "architecture-agent.md",
     "capability-agent.md",
     "roadmap-agent.md",
+    "backlog-agent.md",
     "work-item-agent.md",
     "implementation-agent.md"
   ]
@@ -4959,6 +5081,42 @@ function assessPhase(input) {
   return { phase, reasons, recommendedAgents: recommendedAgents2, nextStep };
 }
 
+// src/core/workspace.ts
+import { dirname, resolve, basename } from "path";
+function findGitEntry(startDir) {
+  let cur = resolve(startDir);
+  while (true) {
+    const g = join(cur, ".git");
+    if (exists(g)) return { dir: cur, gitPath: g };
+    const parent = dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+function readBranch(gitDir) {
+  try {
+    const head = readFile(join(gitDir, "HEAD")).trim();
+    const m = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+    if (m) return m[1].trim();
+    return head ? head.slice(0, 12) : null;
+  } catch {
+    return null;
+  }
+}
+function detectWorkspace(startDir) {
+  const found = findGitEntry(startDir);
+  if (!found) return { isGitRepo: false, root: null, branch: null, isWorktree: false };
+  const { dir, gitPath } = found;
+  if (!isFile(gitPath)) {
+    return { isGitRepo: true, root: dir, branch: readBranch(gitPath), isWorktree: false };
+  }
+  let gitDir = gitPath;
+  const m = readFile(gitPath).match(/gitdir:\s*(.+)/);
+  if (m) gitDir = m[1].trim();
+  const isWorktree = basename(dirname(gitDir)) === "worktrees";
+  return { isGitRepo: true, root: dir, branch: readBranch(gitDir), isWorktree };
+}
+
 // src/core/knowledge-discovery.ts
 var KNOWLEDGE = "knowledge";
 var CONSOLIDATED_TYPE = {
@@ -5008,7 +5166,7 @@ function layerFromPath(filePath) {
   if (p2.includes(`/${KNOWLEDGE}/delivery/`)) return "Delivery";
   return null;
 }
-function basename(p2) {
+function basename2(p2) {
   return p2.replace(/\\/g, "/").split("/").pop() ?? p2;
 }
 function discoverLayers(dir) {
@@ -5025,9 +5183,9 @@ function discoverLayers(dir) {
     const layer2 = layerForType(type) ?? layerFromPath(a.filePath);
     if (!layer2) continue;
     const slot = acc[layer2];
-    slot.detected.add(basename(a.filePath));
+    slot.detected.add(basename2(a.filePath));
     if (layer2 === "Delivery") {
-      if (type === "roadmap" || basename(a.filePath) === "roadmap.md") slot.hasRoadmap = true;
+      if (type === "roadmap" || basename2(a.filePath) === "roadmap.md") slot.hasRoadmap = true;
       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;
       }
@@ -5210,6 +5368,7 @@ function buildProjectExplanation(dir) {
     workItemsMissingOwnership: items.length - withOwnership
   };
   const domains = [...new Set(workItemArtifacts.flatMap((a) => a.domains))].filter(Boolean);
+  const workspace = detectWorkspace(dir);
   const roadmapPath = join(dir, ARCH_DIR4, "delivery", "roadmap.md");
   const roadmapMd = exists(roadmapPath) ? readFile(roadmapPath) : null;
   const roadmap = roadmapStats(roadmapMd, items.length);
@@ -5259,6 +5418,7 @@ function buildProjectExplanation(dir) {
     workItems,
     ownership,
     domains,
+    workspace,
     layers,
     roadmap,
     mappedModules,
@@ -5291,6 +5451,21 @@ function renderExplanationHuman(exp) {
   lines.push(`- Team: ${exp.project.teamSize}`);
   lines.push(`- Structure: ${exp.project.structure}`);
   lines.push("");
+  lines.push("## Workspace");
+  if (exp.workspace.isGitRepo) {
+    lines.push(`- Repository root: ${exp.workspace.root ?? "unknown"}`);
+    lines.push(`- Git worktree: ${exp.workspace.isWorktree ? "yes" : "no"}`);
+    lines.push(`- Active branch: ${exp.workspace.branch ?? "unknown"}`);
+    if (exp.workspace.isWorktree) {
+      lines.push("");
+      lines.push(
+        "> Worktree detected. Run all Kaddo commands (scan, guard, owners suggest, explain) from this worktree while implementation is active, so they observe the same files the agent is changing."
+      );
+    }
+  } else {
+    lines.push("- Not a Git repository");
+  }
+  lines.push("");
   lines.push("## Knowledge Layers");
   lines.push(renderLayersMarkdown(exp.layers));
   lines.push("");
@@ -5781,6 +5956,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     layers,
     roadmap,
     phase,
+    workspace: detectWorkspace(dir),
     deliveryMix,
     mappedModules,
     missing,
@@ -5818,6 +5994,23 @@ function renderContextPack(pack) {
       `- Structure: ${project.structure}`
     ].join("\n") + "\n"
   );
+  parts.push("## Execution Context\n");
+  if (pack.workspace.isGitRepo) {
+    parts.push(
+      [
+        `- Repository root: ${pack.workspace.root ?? "unknown"}`,
+        `- Current branch: ${pack.workspace.branch ?? "unknown"}`,
+        `- Git worktree: ${pack.workspace.isWorktree ? "yes" : "no"}`
+      ].join("\n") + "\n"
+    );
+    if (pack.workspace.isWorktree) {
+      parts.push(
+        "You are inside a Git worktree. Work only in this workspace; run Kaddo commands from here.\n"
+      );
+    }
+  } else {
+    parts.push("- Not a Git repository\n");
+  }
   parts.push("## Current Phase\n");
   parts.push(`Phase: ${pack.phase.phase}
 `);
@@ -6252,6 +6445,12 @@ function runUnderstand() {
   if (assessment.nextStep) {
     console.log(`Next step: ${assessment.nextStep}`);
   }
+  if (exp.workspace.isWorktree) {
+    console.log("");
+    console.log(`Current implementation workspace: ${exp.workspace.branch ?? "(detached)"}`);
+    console.log("  \u2192 You are inside a Git worktree. Run scan, owners suggest, guard and explain");
+    console.log("    from this worktree so they reflect the code being changed here.");
+  }
   const active = activeWorkItems(dir);
   if (active.length > 0) {
     console.log("");

package/package.json

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