@popoverai/dotrequirements 0.24.2 → 0.24.3

package/dist/codebase-to-spec/skill-install.js

@@ -1,21 +1,23 @@
 /**
  * Skill installation logic for the codebase-to-spec skill.
  *
- * The skill is a thin conversational wrapper around `dotrequirements cts run`.
- * It ships as a SKILL.md template bundled in the CLI package, and this module
- * copies it into the host's skill directory (default: `.claude/skills/` for
- * Claude Code).
+ * Ships as a bundle: SKILL.md + cts-worker agent definition + persona-
+ * injection hook script + hook registration in `.claude/settings.local.json`.
+ * The skill body (the conversational orchestrator) DEPENDS on the companion
+ * files — installing just the skill without them would leave Task dispatches
+ * unable to resolve their persona. For `project` scope, all four pieces are
+ * installed in one shot. For `global` and `custom` scopes, only the skill
+ * body is installed; the companions are project-scoped by CC convention.
  *
  * Host portability (CTS-SKILL-5): the install logic supports any host that
  * follows the Agent Skills format. The default target is Claude Code's
  * convention; `--target-dir` lets users place the skill anywhere.
  *
  * Requirements covered:
- * - CTS-SKILL-1: skill artifact exists and points users at `dotrequirements cts run`
- * - CTS-SKILL-5: install logic is host-agnostic and works on any host with
- *   Agent Skills format support
+ * - CTS-SKILL-1, CTS-SKILL-5
+ * - CTSO-CLI-1 (bundles the agent + hook that PreToolUse-injects persona bodies)
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { loadTemplate } from "../utils/templates.js";
@@ -49,31 +51,130 @@ export function loadSkillTemplate() {
     return loadTemplate("skills/codebase-to-spec/SKILL.md");
 }
 /**
- * Install (or refuse to overwrite) the codebase-to-spec SKILL.md at the
- * resolved location.
+ * Load the bundled cts-worker agent definition template.
+ */
+export function loadAgentTemplate() {
+    return loadTemplate("agents/cts-worker.md");
+}
+/**
+ * Load the bundled persona-injection hook script template.
+ */
+export function loadHookTemplate() {
+    return loadTemplate("hooks/cts-worker-persona.sh");
+}
+/**
+ * Install (or refuse to overwrite) one template file at a target path.
+ * Returns true if a write happened.
+ */
+function installTemplateFile(templateContent, targetPath, overwrite, description) {
+    const exists = existsSync(targetPath);
+    if (exists && !overwrite) {
+        const onDisk = readFileSync(targetPath, "utf-8");
+        if (onDisk === templateContent) {
+            return { installed: false, overwrote: false };
+        }
+        throw new Error(`${description} already exists at ${targetPath} and differs from the bundled template. Pass --overwrite to replace it, or delete the file first.`);
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, templateContent, "utf-8");
+    return { installed: true, overwrote: exists };
+}
+/**
+ * Register the cts-worker-persona PreToolUse hook in the project's
+ * `.claude/settings.local.json`, preserving any existing keys.
+ *
+ * Returns true if the hook registration was added or updated.
+ */
+function registerHookInSettings(projectRoot, hookScriptPath) {
+    const settingsPath = join(projectRoot, ".claude", "settings.local.json");
+    const hookEntry = {
+        matcher: "Task",
+        hooks: [{ type: "command", command: hookScriptPath }],
+    };
+    // Read existing settings if present.
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            const content = readFileSync(settingsPath, "utf-8");
+            if (content.trim()) {
+                settings = JSON.parse(content);
+            }
+        }
+        catch {
+            // Invalid JSON — refuse to clobber. Tell caller to fix manually.
+            throw new Error(`Existing ${settingsPath} contains invalid JSON. Fix it or delete it before installing the orchestrator hook.`);
+        }
+    }
+    // Initialize the hooks tree if missing.
+    // biome-ignore lint/suspicious/noExplicitAny: settings.local.json is user-owned; we narrow ad-hoc.
+    const hooks = (settings.hooks ?? {});
+    const preToolUse = (hooks.PreToolUse ?? []);
+    // Check if an entry already references our hook script (idempotent).
+    const alreadyRegistered = preToolUse.some((entry) => {
+        if (entry.matcher !== "Task")
+            return false;
+        const innerHooks = entry.hooks;
+        if (!Array.isArray(innerHooks))
+            return false;
+        return innerHooks.some((h) => h.command === hookScriptPath);
+    });
+    if (alreadyRegistered) {
+        return { settingsPath, registered: false };
+    }
+    preToolUse.push(hookEntry);
+    hooks.PreToolUse = preToolUse;
+    settings.hooks = hooks;
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+    return { settingsPath, registered: true };
+}
+/**
+ * Install (or refuse to overwrite) the codebase-to-spec skill bundle.
+ *
+ * For `project` scope: installs skill body, cts-worker agent, persona hook
+ * script, and registers the hook in settings.local.json.
+ *
+ * For `global` and `custom` scopes: installs only the skill body.
  */
 export function installSkill(options = {}) {
     const skillDir = resolveSkillDir(options);
     const skillPath = join(skillDir, "SKILL.md");
-    const template = loadSkillTemplate();
-    const exists = existsSync(skillPath);
-    if (exists && !options.overwrite) {
-        // Idempotent no-op: if the on-disk content already matches the template,
-        // there's nothing to do and we shouldn't surface that as a conflict.
-        const onDisk = readFileSync(skillPath, "utf-8");
-        if (onDisk === template) {
-            return { installedPath: skillPath, installed: false, overwrote: false };
-        }
-        // Stale or hand-edited copy: refuse without --overwrite so we don't
-        // silently clobber user changes.
-        throw new Error(`SKILL.md already exists at ${skillPath} and differs from the bundled template. Pass --overwrite to replace it, or delete the file first.`);
+    const skillTemplate = loadSkillTemplate();
+    const skillResult = installTemplateFile(skillTemplate, skillPath, options.overwrite === true, "SKILL.md");
+    // Skill body only for global/custom scopes — CC reads agents and hooks
+    // per-project, so the companions don't make sense outside a project.
+    const scope = options.scope ?? "project";
+    if (scope !== "project") {
+        return {
+            installedPath: skillPath,
+            installed: skillResult.installed,
+            overwrote: skillResult.overwrote,
+        };
     }
-    mkdirSync(dirname(skillPath), { recursive: true });
-    writeFileSync(skillPath, template, "utf-8");
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const agentPath = join(projectRoot, ".claude", "agents", "cts-worker.md");
+    const hookScriptPath = join(projectRoot, ".claude", "hooks", "cts-worker-persona.sh");
+    // Install the cts-worker agent definition.
+    installTemplateFile(loadAgentTemplate(), agentPath, options.overwrite === true, "cts-worker agent definition");
+    // Install the persona-injection hook script (executable bit set separately).
+    installTemplateFile(loadHookTemplate(), hookScriptPath, options.overwrite === true, "cts-worker-persona hook script");
+    // chmod the hook script to be executable so Claude Code's PreToolUse
+    // hook can invoke it. (Imported statically — the CLI package is ESM, so
+    // `require("node:fs")` here would throw ReferenceError and silently
+    // leave the script at 0644, breaking the hook on every install.)
+    chmodSync(hookScriptPath, 0o755);
+    // Register the hook in settings.local.json.
+    const { settingsPath, registered } = registerHookInSettings(projectRoot, hookScriptPath);
     return {
         installedPath: skillPath,
-        installed: true,
-        overwrote: exists,
+        installed: skillResult.installed,
+        overwrote: skillResult.overwrote,
+        companions: {
+            agentPath,
+            hookScriptPath,
+            settingsPath,
+            hookRegistered: registered,
+        },
     };
 }
 //# sourceMappingURL=skill-install.js.map

package/dist/commands/codebase-to-spec/compose-orchestrator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `dotrequirements codebase-to-spec compose-orchestrator` subcommand.
+ *
+ * Conversational-orchestrator variant of `compose`. Reads outline.yaml
+ * (must be approved) + per-area partials, writes the composed spec to
+ * .dotrequirements-cache/spec-composed.md. Wraps the legacy `runCompose`
+ * by adapting outline.yaml to the legacy Outline shape.
+ *
+ * Requirements covered:
+ * - CTS-COMPOSE-1, CTS-COMPOSE-2 (reuses the legacy compose logic)
+ * - CTSO-INTEG-1: orchestrator uses existing deterministic stages unchanged
+ */
+export declare function composeOrchestratorCommand(): Promise<void>;
+//# sourceMappingURL=compose-orchestrator.d.ts.map

package/dist/commands/codebase-to-spec/compose-orchestrator.js

@@ -0,0 +1,54 @@
+/**
+ * `dotrequirements codebase-to-spec compose-orchestrator` subcommand.
+ *
+ * Conversational-orchestrator variant of `compose`. Reads outline.yaml
+ * (must be approved) + per-area partials, writes the composed spec to
+ * .dotrequirements-cache/spec-composed.md. Wraps the legacy `runCompose`
+ * by adapting outline.yaml to the legacy Outline shape.
+ *
+ * Requirements covered:
+ * - CTS-COMPOSE-1, CTS-COMPOSE-2 (reuses the legacy compose logic)
+ * - CTSO-INTEG-1: orchestrator uses existing deterministic stages unchanged
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { cachePaths } from "../../codebase-to-spec/cache.js";
+import { runCompose } from "../../codebase-to-spec/compose.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { conversationalOutlineToLegacy, parseConversationalOutline, } from "../../codebase-to-spec/schemas.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+export async function composeOrchestratorCommand() {
+    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline)) {
+        process.stderr.write(`No outline.yaml found at ${paths.outline}. Run the orchestrator's planner first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch (err) {
+        process.stderr.write(`Outline at ${paths.outline} is invalid: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (!outline.review || outline.review.result !== "approved") {
+        process.stderr.write(`Outline at ${paths.outline} is not approved (review.result is "${outline.review?.result ?? "absent"}"). Approve the outline before composing.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const legacyOutline = conversationalOutlineToLegacy(outline);
+    const result = runCompose({
+        outline: legacyOutline,
+        partialPathFor: (sanitized) => paths.partial(sanitized),
+        composedPath: paths.composedSpec,
+    });
+    process.stdout.write(`Composed spec → ${result.composedPath} (${result.partialsIncluded} partials included, ${result.partialsMissing} missing)\n`);
+    if (result.validationError) {
+        process.stderr.write(`Composed spec failed validation:\n${result.validationError}\n`);
+        process.exitCode = ExitCode.StageFailed;
+        return;
+    }
+}
+//# sourceMappingURL=compose-orchestrator.js.map

package/dist/commands/codebase-to-spec/dispatch-context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-context <dispatch-id>` subcommand.
+ *
+ * Returns the composed prompt for a worker dispatch as a JSON object on stdout.
+ * Called by the cts-worker PreToolUse hook to compose the subagent's first-turn
+ * prompt via `modifiedInput`.
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ */
+export declare function dispatchContextCommand(dispatchId: string): Promise<void>;
+//# sourceMappingURL=dispatch-context.d.ts.map

package/dist/commands/codebase-to-spec/dispatch-context.js

@@ -0,0 +1,22 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-context <dispatch-id>` subcommand.
+ *
+ * Returns the composed prompt for a worker dispatch as a JSON object on stdout.
+ * Called by the cts-worker PreToolUse hook to compose the subagent's first-turn
+ * prompt via `modifiedInput`.
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ */
+import { composeDispatchContext } from "../../codebase-to-spec/dispatch.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+export async function dispatchContextCommand(dispatchId) {
+    const ctx = composeDispatchContext(dispatchId);
+    if (!ctx) {
+        process.stderr.write(`Unknown dispatch-id: ${dispatchId}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(ctx)}\n`);
+}
+//# sourceMappingURL=dispatch-context.js.map

package/dist/commands/codebase-to-spec/dispatch-editor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-editor <area-prefix>` subcommand.
+ *
+ * Returns a dispatch payload for an editor pass on a specific area's partial.
+ * Validates that the area's `review.result` is `"needs-revision"` and that
+ * the partial file exists before scaffolding the dispatch.
+ *
+ * The worker overwrites the existing partial via Edit; the area.review.thread
+ * in outline.yaml stays where it is (the orchestrator manages it).
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ * - CTSO-CONV-3: orchestrator dispatches an editor when revisions are needed
+ */
+export declare function dispatchEditorCommand(areaPrefix: string): Promise<void>;
+//# sourceMappingURL=dispatch-editor.d.ts.map

package/dist/commands/codebase-to-spec/dispatch-editor.js

@@ -0,0 +1,71 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-editor <area-prefix>` subcommand.
+ *
+ * Returns a dispatch payload for an editor pass on a specific area's partial.
+ * Validates that the area's `review.result` is `"needs-revision"` and that
+ * the partial file exists before scaffolding the dispatch.
+ *
+ * The worker overwrites the existing partial via Edit; the area.review.thread
+ * in outline.yaml stays where it is (the orchestrator manages it).
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ * - CTSO-CONV-3: orchestrator dispatches an editor when revisions are needed
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { cachePaths } from "../../codebase-to-spec/cache.js";
+import { EDITOR_DISPATCH_ID_PREFIX } from "../../codebase-to-spec/dispatch.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { sanitizeAreaName } from "../../codebase-to-spec/fan-out.js";
+import { parseConversationalOutline, } from "../../codebase-to-spec/schemas.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+export async function dispatchEditorCommand(areaPrefix) {
+    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline)) {
+        process.stderr.write(`No outline.yaml found at ${paths.outline}. Dispatch the planner first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch (err) {
+        process.stderr.write(`Outline at ${paths.outline} is invalid: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const area = outline.areas.find((a) => a.prefix === areaPrefix);
+    if (!area) {
+        process.stderr.write(`No area with prefix "${areaPrefix}" in outline.yaml. Available prefixes: ${outline.areas
+            .map((a) => a.prefix)
+            .join(", ")}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (!area.review) {
+        process.stderr.write(`Area "${areaPrefix}" has no review yet. Write a per-area review with result=needs-revision before dispatching the editor.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (area.review.result === "approved") {
+        process.stderr.write(`Area "${areaPrefix}" has review.result "approved" — nothing to revise. The partial is good as-is.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const partialPath = paths.partial(sanitizeAreaName(area.name));
+    if (!existsSync(partialPath)) {
+        process.stderr.write(`Partial not found at ${partialPath}. Run the specifier for area "${areaPrefix}" before dispatching the editor.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const payload = {
+        dispatch_id: `${EDITOR_DISPATCH_ID_PREFIX}${areaPrefix}`,
+        output_path: partialPath,
+        area_name: area.name,
+        area_prefix: area.prefix,
+    };
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+//# sourceMappingURL=dispatch-editor.js.map

package/dist/commands/codebase-to-spec/dispatch-planner.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-planner [--revise]` subcommand.
+ *
+ * Initial mode: returns a dispatch payload for the first planner pass.
+ *
+ * --revise mode: reads the current `outline.yaml`, validates that its
+ * `review.result` is "needs-revision", and returns a payload for the next
+ * revise dispatch. The worker overwrites outline.yaml's content while
+ * preserving the review section.
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ * - CTSO-CONV-2: orchestrator iterates on planner's outline until approved
+ */
+export interface DispatchPlannerOptions {
+    revise?: boolean;
+}
+export declare function dispatchPlannerCommand(options?: DispatchPlannerOptions): Promise<void>;
+//# sourceMappingURL=dispatch-planner.d.ts.map

package/dist/commands/codebase-to-spec/dispatch-planner.js

@@ -0,0 +1,90 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-planner [--revise]` subcommand.
+ *
+ * Initial mode: returns a dispatch payload for the first planner pass.
+ *
+ * --revise mode: reads the current `outline.yaml`, validates that its
+ * `review.result` is "needs-revision", and returns a payload for the next
+ * revise dispatch. The worker overwrites outline.yaml's content while
+ * preserving the review section.
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ * - CTSO-CONV-2: orchestrator iterates on planner's outline until approved
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { cachePaths } from "../../codebase-to-spec/cache.js";
+import { PLANNER_INITIAL_DISPATCH_ID, PLANNER_REVISE_DISPATCH_ID_PREFIX, } from "../../codebase-to-spec/dispatch.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { parseConversationalOutline, } from "../../codebase-to-spec/schemas.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+export async function dispatchPlannerCommand(options = {}) {
+    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (options.revise) {
+        return dispatchPlannerRevise(paths);
+    }
+    return dispatchPlannerInitial(paths);
+}
+function dispatchPlannerInitial(paths) {
+    if (!existsSync(paths.overview)) {
+        process.stderr.write(`Compressed pack not found at ${paths.overview}. Run \`dotrequirements cts pack\` first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const payload = {
+        dispatch_id: PLANNER_INITIAL_DISPATCH_ID,
+        output_path: paths.outline,
+    };
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+function dispatchPlannerRevise(paths) {
+    if (!existsSync(paths.outline)) {
+        process.stderr.write(`No outline.yaml found at ${paths.outline}. Dispatch the initial planner first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    // Parse and validate the current outline. Surface clear errors rather
+    // than letting a malformed file silently produce a bad revise dispatch.
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch (err) {
+        process.stderr.write(`Outline at ${paths.outline} is invalid: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    // The orchestrator should only call --revise when the outline has been
+    // reviewed and the result is "needs-revision". Other states are user
+    // errors worth surfacing clearly.
+    if (!outline.review) {
+        process.stderr.write(`Outline at ${paths.outline} has no \`review\` section. Add CA's review (with result and thread) before dispatching revise.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (outline.review.result === "approved") {
+        process.stderr.write(`Outline at ${paths.outline} has review.result "approved" — nothing to revise. Proceed to fan-out.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    // Latest thread entry must be needs-revision for there to be revisions
+    // to act on. Schema's discriminated union enforces revisions ≥ 1 when
+    // the entry is needs-revision.
+    const latestEntry = outline.review.thread[outline.review.thread.length - 1];
+    if (!latestEntry || latestEntry.result !== "needs-revision") {
+        process.stderr.write(`Outline at ${paths.outline} has review.result "needs-revision" but the latest thread entry isn't a needs-revision entry. The review thread is malformed.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    // Next turn = current thread length + 1 (the round being PRODUCED by
+    // this revise dispatch; CA's review of THAT output will append a new
+    // thread entry of length+1 after this dispatch completes).
+    const nextTurn = outline.review.thread.length + 1;
+    const payload = {
+        dispatch_id: `${PLANNER_REVISE_DISPATCH_ID_PREFIX}${nextTurn}`,
+        output_path: paths.outline,
+    };
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+//# sourceMappingURL=dispatch-planner.js.map

package/dist/commands/codebase-to-spec/dispatch-spec.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-spec` subcommand.
+ *
+ * Returns an array of specifier dispatch payloads — one per area in the
+ * approved outline. The conversational orchestrator reads this, fires N
+ * background Task dispatches in parallel (one cts-worker per area), and
+ * collects the resulting partials.
+ *
+ * Errors clearly if `outline.yaml`'s `review.result` isn't `"approved"` —
+ * the orchestrator should approve the outline before fan-out.
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ */
+export declare function dispatchSpecCommand(): Promise<void>;
+//# sourceMappingURL=dispatch-spec.d.ts.map

package/dist/commands/codebase-to-spec/dispatch-spec.js

@@ -0,0 +1,59 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-spec` subcommand.
+ *
+ * Returns an array of specifier dispatch payloads — one per area in the
+ * approved outline. The conversational orchestrator reads this, fires N
+ * background Task dispatches in parallel (one cts-worker per area), and
+ * collects the resulting partials.
+ *
+ * Errors clearly if `outline.yaml`'s `review.result` isn't `"approved"` —
+ * the orchestrator should approve the outline before fan-out.
+ *
+ * Requirements covered:
+ * - CTSO-CLI-1: CLI exposes commands that return dispatch instructions
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { cachePaths } from "../../codebase-to-spec/cache.js";
+import { SPECIFIER_DISPATCH_ID_PREFIX } from "../../codebase-to-spec/dispatch.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { sanitizeAreaName } from "../../codebase-to-spec/fan-out.js";
+import { parseConversationalOutline, } from "../../codebase-to-spec/schemas.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+export async function dispatchSpecCommand() {
+    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline)) {
+        process.stderr.write(`No outline.yaml found at ${paths.outline}. Dispatch the planner first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch (err) {
+        process.stderr.write(`Outline at ${paths.outline} is invalid: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (!outline.review) {
+        process.stderr.write(`Outline at ${paths.outline} has no \`review\` section. Add CA's review with result=approved before dispatching specifiers.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (outline.review.result !== "approved") {
+        process.stderr.write(`Outline at ${paths.outline} has review.result "${outline.review.result}", not "approved". Approve the outline before dispatching specifiers.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    // For each area, produce a dispatch payload. The skill body fires N
+    // background Task calls in parallel using these payloads.
+    const dispatches = outline.areas.map((area) => ({
+        dispatch_id: `${SPECIFIER_DISPATCH_ID_PREFIX}${area.prefix}`,
+        output_path: paths.partial(sanitizeAreaName(area.name)),
+        area_name: area.name,
+        area_prefix: area.prefix,
+    }));
+    process.stdout.write(`${JSON.stringify(dispatches)}\n`);
+}
+//# sourceMappingURL=dispatch-spec.js.map

package/dist/commands/codebase-to-spec/index.js

@@ -6,16 +6,31 @@
  */
 import { installCtsAbortHandlers } from "../../codebase-to-spec/progress.js";
 import { composeCommand } from "./compose.js";
+import { composeOrchestratorCommand } from "./compose-orchestrator.js";
+import { dispatchContextCommand } from "./dispatch-context.js";
+import { dispatchEditorCommand } from "./dispatch-editor.js";
+import { dispatchPlannerCommand } from "./dispatch-planner.js";
+import { dispatchSpecCommand } from "./dispatch-spec.js";
 import { editLoopCommand } from "./edit-loop.js";
 import { fanOutCommand } from "./fan-out.js";
 import { packCommand } from "./pack.js";
 import { planLoopCommand } from "./plan-loop.js";
 import { presentCommand } from "./present.js";
+import { presentOrchestratorCommand } from "./present-orchestrator.js";
 import { runCommand } from "./run.js";
 import { skillInstallCommand } from "./skill-install.js";
 import { specifyAreaCommand } from "./specify-area.js";
 import { styleCheckCommand } from "./style-check.js";
 import { validateCommand } from "./validate.js";
+/**
+ * Marker used to hide a command from `--help` output without removing it.
+ * Used for dark-ship: the conversational orchestrator's plumbing commands and
+ * the skill-install entry point ship in the npm package but aren't surfaced
+ * in help listings or documentation. They remain fully invocable (the
+ * orchestrator skill calls them by name) — they just don't pollute the
+ * user-facing CLI surface until we flip the default path in Phase 6.
+ */
+const HIDDEN = { hidden: true };
 export function registerCodebaseToSpec(program) {
     const cts = program
         .command("codebase-to-spec")
@@ -134,7 +149,47 @@ export function registerCodebaseToSpec(program) {
         });
     });
     cts
-        .command("skill-install")
+        .command("dispatch-context <dispatch-id>", HIDDEN)
+        .description("Return the composed prompt for a worker dispatch as JSON on stdout (called by the cts-worker PreToolUse hook)")
+        .action((dispatchId) => dispatchContextCommand(dispatchId));
+    cts
+        .command("dispatch-planner", HIDDEN)
+        .description("Return a dispatch payload for a planner pass (initial, or --revise to scaffold the next turn from the latest cached outline + critique)")
+        .option("--revise", "Scaffold a revise dispatch using the latest cached outline + sibling critique file")
+        .action((opts) => dispatchPlannerCommand({ revise: opts.revise }));
+    cts
+        .command("dispatch-spec", HIDDEN)
+        .description("Return an array of specifier dispatch payloads — one per area in the approved outline (used by the conversational orchestrator skill to fan out N specifiers in parallel)")
+        .action(() => dispatchSpecCommand());
+    cts
+        .command("dispatch-editor <area-prefix>", HIDDEN)
+        .description("Return an editor dispatch payload for one area whose review is needs-revision (used by the conversational orchestrator skill to drive per-area convergence)")
+        .action((areaPrefix) => dispatchEditorCommand(areaPrefix));
+    cts
+        .command("compose-orchestrator", HIDDEN)
+        .description("Compose-orchestrator variant: reads outline.yaml (approved) + partials/, writes composedSpec")
+        .action(() => composeOrchestratorCommand());
+    cts
+        .command("present-orchestrator", HIDDEN)
+        .description("Present-orchestrator variant: reads outline.yaml + composedSpec, writes final files to .requirements/")
+        .option("--interactive", "Force interactive mode (override TTY detection)")
+        .option("--non-interactive", "Force non-interactive mode (override TTY detection)")
+        .option("--overwrite", "Replace existing .requirements/ files without prompting")
+        .option("--skip-existing", "Leave existing .requirements/ files untouched")
+        .action((opts) => {
+        const forceMode = opts.interactive
+            ? "interactive"
+            : opts.nonInteractive
+                ? "non-interactive"
+                : undefined;
+        return presentOrchestratorCommand({
+            forceMode,
+            overwrite: opts.overwrite,
+            skipExisting: opts.skipExisting,
+        });
+    });
+    cts
+        .command("skill-install", HIDDEN)
         .description("Install the codebase-to-spec skill (SKILL.md) into the host's skills directory")
         .option("--global", "Install to ~/.claude/skills/ instead of the project")
         .option("--target-dir <path>", "Install into a custom skills directory (for non-Claude-Code hosts)")