@popoverai/dotrequirements 0.24.3 → 0.25.0

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

@@ -1,13 +1,13 @@
 /**
  * Skill installation logic for the codebase-to-spec skill.
  *
- * 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.
+ * Ships as a bundle: SKILL.md + cts-worker agent definition + the `codebase-to-spec`
+ * dynamic-workflow script. The skill body (the conversational orchestrator)
+ * launches the workflow, which dispatches cts-worker agents; both companions
+ * must be present for the skill to run. For `project` and `global` scope, all
+ * three pieces are installed in one shot (under the project's `.claude/` or the
+ * user's `~/.claude/`). Only a `custom` target dir is skill-only, because
+ * assistants do not auto-discover agents or workflows from arbitrary paths.
  *
  * Host portability (CTS-SKILL-5): the install logic supports any host that
  * follows the Agent Skills format. The default target is Claude Code's
@@ -15,9 +15,9 @@
  *
  * Requirements covered:
  * - CTS-SKILL-1, CTS-SKILL-5
- * - CTSO-CLI-1 (bundles the agent + hook that PreToolUse-injects persona bodies)
+ * - CTSO-INSTALL-1 (bundles the skill, the cts-worker agent, and the workflow)
  */
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { 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";
@@ -34,7 +34,7 @@ export function resolveSkillDir(options) {
             return join(root, ".claude", "skills", "codebase-to-spec");
         }
         case "global":
-            return join(homedir(), ".claude", "skills", "codebase-to-spec");
+            return join(options.globalRoot ?? homedir(), ".claude", "skills", "codebase-to-spec");
         case "custom":
             if (!options.targetDir) {
                 throw new Error('targetDir is required when scope === "custom"');
@@ -57,10 +57,10 @@ export function loadAgentTemplate() {
     return loadTemplate("agents/cts-worker.md");
 }
 /**
- * Load the bundled persona-injection hook script template.
+ * Load the bundled specify-codebase dynamic-workflow script template.
  */
-export function loadHookTemplate() {
-    return loadTemplate("hooks/cts-worker-persona.sh");
+export function loadWorkflowTemplate() {
+    return loadTemplate("workflows/specify-codebase.js");
 }
 /**
  * Install (or refuse to overwrite) one template file at a target path.
@@ -79,101 +79,49 @@ function installTemplateFile(templateContent, targetPath, overwrite, description
     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 `project` and `global` scope: installs the full bundle — the skill body,
+ * the cts-worker agent, and the specify-codebase workflow — under the matching
+ * `.claude/` base (the project's, or the user's `~/.claude/`).
  *
- * For `global` and `custom` scopes: installs only the skill body.
+ * For `custom` scope: installs only the skill body, because Claude Code does
+ * not auto-discover agents or workflows from an arbitrary directory.
  */
 export function installSkill(options = {}) {
     const skillDir = resolveSkillDir(options);
     const skillPath = join(skillDir, "SKILL.md");
     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.
+    // A custom target dir is an arbitrary location CC won't read agents or
+    // workflows from, so it gets the skill body only. Project and global both
+    // install the full bundle under their `.claude/` base.
     const scope = options.scope ?? "project";
-    if (scope !== "project") {
+    if (scope === "custom") {
         return {
             installedPath: skillPath,
             installed: skillResult.installed,
             overwrote: skillResult.overwrote,
         };
     }
-    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");
+    const claudeBase = scope === "global"
+        ? join(options.globalRoot ?? homedir(), ".claude")
+        : join(options.projectRoot ?? process.cwd(), ".claude");
+    const agentPath = join(claudeBase, "agents", "cts-worker.md");
+    const workflowPath = join(claudeBase, "workflows", "specify-codebase.js");
     // 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);
+    // Install the specify-codebase workflow script (discovered by name from
+    // .claude/workflows/; no settings registration needed, unlike a hook).
+    installTemplateFile(loadWorkflowTemplate(), workflowPath, options.overwrite === true, "specify-codebase workflow script");
     return {
         installedPath: skillPath,
         installed: skillResult.installed,
         overwrote: skillResult.overwrote,
         companions: {
             agentPath,
-            hookScriptPath,
-            settingsPath,
-            hookRegistered: registered,
+            workflowPath,
         },
     };
 }

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

@@ -2,11 +2,8 @@
  * `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
+ * Run by cts-worker subagents at the start of their turn to fetch the composed
+ * first-turn prompt for their dispatch-id (see the specify-codebase workflow).
  */
 export declare function dispatchContextCommand(dispatchId: string): Promise<void>;
 //# sourceMappingURL=dispatch-context.d.ts.map

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

@@ -2,11 +2,8 @@
  * `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
+ * Run by cts-worker subagents at the start of their turn to fetch the composed
+ * first-turn prompt for their dispatch-id (see the specify-codebase workflow).
  */
 import { composeDispatchContext } from "../../codebase-to-spec/dispatch.js";
 import { ExitCode } from "../../codebase-to-spec/exit-codes.js";

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

@@ -9,7 +9,6 @@
  * 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>;

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

@@ -9,7 +9,6 @@
  * 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";

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

@@ -9,7 +9,6 @@
  * 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 {

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

@@ -9,7 +9,6 @@
  * 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";

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

@@ -2,15 +2,12 @@
  * `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.
+ * 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.
- *
- * 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

@@ -2,15 +2,12 @@
  * `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.
+ * 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.
- *
- * 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";

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

@@ -46,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)")
@@ -150,7 +151,7 @@ export function registerCodebaseToSpec(program) {
     });
     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)")
+        .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)

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

@@ -43,16 +43,9 @@ export async function skillInstallCommand(options = {}) {
         }
         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(`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).\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

@@ -1,9 +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.
+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. 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.
+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.
 
-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).
+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.