@kaddo/cli 3.25.1 → 3.27.0

package/README.md

@@ -516,6 +516,8 @@ create --from roadmap → owners → guard → explain`.
 | v3.24 | Estimated Savings Model: `kaddo savings` (+ `savings init`, `.kaddo/savings.yml`); evidence-based time/value estimates, confidence; MCP resource + tool |
 | v3.25 | Guard history & drift trend: `kaddo guard --record`, `kaddo drift`; feeds impact Guard Activity + savings Drift Prevention; MCP drift/guard-history resources + tool |
 | v3.25.1 | Savings guard-history messaging fix: distinguishes "no history" from "history with 0 resolved warnings" (drift prevention available at 0 h) |
+| 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`) |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -696,6 +696,14 @@ var COMMAND_HELP = {
   drift: {
     question: "Are code and knowledge drifting apart over time?",
     next: "Review open warnings; `kaddo guard --record` before commits"
+  },
+  questions: {
+    question: "Are there open questions to decide before the roadmap?",
+    next: "Resolve, assume or defer blocking questions, then generate the roadmap"
+  },
+  "adapters install codex": {
+    question: "How does Codex work with this Kaddo project?",
+    next: "Open AGENTS.md, or regenerate it after knowledge changes"
   }
 };
 function commandFooterLines(name) {
@@ -2401,6 +2409,21 @@ open question):
 - \`knowledge/knowledge.md\`
 - business priorities
 
+## Readiness Gate (check first)
+
+Before generating the roadmap, check **roadmap readiness** for open questions that affect scope,
+architecture or the MVP. Read \`kaddo://roadmap-readiness\` (MCP) or run \`kaddo questions\`.
+
+If readiness is \`needs_decisions\` (there are **blocking** open questions), do **not** generate the
+roadmap yet. Instead, list the blocking questions, propose reasonable assumptions for each, and ask
+the user to confirm, e.g.:
+
+> Before generating the roadmap I found blocking open questions that affect the MVP scope.
+> I can proceed with these assumptions: \u2026 Confirm and continue?
+
+Only generate the roadmap once the user confirms the assumptions (or resolves/defers the
+questions). Record confirmed assumptions explicitly in the roadmap.
+
 ## Expected Output
 
 A single Markdown artifact intended to be saved as \`knowledge/delivery/roadmap.md\`.
@@ -2709,6 +2732,13 @@ Work Items into clear, traceable units of work.
 You do not write code. You sharpen the problem, validate the Knowledge Level and make the
 Work Item actionable for a human.
 
+## Readiness Gate (check first)
+
+For high-impact Work Items, check \`kaddo://roadmap-readiness\` (or \`kaddo questions\`) for
+**blocking** open questions related to this Work Item's scope. If any are unresolved, surface them
+and propose assumptions for the user to confirm before refining \u2014 don't bake in invisible
+assumptions.
+
 ## When to Use
 
 Use this agent after a roadmap exists (\`knowledge/delivery/roadmap.md\`) or when an existing Work
@@ -3210,6 +3240,13 @@ You are the Kaddo Bootstrap Agent. You guide the transition from business defini
 initial architecture direction, quality attributes, a roadmap and first Work Items for a
 new project. You propose; the human decides.
 
+## Readiness Gate
+
+Bootstrap surfaces \`## Open Questions\` in the knowledge files. Before moving to the roadmap,
+explicitly recommend reviewing them (\`kaddo questions\` / \`kaddo://roadmap-readiness\`) and turning
+**blocking** ones into resolved decisions or confirmed assumptions \u2014 so the roadmap isn't built on
+invisible assumptions.
+
 ## When to Use
 
 Use this agent after \`kaddo bootstrap\` and after the business artifacts are drafted.
@@ -3321,6 +3358,13 @@ 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.
 
+## Readiness Gate (check first)
+
+Before implementing a high-impact Work Item, check \`kaddo://roadmap-readiness\` (or
+\`kaddo questions\`) for **blocking** open questions about stack, architecture, persistence,
+authentication or the Work Item's scope. If any are unresolved, pause and ask the user to confirm
+assumptions or resolve them before writing code.
+
 ## When to Use
 
 Use this agent after the work-item-agent has produced a clear, traceable Work Item under
@@ -8162,6 +8206,224 @@ function renderDeliveryLifecycle(wi) {
   ];
 }
 
+// src/core/open-questions.ts
+var SOURCES = [
+  "knowledge/business/business.md",
+  "knowledge/product/product.md",
+  "knowledge/tech/codebase.md",
+  "knowledge/delivery/roadmap.md"
+];
+var BLOCKING = [
+  "mvp",
+  "stack",
+  "arquitect",
+  "architecture",
+  "api",
+  "web app",
+  "webapp",
+  "cli",
+  "backend",
+  "auth",
+  "autenticaci",
+  "persist",
+  "base de datos",
+  "database",
+  "roadmap",
+  "alcance",
+  "scope",
+  "primera versi\xF3n",
+  "primera version",
+  "first version",
+  "fastify",
+  "nestjs",
+  "framework"
+];
+var DEFERRED = [
+  "integraci",
+  "integration",
+  "analytics",
+  "notificaci",
+  "notification",
+  "google calendar",
+  "eventbrite",
+  "meetup",
+  "dashboard",
+  "multi-tenant",
+  "multitenant",
+  "mobile",
+  "m\xF3vil",
+  "pago",
+  "payment",
+  "ticketing",
+  "multiple tracks",
+  "m\xFAltiples tracks",
+  "webhook"
+];
+var IMPORTANT = [
+  "validaci",
+  "validation",
+  "paginaci",
+  "pagination",
+  "soft delete",
+  "sponsor",
+  "agenda",
+  "ubicaci",
+  "location",
+  "rol",
+  "role",
+  "permis",
+  "permission"
+];
+function matchesAny(text3, keywords) {
+  return keywords.some((k) => text3.includes(k));
+}
+function classifyQuestion(question) {
+  const t = question.toLowerCase();
+  if (matchesAny(t, BLOCKING)) {
+    return { classification: "blocking", reason: "Affects scope, architecture or the first Work Items." };
+  }
+  if (matchesAny(t, DEFERRED) && !matchesAny(t, IMPORTANT)) {
+    return { classification: "deferred", reason: "Can be moved to a later phase." };
+  }
+  if (matchesAny(t, IMPORTANT)) {
+    return { classification: "important", reason: "Relevant, but a temporary assumption can unblock progress." };
+  }
+  return { classification: "important", reason: "Relevant, but a temporary assumption can unblock progress." };
+}
+function extractFromMarkdown(md) {
+  const lines = md.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^#{1,6}\s+open questions\s*$/i.test(l.trim()) || /^#{1,6}\s+preguntas abiertas\s*$/i.test(l.trim()));
+  if (start < 0) return [];
+  const out = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^#{1,6}\s+/.test(line)) break;
+    const m = line.match(/^\s*(?:[-*]|\d+\.)\s+(.+?)\s*$/);
+    if (m) {
+      const q = m[1].trim();
+      if (q && !/^_.*_$/.test(q)) out.push(q);
+    }
+  }
+  return out;
+}
+function suggestedAssumption(question) {
+  const t = question.toLowerCase();
+  if (matchesAny(t, ["api", "web app", "webapp", "cli", "backend"])) {
+    return "Start as a backend API to keep the initial scope small.";
+  }
+  if (matchesAny(t, ["auth", "autenticaci"])) {
+    return "No authentication in the MVP.";
+  }
+  if (matchesAny(t, ["fastify", "nestjs", "framework", "stack"])) {
+    return "Choose the lighter stack option to minimize MVP scope.";
+  }
+  if (matchesAny(t, ["persist", "base de datos", "database"])) {
+    return "Use a simple local datastore (e.g. SQLite) for the MVP.";
+  }
+  return "Proceed with the smallest reasonable MVP interpretation and revisit later.";
+}
+function buildOpenQuestionsReport(dir, now = /* @__PURE__ */ new Date()) {
+  const project = loadConfig(dir)?.project.name ?? "unknown";
+  const questions = [];
+  let seq = 0;
+  for (const source of SOURCES) {
+    const p2 = join(dir, source);
+    if (!exists(p2)) continue;
+    let md;
+    try {
+      md = readFile(p2);
+    } catch {
+      continue;
+    }
+    for (const q of extractFromMarkdown(md)) {
+      seq += 1;
+      const { classification, reason } = classifyQuestion(q);
+      questions.push({
+        id: `OQ-${String(seq).padStart(3, "0")}`,
+        source,
+        section: "Open Questions",
+        question: q,
+        classification,
+        reason,
+        ...classification === "blocking" ? { suggested_assumption: suggestedAssumption(q) } : {}
+      });
+    }
+  }
+  const blocking = questions.filter((q) => q.classification === "blocking");
+  const important = questions.filter((q) => q.classification === "important");
+  const deferred = questions.filter((q) => q.classification === "deferred");
+  let readiness;
+  if (questions.length === 0) readiness = "unknown";
+  else if (blocking.length > 0) readiness = "needs_decisions";
+  else readiness = "ready";
+  const suggested_assumptions = blocking.map((q) => q.suggested_assumption).filter(Boolean);
+  const recommended_next_step = readiness === "needs_decisions" ? "Confirm suggested assumptions with the user (resolve, assume or defer blocking questions) before generating the roadmap." : readiness === "ready" ? "No blocking questions \u2014 you can proceed to the roadmap (review important questions when convenient)." : "No open questions found. Run `kaddo bootstrap` to capture early questions, or proceed.";
+  return {
+    generated_at: now.toISOString(),
+    project,
+    summary: {
+      open_questions: questions.length,
+      roadmap_readiness: readiness,
+      blocking: blocking.length,
+      important: important.length,
+      deferred: deferred.length
+    },
+    questions,
+    blocking_questions: blocking,
+    important_questions: important,
+    deferred_questions: deferred,
+    suggested_assumptions,
+    recommended_next_step
+  };
+}
+function renderOpenQuestionsMarkdown(r) {
+  const L = [];
+  L.push("# Kaddo Open Questions Readiness Report", "");
+  L.push(`Generated at: ${r.generated_at}`);
+  L.push(`Project: ${r.project}`);
+  L.push("");
+  L.push("## Summary", "");
+  L.push(`- Open questions found: ${r.summary.open_questions}`);
+  L.push(`- Roadmap readiness: ${r.summary.roadmap_readiness}`);
+  L.push(`- Blocking: ${r.summary.blocking}`);
+  L.push(`- Important: ${r.summary.important}`);
+  L.push(`- Deferred: ${r.summary.deferred}`);
+  L.push("");
+  if (r.summary.open_questions === 0) {
+    L.push("No `## Open Questions` sections found in business / product / codebase / roadmap.", "");
+    L.push("## Recommended Next Step", "", r.recommended_next_step, "");
+    return L.join("\n");
+  }
+  L.push("## Blocking Questions", "");
+  if (r.blocking_questions.length === 0) L.push("_None._", "");
+  for (const q of r.blocking_questions) {
+    L.push(`### ${q.id}`, "");
+    L.push(`- Source: \`${q.source}\``);
+    L.push(`- Question: ${q.question}`);
+    L.push(`- Reason: ${q.reason}`);
+    if (q.suggested_assumption) L.push(`- Suggested assumption: ${q.suggested_assumption}`);
+    L.push("");
+  }
+  L.push("## Important Questions", "");
+  if (r.important_questions.length === 0) L.push("_None._");
+  for (const q of r.important_questions) L.push(`- ${q.question}`);
+  L.push("");
+  L.push("## Deferred Questions", "");
+  if (r.deferred_questions.length === 0) L.push("_None._");
+  for (const q of r.deferred_questions) L.push(`- ${q.question}`);
+  L.push("");
+  if (r.suggested_assumptions.length > 0) {
+    L.push("## Suggested Assumptions", "");
+    for (const a of r.suggested_assumptions) L.push(`- ${a}`);
+    L.push("");
+  }
+  L.push("## Recommended Next Step", "", r.recommended_next_step, "");
+  return L.join("\n");
+}
+function serializeOpenQuestionsJson(r) {
+  return JSON.stringify(r, null, 2) + "\n";
+}
+
 // src/commands/understand.ts
 function runUnderstand() {
   const dir = cwd();
@@ -8234,6 +8496,12 @@ function runUnderstand() {
     console.log("  \u2192 Review graph hints before continuing with implementation.");
     console.log("  Suggested agent: graph-agent (see .kaddo/graph-hints.md)");
   }
+  const oq = buildOpenQuestionsReport(dir);
+  if (oq.summary.blocking > 0) {
+    console.log("");
+    console.log(`Open questions: ${oq.summary.blocking} blocking decision(s) before the roadmap (roadmap readiness: ${oq.summary.roadmap_readiness}).`);
+    console.log("  \u2192 Run `kaddo questions` to review them, then resolve, assume or defer before `kaddo create --from roadmap`.");
+  }
   const active = activeWorkItems(dir);
   if (active.length > 0) {
     console.log("");
@@ -8291,35 +8559,35 @@ var DEP_PATTERNS = [
 function normalizePath2(p2) {
   return p2.split(path5.sep).join("/");
 }
-function matchesAny(file, patterns) {
+function matchesAny2(file, patterns) {
   const normalized = normalizePath2(file);
   return patterns.some((p2) => p2.test(normalized));
 }
 function detectSignals(touchedFiles) {
   const signals = [];
   for (const file of touchedFiles) {
-    if (matchesAny(file, MIGRATION_PATTERNS)) {
+    if (matchesAny2(file, MIGRATION_PATTERNS)) {
       signals.push({
         name: "DB migration",
         file,
         implication: "Data schema change \u2014 typically K4 or Migration type",
         suggestedLevel: "K4"
       });
-    } else if (matchesAny(file, CONTRACT_PATTERNS)) {
+    } else if (matchesAny2(file, CONTRACT_PATTERNS)) {
       signals.push({
         name: "API/event contract",
         file,
         implication: "Contract change affects consumers \u2014 typically K3/K4",
         suggestedLevel: "K3"
       });
-    } else if (matchesAny(file, INFRA_PATTERNS)) {
+    } else if (matchesAny2(file, INFRA_PATTERNS)) {
       signals.push({
         name: "Infrastructure",
         file,
         implication: "Infrastructure change \u2014 typically K3/K4",
         suggestedLevel: "K3"
       });
-    } else if (matchesAny(file, DEP_PATTERNS)) {
+    } else if (matchesAny2(file, DEP_PATTERNS)) {
       signals.push({
         name: "Dependency",
         file,
@@ -11995,6 +12263,243 @@ function runDrift(opts = {}) {
   console.log(content);
 }
 
+// src/commands/questions.ts
+function runQuestions(opts = {}) {
+  const dir = cwd();
+  requireConfig(dir);
+  const report = buildOpenQuestionsReport(dir);
+  if (opts.output) {
+    intro2("kaddo questions");
+    writeFile(join(dir, opts.output), opts.json ? serializeOpenQuestionsJson(report) : renderOpenQuestionsMarkdown(report));
+    log2.success(`Wrote ${opts.output.replace(/\\/g, "/")}`);
+    printCommandFooter("questions");
+    outro2("Questions report written.");
+    return;
+  }
+  if (opts.json) {
+    console.log(serializeOpenQuestionsJson(report));
+    return;
+  }
+  console.log("");
+  console.log(`Open questions detected: ${report.summary.open_questions}`);
+  console.log(`Roadmap readiness: ${report.summary.roadmap_readiness === "needs_decisions" ? "needs decisions" : report.summary.roadmap_readiness}`);
+  const list2 = (title, qs) => {
+    if (qs.length === 0) return;
+    console.log("");
+    console.log(`${title}:`);
+    for (const q of qs.slice(0, 8)) console.log(`- ${q.question}`);
+    if (qs.length > 8) console.log(`  \u2026and ${qs.length - 8} more`);
+  };
+  list2("Blocking", report.blocking_questions);
+  list2("Important", report.important_questions);
+  list2("Deferred", report.deferred_questions);
+  console.log("");
+  console.log("Suggested next:");
+  console.log(report.recommended_next_step);
+  printCommandFooter("questions");
+}
+
+// src/core/codex-adapter.ts
+var KNOWLEDGE_PATHS = [
+  "knowledge/business/",
+  "knowledge/product/",
+  "knowledge/tech/",
+  "knowledge/delivery/",
+  "knowledge/agents/",
+  "knowledge/skills/"
+];
+var GENERATED_PATHS = [
+  ".kaddo/context-pack.md",
+  ".kaddo/understand.md",
+  ".kaddo/explain.md",
+  ".kaddo/graph.json",
+  ".kaddo/reports/"
+];
+function discoverAgents(dir) {
+  const base = join(dir, "knowledge", "agents");
+  if (!exists(base) || !isDir(base)) return [];
+  const out = /* @__PURE__ */ new Set();
+  const walk = (d) => {
+    for (const e of readDir(d)) {
+      const full = join(d, e);
+      if (isDir(full)) walk(full);
+      else if (e.endsWith("-agent.md")) out.add(e.replace(/\.md$/, ""));
+    }
+  };
+  walk(base);
+  return [...out].sort();
+}
+function buildCodexAdapterContext(dir) {
+  const config = loadConfig(dir);
+  const agents = discoverAgents(dir);
+  const skills = discoverInstalledSkills(dir).map((s) => s.id);
+  return {
+    projectName: config?.project.name,
+    projectType: config?.project.state,
+    language: config ? config.project.language : void 0,
+    hasAgents: agents.length > 0,
+    agents,
+    hasSkills: skills.length > 0,
+    skills,
+    hasMcpHint: detectMcpHint(dir),
+    knowledgePaths: KNOWLEDGE_PATHS.filter((p2) => exists(join(dir, p2))),
+    generatedPaths: GENERATED_PATHS
+  };
+}
+function detectMcpHint(dir) {
+  for (const f of [".mcp.json", "mcp.json", ".cursor/mcp.json"]) {
+    if (exists(join(dir, f))) return true;
+  }
+  return false;
+}
+var ROLE_HINTS = {
+  "roadmap-agent": "use before creating or refining the roadmap.",
+  "work-item-agent": "use before refining Work Items.",
+  "implementation-agent": "use before implementing Work Items.",
+  "bootstrap-agent": "use when refining initial knowledge.",
+  "ownership-agent": "use to propose precise `code:` ownership globs.",
+  "graph-agent": "use to turn graph hints into front matter.",
+  "capsule-agent": "use to refine a Knowledge Capsule for sharing."
+};
+function renderAgentsMd(ctx) {
+  const L = [];
+  L.push("<!-- Generated by `kaddo adapters install codex`. 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("## 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,");
+  L.push("product, technical and delivery knowledge close to the code.");
+  L.push("");
+  L.push("Before making changes, read the relevant Kaddo knowledge files instead of relying only on");
+  L.push("source code.");
+  L.push("");
+  L.push("## Kaddo knowledge map", "");
+  L.push("Primary knowledge lives in:", "");
+  for (const p2 of ctx.knowledgePaths.length > 0 ? ctx.knowledgePaths : KNOWLEDGE_PATHS) L.push(`- \`${p2}\``);
+  L.push("");
+  L.push("Derived context (generated \u2014 do not edit by hand) lives in:", "");
+  for (const p2 of ctx.generatedPaths) L.push(`- \`${p2}\``);
+  L.push("");
+  L.push("## 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 assume missing product or business decisions \u2014 prefer explicit assumptions.");
+  L.push("- Keep knowledge updated when implementation changes scope.");
+  L.push("- Do not modify `.kaddo/` manually; it is generated output.");
+  L.push("- Do not commit without user confirmation.");
+  L.push("");
+  L.push("## Before roadmap work", "");
+  L.push("Read `knowledge/business/business.md`, `knowledge/product/product.md`,");
+  L.push("`knowledge/tech/codebase.md`, and `.kaddo/reports/questions-report.md` if available.");
+  L.push("");
+  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** \u2014 never build the roadmap on");
+  L.push("invisible assumptions.");
+  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 the related knowledge and skills files.");
+  L.push("");
+  L.push("Do not implement outside the scope of the active Work Item unless the user confirms.");
+  L.push("");
+  L.push("## After implementation", "");
+  L.push("Suggest running, as validation (not mandatory):", "");
+  L.push("```bash");
+  L.push("kaddo guard");
+  L.push("kaddo impact");
+  L.push("kaddo savings");
+  L.push("kaddo drift");
+  L.push("```");
+  L.push("");
+  L.push("Before finishing a change, suggest `kaddo guard`. If warnings appear, explain the possible");
+  L.push("knowledge drift and ask the user whether to update the related knowledge \u2014 never update it");
+  L.push("automatically.");
+  L.push("");
+  if (ctx.hasAgents) {
+    L.push("## Available Kaddo agents", "");
+    L.push("Installed under `knowledge/agents/`. Use them as role-specific guidance when relevant:", "");
+    for (const a of ctx.agents) {
+      const hint = ROLE_HINTS[a];
+      L.push(`- \`${a}\`${hint ? `: ${hint}` : ""}`);
+    }
+    L.push("");
+  }
+  if (ctx.hasSkills) {
+    L.push("## Available Kaddo skills", "");
+    L.push("Reusable skills under `knowledge/skills/`. Read only the skills relevant to the current");
+    L.push("task \u2014 do not load every skill by default.", "");
+    for (const s of ctx.skills) L.push(`- \`${s}\``);
+    L.push("");
+  }
+  if (ctx.hasMcpHint) {
+    L.push("## MCP", "");
+    L.push("A Kaddo MCP server appears to be configured. Prefer MCP resources over manually scanning");
+    L.push("generated files:", "");
+    for (const r of ["kaddo://context-pack", "kaddo://understand", "kaddo://explain", "kaddo://open-questions", "kaddo://roadmap-readiness", "kaddo://impact-report", "kaddo://savings-report", "kaddo://drift-report"]) {
+      L.push(`- \`${r}\``);
+    }
+    L.push("");
+  }
+  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"]) {
+    L.push(c);
+  }
+  L.push("```");
+  L.push("");
+  L.push("## Agent behavior", "");
+  const steps = [
+    "Identify the current task or Work Item.",
+    "Read the related Kaddo knowledge.",
+    "Check readiness gates (open questions).",
+    "Implement only the requested scope.",
+    "Validate with tests or checks.",
+    "Suggest knowledge updates if implementation changed the original understanding.",
+    "Ask before committing."
+  ];
+  steps.forEach((s, i) => L.push(`${i + 1}. ${s}`));
+  L.push("");
+  L.push("## Safety limits", "");
+  L.push("Do not: rewrite the Kaddo methodology, delete knowledge files, manually edit generated");
+  L.push("`.kaddo/` artifacts, bypass readiness gates, generate a roadmap from source code alone, or");
+  L.push("implement broad changes without an active Work Item.");
+  L.push("");
+  return L.join("\n");
+}
+
+// src/commands/adapters.ts
+function runAdaptersInstall(adapter, opts = {}) {
+  const dir = cwd();
+  requireConfig(dir);
+  if (adapter !== "codex") {
+    console.error(`Unknown adapter: "${adapter}". Available: codex.`);
+    process.exit(1);
+  }
+  const content = renderAgentsMd(buildCodexAdapterContext(dir));
+  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.");
+    outro2("Nothing changed.");
+    return;
+  }
+  writeFile(full, content);
+  log2.success(`${existed ? "Overwrote" : "Created"} AGENTS.md for Codex.`);
+  log2.info("Source: Kaddo project knowledge. Regenerate it instead of editing by hand.");
+  printCommandFooter("adapters install codex");
+  outro2("AGENTS.md ready.");
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -12045,6 +12550,16 @@ reportCmd.command("drift").description("Drift Trend Report from recorded guard h
 program.command("drift").description("Drift Trend Report from recorded `kaddo guard --record` history").option("--json", "Output JSON instead of Markdown").option("--output <path>", "Write the report to a file").action((opts) => {
   runDrift(opts);
 });
+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) => {
+  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) => {
+  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) => {
   await runGuard(opts);
 });

package/package.json

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