@popoverai/dotrequirements 0.24.2 → 0.25.0

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

@@ -0,0 +1,18 @@
+/**
+ * `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-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,89 @@
+/**
+ * `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-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,13 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-spec` subcommand.
+ *
+ * Returns an array of specifier dispatch payloads — one per area in the
+ * approved outline. The specify-codebase workflow reads this, fires N
+ * cts-worker dispatches in parallel (one 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.
+ */
+export declare function dispatchSpecCommand(): Promise<void>;
+//# sourceMappingURL=dispatch-spec.d.ts.map

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

@@ -0,0 +1,56 @@
+/**
+ * `dotrequirements codebase-to-spec dispatch-spec` subcommand.
+ *
+ * Returns an array of specifier dispatch payloads — one per area in the
+ * approved outline. The specify-codebase workflow reads this, fires N
+ * cts-worker dispatches in parallel (one 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.
+ */
+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")
@@ -31,7 +46,8 @@ export function registerCodebaseToSpec(program) {
     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("-s, --scope <path>", "Limit to files under this path (subdir of project root, or of the remote repo when --remote is set)")
+        .option("--remote <url>", "Pack a remote repository (GitHub URL or owner/repo) instead of the local project; repomix clones, packs, and cleans up. Combine with --scope to pack just a subdirectory.")
         .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)")
@@ -134,7 +150,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 (run by cts-worker subagents to fetch their dispatch prompt)")
+        .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)")

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

@@ -11,6 +11,11 @@
  */
 export interface PackOptions {
     scope?: string;
+    /**
+     * Pack a remote repository (GitHub URL or `owner/repo`) instead of the local
+     * project. Combine with `scope` to pack just a subdirectory of the remote.
+     */
+    remote?: string;
     fresh?: boolean;
     budgetTokens?: number;
     /**

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

@@ -35,14 +35,17 @@ export async function packCommand(rawOptions = {}) {
     progress.emit({
         stage: "pack",
         step: "start",
-        message: scope
-            ? `Packing codebase at ${scope}`
-            : `Packing codebase at ${projectRoot}`,
+        message: rawOptions.remote
+            ? `Packing remote ${rawOptions.remote}${rawOptions.scope ? ` (scope: ${rawOptions.scope})` : ""}`
+            : scope
+                ? `Packing codebase at ${scope}`
+                : `Packing codebase at ${projectRoot}`,
     });
     const packResult = await runPack({
         projectRoot,
         paths,
         scope: rawOptions.scope,
+        remote: rawOptions.remote,
         ignoreRequirements: rawOptions.ignoreRequirements,
     });
     progress.emit({

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/skill-install.js

@@ -41,7 +41,11 @@ 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 specify-codebase workflow at ${result.companions.workflowPath}\n`);
+        }
+        process.stdout.write("\nSkill ready. In Claude Code, invoke it with `/codebase-to-spec` (or via natural language). Requires a Claude Code version with dynamic-workflow support.\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 workflow. Handles planner, outline-reviewer, specifier, reviewer, and editor dispatches. Each worker fetches its own role-specific instructions from the CLI at dispatch time.
+tools: Bash, Read, Edit, Write, Glob, Grep
+---
+
+You are a codebase-to-spec worker. The prompt you receive tells you which CLI dispatch to fetch: it will instruct you to run `dotrequirements cts dispatch-context <dispatch-id>` (the exact invocation is given in your prompt), read the `"prompt"` field of the JSON it prints, and follow those instructions exactly.
+
+Those fetched instructions are your real task — which files to read, what to write and where, and how to validate and style-check your output via Bash. Follow them exactly and do not improvise beyond what they ask. When your prompt also asks you to return a structured result, return exactly that shape.

package/dist/templates/skills/codebase-to-spec/SKILL.md

@@ -1,118 +1,85 @@
 ---
 name: codebase-to-spec
-description: Generate dotrequirements behavioral specifications from a codebase. Use this when the user wants to capture what an existing codebase does as a set of testable behavioral requirements — e.g. for legacy systems, third-party libraries, or before refactoring.
+description: Generate dotrequirements behavioral specifications from a codebase. You confirm scope and review the result; a background workflow autonomously plans the area outline, drafts each area's requirements, and converges them via independent review. Use when the user wants to capture what an existing codebase does as testable behavioral requirements (legacy systems, third-party libraries, before refactoring).
+allowed-tools: Bash, Read, Workflow, AskUserQuestion
 ---
 
 # Codebase to Spec
 
-You are a thin conversational wrapper around the `dotrequirements cts run` CLI. **You do not implement any pipeline logic yourself.** The CLI handles packing, planning, fan-out parallelism, retry, resumability, review loops, and presentation. Your job is to:
-
-1. Confirm the user's scope.
-2. Run the CLI via the Bash tool.
-3. Narrate progress as the CLI emits it.
-4. Surface the final summary and residual notes.
-5. Offer sensible follow-ups (push to cloud, re-run, narrow scope, etc.).
+You turn an existing codebase into a dotrequirements behavioral spec. You own two human touchpoints — **confirming scope** at the start and **reviewing the result** at the end. Everything between — planning the behavioral-area outline, drafting each area's requirements, and the independent reviews that converge them — runs autonomously inside the **`specify-codebase` dynamic workflow**. You do not draft or review requirements yourself, and you do not dispatch workers yourself; the workflow does.
 
 ## When this skill is right
 
-Use it when the user wants behavioral requirements *from* code that already exists. Typical phrasings:
-- "Generate requirements from this codebase"
-- "Capture the behavior of this library"
-- "I want a behavioral spec for the auth module"
-- "Document what this service does"
+Use when the user wants behavioral requirements *from* code that already exists:
+- "Generate requirements from this codebase" / "capture what this library does" / "spec the auth module before I refactor it"
 
-Do **not** use it for:
-- New feature design (use `dotreq-requirements` / the capture flow instead)
-- Bug investigation
-- Code review
+Do **not** use for new-feature design (use the `dotreq-requirements` skill), bug investigation, or code review.
 
-## Workflow
+## Prerequisite: dynamic workflows
 
-### Step 1 — Confirm scope
+This skill runs its pipeline as a dynamic Workflow. If the `Workflow` tool is not available in this environment, **stop** and tell the user:
 
-If the user passed a scope argument (e.g. a path like `src/auth`), use it. Otherwise, ask one concise question:
+> "codebase-to-spec runs as a dynamic workflow, which this Claude Code version/configuration doesn't support. For CI or headless use, run `dotrequirements cts run --scope <path>` instead."
 
-> "Which part of the codebase should I spec? You can give me a path (e.g. `src/auth`) or say 'the whole thing'."
+Do not attempt a non-workflow fallback.
 
-Whole-codebase runs are fine for small repos. For larger ones, encourage scoping to a single area — the CLI will tell you if the working-context budget is exceeded.
+## Workflow
 
-### Step 2 — Run the CLI
+### 1. Confirm scope
 
-Invoke the pipeline via Bash. The command is:
+If the user gave a scope (a path), use it. Otherwise ask one concise question:
 
-```bash
-dotrequirements cts run --scope <PATH> --non-interactive
-```
+> "Which part of the codebase should I spec? Give me a path (e.g. `src/auth`) or say 'the whole thing'."
+
+For large codebases, encourage scoping to a single area — the pack has a context budget.
 
-Flags:
-- `--scope <path>` — limit packing to a subdirectory. Omit for the whole repo.
-- `--non-interactive` — important: you're running in an agentic context, so prompts won't work.
-- `--overwrite` — replace existing `.requirements/*.requirements.md` files.
-- `--skip-existing` — leave existing files untouched.
-- `--fresh` — clear the cache before running (use only if a previous run is corrupt).
+### 2. Pack (deterministic)
 
-Default to `--non-interactive`. Decide between `--overwrite` and `--skip-existing` based on what the user wants if there are existing `.requirements/` files; otherwise neither flag is needed (the default `fail-fast` policy will surface conflicts).
+Run `dotrequirements cts pack --scope <PATH>` via Bash. Deterministic, no LLM. It emits `[CTS] pack/done` then `pack/budget-ok`, or exits **10 (BudgetExceeded)** if the compressed pack is too large. On BudgetExceeded, surface the limit and offer a narrower scope (back to step 1).
 
-### Step 3 — Narrate progress
+### 3. Run the workflow
 
-The CLI emits lines like:
+Launch the bundled workflow:
 
 ```
-[CTS] pack/done Packed 16 files → ... (compressed), ... (uncompressed)
-[CTS] plan/done Plan loop converged at turn 1 with verdict: approved-with-revisions
-[CTS] specify/summary Completed: 7 / Skipped (resume): 0 / Failed: 0
-[CTS] spec-review/done Edit loop converged at turn 1 with verdict: approved-with-revisions
-[CTS] present/created created: .../sample.requirements.md
+Workflow({ name: "specify-codebase" })
 ```
 
-Surface these to the user in conversational form as they appear. **Do not invent progress claims** — narrate only what the CLI has actually emitted. If the CLI is silent for a long stretch (specifier fan-out can take minutes), a single reassuring note ("still working — the specifier fan-out runs in parallel and takes a few minutes for larger areas") is fine. Don't repeat it.
+You normally pass no `args` — `cli` defaults to `dotrequirements` on PATH, and the iteration caps default to `roundsCap: 5` / `outlineRoundsCap: 4`. Override only if needed, passing `args` as a real object (not a JSON string). *(Only in the dotrequirements dev repo, pass `args: { cli: "node <repo>/packages/cli/dist/cli.js" }`.)*
 
-### Step 4 — Surface the final summary
+The workflow plans the outline (planner + an independent reviewer, looping to convergence), enumerates the areas, fans out one specifier per area, converges each area (specify → review → edit), then composes the partials into one spec and runs a document-level cross-area review/edit pass (dedup, terminology, seam gaps). It runs in the background — watch progress in `/workflows`. Do not narrate every step; only surface the gates below.
 
-When the CLI finishes successfully, it prints a "Pipeline summary:" block with:
-- total areas
-- total top-level requirements
-- outline review turns and verdict
-- specifier completion count
-- spec review turns and verdict
-- the list of output files written
-- residual notes (issues the reviewer flagged in `approved-with-revisions` outcomes)
+### 4. Read the result
 
-Present that summary back to the user. **Highlight the residual notes** prominently — these are concerns the reviewer wanted the human to verify. Common categories:
-- `outline.coverage_gap` — files the planner didn't assign to any area
-- `spec.coverage_gap` — behaviors the spec missed
-- `spec.framing_error` — requirements written as guidance/explanation rather than observable behavior
-- `spec.cross_area` — duplication across areas
-- `spec.internal_mechanics` — internal vocabulary that leaked into a user-facing spec
+The workflow returns one of:
+- **`status: "done"`** — with `areas` (per-area `{ area_prefix, area_name, partial_path, status, rounds }`), `converged_count`, `unconverged` (prefixes that hit the round cap), `failed` (prefixes whose specifier failed outright — no draft was produced), `total`, and the cross-area pass result `cross_area_rounds` / `cross_area_converged`. The workflow has already composed and reconciled the spec. Proceed to step 5.
+- **`status: "outline-unconverged"`** — the outline reviewer didn't approve the decomposition within `outlineRoundsCap`. The latest outline is at `.dotrequirements-cache/outline.yaml`. Surface this; offer to re-run, narrow scope, or hand-edit the outline. Do **not** present.
+- **`status: "enumerate-failed"`** — the approved outline's areas couldn't be enumerated (the agent died). Nothing was drafted. Surface this and offer to re-run. Do **not** present.
 
-### Step 5 — Offer follow-ups
+### 5. Present (deterministic)
 
-After surfacing the summary, ask the user what they want next. Useful options:
+On `status: "done"`, the workflow has already composed the spec and run the cross-area pass. Write the final file(s):
+- `dotrequirements cts present-orchestrator` — writes the composed spec to file(s) under `.requirements/`.
 
-- **Push to cloud** — `dotrequirements push` syncs the generated `.requirements/*.requirements.md` files to dotrequirements cloud. Only suggest this if the user has a cloud account (you can check by reading `.dotrequirements/config.json` or asking).
-- **Refine a specific area** — re-run `dotrequirements cts specify-area "<name>"` for one area, optionally with `--model <name>` for a stronger model.
-- **Refine the whole spec** — re-run `dotrequirements cts edit-loop` to iterate on the composed spec.
-- **Narrow the scope** — re-run with a smaller `--scope`.
-- **Hand-edit** — the output files are plain Markdown; the user can edit them directly.
+`present-orchestrator` errors on existing-file conflicts unless given `--overwrite` or `--skip-existing`. When a conflict is reported, ask the user which they want, then re-run with that flag.
 
-## Failure handling
+When `cross_area_converged` is `false`, the cross-area pass hit `crossAreaRoundsCap` without a clean approval — present the spec, but surface that in the summary so the user gives the composed spec an extra look.
 
-The CLI uses stable exit codes (see `dotrequirements cts run --help`). Common cases:
+### 6. Summarize and offer follow-ups
 
-- **Exit code 10 (BudgetExceeded)** — the codebase is too large for a single agent's context window after compression. Explain this in plain language and offer to retry with a narrower `--scope`.
-- **Exit code 11 (MaxTurnsHit)** — a review loop hit its cap without converging. The CLI still writes the latest artifact; surface the residual review and ask the user whether to ship it, re-run the stage (`dotrequirements cts edit-loop`), or hand-edit.
-- **Exit code 12 (OverwriteRefused)** — existing `.requirements/` files would be overwritten in non-interactive mode. Offer `--overwrite` or `--skip-existing`.
-- **Exit code 3 (StageFailed)** — a stage errored. Read stderr for details. Offer: resume (re-run the same command — the cache means earlier stages are skipped), restart fresh (`--fresh`), or investigate (read files in `.dotrequirements-cache/`).
-- **Any other non-zero exit** — surface stderr verbatim, then offer the same three options.
+Present a readable summary: how many areas and requirements, the file path(s) written, and — importantly — any `unconverged` areas (they hit the round cap; their latest draft was kept and is worth a look) and any `failed` areas (no draft was produced; they are absent from the spec). Then offer, **without auto-running any of them**:
+- **Push to cloud** — `dotrequirements push` (only if cloud is configured; it's a destructive sync).
+- **Refine an area** — re-run on a narrower scope.
+- **Re-run on a different scope.**
 
 ## What you must NOT do
 
-- Don't try to generate requirements yourself; always use the CLI.
-- Don't paraphrase or summarize the CLI's progress lines in ways that change their meaning.
-- Don't claim the pipeline did something it didn't (e.g. don't say "the reviewer approved this" if the verdict was `approved-with-revisions`).
-- Don't push to cloud without asking — `dotrequirements push` is a destructive sync.
-- Don't suggest editing files inside `.dotrequirements-cache/`; that's internal CLI state.
+- Don't draft, review, or edit requirements yourself — the workflow's workers do that.
+- Don't dispatch workers via the Task tool — the workflow owns all agent work.
+- Don't claim convergence when `unconverged` or `failed` is non-empty — surface those areas honestly.
+- Don't present when `status` is `outline-unconverged` or `enumerate-failed`.
+- Don't push to cloud without asking.
 
 ## Host portability
 
-This skill makes no assumptions about subagent mechanisms, Task tools, or framework-specific features. Its only host requirements are: Agent Skills format support, a Bash tool (or equivalent shell-out), and `dotrequirements` installed on the user's machine.
+This skill requires Claude Code with dynamic-workflow support (it launches the `specify-codebase` workflow). On hosts without it, or for CI/headless use, the legacy `dotrequirements cts run` CLI runs the same pipeline non-interactively.