@kaddo/cli 3.27.1 → 3.27.3

package/README.md

@@ -519,6 +519,8 @@ create --from roadmap → owners → guard → explain`.
 | v3.26 | Open-questions readiness gate: `kaddo questions`/`readiness`, blocking/important/deferred classification; MCP open-questions + roadmap-readiness resources + tool; roadmap/work-item/implementation/bootstrap agents check it |
 | v3.27 | Codex adapter: `kaddo adapters install codex` (alias `kaddo export codex`) generates a compact `AGENTS.md` projection (`--dry-run`/`--force`) |
 | v3.27.1 | Codex adapter command fallbacks: AGENTS.md tells Codex to try `corepack pnpm exec` / `pnpm exec` / `npx` kaddo when the global binary isn't on PATH |
+| v3.27.2 | Codex adapter safe merge: `kaddo adapters install codex --inject` adds/updates only a delimited Kaddo block in an existing AGENTS.md, preserving team content |
+| v3.27.3 | Codex adapter reference stabilization: package-manager-aware command fallbacks (lockfile detection) + Adapter Contract & Custom Adapters docs (reference for future adapters) |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -12337,6 +12337,7 @@ function buildCodexAdapterContext(dir) {
     projectName: config?.project.name,
     projectType: config?.project.state,
     language: config ? config.project.language : void 0,
+    packageManager: detectPackageManager2(dir),
     hasAgents: agents.length > 0,
     agents,
     hasSkills: skills.length > 0,
@@ -12346,6 +12347,48 @@ function buildCodexAdapterContext(dir) {
     generatedPaths: GENERATED_PATHS
   };
 }
+function detectPackageManager2(dir) {
+  if (exists(join(dir, "pnpm-lock.yaml"))) return "pnpm";
+  if (exists(join(dir, "yarn.lock"))) return "yarn";
+  if (exists(join(dir, "bun.lockb")) || exists(join(dir, "bun.lock"))) return "bun";
+  if (exists(join(dir, "package-lock.json"))) return "npm";
+  return void 0;
+}
+function commandFallbacks(pm) {
+  switch (pm) {
+    case "pnpm":
+      return ["corepack pnpm exec kaddo <command>", "pnpm exec kaddo <command>", "npx kaddo <command>"];
+    case "yarn":
+      return ["yarn kaddo <command>", "yarn dlx kaddo <command>", "npx kaddo <command>"];
+    case "bun":
+      return ["bunx kaddo <command>", "npx kaddo <command>"];
+    case "npm":
+      return ["npm exec kaddo <command>", "npx kaddo <command>"];
+    default:
+      return ["corepack pnpm exec kaddo <command>", "pnpm exec kaddo <command>", "npm exec kaddo <command>", "npx kaddo <command>"];
+  }
+}
+function commandFallbackSection(pm, heading) {
+  const L = [];
+  const pmNote = pm ? ` (detected package manager: \`${pm}\`)` : " (no package manager detected \u2014 generic options)";
+  L.push(`${heading}Command fallback`, "");
+  L.push(`Prefer the global \`kaddo\` command when available:`, "");
+  L.push("```bash");
+  L.push("kaddo <command>");
+  L.push("```");
+  L.push("");
+  L.push(`If \`kaddo\` is not available in \`PATH\`, try the local project runner${pmNote} before`);
+  L.push("reporting that Kaddo is unavailable:", "");
+  L.push("```bash");
+  for (const f of commandFallbacks(pm)) L.push(f);
+  L.push("```");
+  L.push("");
+  L.push("Do not fail immediately just because the global `kaddo` binary is missing. When you use a");
+  L.push('fallback, mention it briefly (e.g. "the global `kaddo` was not available, so I used the local');
+  L.push('runner").');
+  L.push("");
+  return L;
+}
 function detectMcpHint(dir) {
   for (const f of [".mcp.json", "mcp.json", ".cursor/mcp.json"]) {
     if (exists(join(dir, f))) return true;
@@ -12441,32 +12484,7 @@ function renderAgentsMd(ctx) {
     }
     L.push("");
   }
-  L.push("## Command fallback", "");
-  L.push("Prefer the direct command when available:", "");
-  L.push("```bash");
-  L.push("kaddo <command>");
-  L.push("```");
-  L.push("");
-  L.push("If the global `kaddo` command is not available in `PATH`, try the local project runner");
-  L.push("before reporting that Kaddo is unavailable:", "");
-  L.push("```bash");
-  L.push("corepack pnpm exec kaddo <command>");
-  L.push("```");
-  L.push("");
-  L.push("If that is not available, try:", "");
-  L.push("```bash");
-  L.push("pnpm exec kaddo <command>");
-  L.push("```");
-  L.push("");
-  L.push("As a last resort (may resolve/download the package):", "");
-  L.push("```bash");
-  L.push("npx kaddo <command>");
-  L.push("```");
-  L.push("");
-  L.push("Do not assume Kaddo is unavailable until these local fallbacks have been attempted. When you");
-  L.push('use a fallback, mention it briefly (e.g. "the global `kaddo` was not available, so I used');
-  L.push('`corepack pnpm exec kaddo`").');
-  L.push("");
+  for (const line of commandFallbackSection(ctx.packageManager, "## ")) L.push(line);
   L.push("## Useful Kaddo commands", "");
   L.push("```bash");
   for (const c of ["kaddo context", "kaddo understand", "kaddo explain", "kaddo graph export", "kaddo questions", "kaddo guard", "kaddo impact", "kaddo savings", "kaddo drift"]) {
@@ -12493,6 +12511,85 @@ function renderAgentsMd(ctx) {
   L.push("");
   return L.join("\n");
 }
+var KADDO_BEGIN_MARKER = "<!-- BEGIN KADDO CODEX ADAPTER -->";
+var KADDO_END_MARKER = "<!-- END KADDO CODEX ADAPTER -->";
+var GENERATED_HEADER = "Generated by `kaddo adapters install codex`";
+function detectAgentsState(content) {
+  if (content === null) return "missing";
+  const hasBegin = content.includes(KADDO_BEGIN_MARKER);
+  const hasEnd = content.includes(KADDO_END_MARKER);
+  if (hasBegin !== hasEnd) return "invalid_kaddo_block";
+  if (hasBegin && hasEnd) return "existing_with_kaddo_block";
+  if (content.includes(GENERATED_HEADER)) return "generated_by_kaddo";
+  return "existing_external";
+}
+function renderKaddoBlock(ctx) {
+  const L = [];
+  L.push(KADDO_BEGIN_MARKER, "");
+  L.push("## Kaddo guidance", "");
+  if (ctx.projectName) L.push(`Project: **${ctx.projectName}**${ctx.projectType ? ` (${ctx.projectType})` : ""}.`, "");
+  L.push("This repository uses **Kaddo** for Knowledge Driven Development. Kaddo keeps business,");
+  L.push("product, technical and delivery knowledge close to the code. Read the relevant Kaddo");
+  L.push("knowledge before changing code.");
+  L.push("");
+  L.push("### Kaddo knowledge map", "");
+  L.push("Primary knowledge:");
+  for (const p2 of ctx.knowledgePaths.length > 0 ? ctx.knowledgePaths : KNOWLEDGE_PATHS) L.push(`- \`${p2}\``);
+  L.push("");
+  L.push("Generated context (do not edit by hand):");
+  for (const p2 of ctx.generatedPaths) L.push(`- \`${p2}\``);
+  L.push("");
+  L.push("### Kaddo operating rules", "");
+  L.push("- Do not generate a roadmap without checking open-questions readiness.");
+  L.push("- Do not implement without reading the active Work Item.");
+  L.push("- Do not implement outside the scope of the active Work Item unless the user confirms.");
+  L.push("- Do not modify `.kaddo/` manually; it is generated output.");
+  L.push("- Do not commit without user confirmation.");
+  L.push("");
+  for (const line of commandFallbackSection(ctx.packageManager, "### ")) L.push(line);
+  L.push("### Before roadmap work", "");
+  L.push("Check open-questions readiness first. If blocking open questions exist, ask the user to");
+  L.push("resolve, assume or defer them before generating the roadmap.");
+  L.push("");
+  L.push("### Before implementation", "");
+  L.push("Read the target Work Item in `knowledge/delivery/work-items/`, `.kaddo/context-pack.md`,");
+  L.push("`.kaddo/understand.md`, and related knowledge and skills.");
+  L.push("");
+  L.push("### After implementation", "");
+  L.push("Suggest running `kaddo guard`, `kaddo impact`, `kaddo savings` and `kaddo drift`. If guard");
+  L.push("reports drift, explain it and ask before updating knowledge.");
+  L.push("");
+  if (ctx.hasAgents) {
+    L.push(`### Kaddo agents`, "");
+    L.push(`Installed under \`knowledge/agents/\`: ${ctx.agents.map((a) => `\`${a}\``).join(", ")}.`);
+    L.push("");
+  }
+  if (ctx.hasSkills) {
+    L.push(`### Kaddo skills`, "");
+    L.push(`Installed under \`knowledge/skills/\`: ${ctx.skills.map((s) => `\`${s}\``).join(", ")}. Read only what's relevant.`);
+    L.push("");
+  }
+  L.push(KADDO_END_MARKER);
+  return L.join("\n");
+}
+function injectKaddoBlock(existing, ctx) {
+  const block = renderKaddoBlock(ctx);
+  const begin = existing.indexOf(KADDO_BEGIN_MARKER);
+  const end = existing.indexOf(KADDO_END_MARKER);
+  if (begin === -1 !== (end === -1)) {
+    throw new Error("Invalid Kaddo adapter block: found one marker without its pair.");
+  }
+  if (begin !== -1 && end !== -1) {
+    if (end < begin) throw new Error("Invalid Kaddo adapter block: END marker before BEGIN marker.");
+    const before = existing.slice(0, begin);
+    const after = existing.slice(end + KADDO_END_MARKER.length);
+    return { content: `${before}${block}${after}`, status: "updated" };
+  }
+  const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+  return { content: `${existing.replace(/\s*$/, "")}
+${sep}${block}
+`, status: "injected" };
+}
 
 // src/commands/adapters.ts
 function runAdaptersInstall(adapter, opts = {}) {
@@ -12502,20 +12599,62 @@ function runAdaptersInstall(adapter, opts = {}) {
     console.error(`Unknown adapter: "${adapter}". Available: codex.`);
     process.exit(1);
   }
-  const content = renderAgentsMd(buildCodexAdapterContext(dir));
+  const ctx = buildCodexAdapterContext(dir);
+  const rel = "AGENTS.md";
+  const full = join(dir, rel);
+  const existed = exists(full);
+  const existing = existed ? readFile(full) : null;
+  if (opts.inject) {
+    const state = detectAgentsState(existing);
+    if (state === "invalid_kaddo_block") {
+      console.error("Invalid Kaddo adapter block detected in AGENTS.md.");
+      console.error("Found one marker without its pair. Fix the file manually or use --force to overwrite.");
+      console.error("Nothing changed.");
+      process.exit(1);
+    }
+    if (existing === null) {
+      const content2 = renderAgentsMd(ctx);
+      if (opts.dryRun) {
+        console.log("# AGENTS.md preview", "");
+        console.log(content2);
+        return;
+      }
+      intro2("kaddo adapters install codex --inject");
+      writeFile(full, content2);
+      log2.success("Created AGENTS.md for Codex.");
+      printCommandFooter("adapters install codex");
+      outro2("AGENTS.md ready.");
+      return;
+    }
+    const merged = injectKaddoBlock(existing, ctx);
+    if (opts.dryRun) {
+      console.log("# AGENTS.md preview (inject)", "");
+      console.log(merged.content);
+      return;
+    }
+    intro2("kaddo adapters install codex --inject");
+    writeFile(full, merged.content);
+    if (merged.status === "updated") {
+      log2.success("Updated existing Kaddo guidance block in AGENTS.md.");
+    } else {
+      log2.success("Injected Kaddo guidance block into AGENTS.md.");
+    }
+    log2.info("Content outside the Kaddo markers was preserved.");
+    printCommandFooter("adapters install codex");
+    outro2("AGENTS.md ready.");
+    return;
+  }
+  const content = renderAgentsMd(ctx);
   if (opts.dryRun) {
     console.log("# AGENTS.md preview", "");
     console.log(content);
     return;
   }
   intro2("kaddo adapters install codex");
-  const rel = "AGENTS.md";
-  const full = join(dir, rel);
-  const existed = exists(full);
   if (existed && !opts.force) {
     log2.warn("AGENTS.md already exists.");
-    log2.info("Use `kaddo adapters install codex --force` to overwrite,");
-    log2.info("or `kaddo adapters install codex --dry-run` to preview.");
+    log2.info("Use `--inject` to add or update only the Kaddo block,");
+    log2.info("`--force` to overwrite, or `--dry-run` to preview.");
     outro2("Nothing changed.");
     return;
   }
@@ -12580,10 +12719,10 @@ var questionsAction = (opts) => runQuestions(opts);
 program.command("questions").description("Open-questions readiness gate: blocking/important/deferred decisions before the roadmap").option("--json", "Output JSON instead of a summary").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/questions-report.md)").action(questionsAction);
 program.command("readiness").description("Alias for `kaddo questions`").option("--json", "Output JSON instead of a summary").option("--output <path>", "Write the report to a file").action(questionsAction);
 var adaptersCmd = program.command("adapters").description("Generate adapters that project Kaddo knowledge for external coding agents");
-adaptersCmd.command("install <adapter>").description("Generate an adapter file (codex \u2192 AGENTS.md) from Kaddo knowledge").option("--force", "Overwrite an existing output file").option("--dry-run", "Print the content without writing files").action((adapter, opts) => {
+adaptersCmd.command("install <adapter>").description("Generate an adapter file (codex \u2192 AGENTS.md) from Kaddo knowledge").option("--force", "Overwrite an existing output file").option("--inject", "Add or update only the Kaddo block in an existing file, preserving the rest").option("--dry-run", "Print the content without writing files").action((adapter, opts) => {
   runAdaptersInstall(adapter, opts);
 });
-program.command("export <adapter>").description("Alias for `kaddo adapters install <adapter>` (codex \u2192 AGENTS.md)").option("--force", "Overwrite an existing output file").option("--dry-run", "Print the content without writing files").action((adapter, opts) => {
+program.command("export <adapter>").description("Alias for `kaddo adapters install <adapter>` (codex \u2192 AGENTS.md)").option("--force", "Overwrite an existing output file").option("--inject", "Add or update only the Kaddo block in an existing file, preserving the rest").option("--dry-run", "Print the content without writing files").action((adapter, opts) => {
   runAdaptersInstall(adapter, 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)").option("--include-archived", "Include archived Work Items in ownership matching (excluded by default)").option("--record", "Record this run to .kaddo/history/ for drift trend reporting").action(async (opts) => {

package/package.json

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