@kaddo/cli 3.27.2 → 3.27.3

package/README.md

@@ -520,6 +520,7 @@ 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) |
 
 **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"]) {
@@ -12528,16 +12546,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.");

package/package.json

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