@kaddo/cli 3.33.0 → 3.34.0

package/README.md

@@ -529,6 +529,7 @@ create --from roadmap → owners → guard → explain`.
 | v3.31 | Kiro adapter: `kaddo adapters install kiro` (alias `kaddo export kiro`) generates an `AGENTS.md` projection reusing the shared adapter common core (`--dry-run`/`--force`/`--inject` + inject guard) |
 | v3.32 | Adapter discovery & status: `kaddo adapters list` (alias `ls`) and `kaddo adapters status` (alias `check`) — read-only catalog + per-adapter install state (missing/team-owned/injected/legacy-injected/full-generated/broken-markers), shared-`AGENTS.md` origin detection, `--json` |
 | v3.33 | Open questions resolution tracking: mark questions `[open]`/`[resolved]`/`[assumed]`/`[deferred]` (EN+ES); only `open` blocks readiness, so assumed/resolved/deferred decisions stop false blocks. `kaddo questions` shows status counts + `resolution_status` in JSON |
+| v3.34 | Pre-AI onboarding: `kaddo onboarding` (alias `onboard`) / `kaddo report onboarding` — read-only diagnosis of an existing project's readiness (scan/understand/knowledge/questions/roadmap/work-items/adapters) with a single recommended next step; `--json` |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -704,6 +704,10 @@ var COMMAND_HELP = {
   "adapters install codex": {
     question: "How does Codex work with this Kaddo project?",
     next: "Open AGENTS.md, or regenerate it after knowledge changes"
+  },
+  onboarding: {
+    question: "How ready is this pre-AI project to work with agents?",
+    next: "Run the single recommended next step, then re-run `kaddo onboarding`"
   }
 };
 function commandFooterLines(name) {
@@ -3255,6 +3259,16 @@ on invisible assumptions. When you find unresolved questions, suggest marking ea
 token so Kaddo can track them: \`[open]\`, \`[resolved]\`, \`[assumed]\` or \`[deferred]\` (ES: \`[abierta]\`,
 \`[resuelta]\`, \`[asumida]\`, \`[diferida]\`). Only \`open\` questions block readiness.
 
+## Pre-AI projects
+
+For **pre-AI** projects (existing code, little structured knowledge), use \`kaddo onboarding\` as the
+compass: it diagnoses the current state and recommends a single next step along the cycle
+\`init \u2192 scan \u2192 understand \u2192 onboarding \u2192 questions \u2192 roadmap \u2192 create --from roadmap \u2192 adapter \u2192
+implement \u2192 guard\`. Use the \`scan\` and \`understand\` outputs as input \u2014 **do not invent project
+goals or capabilities**. Capture unknowns as \`[open]\` questions and safe, explicit defaults as
+\`[assumed]\`. Build \`knowledge/tech/current-state.md\` and \`knowledge/tech/codebase.md\` from real
+repo signals before drafting the roadmap or the first Work Item.
+
 ## When to Use
 
 Use this agent after \`kaddo bootstrap\` and after the business artifacts are drafted.
@@ -12891,6 +12905,229 @@ function runAdaptersStatus(opts = {}) {
   }
 }
 
+// src/core/onboarding.ts
+var KNOWLEDGE_FILES = [
+  { key: "current_state", path: "knowledge/tech/current-state.md", label: "knowledge/tech/current-state.md" },
+  { key: "codebase", path: "knowledge/tech/codebase.md", label: "knowledge/tech/codebase.md" },
+  { key: "capabilities", path: "knowledge/product/capabilities.md", label: "knowledge/product/capabilities.md" },
+  { key: "product", path: "knowledge/product/product.md", label: "knowledge/product/product.md" },
+  { key: "business", path: "knowledge/business/business.md", label: "knowledge/business/business.md" }
+];
+function knowledgePresence(dir, rel) {
+  const p2 = join(dir, rel);
+  if (!exists(p2)) return "missing";
+  let md;
+  try {
+    md = readFile(p2);
+  } catch {
+    return "missing";
+  }
+  const body = md.replace(/^---[\s\S]*?---/m, "").split(/\r?\n/).filter((l) => !/^\s*#{1,6}\s/.test(l) && !/^\s*$/.test(l) && !/^\s*<!--/.test(l)).join(" ").trim();
+  return body.length >= 40 ? "present" : "weak";
+}
+function roadmapSignal(dir) {
+  const p2 = join(dir, "knowledge/delivery/roadmap.md");
+  if (!exists(p2)) return "missing";
+  let md;
+  try {
+    md = readFile(p2);
+  } catch {
+    return "missing";
+  }
+  const stripped = md.replace(/^---[\s\S]*?---/m, "");
+  const lines = stripped.split(/\r?\n/);
+  let inOpenQuestions = false;
+  let candidates = 0;
+  for (const l of lines) {
+    if (/^#{1,6}\s/.test(l)) inOpenQuestions = /open questions|preguntas abiertas/i.test(l);
+    else if (!inOpenQuestions && /^\s*(?:[-*]\s+|\|)/.test(l)) candidates += 1;
+  }
+  return candidates > 0 ? "has-candidates" : "empty";
+}
+function workItemsSignal(dir) {
+  const wis = discoverWorkItems(dir);
+  if (wis.length === 0) return "none";
+  if (wis.some((w) => w.lifecycle === "in-progress")) return "in-progress";
+  if (wis.some((w) => w.lifecycle === "ready")) return "ready";
+  return "none-ready";
+}
+function installedAdapters(dir) {
+  return buildAdapterStatuses(dir).filter(
+    (s) => s.state === "injected" || s.state === "legacy-injected" || s.state === "full-generated" && (s.originAdapter === s.id || s.originAdapter === null)
+  ).map((s) => s.id);
+}
+function buildOnboardingReport(dir, now = /* @__PURE__ */ new Date()) {
+  const config = loadConfig(dir);
+  const ts = now.toISOString();
+  const notReady = (status2, label, command) => ({
+    generated_at: ts,
+    project_name: config?.project.name ?? "unknown",
+    project_type: config?.project.state ?? "unknown",
+    status: status2,
+    signals: {
+      scan: "missing",
+      understand: "missing",
+      current_state: "missing",
+      codebase: "missing",
+      capabilities: "missing",
+      product: "missing",
+      business: "missing",
+      roadmap: "missing",
+      work_items: "none",
+      adapters: [],
+      blocking_open_questions: 0,
+      assumed_questions: 0,
+      resolved_questions: 0,
+      deferred_questions: 0
+    },
+    recommended_next_step: { label, ...command ? { command } : {} }
+  });
+  if (!config) return notReady("not-initialized", "Run `kaddo init` to initialize Kaddo.", "kaddo init");
+  if (config.project.state === "new") return notReady("not-applicable", "This guide is optimized for pre-AI projects. Use the standard new-project Kaddo flow.");
+  if (config.project.state === "legacy") return notReady("legacy-project", "Use the legacy project flow. The onboarding guide targets pre-AI projects.");
+  const scan2 = exists(join(dir, ".kaddo", "scan.json")) ? "available" : "missing";
+  const understand = exists(join(dir, ".kaddo", "understand.md")) ? "available" : "missing";
+  const presence = Object.fromEntries(KNOWLEDGE_FILES.map((f) => [f.key, knowledgePresence(dir, f.path)]));
+  const roadmap = roadmapSignal(dir);
+  const work_items = workItemsSignal(dir);
+  const adapters = installedAdapters(dir);
+  const oq = buildOpenQuestionsReport(dir, now);
+  const signals = {
+    scan: scan2,
+    understand,
+    current_state: presence.current_state,
+    codebase: presence.codebase,
+    capabilities: presence.capabilities,
+    product: presence.product,
+    business: presence.business,
+    roadmap,
+    work_items,
+    adapters,
+    blocking_open_questions: oq.summary.blocking_open,
+    assumed_questions: oq.summary.resolution.assumed,
+    resolved_questions: oq.summary.resolution.resolved,
+    deferred_questions: oq.summary.resolution.deferred
+  };
+  let status;
+  let next;
+  const firstWeak = KNOWLEDGE_FILES.find((f) => presence[f.key] !== "present");
+  if (scan2 === "missing") {
+    status = "initialized";
+    next = { label: "Run `kaddo scan` to capture deterministic signals from the existing code.", command: "kaddo scan" };
+  } else if (understand === "missing") {
+    status = "scanned";
+    next = { label: "Run `kaddo understand` to summarize the project context.", command: "kaddo understand" };
+  } else if (firstWeak) {
+    status = "knowledge-incomplete";
+    next = { label: `Complete \`${firstWeak.label}\` (it is ${presence[firstWeak.key]}).` };
+  } else if (oq.summary.blocking_open > 0) {
+    status = "needs-decisions";
+    next = { label: "Resolve, assume or defer the blocking open questions (`kaddo questions`).", command: "kaddo questions" };
+  } else if (roadmap !== "has-candidates") {
+    status = "ready-for-roadmap";
+    next = { label: "Run `kaddo roadmap` to draft the roadmap from the current knowledge.", command: "kaddo roadmap" };
+  } else if (work_items === "none" || work_items === "none-ready") {
+    status = "ready-for-work-item";
+    next = { label: "Run `kaddo create --from roadmap` to materialize the first Work Item.", command: "kaddo create --from roadmap" };
+  } else {
+    status = "ready-for-implementation";
+    next = adapters.length > 0 ? { label: "Implement the ready Work Item with an installed adapter, then run `kaddo guard`." } : { label: "Install an adapter, then implement the ready Work Item.", command: "kaddo adapters list" };
+  }
+  return { generated_at: ts, project_name: config.project.name, project_type: config.project.state, status, signals, recommended_next_step: next };
+}
+function serializeOnboardingJson(r) {
+  return JSON.stringify(r, null, 2) + "\n";
+}
+function renderOnboardingMarkdown(r) {
+  const s = r.signals;
+  const L = [];
+  L.push("# Pre-AI Onboarding Report", "");
+  L.push("## Summary", "");
+  L.push(`- Project: ${r.project_name}`);
+  L.push(`- Project type: ${r.project_type}`);
+  L.push(`- Status: ${r.status}`);
+  L.push("");
+  if (r.status === "not-initialized" || r.status === "not-applicable" || r.status === "legacy-project") {
+    L.push("## Recommended Next Step", "", r.recommended_next_step.label, "");
+    return L.join("\n");
+  }
+  L.push("## Signals", "");
+  L.push(`- Scan: ${s.scan}`);
+  L.push(`- Understand: ${s.understand}`);
+  L.push(`- Current state: ${s.current_state}`);
+  L.push(`- Codebase: ${s.codebase}`);
+  L.push(`- Capabilities: ${s.capabilities}`);
+  L.push(`- Product: ${s.product}`);
+  L.push(`- Business: ${s.business}`);
+  L.push(`- Roadmap: ${s.roadmap}`);
+  L.push(`- Work Items: ${s.work_items}`);
+  L.push(`- Adapters: ${s.adapters.length > 0 ? s.adapters.join(", ") + " installed" : "none installed"}`);
+  L.push("");
+  L.push("## Questions", "");
+  L.push(`- Blocking open: ${s.blocking_open_questions}`);
+  L.push(`- Assumed: ${s.assumed_questions}`);
+  L.push(`- Resolved: ${s.resolved_questions}`);
+  L.push(`- Deferred: ${s.deferred_questions}`);
+  L.push("");
+  L.push("## Recommended Next Step", "", r.recommended_next_step.label, "");
+  return L.join("\n");
+}
+
+// src/commands/onboarding.ts
+function printConsole(r) {
+  const s = r.signals;
+  console.log("");
+  console.log("Pre-AI Onboarding");
+  console.log("");
+  console.log(`Project: ${r.project_name}`);
+  console.log(`Project type: ${r.project_type}`);
+  console.log("");
+  console.log("Status:");
+  console.log(`  overall: ${r.status}`);
+  if (r.status !== "not-initialized" && r.status !== "not-applicable" && r.status !== "legacy-project") {
+    console.log(`  scan: ${s.scan}`);
+    console.log(`  understand: ${s.understand}`);
+    console.log(`  current-state: ${s.current_state}`);
+    console.log(`  codebase: ${s.codebase}`);
+    console.log(`  capabilities: ${s.capabilities}`);
+    console.log(`  roadmap: ${s.roadmap}`);
+    console.log(`  work-items: ${s.work_items}`);
+    console.log(`  adapters: ${s.adapters.length > 0 ? s.adapters.join(", ") + " installed" : "none installed"}`);
+    console.log(`  blocking open questions: ${s.blocking_open_questions}`);
+    console.log(`  assumptions: ${s.assumed_questions}`);
+    console.log(`  deferred: ${s.deferred_questions}`);
+  }
+  console.log("");
+  console.log("Recommended next step:");
+  console.log(`  ${r.recommended_next_step.label}`);
+}
+function runOnboarding(opts = {}) {
+  const dir = cwd();
+  const report = buildOnboardingReport(dir);
+  if (opts.json) {
+    console.log(serializeOnboardingJson(report));
+    return;
+  }
+  printConsole(report);
+  printCommandFooter("onboarding");
+}
+function runOnboardingReport(opts = {}) {
+  const dir = cwd();
+  const report = buildOnboardingReport(dir);
+  if (report.status === "not-initialized") {
+    console.error("Kaddo is not initialized here. Run `kaddo init` first.");
+    return;
+  }
+  intro2("kaddo report onboarding");
+  const base = ".kaddo/reports";
+  writeFile(join(dir, base, "onboarding-report.md"), renderOnboardingMarkdown(report));
+  writeFile(join(dir, base, "onboarding-report.json"), serializeOnboardingJson(report));
+  log2.success(`Wrote ${base}/onboarding-report.md and ${base}/onboarding-report.json`);
+  log2.info(`Status: ${report.status} \u2014 ${report.recommended_next_step.label}`);
+  printCommandFooter("onboarding");
+  outro2("Onboarding report written.");
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -12938,12 +13175,18 @@ savingsCmd.command("init").description("Create an editable `.kaddo/savings.yml`
 reportCmd.command("drift").description("Drift Trend Report from recorded guard history (deterministic, no LLM)").option("--json", "Output JSON instead of Markdown").option("--output <path>", "Write the report to a file (e.g. .kaddo/reports/drift-report.md)").action((opts) => {
   runDrift(opts);
 });
+reportCmd.command("onboarding").description("Write the pre-AI onboarding report to .kaddo/reports/ (deterministic, no LLM)").action(() => {
+  runOnboardingReport();
+});
 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);
+program.command("onboarding").alias("onboard").description("Diagnose a pre-AI project and recommend the next step (read-only)").option("--json", "Output JSON").action((opts) => {
+  runOnboarding(opts);
+});
 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/opencode/antigravity/kiro \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);

package/package.json

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