| name | pr-shepherd |
| description | Iterate a GitHub pull request to completion with pr-shepherd. Use for requests like "use pr-shepherd", "iterate PR #123", or "run pr-shepherd until this PR is ready". |
| user-invocable | true |
| argument-hint | [PR number or URL] |
| allowed-tools | ["Bash","Read","Grep","Edit","Write","Glob","Skill"] |
pr-shepherd
Poll dispatcher for iterating a PR to completion.
Arguments: $ARGUMENTS
Steps
-
Resolve the PR number ($N): use the number or URL in $ARGUMENTS; otherwise infer it with gh pr view --json number --jq .number. If none is found, report an error and stop.
-
Define the poll command once: pr-shepherd $N --interval 60s --until-terminal --quiet-status. Do not forward $ARGUMENTS as extra flags. Run pr-shepherd --help to inspect supported options.
-
Loop: Run the poll, print its full output, and follow its ## Instructions section exactly. Then run the poll again. Repeat until the CLI emits [CANCEL] or [ESCALATE], unless the human directs you to stop. [FIX_CODE] is non-terminal: do its instructions, then poll again. The poll already waits between ticks via --interval; do not add manual sleeps between ticks.
-
Nonzero exit codes: Treat a nonzero poll exit as PR state only when the output contains a matching # PR #$N [ACTION] heading. Exit 1 can also mean a command or validation failure; if there is no [ACTION] heading, surface the error and stop instead of looping.
-
Terminal states (stop):
[CANCEL] — ready-delay completed, or PR merged/closed.[ESCALATE] — needs human direction (includes stall-timeout for repeated unchanged CI failures or CI that never starts).- Do NOT merge the pull request unless the human has explicitly requested or allowed it.
