@popoverai/dotrequirements 0.24.1 → 0.24.3

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

@@ -4,28 +4,52 @@
  * Subcommands route to focused handlers in this directory. Each subcommand can
  * be invoked granularly (e.g., `dotrequirements cts pack`) per CTS-CLI-2.
  */
+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")
         .alias("cts")
         .description("Generate dotrequirements behavioral specifications from a codebase");
+    // Install SIGTERM/SIGINT handlers for every cts subcommand so an interrupted
+    // pipeline emits a structured `pipeline/aborted` line before exiting
+    // (CTS-OBSERVE-1.5). preAction fires after argv parsing and before the
+    // subcommand action runs.
+    cts.hook("preAction", () => {
+        installCtsAbortHandlers();
+    });
     cts
         .command("pack")
         .description("Pack the codebase (compressed and uncompressed views) into the cache")
         .option("-s, --scope <path>", "Limit to files under this path (subdir of project root)")
         .option("--fresh", "Clear the cache before running")
         .option("--budget <tokens>", "Override the working-context budget (in tokens)", (v) => parseInt(v, 10))
+        .option("--ignore-requirements", "Exclude `.requirements/**` from the pack (use when testing cts against a codebase whose existing requirements should not influence the output)")
         .action((opts) => packCommand({ ...opts, budgetTokens: opts.budget }));
     cts
         .command("plan-loop")
@@ -81,6 +105,7 @@ export function registerCodebaseToSpec(program) {
         .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")
+        .option("--ignore-requirements", "Write output to `.requirements/cts/` instead of `.requirements/` (use together with `cts pack --ignore-requirements` when isolating cts from an existing requirements directory)")
         .action((opts) => {
         const forceMode = opts.interactive
             ? "interactive"
@@ -91,6 +116,7 @@ export function registerCodebaseToSpec(program) {
             forceMode,
             overwrite: opts.overwrite,
             skipExisting: opts.skipExisting,
+            ignoreRequirements: opts.ignoreRequirements,
         });
     });
     cts
@@ -105,6 +131,7 @@ export function registerCodebaseToSpec(program) {
         .option("--non-interactive", "Force non-interactive mode for the present stage")
         .option("--overwrite", "Replace existing .requirements/ files without prompting")
         .option("--skip-existing", "Leave existing .requirements/ files untouched")
+        .option("--ignore-requirements", "Exclude `.requirements/**` from the pack and write output to `.requirements/cts/` instead of `.requirements/` (use when testing cts against a codebase whose existing requirements should not influence the output)")
         .action((opts) => {
         const forceMode = opts.interactive
             ? "interactive"
@@ -118,10 +145,51 @@ export function registerCodebaseToSpec(program) {
             forceMode,
             overwrite: opts.overwrite,
             skipExisting: opts.skipExisting,
+            ignoreRequirements: opts.ignoreRequirements,
+        });
+    });
+    cts
+        .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")
+        .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)")

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

@@ -13,6 +13,12 @@ export interface PackOptions {
     scope?: string;
     fresh?: boolean;
     budgetTokens?: number;
+    /**
+     * When true, exclude `.requirements/**` from the pack so an existing
+     * requirements directory does not influence the generated output.
+     * See CTS-PRESENT-5.
+     */
+    ignoreRequirements?: boolean;
     /** Override progress emitter, mainly for tests. */
     progress?: import("../../codebase-to-spec/progress.js").ProgressEmitter;
     /** Override the project root, mainly for tests. */

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

@@ -43,6 +43,7 @@ export async function packCommand(rawOptions = {}) {
         projectRoot,
         paths,
         scope: rawOptions.scope,
+        ignoreRequirements: rawOptions.ignoreRequirements,
     });
     progress.emit({
         stage: "pack",

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

@@ -0,0 +1,20 @@
+/**
+ * `dotrequirements codebase-to-spec present-orchestrator` subcommand.
+ *
+ * Conversational-orchestrator variant of `present`. Reads outline.yaml +
+ * composedSpec (produced by compose-orchestrator), writes the final spec
+ * to `.requirements/`. The orchestrator doesn't have a separate
+ * document-level edit-loop, so this reads from composedSpec directly
+ * rather than specFinal.
+ *
+ * Requirements covered:
+ * - CTS-PRESENT-1..4 (reuses the legacy present logic)
+ * - CTSO-INTEG-1: orchestrator uses existing deterministic stages unchanged
+ */
+export interface PresentOrchestratorOptions {
+    forceMode?: "interactive" | "non-interactive";
+    overwrite?: boolean;
+    skipExisting?: boolean;
+}
+export declare function presentOrchestratorCommand(options?: PresentOrchestratorOptions): Promise<void>;
+//# sourceMappingURL=present-orchestrator.d.ts.map

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

@@ -0,0 +1,81 @@
+/**
+ * `dotrequirements codebase-to-spec present-orchestrator` subcommand.
+ *
+ * Conversational-orchestrator variant of `present`. Reads outline.yaml +
+ * composedSpec (produced by compose-orchestrator), writes the final spec
+ * to `.requirements/`. The orchestrator doesn't have a separate
+ * document-level edit-loop, so this reads from composedSpec directly
+ * rather than specFinal.
+ *
+ * Requirements covered:
+ * - CTS-PRESENT-1..4 (reuses the legacy present 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 { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { detectMode } from "../../codebase-to-spec/interactive.js";
+import { runPresent, } from "../../codebase-to-spec/present.js";
+import { conversationalOutlineToLegacy, parseConversationalOutline, } from "../../codebase-to-spec/schemas.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+function resolvePolicy(isInteractive, options) {
+    if (options.overwrite && options.skipExisting) {
+        return { error: "--overwrite and --skip-existing are mutually exclusive." };
+    }
+    if (options.overwrite)
+        return "overwrite";
+    if (options.skipExisting)
+        return "skip-existing";
+    if (isInteractive)
+        return "prompt";
+    return "fail-fast";
+}
+export async function presentOrchestratorCommand(options = {}) {
+    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;
+    }
+    if (!existsSync(paths.composedSpec)) {
+        process.stderr.write(`No composed spec at ${paths.composedSpec}. Run \`cts compose-orchestrator\` 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 { isInteractive } = detectMode(options.forceMode);
+    const policy = resolvePolicy(isInteractive, options);
+    if (typeof policy === "object") {
+        process.stderr.write(`${policy.error}\n`);
+        process.exitCode = ExitCode.InvalidFlags;
+        return;
+    }
+    const legacyOutline = conversationalOutlineToLegacy(outline);
+    const result = await runPresent({
+        outline: legacyOutline,
+        finalSpecPath: paths.composedSpec,
+        projectRoot,
+        overwritePolicy: policy,
+    });
+    if (!result.allWritten) {
+        if (result.conflictPath) {
+            process.stderr.write(`Refusing to overwrite ${result.conflictPath}. Pass --overwrite or --skip-existing.\n`);
+        }
+        process.exitCode = ExitCode.OverwriteRefused;
+        return;
+    }
+    for (const action of result.actions) {
+        process.stdout.write(`  ${action.action}: ${action.path}\n`);
+    }
+    process.stdout.write(`Wrote ${result.actions.filter((a) => a.action === "created" || a.action === "overwrote").length} file(s) to .requirements/\n`);
+}
+//# sourceMappingURL=present-orchestrator.js.map

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

@@ -15,6 +15,11 @@ export interface PresentCmdOptions {
     overwrite?: boolean;
     /** Skip writing files that would conflict (non-interactive). */
     skipExisting?: boolean;
+    /**
+     * When true, write output under `.requirements/cts/` instead of
+     * `.requirements/`. See CTS-PRESENT-5.
+     */
+    ignoreRequirements?: boolean;
     projectRoot?: string;
 }
 export declare function presentCommand(rawOptions?: PresentCmdOptions): Promise<void>;

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

@@ -51,16 +51,21 @@ export async function presentCommand(rawOptions = {}) {
         process.exitCode = ExitCode.InvalidFlags;
         return;
     }
+    const outputSubdir = rawOptions.ignoreRequirements ? "cts" : undefined;
+    const outputDirLabel = outputSubdir
+        ? `.requirements/${outputSubdir}/`
+        : ".requirements/";
     progress.emit({
         stage: "present",
         step: "start",
-        message: `Writing final spec to .requirements/ (mode: ${isInteractive ? "interactive" : "non-interactive"}, policy: ${policy})`,
+        message: `Writing final spec to ${outputDirLabel} (mode: ${isInteractive ? "interactive" : "non-interactive"}, policy: ${policy})`,
     });
     const result = await runPresent({
         outline,
         finalSpecPath: paths.specFinal,
         projectRoot,
         overwritePolicy: policy,
+        outputSubdir,
     });
     // Per-file outcome announcements.
     for (const action of result.actions) {

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

@@ -77,6 +77,7 @@ export async function runCommand(options = {}) {
         forceMode: options.forceMode,
         overwrite: options.overwrite,
         skipExisting: options.skipExisting,
+        ignoreRequirements: options.ignoreRequirements,
         projectRoot: options.projectRoot,
     });
     // Present sets a non-zero exit code on overwrite refusal or validation

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

@@ -41,7 +41,18 @@ export async function skillInstallCommand(options = {}) {
         else {
             process.stdout.write(`SKILL.md already up to date at ${result.installedPath}\n`);
         }
-        process.stdout.write("Skill ready. In Claude Code, invoke it with `/codebase-to-spec` (or via natural language).\n");
+        if (result.companions) {
+            process.stdout.write(`Installed cts-worker agent at ${result.companions.agentPath}\n`);
+            process.stdout.write(`Installed persona-injection hook at ${result.companions.hookScriptPath}\n`);
+            if (result.companions.hookRegistered) {
+                process.stdout.write(`Registered PreToolUse hook in ${result.companions.settingsPath}\n`);
+            }
+            else {
+                process.stdout.write(`PreToolUse hook already registered in ${result.companions.settingsPath}\n`);
+            }
+            process.stdout.write("\n⚠️  The hook script uses `dotrequirements` from PATH. If you're working in a local dev clone, set DOTREQUIREMENTS_CLI to override (see the hook script for details).\n");
+        }
+        process.stdout.write("\nSkill ready. In Claude Code, invoke it with `/codebase-to-spec` (or via natural language).\n");
     }
     catch (err) {
         process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);

package/dist/templates/agents/cts-worker.md

@@ -0,0 +1,9 @@
+---
+name: cts-worker
+description: Generic worker subagent for the codebase-to-spec conversational orchestrator. Used for planner, specifier, editor, and reviewer dispatches. The per-dispatch persona is injected by the cts-worker-persona PreToolUse hook at dispatch time.
+tools: Bash, Read, Edit, Write, Glob, Grep
+---
+
+You are a codebase-to-spec worker. Your dispatched prompt is composed externally and supplied to you at dispatch time. It will specify your role for this dispatch (planner, specifier, editor, or reviewer), the artifacts you're working with, and the output convention you must follow.
+
+Follow the dispatched prompt exactly. Do not improvise behavior beyond what it asks. When your work is done, submit via the convention specified in the dispatch (typically a `dotrequirements cts submit` call).

package/dist/templates/hooks/cts-worker-persona.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# PreToolUse hook for Task(subagent_type=cts-worker) dispatches.
+# Composes the worker's first-turn prompt by calling
+# `dotrequirements cts dispatch-context <dispatch-id>` and emits the
+# result via `updatedInput.prompt`.
+#
+# The orchestrator's convention: the original Task prompt MUST include
+# the verbatim token `dispatch-id=<id>` so the hook can extract it.
+#
+# Bundled with the codebase-to-spec skill (CTSO-CLI-1).
+#
+# CLI resolution order:
+#   1. DOTREQUIREMENTS_CLI env var (explicit override)
+#   2. If running inside the dotrequirements monorepo itself
+#      ($CLAUDE_PROJECT_DIR/packages/cli/dist/cli.js exists), use that
+#      local build. Lets dotrequirements developers use the orchestrator
+#      against any worktree without a global install.
+#   3. `dotrequirements` from PATH (the canonical end-user setup).
+
+INPUT=$(cat)
+SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // ""')
+
+# Self-filter: only act on cts-worker dispatches.
+if [[ "$SUBAGENT_TYPE" != "cts-worker" ]]; then
+  exit 0
+fi
+
+ORIGINAL_PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // ""')
+
+# Extract dispatch-id token from the original prompt.
+DISPATCH_ID=$(echo "$ORIGINAL_PROMPT" | grep -oE 'dispatch-id=[a-zA-Z0-9_-]+' | head -1 | sed 's/dispatch-id=//')
+
+if [[ -z "$DISPATCH_ID" ]]; then
+  # No dispatch-id in the prompt — let it through unmodified.
+  exit 0
+fi
+
+# Resolve the CLI invocation (see header for order).
+if [[ -n "${DOTREQUIREMENTS_CLI:-}" ]]; then
+  CLI="$DOTREQUIREMENTS_CLI"
+elif [[ -n "${CLAUDE_PROJECT_DIR:-}" && -f "$CLAUDE_PROJECT_DIR/packages/cli/dist/cli.js" ]]; then
+  CLI="node $CLAUDE_PROJECT_DIR/packages/cli/dist/cli.js"
+else
+  CLI="dotrequirements"
+fi
+
+# Compose the dispatch context. CLI returns JSON like {"prompt": "..."}.
+COMPOSED=$($CLI cts dispatch-context "$DISPATCH_ID" 2>/dev/null)
+COMPOSE_STATUS=$?
+
+if [[ $COMPOSE_STATUS -ne 0 || -z "$COMPOSED" ]]; then
+  # CLI call failed — let the dispatch through unmodified so the
+  # worker's failure is legible.
+  exit 0
+fi
+
+PROMPT=$(echo "$COMPOSED" | jq -r '.prompt // ""')
+
+if [[ -z "$PROMPT" ]]; then
+  exit 0
+fi
+
+# Emit updatedInput so the worker subagent sees the composed prompt
+# as its first-turn input. (Field name is `updatedInput`, not
+# `modifiedInput` — verified by spike work; see working doc.)
+jq -nc --arg p "$PROMPT" '{
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "allow",
+    updatedInput: {
+      prompt: $p
+    }
+  }
+}'
+
+exit 0