pr-shepherd 0.12.0 → 0.13.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "jonathanong",
+  "interface": {
+    "displayName": "Jonathan Ong"
+  },
+  "plugins": [
+    {
+      "name": "pr-shepherd",
+      "source": {
+        "source": "local",
+        "path": "./plugins/pr-shepherd"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Coding"
+    }
+  ]
+}

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.12.0",
+  "version": "0.13.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -205,7 +205,18 @@ On each tick (4-minute default, tunable via `watch.interval`): fetch PR state in
 >
 > A plain `npm install pr-shepherd` adds it to regular dependencies instead; use that only if you specifically want it under `dependencies`. Or install globally: `npm install -g pr-shepherd`.
 
-### As individual skills via `npx skills`
+### Claude Code
+
+Install as a Claude Code plugin:
+
+```bash
+claude /plugin marketplace add jonathanong/pr-shepherd
+claude /plugin install pr-shepherd
+```
+
+This repo ships two `marketplace.json` files that serve different Claude install flows: the root `marketplace.json` resolves the plugin from the npm registry (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
+
+Alternatively, install the Claude skills individually via `npx skills`:
 
 ```bash
 npx skills add jonathanong/pr-shepherd
@@ -213,23 +224,39 @@ npx skills add jonathanong/pr-shepherd
 
 Installs the three skills (`check`, `monitor`, `resolve`) into your agent's skill directory (`.claude/skills/` for project scope, `~/.claude/skills/` with `-g` for global scope). Powered by [skills.sh](https://skills.sh).
 
-### As a Claude Code plugin (recommended)
+### Codex
+
+Codex uses the repo-shipped Codex plugin rather than the Claude plugin or `/pr-shepherd:*` slash commands. The plugin provides one umbrella `pr-shepherd` skill for check, resolve, monitor, and iterate workflows.
+
+Install the Codex plugin marketplace from GitHub:
 
 ```bash
-claude /plugin marketplace add jonathanong/pr-shepherd
-claude /plugin install pr-shepherd
+codex plugin marketplace add jonathanong/pr-shepherd
+```
+
+Or pin a branch/tag/ref:
+
+```bash
+codex plugin marketplace add jonathanong/pr-shepherd --ref main
 ```
 
-This repo ships two `marketplace.json` files that serve different install flows: the root `marketplace.json` resolves the plugin from the npm registry (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
+For local development, point Codex at a checkout:
 
-### For Codex
+```bash
+git clone https://github.com/jonathanong/pr-shepherd ~/.codex/plugin-sources/pr-shepherd
+codex plugin marketplace add ~/.codex/plugin-sources/pr-shepherd
+```
 
-Codex does not use the Claude plugin or `/pr-shepherd:*` slash commands. Install the CLI where Codex will run it, then call `npx pr-shepherd` directly:
+After adding the marketplace, open the Codex plugin directory, choose the `jonathanong` marketplace, and install/enable `pr-shepherd`. The marketplace root must contain `.agents/plugins/marketplace.json` and `plugins/pr-shepherd/`.
+
+Install the CLI where Codex will run it:
 
 ```bash
 npm install --save-dev pr-shepherd
 ```
 
+The plugin only installs the skill; it does not install the CLI into target repositories. To install the CLI globally instead, use `npm install -g pr-shepherd`.
+
 If your Codex environment does not already set `CODEX_CI=1`, set `AGENT=codex` so `pr-shepherd` emits Codex-compatible instructions instead of Claude `/loop` instructions:
 
 ```bash
@@ -242,7 +269,7 @@ Then start a PR monitor from Codex:
 npx pr-shepherd monitor 42
 ```
 
-Follow the output's `## Instructions`. The monitor bootstrap runs one tick and prints the reusable follow-up command, usually:
+Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until this PR is ready`. Follow the output's `## Instructions`. The monitor bootstrap runs one tick and prints the reusable follow-up command, usually:
 
 ```bash
 npx pr-shepherd 42
@@ -276,14 +303,14 @@ actions:
   autoMarkReady: false # disable to stay draft until you manually promote
 ```
 
-Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`), `PR_SHEPHERD_STATE_DIR` (override loop-state and log base dir), `PR_SHEPHERD_LOG_DISABLED=1` (disable the per-worktree debug log), `AGENT=codex` or `CODEX_CI=1` (emit Codex-compatible monitor instructions).
+Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`, then `GITHUB_PERSONAL_ACCESS_TOKEN`), `PR_SHEPHERD_STATE_DIR` (override loop-state and log base dir), `PR_SHEPHERD_LOG_DISABLED=1` (disable the per-worktree debug log), `AGENT=codex` or `CODEX_CI=1` (emit Codex-compatible monitor instructions).
 
 See [docs/configuration.md](docs/configuration.md) for full semantics and deprecated-key migration.
 
 ## Requirements
 
 - Node.js ≥ 22.0.0
-- A GitHub token: set `GH_TOKEN` or `GITHUB_TOKEN`, **or** install and authenticate the `gh` CLI (`gh auth login`) — pr-shepherd uses `gh auth token` as a fallback. The `repo` scope is required for private repositories.
+- A GitHub token: set `GH_TOKEN` or `GITHUB_TOKEN`, **or** install and authenticate the `gh` CLI (`gh auth login`) — pr-shepherd uses `gh auth token` as a fallback before trying `GITHUB_PERSONAL_ACCESS_TOKEN`. The `repo` scope is required for private repositories.
 - `git`
 
 ## Docs

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

@@ -52,12 +52,10 @@ export async function handleFixCode(ctx) {
     const checks = toAgentChecks(failingChecks);
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
-    const needsPush = threads.length > 0 ||
-        actionableComments.length > 0 ||
-        checks.length > 0 ||
-        changesRequestedReviews.length > 0 ||
-        hasConflicts;
-    const inProgressRunIds = needsPush ? buildInProgressRunIds(report, cancelledSet) : [];
+    const hasGuaranteedSupersedingPush = threads.length > 0 || checks.length > 0 || changesRequestedReviews.length > 0 || hasConflicts;
+    const inProgressRunIds = hasGuaranteedSupersedingPush
+        ? buildInProgressRunIds(report, cancelledSet)
+        : [];
     const allCommentIds = [...actionableComments.map((c) => c.id), ...reviewSummaryIds];
     const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber);
     if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {

package/bin/commands/iterate/render.mjs

@@ -60,7 +60,7 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (reviews.length > 0) {
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.`);
     }
-    const hasCodeChanges = threads.length > 0 || actionableComments.length > 0 || checks.length > 0 || reviews.length > 0;
+    const hasCodeChanges = threads.length > 0 || checks.length > 0 || reviews.length > 0;
     const needsPush = hasCodeChanges || hasConflicts;
     if (hasCodeChanges) {
         instructions.push(`Commit changed files: \`git add <files> && git commit -m "<descriptive message>"\``);

package/bin/github/http.mjs

@@ -30,7 +30,12 @@ async function resolveToken() {
     catch {
         // fall through to error
     }
-    throw new Error("No GitHub token found. Set GH_TOKEN or GITHUB_TOKEN, or run `gh auth login`.");
+    const codexToken = process.env["GITHUB_PERSONAL_ACCESS_TOKEN"];
+    if (codexToken) {
+        _token = codexToken;
+        return _token;
+    }
+    throw new Error("No GitHub token found. Set GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN, or run `gh auth login`.");
 }
 async function makeHeaders() {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -11,7 +11,10 @@
   "files": [
     "bin/**",
     "plugin/**",
+    "plugins/**",
+    "plugins/**/.codex-plugin/**",
     ".claude-plugin/**",
+    ".agents/plugins/marketplace.json",
     "marketplace.json",
     "README.md",
     "LICENSE"
@@ -36,9 +39,9 @@
     "prepare": "node scripts/install-husky.mjs && node scripts/install-plugin-symlink.mjs && npm run build",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "typecheck": "tsc --noEmit",
-    "lint": "oxlint src/ plugin/skills/",
-    "format": "oxfmt src/ plugin/skills/ docs/ README.md",
-    "format:check": "oxfmt --check src/ plugin/skills/ docs/ README.md",
+    "lint": "oxlint src/ plugin/skills/ plugins/ .agents/plugins/",
+    "format": "oxfmt src/ plugin/skills/ plugins/ .agents/plugins/ docs/ README.md",
+    "format:check": "oxfmt --check src/ plugin/skills/ plugins/ .agents/plugins/ docs/ README.md",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest"

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

@@ -0,0 +1,43 @@
+{
+  "name": "pr-shepherd",
+  "version": "0.13.0",
+  "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
+  "author": {
+    "name": "Jonathan Ong",
+    "email": "jonathanrichardong@gmail.com",
+    "url": "https://github.com/jonathanong"
+  },
+  "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"
+  ],
+  "skills": "../skills/",
+  "interface": {
+    "displayName": "pr-shepherd",
+    "shortDescription": "Monitor PR CI and review comments from Codex",
+    "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"
+    ],
+    "websiteURL": "https://github.com/jonathanong/pr-shepherd",
+    "privacyPolicyURL": "https://github.com/jonathanong/pr-shepherd",
+    "termsOfServiceURL": "https://github.com/jonathanong/pr-shepherd",
+    "defaultPrompt": [
+      "Check this PR with pr-shepherd",
+      "Run pr-shepherd until this PR is ready",
+      "Resolve this PR's review comments"
+    ],
+    "brandColor": "#2563EB",
+    "screenshots": []
+  }
+}

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

@@ -0,0 +1,50 @@
+---
+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.'
+---
+
+# pr-shepherd
+
+Codex-only workflow for getting actionable PR updates from `pr-shepherd`.
+
+## Workflow
+
+1. Resolve the PR number.
+   - If the user provides a PR number, use it.
+   - If the user provides a GitHub PR URL, extract the PR number.
+   - If no PR is provided, infer it from the current branch with:
+     `gh pr view --json number --jq .number`
+   - If no PR is found, report that and stop.
+
+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.`
+
+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:
+     `npm install`
+   - In other repositories, use `npx --no-install pr-shepherd` so Codex does not install packages implicitly. If that fails because the package is missing, tell the user to install `pr-shepherd` in the target repo with `npm install --save-dev pr-shepherd`.
+
+4. Run the appropriate command from the repository root.
+   - For a status check:
+     `npx --no-install pr-shepherd check PR_NUMBER`
+   - For review comment resolution:
+     `npx --no-install pr-shepherd resolve PR_NUMBER --fetch`
+   - For a monitor bootstrap:
+     `npx --no-install pr-shepherd monitor PR_NUMBER`
+   - For the recurring explicit monitor tick:
+     `npx --no-install pr-shepherd PR_NUMBER`
+   - `npx --no-install pr-shepherd iterate PR_NUMBER` remains supported as a legacy alias, but use the default `pr-shepherd PR_NUMBER` form for recurring Codex cycles.
+
+5. Print or summarize the important status, then follow the output's `## Instructions` exactly.
+
+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.
+
+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.
+
+9. Stop only when Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or when it emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures. If a Codex goal is active, mark it complete only when one of those terminal conditions is actually satisfied.
+
+10. If the output includes fixes, pushes, rebases, or resolve commands, perform only the instructed scoped actions. Do not resolve, minimize, or dismiss comments until the CLI-provided post-push and `--require-sha` instructions are satisfied.