karajan-code 2.7.3 → 2.8.0

package/src/cli/register-meta.js

@@ -0,0 +1,204 @@
+import { discoverCommand } from "../commands/discover.js";
+import { triageCommand } from "../commands/triage.js";
+import { researcherCommand } from "../commands/researcher.js";
+import { architectCommand } from "../commands/architect.js";
+import { auditCommand } from "../commands/audit.js";
+import { resumeCommand } from "../commands/resume.js";
+import { boardCommand } from "../commands/board.js";
+import { undoCommand } from "../commands/undo.js";
+import { syncCommand } from "../commands/sync.js";
+import { cleanCommand } from "../commands/clean.js";
+import { withConfig } from "./_shared.js";
+
+/**
+ * Register the "meta" / single-role / housekeeping commands: pre-pipeline
+ * analysis (discover, triage, researcher, architect, audit), session
+ * management (resume, board, undo) and maintenance (update, sync, clean).
+ *
+ * Note: `triage` lives here (not in pipeline) because it's a single-role
+ * analysis command in the same family as discover / researcher /
+ * architect / audit, none of which run the full agent loop.
+ */
+export function registerMeta(program, { pkgVersion }) {
+  program
+    .command("discover")
+    .description("Analyze task for gaps, ambiguities and missing info")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--mode <name>", "Discovery mode: gaps|momtest|wendel|classify|jtbd", "gaps")
+    .option("--discover <name>", "Override discover agent")
+    .option("--discover-model <name>", "Override discover model")
+    .option("--json", "Output raw JSON")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "discover", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await discoverCommand({ task: resolvedTask, config, logger, mode: flags.mode, json: flags.json });
+      });
+    });
+
+  program
+    .command("triage")
+    .description("Classify task complexity and recommend pipeline roles")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--triage <name>", "Override triage agent")
+    .option("--triage-model <name>", "Override triage model")
+    .option("--json", "Output raw JSON")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "triage", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await triageCommand({ task: resolvedTask, config, logger, json: flags.json });
+      });
+    });
+
+  program
+    .command("researcher")
+    .description("Research codebase for a task (files, patterns, constraints)")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--researcher <name>", "Override researcher agent")
+    .option("--researcher-model <name>", "Override researcher model")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "researcher", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await researcherCommand({ task: resolvedTask, config, logger });
+      });
+    });
+
+  program
+    .command("architect")
+    .description("Design solution architecture (layers, patterns, contracts)")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--architect <name>", "Override architect agent")
+    .option("--architect-model <name>", "Override architect model")
+    .option("--context <text>", "Additional context (e.g. researcher output)")
+    .option("--json", "Output raw JSON")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "architect", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await architectCommand({ task: resolvedTask, config, logger, context: flags.context, json: flags.json });
+      });
+    });
+
+  program
+    .command("audit")
+    .description("Analyze codebase health (read-only)")
+    .argument("[task]", "Task description. If absent, defaults to a full-codebase analysis. Use --task-file to point at a .md.")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--dimensions <list>", "Comma-separated: security,quality,performance,architecture,testing", "all")
+    .option("--json", "Output raw JSON")
+    .option("--agent-readiness", "Score the repo for AI-agent readability (llms.txt, SKILL.md coverage, page token budgets, robots allowlist, heading hierarchy). LLM-free; uses [path] or cwd as the audit target. See issue #542.")
+    .option("--path <dir>", "Path to audit (used with --agent-readiness; defaults to cwd)")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "audit", flags, async ({ config, logger }) => {
+        let resolvedTask = task;
+        if (flags.taskFile) {
+          const { readTaskFile } = await import("../utils/task-file.js");
+          resolvedTask = await readTaskFile(flags.taskFile, { projectDir: config.projectDir });
+        }
+        await auditCommand({
+          task: resolvedTask || "Analyze the full codebase",
+          config, logger,
+          dimensions: flags.dimensions, json: flags.json,
+          agentReadiness: Boolean(flags.agentReadiness),
+          path: flags.path,
+        });
+      });
+    });
+
+  program
+    .command("resume")
+    .description("Resume a paused session")
+    .argument("<sessionId>")
+    .option("--answer <text>", "Answer to the question that caused the pause")
+    .option("--json", "Output JSON only")
+    .action(async (sessionId, flags) => {
+      await withConfig(pkgVersion, "resume", flags, async ({ config, logger }) => {
+        await resumeCommand({ sessionId, answer: flags.answer, config, logger, flags });
+      });
+    });
+
+  program
+    .command("update")
+    .description("Update karajan-code to the latest version from npm")
+    .action(async () => {
+      // Audit follow-up: was execaCommand (shell parsing). Inputs are
+      // constants today, but the project standard since #555 is execa
+      // with arg arrays (no shell). Migrated for consistency.
+      const { execa } = await import("execa");
+      console.log(`Current version: ${pkgVersion}`);
+      console.log("Checking for updates...");
+      try {
+        const { stdout } = await execa("npm", ["view", "karajan-code", "version"]);
+        const latest = stdout.trim();
+        if (latest === pkgVersion) {
+          console.log(`Already on the latest version (${pkgVersion}).`);
+          return;
+        }
+        console.log(`Updating ${pkgVersion} → ${latest}...`);
+        await execa("npm", ["install", "-g", "karajan-code@latest"], { stdio: "inherit" });
+        console.log(`Updated to ${latest}. Restart Claude to pick up the new MCP server.`);
+      } catch (err) {
+        console.error(`Update failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("board [action]")
+    .description("Manage HU Board (start|stop|status|open)")
+    .option("--port <number>", "Port (default: 4000)", "4000")
+    .action(async (action = "start", opts) => {
+      await withConfig(pkgVersion, "board", opts, async ({ config, logger }) => {
+        const port = Number(opts.port) || config.hu_board?.port || 4000;
+        await boardCommand({ action, port, logger });
+      });
+    });
+
+  program
+    .command("undo")
+    .description("Revert last pipeline run")
+    .option("--hard", "Discard all changes (default: soft reset, keeps changes staged)")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "undo", flags, async ({ logger }) => {
+        const result = await undoCommand({ hard: !!flags.hard, logger });
+        if (!result.ok) process.exit(1);
+      });
+    });
+
+  program
+    .command("sync")
+    .description("Detect drift between code and the latest plan. Read-only report (issue #540 MVP).")
+    .option("--plan <planId>", "Sync against a specific plan instead of the latest")
+    .option("--json", "Emit machine-readable JSON instead of human output")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "sync", flags, async ({ config, logger }) => {
+        await syncCommand({ config, logger, planId: flags.plan, json: flags.json });
+      });
+    });
+
+  program
+    .command("clean")
+    .description("Garbage-collect stale plans, sessions and HU batches (dry-run by default)")
+    .option("--yes", "Actually delete — without this flag, only prints what would be removed")
+    .option("--nuke", "Retention=0 everywhere + wipe HU board DB. \"I want it all gone\"")
+    .option("--plan-days <n>", "Keep finalised plans (approved/rejected/executed) for N days (default: 30)")
+    .option("--draft-days <n>", "Keep draft plans for N days (default: 60)")
+    .option("--session-days <n>", "Keep finalised sessions for N days (default: 7)")
+    .option("--hu-days <n>", "Keep HU story batches for N days (default: 14)")
+    .action(async (flags) => {
+      await cleanCommand({
+        yes: Boolean(flags.yes),
+        nuke: Boolean(flags.nuke),
+        planDays: flags.planDays ? Number(flags.planDays) : undefined,
+        draftDays: flags.draftDays ? Number(flags.draftDays) : undefined,
+        sessionDays: flags.sessionDays ? Number(flags.sessionDays) : undefined,
+        huDays: flags.huDays ? Number(flags.huDays) : undefined,
+      });
+    });
+}

package/src/cli/register-pipeline.js

@@ -0,0 +1,212 @@
+import { initCommand } from "../commands/init.js";
+import { configCommand } from "../commands/config.js";
+import { codeCommand } from "../commands/code.js";
+import { reviewCommand } from "../commands/review.js";
+import { scanCommand } from "../commands/scan.js";
+import { doctorCommand } from "../commands/doctor.js";
+import { reportCommand } from "../commands/report.js";
+import { runCommandHandler } from "../commands/run.js";
+import { statusCommand } from "../commands/status.js";
+import { loadPlan } from "../plan/plan-store.js";
+import { withConfig } from "./_shared.js";
+
+/**
+ * Register the "core pipeline" commands: everything the user runs day-to-day
+ * to drive the agent loop or inspect its output. Kept together so the
+ * shape of the run/code/review trio (and the scan/report/doctor helpers
+ * that frame them) lives in one file.
+ */
+export function registerPipeline(program, { pkgVersion }) {
+  program
+    .command("init")
+    .description("Initialize config, review rules and SonarQube")
+    .option("--no-interactive", "Skip wizard, use defaults (for CI/scripts)")
+    .option("--scaffold-ci", "Scaffold Karajan CI Gateway workflow files")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "init", flags, async ({ config: _config, logger }) => {
+        await initCommand({ logger, flags });
+      });
+    });
+
+  program
+    .command("config")
+    .description("Show current config")
+    .option("--json", "Show as JSON")
+    .option("--edit", "Open config in $EDITOR for editing")
+    .action(async (flags) => {
+      await configCommand(flags);
+    });
+
+  program
+    .command("run")
+    .description("Run coder+sonar+reviewer loop")
+    .argument("[task]", "Task description (or use --task-file to read from a .md file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md). Alternative to the positional task argument.")
+    .option("-y, --yes", "Skip the cwd confirmation prompt (CI / scripted runs).")
+    .option("--planner <name>")
+    .option("--coder <name>")
+    .option("--reviewer <name>")
+    .option("--refactorer <name>")
+    .option("--planner-model <name>")
+    .option("--coder-model <name>")
+    .option("--reviewer-model <name>")
+    .option("--refactorer-model <name>")
+    .option("--enable-planner")
+    .option("--enable-reviewer")
+    .option("--enable-refactorer")
+    .option("--enable-researcher")
+    .option("--enable-tester")
+    .option("--enable-security")
+    .option("--enable-impeccable")
+    .option("--enable-triage")
+    .option("--enable-discover")
+    .option("--enable-architect")
+    .option("--plan <planId>", "Plan ID from kj plan. Loads persisted plan context and skips researcher/architect/planner.")
+    // PR4: launch a single HU (or comma-separated list) instead of the
+    // entire plan. The board uses this for the per-HU ▶ button so the
+    // user can re-run only a failed HU without restarting the whole
+    // plan. Requires --plan to also be set.
+    .option("--hu <huIds>", "Comma-separated HU IDs to run. When set, the plan's other HUs are skipped. Requires --plan.")
+    .option("--enable-hu-reviewer")
+    .option("--hu-file <path>", "YAML file with HU stories to certify before coding")
+    .option("--enable-serena")
+    .option("--mode <name>")
+    .option("--max-iterations <n>")
+    .option("--max-iteration-minutes <n>")
+    .option("--max-total-minutes <n>")
+    .option("--base-branch <name>")
+    .option("--base-ref <ref>")
+    .option("--coder-fallback <name>")
+    .option("--reviewer-fallback <name>")
+    .option("--reviewer-retries <n>")
+    .option("--auto-commit")
+    .option("--auto-push")
+    .option("--auto-pr")
+    .option("--enable-ci", "Enable Karajan CI (early PR + dispatch comments/reviews)")
+    .option("--branch-prefix <prefix>")
+    .option("--task-type <type>", "Explicit task type: sw, infra, doc, add-tests, refactor")
+    .option("--methodology <name>")
+    .option("--no-auto-rebase")
+    .option("--no-sonar")
+    .option("--enable-sonarcloud", "Enable SonarCloud scan (complementary to SonarQube)")
+    .option("--no-sonarcloud")
+    .option("--checkpoint-interval <n>", "Minutes between interactive checkpoints (default: 5)")
+    .option("--pg-task <cardId>", "Planning Game card ID (e.g., KJC-TSK-0042)")
+    .option("--pg-project <projectId>", "Planning Game project ID")
+    .option("--auto-simplify", "Auto-simplify pipeline for simple tasks (disable reviewer/tester)")
+    .option("--no-auto-simplify", "Force full pipeline regardless of triage level")
+    .option("--smart-models", "Enable smart model selection based on triage complexity")
+    .option("--no-smart-models", "Disable smart model selection")
+    .option("--design", "Activate design refactoring mode (impeccable role applies design changes)")
+    .option("--domain <text-or-path>", "Domain knowledge: inline text or path to .md file")
+    .option("--skills-mode <mode>", "Skill detection mode: auto|regex|semantic|none (default: auto)")
+    .option("--brain <mode>", "Brain decisor: on|off (default: on). When off, only legacy flags drive routing.")
+    .option("--skip-role <role...>", "Force one or more roles OFF regardless of triage (e.g. --skip-role tester security)")
+    .option("--force-role <role...>", "Force one or more roles ON regardless of triage")
+    .option("--dry-run", "Show what would be executed without running anything")
+    .option("--json", "Output JSON only (no styled display)")
+    .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")
+    .option("-v, --verbose", "Show full agent output (stream-json, raw lines)")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "run", flags, async ({ config, logger }) => {
+        // If `--plan <id>` was passed and the user didn't provide a task
+        // argument or --task-file, fall back to the task embedded in the
+        // plan JSON. The whole point of `kj plan generate` is that the
+        // task is captured once and re-used; forcing the user to repeat
+        // --task-file on every run is friction with no upside.
+        let effectiveTask = task;
+        if (!task && !flags.taskFile && flags.plan) {
+          // config.projectDir is only populated post-init; before runFlow
+          // it can still be undefined. Plans are stored under cwd, so
+          // that's the correct fallback for the lookup.
+          const projectDir = config.projectDir || process.cwd();
+          const plan = await loadPlan(projectDir, flags.plan);
+          if (plan?.task && String(plan.task).trim()) {
+            effectiveTask = plan.task;
+          }
+        }
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task: effectiveTask, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await runCommandHandler({ task: resolvedTask, config, logger, flags });
+      });
+    });
+
+  program
+    .command("code")
+    .description("Run only coder")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--coder <name>")
+    .option("--coder-model <name>")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "code", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await codeCommand({ task: resolvedTask, config, logger });
+      });
+    });
+
+  program
+    .command("review")
+    .description("Run only reviewer")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--reviewer <name>")
+    .option("--reviewer-model <name>")
+    .option("--base-ref <ref>")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "review", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await reviewCommand({ task: resolvedTask, config, logger, baseRef: flags.baseRef });
+      });
+    });
+
+  program
+    .command("scan")
+    .description("Run SonarQube scan")
+    .action(async () => {
+      await withConfig(pkgVersion, "scan", {}, scanCommand);
+    });
+
+  program
+    .command("doctor")
+    .description("Check environment requirements and auto-remediate when possible")
+    .option("--check-only", "Detect issues without applying fixes")
+    .option("-y, --yes", "Auto-confirm prompts for invasive remediations (CI mode)")
+    .option("--json", "Emit machine-readable JSON instead of human output")
+    .option("--verbose", "Include fix hints and timing for every check")
+    .action(async (flags) => {
+      const exitCode = await withConfig(pkgVersion, "doctor", {}, (ctx) =>
+        doctorCommand({
+          ...ctx,
+          checkOnly: !!flags.checkOnly,
+          yes: !!flags.yes,
+          json: !!flags.json,
+          verbose: !!flags.verbose,
+        })
+      );
+      if (Number.isInteger(exitCode)) process.exit(exitCode);
+    });
+
+  program
+    .command("status")
+    .description("Show pipeline dashboard with HU progress")
+    .option("-n, --lines <n>", "Max log lines to read", "50")
+    .action(async (flags) => {
+      await statusCommand({ lines: Number(flags.lines) });
+    });
+
+  program
+    .command("report")
+    .description("Show latest session report")
+    .option("--list", "List session ids")
+    .option("--session-id <id>", "Show report for a specific session ID")
+    .option("--format <type>", "Output format: text|json", "text")
+    .option("--trace", "Show chronological trace of all pipeline stages")
+    .option("--currency <code>", "Display costs in currency: usd|eur", "usd")
+    .option("--pg-task <cardId>", "Filter reports by Planning Game card ID")
+    .action(async (flags) => {
+      await reportCommand(flags);
+    });
+}

package/src/cli/register-plan.js

@@ -0,0 +1,152 @@
+import {
+  planGenerateCommand,
+  planListCommand,
+  planShowCommand,
+  planReadyCommand,
+  planValidateCommand,
+  planDeleteCommand,
+  planAddHuCommand,
+  planRemoveHuCommand,
+} from "../commands/plan.js";
+import { parseCanvasMarkdown } from "../canvas/parse-md.js";
+import { validateCanvas } from "../canvas/validate.js";
+import { canvasToTask } from "../canvas/to-flat.js";
+import { withConfig } from "./_shared.js";
+
+/**
+ * Register the `plan` parent command and every sub-command that lives
+ * under it (generate / list / show / ready / validate / delete /
+ * add-hu / remove-hu). Centralising plan management here keeps the
+ * REASONS Canvas auto-detection logic in one file alongside the
+ * planner entrypoint.
+ */
+export function registerPlan(program, { pkgVersion }) {
+  const plan = program.command("plan").description("Plan management (generate, review, approve, execute)");
+
+  plan
+    .command("generate", { isDefault: true })
+    .description("Generate implementation plan with HUs")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--planner <name>")
+    .option("--planner-model <name>")
+    .option("--context <text>", "Additional context for the planner")
+    .option("--json", "Output raw JSON plan")
+    // Tests-first quality knobs (v2.7.5). Default is "thorough":
+    // when the planner skips acceptance_tests on some HUs, run a
+    // focused synthesizer pass to fill them in. Disable with these
+    // flags only if you explicitly want a fast / sketch plan.
+    .option("--no-tests-synth", "Skip the tests-synthesizer pass that fills in missing acceptance_tests")
+    .option("--no-plan-review", "Skip the high-level plan reviewer pass (gaps / deps / overlap / order)")
+    .option("--quick", "Sketch mode — skip every quality pass after the initial planner call")
+    .option("-y, --yes", "Skip the project-name prompt (use the auto-derived default).")
+    .option("--no-interactive", "Force non-interactive mode (no prompts, use defaults).")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "plan", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+
+        // REASONS Canvas auto-detection: a SPEC that contains
+        // `## REASONS:Section` headings is treated as a structured
+        // Canvas — parsed + validated BEFORE the planner runs. This
+        // catches broken acceptance tests (jq syntax, bash parse,
+        // gherkin missing Given/Then, the 2026-04-29 as-binding
+        // misuse class) at plan-time, without spending LLM dollars.
+        //
+        // Detection by file CONTENTS, not by CLI flag — the Canvas
+        // format is the signal. Flat SPECs without REASONS sections
+        // continue through the legacy path unchanged (back-compat).
+        if (typeof resolvedTask === "string" && /^##\s+REASONS:/m.test(resolvedTask)) {
+          let parsed;
+          try {
+            parsed = parseCanvasMarkdown(resolvedTask);
+          } catch (err) {
+            throw new Error(`Canvas parse error: ${err.message}`, { cause: err });
+          }
+          const validation = validateCanvas(parsed);
+          if (!validation.valid) {
+            const lines = ["Canvas validation failed."];
+            if (validation.schemaIssues) {
+              lines.push("Schema issues:");
+              for (const issue of validation.schemaIssues) {
+                lines.push(`  - ${issue.path?.map((p) => p.key).join(".") || "(root)"}: ${issue.message}`);
+              }
+            }
+            if (validation.testIssues) {
+              lines.push("Acceptance test issues:");
+              for (const issue of validation.testIssues) {
+                lines.push(`  - Operation #${issue.operationIndex + 1} "${issue.operationTitle}", test #${issue.testIndex + 1} (${issue.type}, ${issue.kind}):`);
+                lines.push(`      ${issue.content}`);
+                lines.push(`      → ${issue.error}`);
+              }
+            }
+            throw new Error(lines.join("\n"));
+          }
+          // Pass the Canvas-derived flat task to the existing planner.
+          // Norms + Safeguards ride along under explicit headings the
+          // coder prompt can grep for.
+          const taskFromCanvas = canvasToTask(validation.canvas);
+          await planGenerateCommand({ task: taskFromCanvas, config, logger, flags });
+          return;
+        }
+        await planGenerateCommand({
+          task: resolvedTask, config, logger, json: flags.json, context: flags.context,
+          flags: {
+            noTestsSynth: flags.testsSynth === false,
+            noPlanReview: flags.planReview === false,
+            quick: Boolean(flags.quick),
+            yes: Boolean(flags.yes),
+            interactive: flags.interactive,
+          },
+        });
+      });
+    });
+
+  plan.command("list").description("List all plans").action(async (flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      // TSK-0340: was `await import(...)` — now served by the top-level static import.
+      await planListCommand({ config });
+    });
+  });
+
+  plan.command("show").description("Show plan details + HUs").argument("<planId>").action(async (planId, flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      await planShowCommand({ config, planId });
+    });
+  });
+
+  plan.command("ready").description("Approve plan — certify all HUs").argument("<planId>").action(async (planId, flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      await planReadyCommand({ config, planId });
+    });
+  });
+
+  plan.command("validate").description("Validate plan structure").argument("<planId>").action(async (planId, flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      await planValidateCommand({ config, planId });
+    });
+  });
+
+  plan.command("delete").description("Delete a plan").argument("<planId>").action(async (planId, flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      await planDeleteCommand({ config, planId });
+    });
+  });
+
+  plan.command("add-hu").description("Add HU to plan").argument("<planId>")
+    .option("--title <text>", "HU title")
+    .option("--type <type>", "Task type: sw|infra|doc|add-tests|refactor|nocode", "sw")
+    .option("--deps <ids>", "Comma-separated HU IDs this depends on")
+    .option("--scope <text>", "Scope description")
+    .action(async (planId, flags) => {
+      await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+        await planAddHuCommand({ config, planId, title: flags.title, type: flags.type, deps: flags.deps, scope: flags.scope });
+      });
+    });
+
+  plan.command("remove-hu").description("Remove HU from plan").argument("<planId>").argument("<huId>").action(async (planId, huId, flags) => {
+    await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+      await planRemoveHuCommand({ config, planId, huId });
+    });
+  });
+}

package/src/cli/register-roles-skills.js

@@ -0,0 +1,38 @@
+import { rolesCommand } from "../commands/roles.js";
+import { agentsCommand } from "../commands/agents.js";
+import { withConfig } from "./_shared.js";
+
+/**
+ * Register the meta-configuration commands the user reaches for when
+ * setting up the pipeline itself: which skills to load, which roles
+ * are wired in, which provider is mapped to each agent slot.
+ */
+export function registerRolesSkills(program, { pkgVersion }) {
+  program
+    .command("skills [action]")
+    .description("Manage the skill cache (actions: list | clear-cache | sync-addyosmani | list-addyosmani)")
+    .action(async (action) => {
+      const { skillsCommand } = await import("../commands/skills.js");
+      const exitCode = await skillsCommand({ action: action || "list" });
+      if (Number.isInteger(exitCode)) process.exit(exitCode);
+    });
+
+  program
+    .command("roles [subcommand] [role]")
+    .description("List pipeline roles or show role template instructions")
+    .action(async (subcommand, role) => {
+      await withConfig(pkgVersion, "roles", {}, async ({ config }) => {
+        await rolesCommand({ config, subcommand: subcommand || "list", roleName: role });
+      });
+    });
+
+  program
+    .command("agents [subcommand] [role] [provider]")
+    .description("List or change AI agent assignments per role (e.g. kj agents set coder gemini)")
+    .option("--global", "Persist change to kj.config.yml (default for CLI)")
+    .action(async (subcommand, role, provider, flags) => {
+      await withConfig(pkgVersion, "agents", {}, async ({ config }) => {
+        await agentsCommand({ config, subcommand: subcommand || "list", role, provider, global: flags.global });
+      });
+    });
+}

package/src/cli/register-sonar.js

@@ -0,0 +1,28 @@
+import { sonarCommand, sonarOpenCommand } from "../commands/sonar.js";
+import { loadConfig } from "../config.js";
+
+/**
+ * Register the `sonar` parent command and its sub-actions
+ * (status / start / stop / logs / open). Kept in its own module
+ * because every sub-command shares the same one-liner shape and
+ * the only one that needs config is `open`.
+ */
+export function registerSonar(program) {
+  const sonar = program.command("sonar").description("Manage SonarQube container");
+  sonar.command("status").action(async () => sonarCommand({ action: "status" }));
+  sonar.command("start").action(async () => sonarCommand({ action: "start" }));
+  sonar.command("stop").action(async () => sonarCommand({ action: "stop" }));
+  sonar.command("logs").action(async () => sonarCommand({ action: "logs" }));
+  sonar
+    .command("open")
+    .description("Open SonarQube dashboard in the browser")
+    .action(async () => {
+      const { config } = await loadConfig();
+      const result = await sonarOpenCommand({ config });
+      if (!result.ok) {
+        console.error(result.error);
+        process.exit(1);
+      }
+      console.log(`Opened ${result.url}`);
+    });
+}