pr-shepherd 0.13.0 → 0.14.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"
@@ -9,12 +9,6 @@
   "homepage": "https://github.com/jonathanong/pr-shepherd",
   "repository": "https://github.com/jonathanong/pr-shepherd",
   "license": "MIT",
-  "keywords": [
-    "github",
-    "pull-request",
-    "ci",
-    "code-review",
-    "automation"
-  ],
+  "keywords": ["github", "pull-request", "ci", "code-review", "automation"],
   "skills": "./plugin/skills/"
 }

package/README.md

@@ -20,9 +20,9 @@ Example Workflow:
 
 `pr-shepherd` optimizes token management, rate limits, and agentic orchestration by moving **ALL** deterministic logic and prompts to code via a CLI tool, enshrining what would be a large skill or command prompt (of which the agent would inevitably make mistakes) into the code and returning a clear, actionable prompt.
 
-The CLI adapts monitor instructions to the calling agent. Claude Code gets `/loop` bootstrap instructions. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`; it gets a reusable `npx pr-shepherd <PR>` command and explicit goal-friendly iterate instructions because Codex does not provide `/loop` scheduling in this workflow.
+The CLI adapts monitor instructions to the calling agent. Claude Code gets `/loop` bootstrap instructions. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`; it gets a reusable pr-shepherd command and explicit goal-friendly iterate instructions because Codex does not provide `/loop` scheduling in this workflow. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, or `yarn`.
 
-At a high level, to start the monitor, the skill/command invokes a CLI that returns a prompt to be ingested by the agent _(schematic — paraphrased for brevity; actual output is more detailed)_:
+At a high level, to start the monitor, the skill/command invokes a CLI that returns a prompt to be ingested by the agent _(schematic — paraphrased for brevity; actual output is more detailed; examples use `npx` as the default spelling — a pnpm or yarn repo would emit `pnpm exec` or `yarn run` instead)_:
 
 ```
 /pr-shepherd:monitor
@@ -32,14 +32,14 @@ At a high level, to start the monitor, the skill/command invokes a CLI that retu
 # PR #123 [MONITOR]
 
 Loop tag: `#pr-shepherd-loop:pr=123:`
-Loop args: `4m`
 
 ## Loop prompt
 
 #pr-shepherd-loop:pr=123:
 
-**IMPORTANT — recurrence rules:** Do not call ScheduleWakeup or /loop. End the turn
-after completing the actions below. The cron job handles the next fire.
+**IMPORTANT — dynamic recurrence rules:** Do not invoke `/loop` again from inside
+this prompt. For nonterminal iterations, call `ScheduleWakeup` with `delaySeconds`
+between 60 and 240 and this same prompt body.
 
 Run in a single Bash call:
   npx pr-shepherd 123
@@ -48,11 +48,10 @@ Run in a single Bash call:
 
 ## Instructions
 
-1. Run `CronList`. If any job's prompt contains the loop tag, run the ## Loop prompt inline then stop.
-2. Otherwise, invoke the /loop skill with Loop args and the full ## Loop prompt body.
+1. Invoke the /loop skill with the full ## Loop prompt body and no fixed interval.
 ```
 
-Each iteration calls `npx pr-shepherd <PR>`, which provides actionable feedback directly to the agent:
+Each iteration calls `pr-shepherd <PR>` through the selected package runner, which provides actionable feedback directly to the agent:
 
 ```
 > npx pr-shepherd 123
@@ -127,7 +126,7 @@ Some other workflow improvements:
 
 Recommendations:
 
-- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. In Claude Code, `/pr-shepherd:monitor` uses `/loop` and continues working when your rate limit window is reset. In Codex, keep an active goal cycling the reusable `npx pr-shepherd <PR>` command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
+- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. In Claude Code, `/pr-shepherd:monitor` uses `/loop` and continues working when your rate limit window is reset. In Codex, keep an active goal cycling the reusable command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
 - Instruct your agents to write comments in a single review (comment, changes requested, or approved). This allows the review's comments/threads to be minimized or resolved together, keeping your pull request history clean. If you write inline comments outside of a review, each comment would still show up in the pull request history and take up space.
 - Avoid sticky comments as they will continue to be hidden. Instead, just make a new comment, especially on reviews. If you really want sticky comments, instruct your agent to unhide/unminimize them when updating them.
 - Avoid having automation edit comments, reviews, or threads in place because updated items get minimized. Instead, always make a new review, comment, thread, etc.
@@ -144,16 +143,15 @@ Recommendations:
 
 ### Monitor a PR
 
-In Claude Code, creates a cron loop that fires every 4 minutes, checks CI and review comments, fixes issues, and marks the PR ready for review when clean. The loop cancels automatically when the PR is merged or closed.
+In Claude Code, creates a fixed-interval loop (default every 4 minutes, configurable via `watch.interval`) that checks CI and review comments, fixes issues, and marks the PR ready for review when clean. The loop runs as a cron job that fires on schedule — agents end each turn cleanly and the cron fires again automatically. The loop stops automatically when the PR is merged or closed (auto-expires after 7 days).
 
-In Codex, run `npx pr-shepherd monitor <PR>` once to emit the goal-friendly recurrence prompt, then follow that prompt. Its reusable follow-up command is `npx pr-shepherd <PR>`.
+In Codex, run `pr-shepherd monitor <PR>` once through the repo package runner to emit the goal-friendly recurrence prompt, then follow that prompt. Its reusable follow-up command is emitted by the CLI.
 
 Claude Code:
 
 ```
 /pr-shepherd:monitor                     # infer PR from current branch
 /pr-shepherd:monitor 42
-/pr-shepherd:monitor 42 every 8m
 /pr-shepherd:monitor 42 --ready-delay 15m
 ```
 
@@ -193,11 +191,11 @@ See [docs/skills.md](docs/skills.md) for full argument reference.
 
 ## Iterate decision loop
 
-On each tick (4-minute default, tunable via `watch.interval`): fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, `wait`, or `cooldown`). See [docs/iterate-flow.md](docs/iterate-flow.md) for the decision table and [docs/flow.md](docs/flow.md) for the end-to-end flow diagram.
+On each dynamic tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, `wait`, or `cooldown`). Claude and Codex both choose a fresh wait between 1 and 4 minutes for each nonterminal recurrence. See [docs/iterate-flow.md](docs/iterate-flow.md) for the decision table and [docs/flow.md](docs/flow.md) for the end-to-end flow diagram.
 
 ## Install
 
-> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. The skills invoke `npx pr-shepherd`, so you also need the CLI available. If you're using `pr-shepherd` as development tooling for your repo, install it as a dev dependency so `npx` resolves it without prompting:
+> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. The skills invoke `pr-shepherd` through the repo package runner, so you also need the CLI available. If you're using `pr-shepherd` as development tooling for your repo, install it as a dev dependency so the selected runner resolves it without prompting:
 >
 > ```bash
 > npm install --save-dev pr-shepherd
@@ -275,7 +273,7 @@ Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until
 npx pr-shepherd 42
 ```
 
-For an active Codex goal, rerun that command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `npx pr-shepherd iterate 42` remains supported for existing workflows. There is no background `/loop` scheduler in Codex.
+For an active Codex goal, rerun that command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows. There is no background `/loop` scheduler in Codex.
 
 ### Without the plugin
 

package/bin/cli/fix-formatter.mjs

@@ -7,6 +7,7 @@ export function formatFixCodeResult(header, result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const retryInterval = opts?.retryInterval;
+    const runner = opts?.runner;
     const sections = [header];
     if (result.fix.threads.length > 0) {
         sections.push("## Review threads");
@@ -117,7 +118,7 @@ export function formatFixCodeResult(header, result, opts) {
     }
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");
-    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval)));
+    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner)));
     return joinSections(sections);
 }
 function blockquote(body) {

package/bin/cli/handlers.mjs

@@ -63,7 +63,12 @@ export async function handleIterate(args) {
         noAutoMarkReady,
         noAutoCancelActionable,
     });
-    const projectionOpts = { runtime, readyDelaySuffix, retryInterval: cfg.watch.interval };
+    const projectionOpts = {
+        runtime,
+        readyDelaySuffix,
+        retryInterval: cfg.watch.interval,
+        runner: cfg.cli?.runner,
+    };
     if (globalOpts.format === "json") {
         const output = globalOpts.verbose
             ? projectIterateVerbose(result, projectionOpts)
@@ -71,10 +76,8 @@ export async function handleIterate(args) {
         process.stdout.write(`${JSON.stringify(output)}\n`);
     }
     else {
-        process.stdout.write(`${formatIterateResult(result, {
-            verbose: globalOpts.verbose,
-            ...projectionOpts,
-        })}\n`);
+        const text = formatIterateResult(result, { verbose: globalOpts.verbose, ...projectionOpts });
+        process.stdout.write(`${text}\n`);
     }
     process.exitCode = iterateActionToExitCode(result.action);
 }

package/bin/cli/iterate-formatter.mjs

@@ -21,6 +21,7 @@ export function formatIterateResult(result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const retryInterval = opts?.retryInterval;
+    const runner = opts?.runner;
     const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
         ? ` · **reviewDecision** \`${result.reviewDecision}\``
@@ -56,33 +57,38 @@ export function formatIterateResult(result, opts) {
             return joinSections([
                 verbose ? header : heading,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
             ]);
         case "wait":
             return joinSections([
                 header,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
             ]);
         case "mark_ready":
             return joinSections([
                 header,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
             ]);
         case "cancel":
             return joinSections([
                 [`${heading} — ${result.reason}`, "", baseLine, summaryLine].join("\n"),
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
             ]);
         case "escalate":
             return joinSections([
                 header,
                 result.escalate.humanMessage,
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
             ]);
         case "fix_code":
-            return formatFixCodeResult(header, result, { runtime, readyDelaySuffix, retryInterval });
+            return formatFixCodeResult(header, result, {
+                runtime,
+                readyDelaySuffix,
+                retryInterval,
+                runner,
+            });
     }
 }

package/bin/cli/iterate-instructions.mjs

@@ -1,48 +1,50 @@
 import { FIX_INSTRUCTION_END_ITERATION, FIX_INSTRUCTION_STOP_AFTER_PUSH, FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK, } from "../commands/iterate/render.mjs";
+import { buildPrShepherdCommand } from "./runner.mjs";
 const DEFAULT_CODEX_RETRY_INTERVAL = "4m";
 const VALID_RETRY_INTERVAL = /^\d+[smhd]$/;
-export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval) {
-    const rerunCommand = buildCodexIterateCommand(result.pr, readyDelaySuffix);
+const CLAUDE_DYNAMIC_WAKEUP = "Schedule the next dynamic wakeup with `ScheduleWakeup` using `delaySeconds` between 60 and 240 and the same loop prompt (skip if running under a fixed-interval cron loop — the next scheduled fire handles it), then end this iteration.";
+export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner) {
+    const rerunCommand = buildCodexIterateCommand(result.pr, readyDelaySuffix, runner);
     const retryDelay = buildCodexRetryDelay(retryInterval);
     switch (result.action) {
         case "cooldown":
             return [
                 runtime === "codex"
                     ? `Continue the active Codex goal — wait about ${retryDelay}, then rerun \`${rerunCommand}\` after CI starts reporting.`
-                    : "End this iteration — the next cron fire will recheck once CI starts reporting.",
+                    : `CI still needs time to start reporting. ${CLAUDE_DYNAMIC_WAKEUP}`,
             ];
         case "wait":
             return [
                 runtime === "codex"
                     ? `Continue the active Codex goal — wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
-                    : "End this iteration — the next cron fire will recheck.",
+                    : CLAUDE_DYNAMIC_WAKEUP,
             ];
         case "mark_ready":
             return [
                 runtime === "codex"
                     ? `The CLI already marked the PR ready for review. Continue the active Codex goal until the ready-delay completes — wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
-                    : "The CLI already marked the PR ready for review — end this iteration.",
+                    : `The CLI already marked the PR ready for review. ${CLAUDE_DYNAMIC_WAKEUP}`,
             ];
         case "cancel":
             return [
                 runtime === "codex"
                     ? "Stop — no recurring Codex monitor is running to cancel."
-                    : "Invoke `/loop cancel` via the Skill tool.",
+                    : `Stop — do not schedule another dynamic wakeup. If this loop was started with a fixed-interval \`/loop\` schedule, call \`CronList\`, find the job whose prompt contains \`#pr-shepherd-loop:pr=${result.pr}:\`, and cancel it with \`CronDelete\`.`,
                 "Stop.",
             ];
         case "escalate":
             return [
                 runtime === "codex"
                     ? "Stop — no recurring Codex monitor is running to cancel."
-                    : "Invoke `/loop cancel` via the Skill tool.",
+                    : `Stop — do not schedule another dynamic wakeup. If this loop was started with a fixed-interval \`/loop\` schedule, call \`CronList\`, find the job whose prompt contains \`#pr-shepherd-loop:pr=${result.pr}:\`, and cancel it with \`CronDelete\`.`,
                 "Stop — the PR needs human direction before monitoring can resume.",
             ];
     }
 }
-export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, retryInterval) {
+export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, retryInterval, runner) {
     if (runtime !== "codex")
         return instructions;
-    const rerunCommand = buildCodexIterateCommand(pr, readyDelaySuffix);
+    const rerunCommand = buildCodexIterateCommand(pr, readyDelaySuffix, runner);
     const retryDelay = buildCodexRetryDelay(retryInterval);
     return instructions.map((instruction) => {
         if (instruction === FIX_INSTRUCTION_STOP_AFTER_PUSH) {
@@ -60,9 +62,11 @@ export function adaptIterateLog(log, runtime) {
         return log;
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }
-export function buildCodexIterateCommand(pr, readyDelaySuffix) {
+export function buildCodexIterateCommand(pr, readyDelaySuffix, runner) {
     const suffix = readyDelaySuffix?.trim();
-    return `npx pr-shepherd ${pr}${suffix ? ` --ready-delay ${suffix}` : ""}`;
+    return buildPrShepherdCommand([String(pr), ...(suffix ? ["--ready-delay", suffix] : [])], {
+        runner,
+    }).text;
 }
 export function buildCodexRetryDelay(retryInterval) {
     const interval = typeof retryInterval === "string" ? retryInterval.trim() : "";

package/bin/cli/iterate-lean.mjs

@@ -8,7 +8,8 @@ export function projectIterateLean(result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const retryInterval = opts?.retryInterval;
-    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, runtime, readyDelaySuffix, retryInterval);
+    const runner = opts?.runner;
+    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, runtime, readyDelaySuffix, retryInterval, runner);
     const base = {
         action: result.action,
         pr: result.pr,
@@ -101,7 +102,7 @@ export function projectIterateLean(result, opts) {
                     }),
                     resolveCommand: result.fix.resolveCommand,
                     ...(result.fix.instructions.length > 0 && {
-                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval),
+                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner),
                     }),
                 },
             };
@@ -134,12 +135,13 @@ export function projectIterateVerbose(result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const retryInterval = opts?.retryInterval;
+    const runner = opts?.runner;
     if (result.action === "fix_code") {
         return {
             ...result,
             fix: {
                 ...result.fix,
-                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval),
+                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner),
             },
         };
     }
@@ -149,6 +151,6 @@ export function projectIterateVerbose(result, opts) {
     return {
         ...result,
         ...log,
-        instructions: buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval),
+        instructions: buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner),
     };
 }

package/bin/cli/runner.mjs

@@ -0,0 +1,109 @@
+import { readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+export function buildPrShepherdCommand(args, opts) {
+    const runner = resolveCliRunner(opts.runner, opts.cwd);
+    const argv = baseArgvForRunner(runner).concat(args);
+    return { argv, text: renderShellCommand(argv) };
+}
+export function resolveCliRunner(runner, cwd = process.cwd()) {
+    const configured = parseCliRunner(runner);
+    return configured === "auto" ? detectPackageRunner(cwd) : configured;
+}
+export function parseCliRunner(runner) {
+    if (runner === undefined)
+        return "auto";
+    if (typeof runner !== "string") {
+        throw new Error(`Invalid config: cli.runner must be one of "auto", "npx", "pnpm", or "yarn", got ${JSON.stringify(runner)}`);
+    }
+    const value = runner.trim();
+    if (value === "auto" || value === "npx" || value === "pnpm" || value === "yarn")
+        return value;
+    throw new Error(`Invalid config: cli.runner must be one of "auto", "npx", "pnpm", or "yarn", got ${JSON.stringify(runner)}`);
+}
+export function renderShellCommand(argv) {
+    return argv.map(renderShellArg).join(" ");
+}
+function baseArgvForRunner(runner) {
+    switch (runner) {
+        case "npx":
+            return ["npx", "pr-shepherd"];
+        case "pnpm":
+            return ["pnpm", "exec", "pr-shepherd"];
+        case "yarn":
+            return ["yarn", "run", "pr-shepherd"];
+    }
+}
+const runnerCache = new Map();
+export function __resetRunnerCache() {
+    runnerCache.clear();
+}
+function detectPackageRunner(startDir) {
+    const cached = runnerCache.get(startDir);
+    if (cached)
+        return cached;
+    const home = homedir();
+    const repoRoot = findRepoRoot(startDir);
+    let current = startDir;
+    while (true) {
+        const atBoundary = current === repoRoot || current === home || current === dirname(current);
+        // Read signals for this directory unless it is home without being the repo root.
+        // This lets dotfiles repos (repoRoot === home) detect their own package manager
+        // while still preventing home's lockfiles from influencing unrelated projects.
+        if (!atBoundary || current === repoRoot) {
+            const packageManager = readPackageManager(current);
+            if (packageManager?.startsWith("pnpm@"))
+                return cacheRunner(startDir, "pnpm");
+            if (packageManager?.startsWith("yarn@"))
+                return cacheRunner(startDir, "yarn");
+            if (packageManager?.startsWith("npm@"))
+                return cacheRunner(startDir, "npx");
+            if (isFile(join(current, "pnpm-lock.yaml")))
+                return cacheRunner(startDir, "pnpm");
+            if (isFile(join(current, "yarn.lock")))
+                return cacheRunner(startDir, "yarn");
+            if (isFile(join(current, "package-lock.json")))
+                return cacheRunner(startDir, "npx");
+        }
+        if (atBoundary)
+            return cacheRunner(startDir, "npx");
+        current = dirname(current);
+    }
+}
+function cacheRunner(startDir, runner) {
+    runnerCache.set(startDir, runner);
+    return runner;
+}
+function readPackageManager(packageDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+        return typeof parsed.packageManager === "string" ? parsed.packageManager.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function findRepoRoot(startDir) {
+    let current = startDir;
+    while (true) {
+        if (statSync(join(current, ".git"), { throwIfNoEntry: false }))
+            return current;
+        if (current === dirname(current))
+            return null;
+        current = dirname(current);
+    }
+}
+function isFile(path) {
+    return statSync(path, { throwIfNoEntry: false })?.isFile() === true;
+}
+function renderShellArg(arg) {
+    if (/^\$[A-Z_][A-Z0-9_]*$/.test(arg))
+        return `"${arg}"`;
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg))
+        return arg;
+    if (!/["$`\\]/.test(arg))
+        return `"${arg}"`;
+    if (!arg.includes("'"))
+        return `'${arg}'`;
+    throw new Error(`Unexpected character in shell arg: ${JSON.stringify(arg)}`);
+}

package/bin/cli-parser.mjs

@@ -31,6 +31,7 @@ import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
 import { handleCommitSuggestion, handleIterate, handleMonitor, handleStatus, } from "./cli/handlers.mjs";
 import { setupLog } from "./log/setup.mjs";
 import { detectAgentRuntime } from "./agent-runtime.mjs";
+import { loadConfig } from "./config/load.mjs";
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
@@ -92,10 +93,11 @@ function readVersion() {
 async function handleCheck(args) {
     const { prNumber, global: globalOpts } = parseCommonArgs(args);
     const runtime = detectAgentRuntime();
+    const cfg = loadConfig();
     const report = await runCheck({ ...globalOpts, prNumber, autoResolve: false });
     const output = globalOpts.format === "json"
-        ? formatJson(report, { runtime })
-        : formatText(report, { runtime });
+        ? formatJson(report, { runtime, runner: cfg.cli?.runner })
+        : formatText(report, { runtime, runner: cfg.cli?.runner });
     process.stdout.write(`${output}\n`);
     process.exitCode = statusToExitCode(report.status);
 }

package/bin/commands/commit-suggestion.mjs

@@ -5,6 +5,8 @@ import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/cli
 import { fetchPrBatch } from "../github/batch.mjs";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
 const execFile = promisify(execFileCb);
 export async function runCommitSuggestion(opts) {
     if (!opts.threadId) {
@@ -91,11 +93,12 @@ export async function runCommitSuggestion(opts) {
         `-m ${sq(commitMessageArg)}`,
         ...commitBodyArg.split("\n\n").map((p) => `-m ${sq(p)}`),
     ].join(" ");
+    const resolveCommand = buildPrShepherdCommand(["resolve", String(prNumber), "--resolve-thread-ids", opts.threadId], { runner: loadConfig().cli?.runner }).text;
     const postActionInstructions = [
         `Apply the patch to \`${filePath}\`: run \`git apply\` with the diff shown above, or edit the file directly using the line range (${range}).`,
         `Stage the file: \`git add -- ${quotedPath}\``,
         `Commit: \`${commitCmd}\``,
-        `Resolve the thread on GitHub: \`npx pr-shepherd resolve ${prNumber} --resolve-thread-ids ${opts.threadId}\``,
+        `Resolve the thread on GitHub: \`${resolveCommand}\``,
         `Push when ready: \`git push\` (or \`git push --force-with-lease\` after rebasing).`,
     ];
     return {

package/bin/commands/iterate/classify.mjs

@@ -1,3 +1,4 @@
+import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals) {
     // First-look and seen summaries go into the minimize mutation; edited summaries do NOT —
     // they are already minimized server-side (body changed after minimize was applied).
@@ -20,8 +21,8 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals)
         surfacedApprovals: approvals,
     };
 }
-export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prNumber) {
-    const argv = ["npx", "pr-shepherd", "resolve", String(prNumber)];
+export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prNumber, runner) {
+    const argv = buildPrShepherdCommand(["resolve", String(prNumber)], { runner }).argv;
     const threadIds = [...threads.map((t) => t.id), ...resolutionOnlyThreads.map((t) => t.id)];
     if (threadIds.length > 0) {
         argv.push("--resolve-thread-ids", threadIds.join(","));

package/bin/commands/iterate/fix-code.mjs

@@ -6,7 +6,7 @@ import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun, buildInProgressRunIds } from "./helpers.mjs";
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, cliRunner, } = ctx;
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const isNewSha = stored?.headSha !== headSha;
@@ -57,7 +57,7 @@ export async function handleFixCode(ctx) {
         ? buildInProgressRunIds(report, cancelledSet)
         : [];
     const allCommentIds = [...actionableComments.map((c) => c.id), ...reviewSummaryIds];
-    const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber);
+    const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, cliRunner);
     if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],
@@ -77,7 +77,7 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, cliRunner);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,

package/bin/commands/iterate/index.mjs

@@ -117,6 +117,7 @@ export async function runIterate(opts) {
             firstLookSummaries,
             editedSummaries,
             surfacedApprovals,
+            cliRunner: config.cli?.runner,
         });
     }
     const canMarkReady = report.status === "READY" &&

package/bin/commands/iterate/render.mjs

@@ -1,34 +1,36 @@
+import { buildPrShepherdCommand, renderShellCommand } from "../../cli/runner.mjs";
 export const FIX_INSTRUCTION_STOP_AFTER_PUSH = "Stop this iteration — CI needs time to run on the new push before the next tick.";
 export const FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK = "Stop this iteration before the next tick.";
 export const FIX_INSTRUCTION_END_ITERATION = "End this iteration.";
 /**
- * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE` and whitespace-bearing
- * argv entries in double quotes for placeholder substitution. Throws if argv contains `"`, `$`,
- * `` ` ``, or `\`. `$HEAD_SHA` is appended separately when `requiresHeadSha` is set.
+ * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE`, `$HEAD_SHA`, and
+ * whitespace-bearing argv entries for placeholder substitution. `$HEAD_SHA` is appended separately
+ * when `requiresHeadSha` is set.
  */
 export function renderResolveCommand(rc) {
-    const needsQuoting = (arg) => {
-        if (arg === "$DISMISS_MESSAGE")
-            return true;
-        if (/["$`\\]/.test(arg)) {
-            throw new Error(`Unexpected character in argv arg that needsQuoting can't handle: ${JSON.stringify(arg)}`);
-        }
-        return /\s/.test(arg);
-    };
-    const parts = rc.argv.map((a) => (needsQuoting(a) ? `"${a}"` : a));
+    const parts = [...rc.argv];
     if (rc.requiresHeadSha) {
-        parts.push("--require-sha", '"$HEAD_SHA"');
+        parts.push("--require-sha", "$HEAD_SHA");
     }
-    return parts.join(" ");
+    return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = []) {
+export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], runner) {
     const instructions = [];
     if (inProgressRunIds.length > 0) {
         instructions.push(`Cancel in-progress CI runs first: for each ID under \`## In-progress runs\`, run \`gh run cancel <id>\`. Do this before applying any code fixes — the push at the end of this iteration will supersede those runs anyway, so letting them continue burns CI minutes for results no one will read. If \`gh\` reports a run is already completed, ignore it and continue with the next ID.`);
     }
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions) {
-        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the \`resolve:\` command below (the thread is not auto-resolved). If the patch fails to apply, fall through to the manual-edit step. Do not retry the same command.`);
+        const commitSuggestionCommand = buildPrShepherdCommand([
+            "commit-suggestion",
+            String(prNumber),
+            "--thread-id",
+            "<id>",
+            "--message",
+            "<one-sentence headline>",
+            "--format=json",
+        ], { runner }).text;
+        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`${commitSuggestionCommand}\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the \`resolve:\` command below (the thread is not auto-resolved). If the patch fails to apply, fall through to the manual-edit step. Do not retry the same command.`);
     }
     if (threads.length > 0 || actionableComments.length > 0) {
         const suggestionFallback = hasSuggestions

package/bin/commands/monitor.mjs

@@ -1,6 +1,7 @@
 import { getCurrentPrNumber } from "../github/client.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { joinSections } from "../util/markdown.mjs";
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
 export async function runMonitor(opts) {
     const config = loadConfig();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -18,8 +19,8 @@ export async function runMonitor(opts) {
     // block depend on this exact string — don't change the format.
     const loopTag = `#pr-shepherd-loop:pr=${prNumber}:`;
     const loopArgs = interval;
-    const reusableCommand = buildIterateCommand(prNumber, opts.readyDelaySuffix);
-    const loopPrompt = buildLoopPrompt(prNumber, loopTag, reusableCommand, loopArgs, opts.runtime ?? "claude");
+    const reusableCommand = buildIterateCommand(prNumber, opts.readyDelaySuffix, config.cli?.runner);
+    const loopPrompt = buildLoopPrompt(prNumber, loopTag, reusableCommand, loopArgs, opts.runtime ?? "claude", config.cli?.runner);
     return {
         prNumber,
         loopTag,
@@ -72,11 +73,11 @@ function validateReadyDelaySuffix(readyDelaySuffix) {
     }
     return trimmed;
 }
-function buildIterateCommand(prNumber, readyDelaySuffix) {
+function buildIterateCommand(prNumber, readyDelaySuffix, runner) {
     const validatedDelay = validateReadyDelaySuffix(readyDelaySuffix);
-    return `npx pr-shepherd ${prNumber}${validatedDelay ? ` --ready-delay ${validatedDelay}` : ""}`;
+    return buildPrShepherdCommand([String(prNumber), ...(validatedDelay ? ["--ready-delay", validatedDelay] : [])], { runner }).text;
 }
-function buildLoopPrompt(prNumber, loopTag, iterateCmd, loopArgs, runtime = "claude") {
+function buildLoopPrompt(prNumber, loopTag, iterateCmd, loopArgs, runtime = "claude", runner) {
     if (runtime === "codex") {
         return [
             loopTag,
@@ -85,7 +86,7 @@ function buildLoopPrompt(prNumber, loopTag, iterateCmd, loopArgs, runtime = "cla
             "- Run the command below once and follow its `## Instructions` exactly.",
             `- If the output tells you to continue the active Codex goal, wait about the configured interval (${loopArgs}) and rerun the reusable command from the monitor output.`,
             "- Stop only when Shepherd emits `[CANCEL]` because the ready-delay completed or the PR was merged/closed, or when Shepherd emits `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).",
-            "- Do not call `/loop`, `ScheduleWakeup`, `CronCreate`, or `npx pr-shepherd monitor`; Codex recurrence is explicit `iterate` command cycles.",
+            `- Do not call \`/loop\`, \`ScheduleWakeup\`, \`CronCreate\`, or \`${buildPrShepherdCommand(["monitor", String(prNumber)], { runner }).text}\`; Codex recurrence is explicit \`iterate\` command cycles.`,
             "",
             "Run in a single Bash call:",
             `  ${iterateCmd}`,

package/bin/commands/resolve-instructions.mjs

@@ -1,9 +1,10 @@
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
 /**
  * Build the numbered triage/fix/resolve instruction steps for the agent to follow.
  * Steps are conditionally emitted based on what the fetch returned (mirrors
  * `buildFixInstructions` in `commands/iterate/render.mts`).
  */
-export function buildFetchInstructions(prNumber, result) {
+export function buildFetchInstructions(prNumber, result, runner) {
     const { actionableThreads, resolutionOnlyThreads, firstLookThreads, actionableComments, firstLookComments, changesRequestedReviews, reviewSummaries, commitSuggestionsEnabled, } = result;
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     const total = actionableThreads.length +
@@ -30,7 +31,16 @@ export function buildFetchInstructions(prNumber, result) {
         instructions.push(`First-look bullets tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body before deciding whether any matching \`## Review threads to resolve\` item should be resolved.`);
     }
     if (hasSuggestions) {
-        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the resolve command below (the thread is not auto-resolved). If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step. Do not retry the same \`commit-suggestion\` invocation.`);
+        const commitSuggestionCommand = buildPrShepherdCommand([
+            "commit-suggestion",
+            String(prNumber),
+            "--thread-id",
+            "<id>",
+            "--message",
+            "<one-sentence headline>",
+            "--format=json",
+        ], { runner }).text;
+        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`${commitSuggestionCommand}\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the resolve command below (the thread is not auto-resolved). If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step. Do not retry the same \`commit-suggestion\` invocation.`);
     }
     if (hasCodeItems) {
         instructions.push(`Read and edit each file referenced under \`## Actionable Review Threads\`, \`## Actionable PR Comments\`, and \`## Pending CHANGES_REQUESTED reviews\` above. Reclassify each fixed item as Fixed. If an item is too complex to address, leave it as Actionable for the final report.`);
@@ -50,7 +60,10 @@ export function buildFetchInstructions(prNumber, result) {
         : reviewSummaries.length > 0
             ? ` Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`.`
             : "";
-    instructions.push(`Run \`npx pr-shepherd resolve ${prNumber} [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids> --message "<reason>"]\` with only the non-empty flag subsets. Skip the command entirely if all three ID lists are empty.${requireShaHint}${dismissNote}`);
+    const resolveCommand = `${buildPrShepherdCommand(["resolve", String(prNumber)], {
+        runner,
+    }).text} [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids> --message "<reason>"]`;
+    instructions.push(`Run \`${resolveCommand}\` with only the non-empty flag subsets. Skip the command entirely if all three ID lists are empty.${requireShaHint}${dismissNote}`);
     instructions.push(`For any large decisions or rejections you made this iteration, add or update a \`## Shepherd Journal\` section in the PR description (\`gh pr edit ${prNumber} --body …\`) summarizing each decision. For threads and comments, use the markdown link shown in each item's bullet above; for reviews, reference the review ID.`);
     instructions.push(`Report: echo the CLI's mutation output, then one line per Acknowledged item: \`Acknowledged <id> (@<author>): <reason>\`. If any fetched item was neither resolved nor acknowledged, stop and escalate: "<N> item(s) fetched but not acted on or acknowledged — need human direction before closing".`);
     return instructions;

package/bin/commands/resolve.mjs

@@ -126,7 +126,7 @@ export async function runResolveFetch(opts) {
         reviewSummaries: cfg.resolve.fetchReviewSummaries ? data.reviewSummaries : [],
         commitSuggestionsEnabled: cfg.actions.commitSuggestions,
     };
-    return { ...result, instructions: buildFetchInstructions(prNumber, result) };
+    return { ...result, instructions: buildFetchInstructions(prNumber, result, cfg.cli?.runner) };
 }
 export async function runResolveMutate(opts) {
     const repo = await getRepoInfo();

package/bin/config/load.mjs

@@ -3,6 +3,7 @@ import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { parse } from "yaml";
 import builtins from "../config.json" with { type: "json" };
+import { parseCliRunner } from "../cli/runner.mjs";
 const RC_FILENAME = ".pr-shepherdrc.yml";
 function findRcFile(startDir) {
     const home = homedir();
@@ -51,6 +52,15 @@ export function loadConfig() {
         const raw = readFileSync(rcPath, "utf8");
         const parsed = (parse(raw) ?? {});
         const config = deepMerge(defaults, parsed);
+        // Validate cli and watch at load time so misconfigurations are caught once
+        // with the rc file path in context, rather than during instruction rendering.
+        if (config.cli === null || Array.isArray(config.cli) || typeof config.cli !== "object") {
+            throw new Error(`Invalid config: cli must be a plain object, got ${JSON.stringify(config.cli)}`);
+        }
+        config.cli.runner = parseCliRunner(config.cli.runner);
+        if (typeof config.watch?.interval !== "string" || !/^\d+[smhd]$/.test(config.watch.interval)) {
+            throw new Error(`Invalid config: watch.interval must be a duration string like "4m" or "1h", got ${JSON.stringify(config.watch?.interval)}`);
+        }
         configCache.set(cwd, config);
         return config;
     }

package/bin/config.json

@@ -1,4 +1,7 @@
 {
+  "cli": {
+    "runner": "auto"
+  },
   "iterate": {
     "cooldownSeconds": 30,
     "fixAttemptsPerThread": 3,

package/bin/reporters/check-instructions.mjs

@@ -1,3 +1,4 @@
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
 /**
  * Build the numbered instruction steps for the agent to follow after a `check` run.
  * All rebase policy, CI budget policy, and ready-to-merge gating live here so the
@@ -59,7 +60,7 @@ export function buildCheckInstructions(report, opts) {
     // 5. Continuous monitoring pointer (suppressed only when truly ready to merge)
     if (!isReady) {
         instructions.push(runtime === "codex"
-            ? `This is a one-shot check. For follow-up monitoring, run \`npx pr-shepherd ${report.pr}\`.`
+            ? `This is a one-shot check. For follow-up monitoring, run \`${buildPrShepherdCommand([String(report.pr)], { runner: opts?.runner }).text}\`.`
             : "This is a one-shot check. For continuous monitoring that acts on these signals automatically, use `/pr-shepherd:monitor`.");
     }
     return instructions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -29,7 +29,7 @@
     "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
-    "oxfmt": "^0.46.0",
+    "oxfmt": "^0.47.0",
     "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4"

package/plugin/skills/monitor/SKILL.md

@@ -4,7 +4,18 @@ description: "Start continuous CI monitoring — marks PR ready for review when
 argument-hint: "[PR number or URL]"
 user-invocable: true
 allowed-tools:
-  ["Bash", "Read", "Grep", "Edit", "Write", "Glob", "Skill", "CronCreate", "CronList", "CronDelete"]
+  [
+    "Bash",
+    "Read",
+    "Grep",
+    "Edit",
+    "Write",
+    "Glob",
+    "Skill",
+    "ScheduleWakeup",
+    "CronList",
+    "CronDelete",
+  ]
 ---
 
 # pr-shepherd monitor — Continuous PR Monitor

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",
@@ -10,14 +10,7 @@
   "homepage": "https://github.com/jonathanong/pr-shepherd",
   "repository": "https://github.com/jonathanong/pr-shepherd",
   "license": "MIT",
-  "keywords": [
-    "github",
-    "pull-request",
-    "ci",
-    "code-review",
-    "automation",
-    "codex"
-  ],
+  "keywords": ["github", "pull-request", "ci", "code-review", "automation", "codex"],
   "skills": "../skills/",
   "interface": {
     "displayName": "pr-shepherd",
@@ -25,10 +18,7 @@
     "longDescription": "Use pr-shepherd from Codex to check pull requests, resolve review feedback, and keep explicit iterate cycles running until a PR is ready, merged, closed, or escalated.",
     "developerName": "Jonathan Ong",
     "category": "Coding",
-    "capabilities": [
-      "Interactive",
-      "Write"
-    ],
+    "capabilities": ["Interactive", "Write"],
     "websiteURL": "https://github.com/jonathanong/pr-shepherd",
     "privacyPolicyURL": "https://github.com/jonathanong/pr-shepherd",
     "termsOfServiceURL": "https://github.com/jonathanong/pr-shepherd",

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr-shepherd
-description: 'Codex-only skill for checking, updating, monitoring, or resolving a GitHub pull request with pr-shepherd. Use for requests like "check this PR", "use pr-shepherd", "iterate PR #123", "resolve this PR''s comments", or "run pr-shepherd until this PR is ready". For open-ended requests, create a Codex goal and run explicit `npx --no-install pr-shepherd PR_NUMBER` cycles every configured interval until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` including repeated unchanged CI failures.'
+description: 'Codex-only skill for checking, updating, monitoring, or resolving a GitHub pull request with pr-shepherd. Use for requests like "check this PR", "use pr-shepherd", "iterate PR #123", "resolve this PR''s comments", or "run pr-shepherd until this PR is ready". For open-ended requests, create a Codex goal and run explicit `npx --no-install pr-shepherd PR_NUMBER` cycles, picking a fresh sleep/timeout between 1 and 4 minutes before each rerun until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` including repeated unchanged CI failures.'
 ---
 
 # pr-shepherd
@@ -19,7 +19,7 @@ Codex-only workflow for getting actionable PR updates from `pr-shepherd`.
 2. Decide whether this is one cycle or an open-ended goal.
    - For one-off requests such as "check this PR", "run pr-shepherd once", or "resolve this PR's comments", run one explicit CLI command.
    - For requests such as "continue", "until ready", "until this PR is ready", or "keep iterating", create a Codex goal before the first recurring cycle with this objective:
-     `Run npx --no-install pr-shepherd PR_NUMBER cycles every configured interval until Shepherd emits [CANCEL] for ready-delay completion or PR #PR_NUMBER is merged/closed, or pr-shepherd escalates, including repeated unchanged CI failures.`
+     `Run npx --no-install pr-shepherd PR_NUMBER cycles, picking a fresh sleep/timeout between 1 and 4 minutes before each rerun, until Shepherd emits [CANCEL] for ready-delay completion or PR #PR_NUMBER is merged/closed, or pr-shepherd escalates, including repeated unchanged CI failures.`
 
 3. Verify the CLI is available.
    - In the pr-shepherd source checkout, before any `npx --no-install pr-shepherd` invocation, verify `bin/` and `node_modules/` exist. If either is missing, run:
@@ -41,7 +41,7 @@ Codex-only workflow for getting actionable PR updates from `pr-shepherd`.
 
 6. Do not call `/loop`, `ScheduleWakeup`, `CronCreate`, or `npx pr-shepherd monitor` for recurrence. Codex does explicit `pr-shepherd PR_NUMBER` cycles.
 
-7. For open-ended goal requests, complete the CLI-provided instructions for the current cycle. If the output says to continue the active Codex goal, wait for the configured interval named in the output and run another explicit `pr-shepherd PR_NUMBER` cycle.
+7. For open-ended goal requests, complete the CLI-provided instructions for the current cycle. If the output says to continue the active Codex goal, pick a fresh sleep/timeout between 1 and 4 minutes, wait that long, and run another explicit `pr-shepherd PR_NUMBER` cycle.
 
 8. Do not stop an open-ended goal only because the output is `[WAIT]`, `[COOLDOWN]`, `[MARK_READY]`, or a post-fix CI wait. These are nonterminal Codex recurrence states.