@kaddo/cli 3.27.2 → 3.28.0

package/README.md

@@ -520,6 +520,8 @@ create --from roadmap → owners → guard → explain`.
 | 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) |
+| v3.28 | Claude Code adapter: `kaddo adapters install claude` (alias `kaddo export claude`) generates a `CLAUDE.md` projection reusing the shared adapter common core (`--dry-run`/`--force`) |
 
 **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;
@@ -12361,11 +12404,13 @@ var ROLE_HINTS = {
   "graph-agent": "use to turn graph hints into front matter.",
   "capsule-agent": "use to refine a Knowledge Capsule for sharing."
 };
-function renderAgentsMd(ctx) {
+var TARGET_FILE = { codex: "AGENTS.md", claude: "CLAUDE.md" };
+function renderAdapterMarkdown(ctx, target) {
+  const file = TARGET_FILE[target];
   const L = [];
-  L.push("<!-- Generated by `kaddo adapters install codex`. Kaddo is the source of truth \u2014");
+  L.push(`<!-- Generated by \`kaddo adapters install ${target}\`. Kaddo is the source of truth \u2014`);
   L.push("     regenerate this file instead of editing it by hand. Do not treat it as primary. -->");
-  L.push("# AGENTS.md", "");
+  L.push(`# ${file}`, "");
   L.push("## Project 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,");
@@ -12441,32 +12486,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 +12513,9 @@ function renderAgentsMd(ctx) {
   L.push("");
   return L.join("\n");
 }
+function renderAgentsMd(ctx) {
+  return renderAdapterMarkdown(ctx, "codex");
+}
 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`";
@@ -12528,16 +12551,7 @@ function renderKaddoBlock(ctx) {
   L.push("- Do not modify `.kaddo/` manually; it is generated output.");
   L.push("- Do not commit without user confirmation.");
   L.push("");
-  L.push("### Command fallback", "");
-  L.push("Prefer `kaddo <command>`. If the global `kaddo` is not on `PATH`, try the local runner");
-  L.push("before reporting Kaddo is unavailable:");
-  L.push("```bash");
-  L.push("corepack pnpm exec kaddo <command>");
-  L.push("pnpm exec kaddo <command>");
-  L.push("npx kaddo <command>");
-  L.push("```");
-  L.push("Do not assume Kaddo is unavailable until these fallbacks have been attempted.");
-  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.");
@@ -12583,77 +12597,85 @@ ${sep}${block}
 }
 
 // src/commands/adapters.ts
+var TARGETS2 = {
+  codex: { target: "codex", file: "AGENTS.md", label: "Codex", supportsInject: true },
+  claude: { target: "claude", file: "CLAUDE.md", label: "Claude Code", supportsInject: false }
+};
 function runAdaptersInstall(adapter, opts = {}) {
   const dir = cwd();
   requireConfig(dir);
-  if (adapter !== "codex") {
-    console.error(`Unknown adapter: "${adapter}". Available: codex.`);
+  const spec = TARGETS2[adapter];
+  if (!spec) {
+    console.error(`Unknown adapter: "${adapter}". Available: ${Object.keys(TARGETS2).join(", ")}.`);
     process.exit(1);
+    return;
   }
   const ctx = buildCodexAdapterContext(dir);
-  const rel = "AGENTS.md";
+  const rel = spec.file;
   const full = join(dir, rel);
   const existed = exists(full);
   const existing = existed ? readFile(full) : null;
-  if (opts.inject) {
+  const cmd = `kaddo adapters install ${adapter}`;
+  if (opts.inject && spec.supportsInject) {
     const state = detectAgentsState(existing);
     if (state === "invalid_kaddo_block") {
-      console.error("Invalid Kaddo adapter block detected in AGENTS.md.");
+      console.error(`Invalid Kaddo adapter block detected in ${rel}.`);
       console.error("Found one marker without its pair. Fix the file manually or use --force to overwrite.");
       console.error("Nothing changed.");
       process.exit(1);
+      return;
     }
     if (existing === null) {
       const content2 = renderAgentsMd(ctx);
       if (opts.dryRun) {
-        console.log("# AGENTS.md preview", "");
+        console.log(`# ${rel} preview`, "");
         console.log(content2);
         return;
       }
-      intro2("kaddo adapters install codex --inject");
+      intro2(`${cmd} --inject`);
       writeFile(full, content2);
-      log2.success("Created AGENTS.md for Codex.");
+      log2.success(`Created ${rel} for ${spec.label}.`);
       printCommandFooter("adapters install codex");
-      outro2("AGENTS.md ready.");
+      outro2(`${rel} ready.`);
       return;
     }
     const merged = injectKaddoBlock(existing, ctx);
     if (opts.dryRun) {
-      console.log("# AGENTS.md preview (inject)", "");
+      console.log(`# ${rel} preview (inject)`, "");
       console.log(merged.content);
       return;
     }
-    intro2("kaddo adapters install codex --inject");
+    intro2(`${cmd} --inject`);
     writeFile(full, merged.content);
     if (merged.status === "updated") {
-      log2.success("Updated existing Kaddo guidance block in AGENTS.md.");
+      log2.success(`Updated existing Kaddo guidance block in ${rel}.`);
     } else {
-      log2.success("Injected Kaddo guidance block into AGENTS.md.");
+      log2.success(`Injected Kaddo guidance block into ${rel}.`);
     }
     log2.info("Content outside the Kaddo markers was preserved.");
     printCommandFooter("adapters install codex");
-    outro2("AGENTS.md ready.");
+    outro2(`${rel} ready.`);
     return;
   }
-  const content = renderAgentsMd(ctx);
+  const content = renderAdapterMarkdown(ctx, spec.target);
   if (opts.dryRun) {
-    console.log("# AGENTS.md preview", "");
+    console.log(`# ${rel} preview`, "");
     console.log(content);
     return;
   }
-  intro2("kaddo adapters install codex");
+  intro2(cmd);
   if (existed && !opts.force) {
-    log2.warn("AGENTS.md already exists.");
-    log2.info("Use `--inject` to add or update only the Kaddo block,");
-    log2.info("`--force` to overwrite, or `--dry-run` to preview.");
+    log2.warn(`${rel} already exists.`);
+    if (spec.supportsInject) log2.info("Use `--inject` to add or update only the Kaddo block,");
+    log2.info(`Use \`--force\` to overwrite, or \`--dry-run\` to preview.`);
     outro2("Nothing changed.");
     return;
   }
   writeFile(full, content);
-  log2.success(`${existed ? "Overwrote" : "Created"} AGENTS.md for Codex.`);
+  log2.success(`${existed ? "Overwrote" : "Created"} ${rel} for ${spec.label}.`);
   log2.info("Source: Kaddo project knowledge. Regenerate it instead of editing by hand.");
   printCommandFooter("adapters install codex");
-  outro2("AGENTS.md ready.");
+  outro2(`${rel} ready.`);
 }
 
 // src/index.ts
@@ -12710,10 +12732,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("--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) => {
+adaptersCmd.command("install <adapter>").description("Generate an adapter file (codex \u2192 AGENTS.md, claude \u2192 CLAUDE.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("--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) => {
+program.command("export <adapter>").description("Alias for `kaddo adapters install <adapter>` (codex \u2192 AGENTS.md, claude \u2192 CLAUDE.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.2",
+  "version": "3.28.0",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {