pr-shepherd 0.13.1 → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/README.md +22 -18
  3. package/bin/cli/fix-formatter.mjs +2 -1
  4. package/bin/cli/formatters.mjs +27 -2
  5. package/bin/cli/handlers.mjs +8 -5
  6. package/bin/cli/iterate-formatter.mjs +12 -6
  7. package/bin/cli/iterate-instructions.mjs +15 -11
  8. package/bin/cli/iterate-lean.mjs +6 -4
  9. package/bin/cli/runner.mjs +109 -0
  10. package/bin/cli-parser.mjs +4 -2
  11. package/bin/commands/commit-suggestion.mjs +4 -1
  12. package/bin/commands/iterate/classify.mjs +3 -2
  13. package/bin/commands/iterate/fix-code.mjs +3 -3
  14. package/bin/commands/iterate/index.mjs +1 -0
  15. package/bin/commands/iterate/render.mjs +18 -16
  16. package/bin/commands/monitor.mjs +7 -6
  17. package/bin/commands/resolve-instructions.mjs +16 -3
  18. package/bin/commands/resolve.mjs +1 -1
  19. package/bin/comments/pending-ops.mjs +20 -0
  20. package/bin/comments/rate-limit.mjs +45 -0
  21. package/bin/comments/resolve.mjs +38 -34
  22. package/bin/comments/sha-poll.mjs +25 -0
  23. package/bin/config/load.mjs +10 -0
  24. package/bin/config.json +3 -0
  25. package/bin/github/client.mjs +2 -1
  26. package/bin/github/errors.mjs +12 -0
  27. package/bin/github/http.mjs +17 -5
  28. package/bin/reporters/check-instructions.mjs +2 -1
  29. package/package.json +2 -2
  30. package/plugin/skills/check/SKILL.md +3 -1
  31. package/plugin/skills/monitor/SKILL.md +15 -2
  32. package/plugin/skills/resolve/SKILL.md +3 -1
  33. package/plugins/pr-shepherd/.codex-plugin/plugin.json +1 -1
  34. package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md +22 -17
package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: pr-shepherd
3
- 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.'
3
+ 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 pr-shepherd cycles through the target repo package runner, 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.'
4
4
  ---
5
5
 
6
6
  # pr-shepherd
@@ -19,32 +19,37 @@ Codex-only workflow for getting actionable PR updates from `pr-shepherd`.
19
19
  2. Decide whether this is one cycle or an open-ended goal.
20
20
  - For one-off requests such as "check this PR", "run pr-shepherd once", or "resolve this PR's comments", run one explicit CLI command.
21
21
  - 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:
22
- `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.`
22
+ `Run pr-shepherd PR_NUMBER cycles through the target repo package runner, 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.`
23
23
 
24
- 3. Verify the CLI is available.
25
- - 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:
24
+ 3. Select the package runner from the target repository root.
25
+ - Prefer `package.json` `packageManager`: `pnpm@...` -> `pnpm exec`, `yarn@...` -> `yarn run`, `npm@...` -> `npx --no-install`.
26
+ - If `packageManager` is absent, use lockfiles: `pnpm-lock.yaml` -> `pnpm exec`, `yarn.lock` -> `yarn run`, `package-lock.json` or no signal -> `npx --no-install`.
27
+ - Example: in `~/filaments`, use `pnpm exec pr-shepherd ...` because the root package declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml`.
28
+
29
+ 4. Verify the CLI is available.
30
+ - Only when the target repository itself is the pr-shepherd source checkout, verify `bin/` and `node_modules/` exist before any local CLI invocation. If either is missing, run the source checkout's package-manager install command. This repository currently uses npm, so run:
26
31
  `npm install`
27
- - 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`.
32
+ - In other repositories, run through the selected package runner so Codex does not install packages implicitly. If the package is missing, tell the user to install `pr-shepherd` with the matching dev-dependency command: `pnpm add -D pr-shepherd`, `yarn add -D pr-shepherd`, or `npm install --save-dev pr-shepherd`.
28
33
 
29
- 4. Run the appropriate command from the repository root.
34
+ 5. Run the appropriate command from the repository root.
30
35
  - For a status check:
31
- `npx --no-install pr-shepherd check PR_NUMBER`
36
+ `<runner> pr-shepherd check PR_NUMBER`
32
37
  - For review comment resolution:
33
- `npx --no-install pr-shepherd resolve PR_NUMBER --fetch`
38
+ `<runner> pr-shepherd resolve PR_NUMBER --fetch`
34
39
  - For a monitor bootstrap:
35
- `npx --no-install pr-shepherd monitor PR_NUMBER`
40
+ `<runner> pr-shepherd monitor PR_NUMBER`
36
41
  - For the recurring explicit monitor tick:
37
- `npx --no-install pr-shepherd PR_NUMBER`
38
- - `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.
42
+ `<runner> pr-shepherd PR_NUMBER`
43
+ - `pr-shepherd iterate PR_NUMBER` remains supported as a legacy alias, but use the default `pr-shepherd PR_NUMBER` form for recurring Codex cycles.
39
44
 
40
- 5. Print or summarize the important status, then follow the output's `## Instructions` exactly.
45
+ 6. Print or summarize the important status, then follow the output's `## Instructions` exactly.
41
46
 
42
- 6. Do not call `/loop`, `ScheduleWakeup`, `CronCreate`, or `npx pr-shepherd monitor` for recurrence. Codex does explicit `pr-shepherd PR_NUMBER` cycles.
47
+ 7. Do not call `/loop`, `ScheduleWakeup`, `CronCreate`, or `pr-shepherd monitor` for recurrence. Codex does explicit `pr-shepherd PR_NUMBER` cycles.
43
48
 
44
- 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.
49
+ 8. 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 through the same runner.
45
50
 
46
- 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.
51
+ 9. 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.
47
52
 
48
- 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.
53
+ 10. 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.
49
54
 
50
- 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.
55
+ 11. 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.