pull-request
When the bundled pr skill or built-in commit-push-pr command resolves in this session, prefer pr for a one-shot PR from committed work and commit-push-pr to commit, push and open one at once, only when no draft, body contract, or later ready, monitor, or merge step applies; this skill otherwise. Orchestrate the full PR lifecycle: prep (review + verify), create, ready (update branch, security review + verify, flip), monitor CI + review comments, merge, and fetch CI logs. Use when: 'create pr', 'ship it', 'pr prep', 'mark ready', 'ready for review', 'fix CI', 'address comments', 'monitor PR', 'merge this', 'check pr status', not for the all-PR babysit loop (use /babysit-prs), branch/worktree lifecycle (use /worktree), or committing without a PR (use /commit).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 30
- Forks
- 7
01 前言 Front Matter
- metadata
- { "summary": "Full PR lifecycle. Prep, create, monitor CI, address reviews, merge", "workflow-stage": "pr" }
- description
- When the bundled pr skill or built-in commit-push-pr command resolves in this session, prefer pr for a one-shot PR from committed work and commit-push-pr to commit, push and open one at once, only when no draft, body contract, or later ready, monitor, or merge step applies; this skill otherwise. Orchestrate the full PR lifecycle: prep (review + verify), create, ready (update branch, security review + verify, flip), monitor CI + review comments, merge, and fetch CI logs. Use when: 'create pr', 'ship it', 'pr prep', 'mark ready', 'ready for review', 'fix CI', 'address comments', 'monitor PR', 'merge this', 'check pr status', not for the all-PR babysit loop (use /babysit-prs), branch/worktree lifecycle (use /worktree), or committing without a PR (use /commit).
- argument-hint
- [prep|create|ready|monitor|comments|ci|merge|reassess|evidence|status|full|…] [--unattended] [args]
- user-invocable
- true
- disable-model-invocation
- false
02 资源文件 93
- 参考文档.claude/source-control.md562 B
- 参考文档evals/docs/conventions/source-control.yaml395 B
- 参考文档evals/evals.json87.6 KB
- 参考文档evals/fixtures/ci-status-security-fail.md715 B
- 参考文档evals/fixtures/source-control-open-draft.yaml122 B
- 参考文档evals/fixtures/source-control-open-invalid.yaml131 B
- 参考文档evals/fixtures/source-control-open-ready.yaml122 B
- 参考文档evals/fixtures/source-control-pre-ready-security-off.yaml211 B
- 参考文档evals/fixtures/source-control-pre-ready-unknown-step.yaml198 B
- 参考文档evals/fixtures/source-control-prep-audits-replace-markdown.yaml270 B
- 参考文档evals/fixtures/source-control-prep-audits-unknown-class.yaml206 B
- 参考文档evals/fixtures/source-control-required-none.yaml195 B
- 参考文档evals/fixtures/source-control-required-related.yaml228 B
- 参考文档evals/fixtures/source-control-required-summary-test-plan.yaml221 B
- 参考文档reference/ci-ci.md10.4 KB
- 参考文档reference/comments-ci.md11.7 KB
- 参考文档reference/conflicts-ci.md3.0 KB
- 参考文档reference/create.md68.9 KB
- 参考文档reference/dependency-ci.md7.3 KB
- 参考文档reference/evidence.md11.7 KB
- 参考文档reference/full-lifecycle.md3.2 KB
- 参考文档reference/media.md11.1 KB
- 参考文档reference/merge.md19.2 KB
- 参考文档reference/monitor.md73.6 KB
- 参考文档reference/native-surfaces.md4.1 KB
- 参考文档reference/prep.md13.5 KB
- 参考文档reference/read.md3.9 KB
- 参考文档reference/readiness.md20.1 KB
- 参考文档reference/ready-for-review.md45.7 KB
- 参考文档reference/reassess.md7.0 KB
- 参考文档reference/review-venue.md7.7 KB
- 参考文档reference/reviewer-shapes.md9.2 KB
- 参考文档reference/watch-handoff.md9.0 KB
- 脚本scripts/check-body-sections.sh935 B
- 脚本scripts/check-body-sections.test.sh4.4 KB
- 脚本scripts/check-gate-lines.sh3.9 KB
- 脚本scripts/check-gate-lines.test.sh4.9 KB
- 脚本scripts/check-ready-holds.sh4.2 KB
- 脚本scripts/check-ready-holds.test.sh8.6 KB
- 脚本scripts/confirm-verdict.sh6.2 KB
- 脚本scripts/feedback-thread.sh15.6 KB
- 脚本scripts/feedback-thread.test.sh29.5 KB
- 脚本scripts/fetch-annotations.sh5.7 KB
- 脚本scripts/fetch-annotations.test.sh15.0 KB
- 脚本scripts/fetch-failed-logs.sh14.1 KB
- 脚本scripts/fetch-failed-logs.test.sh16.4 KB
- 脚本scripts/fixtures/body-with-reviewer-media.md702 B
- 脚本scripts/media.py36.5 KB
- 脚本scripts/media.test.sh36.4 KB
- 脚本scripts/monitor-poll.test.sh10.4 KB
- 脚本scripts/parse-branch-issue.sh13.7 KB
- 脚本scripts/parse-branch-issue.test.sh25.7 KB
- 脚本scripts/parse-ready-skip.sh2.4 KB
- 脚本scripts/parse-ready-skip.test.sh4.2 KB
- 脚本scripts/pr-worktree.sh3.2 KB
- 脚本scripts/pr-worktree.test.sh7.5 KB
- 脚本scripts/pre-ready-steps.sh354 B
- 脚本scripts/pre-ready-steps.test.sh1.2 KB
- 脚本scripts/prep_warnings.py6.2 KB
- 脚本scripts/prep-warnings.sh2.5 KB
- 脚本scripts/prep-warnings.test.sh6.7 KB
- 脚本scripts/push-branch.sh24.1 KB
- 脚本scripts/push-branch.test.sh59.2 KB
- 脚本scripts/read-pr.sh9.2 KB
- 脚本scripts/read-pr.test.sh13.5 KB
- 脚本scripts/read-pre-ready.sh6.0 KB
- 脚本scripts/read-pre-ready.test.sh11.0 KB
- 脚本scripts/read-prep-audits.sh5.8 KB
- 脚本scripts/read-prep-audits.test.sh9.0 KB
- 脚本scripts/read-review-comments.sh8.8 KB
- 脚本scripts/read-review-comments.test.sh16.5 KB
- 脚本scripts/read-review-venue.sh4.2 KB
- 脚本scripts/read-review-venue.test.sh5.1 KB
- 脚本scripts/ready-flip.test.sh14.6 KB
- 脚本scripts/ready-skip-comment.sh2.5 KB
- 脚本scripts/ready-skip-comment.test.sh3.2 KB
- 脚本scripts/ready-verify-local.test.sh1.7 KB
- 脚本scripts/reassess-comment.sh2.0 KB
- 脚本scripts/reassess-comment.test.sh2.6 KB
- 脚本scripts/reassess-limits.sh7.7 KB
- 脚本scripts/reassess-limits.test.sh10.9 KB
- 脚本scripts/resolve-remote.sh4.1 KB
- 脚本scripts/resolve-remote.test.sh7.9 KB
- 脚本scripts/review-venue.sh11.7 KB
- 脚本scripts/review-venue.test.sh23.6 KB
- 脚本scripts/siblings-line.sh2.7 KB
- 脚本scripts/siblings-line.test.sh3.1 KB
- 脚本scripts/target-repo.sh3.8 KB
- 脚本scripts/target-repo.test.sh5.8 KB
- 脚本scripts/verify-gate.sh3.4 KB
- 脚本scripts/verify-gate.test.sh4.5 KB
- 参考文档templates/checklist.md2.1 KB
- 参考文档templates/evidence-comment.md329 B
03 SKILL.md 正文
Arguments. [prep|create|ready|monitor|comments|ci|merge|reassess|evidence|status|full|…] [--unattended] [args]. Full set: the Arguments table below. e.g., /pull-request prep, /pull-request create, /pull-request ready, /pull-request monitor, /pull-request comments, /pull-request merge, /pull-request evidence <pr> --evidence <file>, /pull-request media <pr> --manifest <file>, /pull-request status, /pull-request full, /pull-request fetch-logs <pr|run>, /pull-request view <pr> --diff, /pull-request list --head <branch>, /pull-request review-venue
Repository context. Gather first
The read actions view, list, review-comments and review-venue, comments --ci, conflicts --ci, dependency --ci and ci --ci skip this section. For every other action, collect these with
individual Bash calls, one command per call, never combined into a single invocation:
- Current branch,
git branch --show-current - Recent commits,
git log --oneline -5 - Working tree status,
git status --porcelain - Changed files (staged+unstaged),
git diff --name-only HEAD
Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep them separate body calls, not pre-computed, so the skill stays invocable from inside a worktree: the composition record is the gather-block convention. Pointer: when an isolated session refuses a git command, fetch How Claude Code enforces isolation live.
Purpose
Run the PR lifecycle from quality review through merge and the post-merge worktree transition, detecting state and resuming.
The two non-negotiable gates:
- Finding verification (prep phase): agent review findings have a demonstrated error rate, so every finding is verified against current docs and actual code before it reaches the user.
- Research-gated CI fixes (monitor phase): no code fix without multi-source research consensus on the root cause. Unresearched "obvious" CI fixes are how wrong fixes ship.
Adapting to your environment (graceful degrade)
This skill is self-contained: it runs on git, the forge's CLI, jq, and its bundled scripts (skill-private ones under ${CLAUDE_PLUGIN_ROOT}/skills/pull-request/scripts/, plugin-shared ones under ${CLAUDE_PLUGIN_ROOT}/scripts/, which the reference/ files call <scripts-dir>: substitute the resolved path before a command from them reaches Bash). jq is required (the merge and readiness paths pipe forge API output through it): check command -v jq before the first phase that parses; if missing, stop with the install remediation (https://jqlang.org/download/; a separate install under Git Bash on native Windows) instead of failing mid-phase. The readiness thread gate (Gate 7) also needs Python 3.11+; without it that gate holds as unproven and the rest of the skill runs. The media action and the stale reviewer-media check need Python 3.11+ too: without it media stops with the install remediation (https://www.python.org/downloads/) and the stale check is skipped. An adjacent capability a phase names (a code-review skill or agents, a simplifier, a build/test/lint verifier, an external research skill, an exploration skill, a work-item tracker, a CI-log-audit agent, a forge-events push channel) is optional: invoke it when your environment provides it (a skill, plugin, agent, or MCP server), else follow the inline guidance, which stands on its own. Never block a phase because an adjacent tool is absent.
Consumer conventions come from the consuming project's own CLAUDE.md, AGENTS.md, and rules. Notably: PR body template, branch naming, merge style (this skill defaults to squash), review-reply identity (some projects post bot-identity replies via a wrapper; default is the forge CLI under your own login), and any extra pre-PR gates. Read them before creating or merging.
Provider commands. This body names forge operations (resolve the PR, read its checks, reply on a thread); their GitHub commands (the one forge supported today) are in the GitHub provider reference. Read it before the first forge operation. The phase files under reference/ carry each phase's full GitHub procedure.
PR title format resolves via the same ladder /source-control:commit uses for the commit subject (see its SKILL.md), checked in order: the pr_title_pattern resolved across the layers of the source-control convention config (team value in docs/conventions/source-control.yaml) per ../../reference/config-resolution.md → the consuming project's own CLAUDE.md/AGENTS.md/rules → Conventional Commits (11-type vocabulary. build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test; security is not a member. Pointer: when the default set is questioned, fetch commitlint's config-conventional type-enum live. As of: 2026-11-10. Recheck trigger: that rule's value changes) as the default. See reference/create.md §2.4.1 for where the title is derived. When no layer resolves a pr_title_pattern and nothing is inferable, point the user at /source-control:setup.
PR-body attribution (the 🤖 Generated with [Claude Code]… line) resolves from the pr_body_attribution key across the same layers (team YAML first, ../../reference/config-resolution.md). Absent → the default line, none → omitted, any other value → that line. It is the PR-body analogue of /source-control:commit's trailer_policy and gated separately; see reference/create.md §2.4.1 for the assembly.
Branch-to-issue grammar is a POSIX ERE whose LAST capture group is the work-item reference (an issue number or a tracker key), e.g. ^[^/]+/([0-9]+)-. It resolves first from the branch_issue_pattern key across the layers (team value in the YAML; ../../reference/config-resolution.md), which parse-branch-issue.sh reads itself. The branch_issue_pattern userConfig is a deprecated fallback, read only when no layer sets the key: its value is ${user_config.branch_issue_pattern} (this line is the substituted surface; a literal ${user_config.branch_issue_pattern} token means unset), and reference/create.md §2.4.0 fills its <branch-issue-pattern> slot with a real ERE from it. When the script falls back to that value it prints a deprecation note on stderr; relay it to the user. Neither set: a bound work-item tracker's adapter supplies the grammar (§2.4.0), else the built-in <type>/<N>-<slug> (and routine-issue-<N>) convention.
PR open state (ready or draft) decides whether create takes the new PR through ready or leaves it a draft. A draft means a person asked to see the work early or the PR is a multi-session container; ready means complete and through ready's gates. The per-user value is ${user_config.pr_open_state} (this line carries the substituted value; a literal ${user_config.pr_open_state} token means unset). A pr_open_state key in the repository's docs/conventions/source-control.yaml, read at the PR's base branch and never at its head, wins over it; a request for a draft wins over both; with none set the state is ready, and a consumer opts into draft. An unattended run follows the resolved value like an attended one, and ready --unattended's holds still apply. reference/create.md §2.4.3 holds the state meanings, resolves the state and reports the supplying level; the levels and the invalid-value rule are in ../../reference/config-resolution.md.
Review venue (auto, local, ci or both) decides which local review steps run before and at the ready flip. The per-user value is ${user_config.review_venue} (this line carries the substituted value; a literal ${user_config.review_venue} token means unset), passed as --user to scripts/read-review-venue.sh. A review_venue key in the repository's docs/conventions/source-control.yaml, read at the PR's base branch, wins over it. reference/review-venue.md reads it and owns what each value does.
PR body preview (post or preview) decides whether an attended run shows a body and waits for a yes before posting it. The per-user value is ${user_config.pr_body_preview}; PR body refresh (true or false) decides whether a push to an open PR also rewrites the body sections it made stale, per-user value ${user_config.pr_body_refresh}. A literal unexpanded token means unset. A key of the same name in the repository's docs/conventions/source-control.yaml wins over each; the levels are in ../../reference/config-resolution.md. reference/create.md §2.4.3 applies the preview and reference/monitor.md §3.3.2 the refresh.
Emit checklist
For runs spanning 3+ phases, copy ${CLAUDE_PLUGIN_ROOT}/skills/pull-request/templates/checklist.md into your project's working-notes location (or track it inline) and tick each - [ ] as its phase produces output. It survives /clear.
Arguments
$ARGUMENTS. Action selector:
| Action | Entry point | Use case |
|---|---|---|
| (empty) | Smart default | Detect current state, resume from right phase |
prep |
Phase 1 | Review (skipped when the CI code-review lane covers it, reference/review-venue.md) + verify findings + simplify + comment pass + verify build |
prep quick |
Phase 1 (fast) | Code errors only, skip simplify and the comment pass |
prep review-only |
Phase 1 (partial) | Just review + verify findings |
prep simplify-only |
Phase 1 (partial) | Just simplify + comment pass + re-verify |
create [--draft '<reason>'] |
Phase 2 | Branch-name check + commit + changelog fragments where the repo releases from them (reference/create.md §2.3.3) + push + open the PR as a draft, its body carrying the plan Brief's acceptance criteria when the branch implements a plan and Closes only for an issue whose done-when items the diff delivers, else Refs: with a ## Remaining section (reference/create.md §2.4.0, §2.4.1), then run ready on it when the resolved PR open state is ready; --draft requests a draft whose Draft: line names the reason. Reports the PR URL, its open state and the level that set it, then arms event delivery (reference/create.md §2.6) when the session keeps acting on the PR, else stops |
create --pushed --worktree <path> [--draft '<reason>'] [--hold '<line>'] |
Phase 2 (PR-only) | PR-only entry for an orchestrated flow, the branch is already committed and pushed (by a dispatched worker), so this skips commit / push / branch update, re-resolves branch and diff from the given target worktree (not the session cwd), and runs body assembly + gates + opens the PR for <branch>, then follows the resolved open state like an attended run (the repository level is read at the base branch, never from the worktree). --draft requests a draft whose Draft: line names the reason; --hold puts a Hold: line in the body the PR opens with. Used by /work-items:work's orchestrator after its pre-PR gate. See reference/create.md §2.7 |
ready |
Phase 2.5 | Update the branch from its base by the method the shared branch-update decision chooses (ready --unattended never rewrites a pushed head), run the code and security reviews over the PR diff in fresh-context subagents (each skipped when its CI review lane is present and healthy, reference/review-venue.md) and the verify gate on the updated head (its test suites skipped when CI's test lanes already passed on that head, reported as skipped (CI covers it); ready --verify-local runs them anyway), flip the draft to ready (the base branch's pre_ready list can turn off any of its six configurable steps; each step's outcome is reported), post the evidence comment when an evidence file exists for the confirmed head (--evidence <file> names one; attended runs only, and a refusal is reported, never undoes the flip), then hand the PR to /review:explain-change, whose digest_policy decides whether a digest is offered or built, then to /review:reviewer-media, whose policy decides whether a narrated walkthrough is built (neither gates anything). Never arms auto-merge: ready starts the AI reviews. Refuses on a branch with no PR, and leaves in draft a held or superseded draft, or one whose body closes an issue the diff does not finish. ready --unattended (every lane, loop or dispatched caller) also leaves a draft a person asked for (its Draft: body line) in draft. ready [<pr>] --skip <step>[,<step>...] --reason "<text>" lets a person present skip configurable steps for this run only, reported and recorded in one PR comment, never in the body; refused unattended. See reference/ready-for-review.md |
monitor |
Phase 3 | Watch CI, fix failures, evaluate comments. Three-tier event delivery: (1) push channel when your environment ships a forge-events channel (an MCP server delivering webhook events into the session), ~0 idle requests; (2) Monitor tool fallback (60s poll); (3) polling in cloud/headless sessions, plus the PR-activity subscription where the session offers it. Check the push channel FIRST per monitor.md §3.0.05 before falling back |
comments |
Phase 3.5 | Evaluate/respond to PR comments only |
comments --ci |
Phase 3.5 (CI) | The pr-unblock lane's unattended mode: the runner's kept reviewer-bot threads, or an earlier pr-verify FAIL's notes, only, through its review-thread tool, running no head code. See reference/comments-ci.md |
conflicts --ci |
Phase 2.5.2 (CI) | Unattended conflict resolution for the pr-unblock lane: reads the runner's conflicts.json as data, resolves each conflicted path in place under the base-merge step's discipline, runs no command, never edits a path under .github/workflows/, and leaves a path whose two intents cannot both hold with its markers, which escalates it. See reference/conflicts-ci.md |
dependency --ci |
Phase 3.5 (CI) | The pr-unblock lane's unattended review of one risky Dependabot update: reads the context file, the checkout and the upstream release notes as data, leaves a scoped fix outside .github/ uncommitted for a later job to push, and returns a merge, fix, close or escalate verdict as structured output, running no head code. See reference/dependency-ci.md |
ci --ci |
CI | The pr-unblock lane's unattended fix of a PR's failing checks: reads the runner's context file as data, reproduces each check with the repository's own command, fixes the cause, reruns it, and leaves the fix uncommitted for the runner's patch; never weakens a check, and escalates what it cannot fix with a named reason. See reference/ci-ci.md |
merge |
Phase 4 | Squash merge, or merge or enqueue without asking once the PR is CLEAN and the AI review checks have passed on the reviewed head, with the plain merge command (a refusal is reported, never handed to the user or retried in another shape), then confirm a merge-queue PR entered the queue (enqueue a CLEAN one left out, report the refusal text verbatim; §4.2.2) and wait for MERGED (no strategy flag behind a merge queue, --auto only pinned to the reviewed head; reference/merge.md §4.2.1) + worktree transition (reuse it, or release this session's lock) + verify. Never removes a worktree: that is /source-control:worktree cleanup |
evidence <pr> --evidence <file> [--attach <path>]... [--summary <file>] [--artifact-url <url> [--retention-days <n>]] |
Evidence | After the verifier passed for the PR's head, post one evidence comment, or update it in place for a new head, with gh pr comment --edit-last --create-if-none --attach: the text summary, publishable captures only in collapsed sections laid out by templates/evidence-comment.md, and the CI capture artifact link with its expiry. A file outside the publishable list, or a leak-scan hit on the body, posts nothing. See reference/evidence.md |
media <pr> --manifest <file> [--artifact-url <url> [--retention-days <n>]] |
Reviewer media | Place a produced walkthrough (video, contact sheet, chapter list, screenshots) in the marked ## Reviewer media section near the top of the PR body, rewriting only the text between its two marker lines: claim the head first, attach only the files the producer's manifest.json lists with gh pr edit --attach, else link the Actions artifact with its expiry, and swap the request label for the posted one. A leak-scan hit, a screenshot with no frame-text sidecar, a claim another run holds, a body that changed under the edit, or no way to host the media posts nothing. media stale <pr> marks a section that shows an older commit; media shows --facts <file> prints the commit it shows; media fail <pr> records a failed build once per commit. See reference/media.md |
reassess [<pr>] [--act] [--state-dir <dir>] |
Reassess | Judge whether one open PR should still land, even when green and mergeable, and return continue, rework or close with its evidence: report-only unless --act carries out the verdict. Runs on one PR and is no merge prerequisite. --state-dir defaults to ${CLAUDE_PLUGIN_DATA}/state/babysit-prs. See reference/reassess.md |
status |
Report only | Unified status across all phases |
full |
Phase 1-4 | Run prep → create → monitor → merge end-to-end |
fetch-logs <pr|run> [--raw|--job <job-id>] |
CI log retrieval | Pull failed-CI evidence: default = ::error/::warning annotations only (cheapest); --raw = full ZIP dump for archive review; --job <id> = per-job plain text |
view [<pr>] [--repo <owner/repo>] [--diff] [--out <file>] |
Read only | One PR's facts as JSON, or its diff with --diff; no number reads the current branch's PR. See reference/read.md |
list [--head <branch>|--head-match <ERE>] [--search <text>] [--state open|closed|merged|all] [--repo <owner/repo>] |
Read only | PRs as a JSON array, open by default |
review-comments (--prs <n> | --pr <number>) [--repo <owner/repo>] |
Read only | The review comments of the last <n> merged PRs, or of one PR, as JSON lines. See reference/read.md |
review-venue [--repo <owner/repo>] [--max-age-days <n>] [--head <sha>] |
Read only | Per AI review lane (code, security): ci when the repository's CI lane is present and healthy, so no local review runs for it, else local; with --head, a tests line: ci when CI's test lanes passed on that commit. See reference/review-venue.md |
For the all-PR continuous loop (discover every open PR, work each to readiness, self-pace), use
the sibling skill /source-control:babysit-prs. It wraps this skill's per-PR review discipline
in fleet orchestration and never merges.
Action defaults
- Merge mode:
mergesquash-merges (one squashed commit per PR onto the default branch), see reference/merge.md §4.2. Follow the consuming project's convention when it differs. A stacked PR lands every layer below it: see stacked-prs.md. - Stack or separate: before
createopens a PR that builds on another open PR, decide stack versus sequential PRs off the trunk by "When to stack" in stacked-prs.md. - Monitor cadence:
monitorpolls the PR's checks (the §3.0.1 REST read) and comment fetches every 60 seconds, see reference/monitor.md §3.1; every loop follows the API budget. A wait is a REST poll that runs in the background (the §3.0.1 Monitor watch, or arun_in_backgroundpoll where Monitor is unavailable), never a foregroundsleeporuntilloop and never the CLI's blocking checks watch, and it first reports each pending job as queued or running ("Waiting on a pending check"). A dispatched subagent does not wait: it stops once its PR is marked ready and reports the full head sha, and the dispatching session watches and merges (reference/monitor.md). - Required reviewers:
createrequests no reviewers when it opens the PR. See reference/create.md §2.4.3.
PR identity resolution
PR identity (number, URL) resolves live from the forge, the authoritative source, at every phase that needs it. No caching, no state files.
Standard pattern (every phase): resolve the current branch's PR number; when that is ambiguous (multiple open PRs, stale checkout, returning days later), name the branch explicitly. Both commands are in the provider reference's "Resolve a pull request".
After resolving once at phase entry, pass <pr_number> explicitly to all subsequent forge calls in that phase (reading checks, merging, etc.). Never rely on bare-branch resolution mid-phase.
Why explicit PR numbers? Resolution with no number goes by the HEAD branch, which fails when the worktree was cleaned up (branch context lost), multiple open PRs exist (wrong match), you return days later (stale checkout), or another session's PR merged first. Resolving once per phase bounds this risk to one point.
Phase 0: Parse action and detect state
Parse $ARGUMENTS to extract the action (first token) and any sub-arguments, after taking out
--unattended wherever it appears: it is the caller declaring that nobody is present. Pass it on
to ready (which takes it as its own flag) and to no script; with nothing else left, the action
is the smart default.
Smart default (empty args): read live state from the forge to determine the right phase:
1. Check git branch — on the default branch? → "Create a worktree or branch first"
2. Resolve PR for current branch, reading its number, state and draft flag:
a. no PR found → no PR yet → START AT PHASE 1 (prep); skip steps 3-6
entirely (they all need a PR number that does not exist yet)
b. state = MERGED → skip to Phase 4.3 (worktree transition only: new branch from the default branch, delete the merged local branch)
c. state = CLOSED → report "PR was closed without merging" and stop
d. state = OPEN → capture pr_number, continue to step 3
3. isDraft = true → START AT PHASE 2.5 (ready); skip steps 4-6. A draft owes its
review and its flip, not monitoring: no reviewer has been asked to read it yet
4. Read the PR's checks — still running? → start at monitor
5. Check for unaddressed comments → start at monitor (comments sub-phase)
6. CI green + comments addressed → suggest merge
Present the detected state and proceed to its phase, announcing it in interactive mode; in autonomous mode (full), proceed without pausing. Phase transitions are not decision points.
Status action: read the PR's number, URL and state, then report current state across all phases.
Phases
Execute in order. Each phase is self-contained. Read the relevant file for detailed steps:
| Phase | File | Entry actions |
|---|---|---|
| 1. Prep | reference/prep.md | prep, prep quick, prep review-only, prep simplify-only |
| 2. Create | reference/create.md | create |
| 2.5. Ready for review | reference/ready-for-review.md | ready |
| 3. Monitor | reference/monitor.md | monitor, comments |
| 2.5.2 (CI) | reference/conflicts-ci.md | conflicts --ci |
| 3.5 (CI) | reference/comments-ci.md | comments --ci |
| 3.5 (CI) | reference/dependency-ci.md | dependency --ci |
| CI | reference/ci-ci.md | ci --ci |
| 4. Merge | reference/merge.md | merge |
| Evidence | reference/evidence.md | evidence |
| Reviewer media | reference/media.md | media |
| Reassess | reference/reassess.md | reassess |
Monitor entry
On monitor, comments, or full reaching monitor, read reference/monitor.md before any CI polling or comment evaluation: its entry checklist runs first, and its per-iteration checklist governs every CI or comment event. Standalone create runs Steps 1-3 of that entry checklist when its session will keep acting on the PR it opened (reference/create.md §2.6); create --pushed leaves them to its caller. comments --ci skips it, and conflicts --ci, dependency --ci and ci --ci do not enter Phase 3.
Full lifecycle (/source-control:pull-request full)
full chains prep, create, monitor, and merge in one invocation. Read
reference/full-lifecycle.md when invoked with full, and only
then: it owns the phase-to-phase handoff state, the abort points, and what full does
differently from running the four phases by hand. Any other action routes through the phase table
above instead.
Fetch CI logs (/source-control:pull-request fetch-logs <pr|run> [--raw|--job <job-id>])
Public action for failed-CI evidence, a tiered fetch chain: cheapest signal first, escalating only when the lower tier is insufficient. Consumers say WHAT they want; the skill picks the internal helper from the flags.
Behaviors:
| Invocation | What it returns | When to use |
|---|---|---|
fetch-logs <pr-number> (default) |
::error:: + ::warning:: annotations across all failed jobs |
First-pass. Usually enough to identify the cause |
fetch-logs <pr-number> --failed |
Annotations from failed jobs only | When the run has many jobs and noise is a concern |
fetch-logs <run-id> --raw |
Full CI log archive, dumped in scope | When annotations are sparse / missing. Debug-grade detail |
fetch-logs <run-id> --job <job-id> |
Plain-text log of one job | Targeted dive after seeing which job failed |
<pr-number> and <run-id> are interchangeable; given a PR number, the skill resolves its latest run.
Composition with monitor: monitor invokes this action on CI failure. Direct fetch-logs is for ad-hoc post-mortem (e.g., a closed PR's CI failure, auditing a green run for warnings).
Implementation note: this action delegates to the bundled, private fetch-annotations.sh and fetch-failed-logs.sh scripts. Consumers MUST NOT cite script paths; use this action.
Read a pull request (view, list)
view and list are the read-only actions other skills call instead of a forge CLI. Read
reference/read.md when invoked with either, and only then: it owns the
command, the output fields, and the exit codes.
Read the review venue (review-venue)
review-venue is the read action prep, ready and other skills call before a local AI review, so a
review runs in CI or locally, never in both. Read
reference/review-venue.md when invoked with it, or when a phase
reaches a review: it owns the command, what makes a lane healthy, and how each line is applied and
reported.
Important notes
- Side effects: this skill commits, pushes, creates PRs, and merges. User approval gates at each dangerous step (commit message, CI fix, merge outside the reference/merge.md §4.2.1 merge after AI review) are the human checkpoints the skill enforces
- Finding verification is non-negotiable (the first gate under Purpose)
- Research-driven fixes are the point of the monitor phase: a short research burst costs little; an unresearched fix costs a lot
- Max 3 CI fix iterations, to stop fix-push-fail loops
- Findings triage:
- Bot comments classified CORRECT (Codex, claude-review, etc., after evidence-based verification against actual code): auto-fix + test + react 👍 + D5 reply in the same turn, then push with the round's other fixes and post the D7 reply (monitor.md §3.3.2). No user-approval pause: the CORRECT/INCORRECT classification is the safety gate. Applies when the fix is small and scoped (<~50 LOC, single concern); pause for cross-cutting refactors even when CORRECT
- Bot comments classified INCORRECT: autonomous 👎 reaction + reply with research-backed counter-evidence. Never silently ignore
- Human reviewer comments: always pause for user approval before reacting or fixing, regardless of classification
- Prep skips the review/simplify work when no
codeclass is detected, and the verify gate reduces to lint.readystill reviews a diff that touches an instruction surface (definition). Extra project-specific prep-evidence requirements come from the consuming project's own hooks
Boundary, native Claude Code surfaces
Three native surfaces cover parts of this lifecycle and get conflated with it when a PR is opened or watched.
pr(bundled skill): creates one pull request generically; it gathers branch context and applies Claude Code's own title, body, and attribution. The model and the person can both invoke it./commit-push-pr(built-in command): commits, pushes, and opens a PR in one prompt-driven step. The model and the person can both invoke it./autofix-pr(built-in command): spawns a cloud session that watches the current branch's PR and pushes fixes when CI fails or reviewers comment. Reserved for the person to run; the model does not invoke it.- This skill (marketplace plugin). The whole lifecycle: prep with verified findings, a draft under this repository's PR title and body contract, the ready flip after updating the branch from its base, research-gated local monitoring with per-finding classification and replies, and merge.
Routing. Where no draft discipline, body contract, or later lifecycle step applies: when the
bundled pr skill resolves in this session, prefer it to open a PR from work already committed;
when /commit-push-pr resolves, prefer it only when the whole working tree belongs in the commit,
since it commits, pushes and opens the PR in one step. With unrelated uncommitted changes, pr
is the native route, never /commit-push-pr. Prefer
this skill whenever the repository declares a PR convention or the work continues into ready,
monitor, or merge.
Choose who watches the PR. At the end of ready, and at monitor entry when no choice was
made, pick between this skill's monitor, a background agent, /background, /autofix-pr and the
babysit loop by whether the person is staying and whether the machine stays on, after reading the
plan's rate-limit windows: at 95% or above, report the window and the options, and the person decides. For a route only
the person can start, print it ready to run. If /autofix-pr is available in your session (gate
basis: it registers gated and needs forge CLI and cloud-session access; records in
reference/native-surfaces.md), the person can run it instead of or
alongside this skill's monitor, with a filled-in prompt carrying this skill's review discipline. The
matrix and the prompt:
reference/watch-handoff.md. When the caller passes --unattended,
with any action, the run records that recommendation and the /autofix-pr prompt in its output
and does not ask the person; without that flag it asks.
Mutation gate. pr and /commit-push-pr commit, push, and open a PR; /autofix-pr pushes
fixes to the PR branch from a cloud session. This skill never chains into any of them on its own
behalf. When /autofix-pr runs alongside this loop, both push to one branch. Before each fix
commit, fetch the PR head and merge it into the checked-out branch (git merge --ff-only when there
are no local commits, else git merge), then re-check the pending edit against the merged tree and
drop it when the cloud session already fixed that finding. A fetch alone leaves the local branch on
the old tip, and the push that follows is rejected as non-fast-forward.
Availability is never assumed. pr and /autofix-pr register gated, and /autofix-pr also
needs forge CLI and cloud-session access; this section states what to do when a surface resolves, never
that it is present. The four-part records live in
reference/native-surfaces.md.
Spoke paths
The reference/ files write this skill's directory as <skill-dir>, which is
${CLAUDE_SKILL_DIR}, and the plugin's root directory as <plugin-root>, which is
${CLAUDE_PLUGIN_ROOT}. Put each path in place of its placeholder before running a command or
writing it into a brief. Those files arrive through the Read tool as plain bytes, so a ${…} token
in them would reach the Bash tool unsubstituted, and the Bash tool's environment has no
CLAUDE_SKILL_DIR or CLAUDE_PLUGIN_ROOT to expand it from. Basis: the plugins reference,
https://code.claude.com/docs/en/plugins/manifest-reference#where-each-variable-resolves.
Related
/review:explain-changewrites a pull request digest; it never posts to the PR./explainer-video:producerenders a storyboard into the narrated video, contact sheet andmanifest.jsonthat themediaaction places./review:reviewer-mediadecides which media a PR needs, builds the storyboard from the digest and hands the manifest to themediaaction./playwright:demo-videorecords a live UI flow as PR evidence; theevidenceaction posts it./education:illustrateexplains a concept, with a video view through the same producer.
Next
- PR merged, optional review of how the session went: /session-flow:retro.
reassessreturnedrework: /implementation:implement.- A reviewer walkthrough still to build for the
mediaaction: /review:reviewer-media <pr>.
Gotchas
- Verify every agent review finding before presenting it. Automated reviewers produce incorrect findings often enough that an unverified finding is not evidence; check each against current docs and actual code (step 1.3) before it reaches the user
- Never guess at CI failure causes. Use monitor.md §3.2's prioritized fetch chain: annotations → full log archive → the CLI's failed-log view as last resort. The configured CI-log size cap is
${user_config.fetch_logs_max_bytes}; when that value is a number other than the 52428800 default (not empty, not a literal unexpanded token), pass it to the archive fetch as--max-bytes <value>. The CLI's failed-log view truncates large logs (provider reference "Checks and CI logs"); the script-based paths return complete data. Do NOT use broad keyword grep (error|fail|...): it matches cleanup steps, variable names, and incidental output - OIDC-based workflows fail when the PR modifies the workflow file. A forge limitation (provider reference "Checks and CI logs"); classify as informational when it applies
- Resolving the PR without a number is fragile. Resolve
<pr_number>once at phase entry and pass it to every later forge call ("PR identity resolution" above) - Squash merge needs
git branch -D, not-d. After a squash merge the local branch commit is not in the default branch's history (different SHA), so-dsays "not fully merged."-Dis safe because you already confirmed the merge git add -Aandgit add .are banned. They risk committing secrets, build artifacts, or unrelated changes. Alwaysgit add <specific-files>- Bot comments need reactions AND replies. React (👍/👎/👀) on every substantive comment AND reply with a per-finding classification table with evidence, for every reviewer. Verify BOTH the reaction and the reply landed on the forge by reading them back. Resolve the thread only when D7.5's conditions are met for EVERY finding in it, and only IF bot-authored; never human-authored, never your own. D7.5 in reference/monitor.md's per-iteration checklist is the single statement of which dispositions qualify and who may act on one, do not restate it here
- Monitor is async, not serial. Process comments as they arrive while CI is still running; bots post at different times
- Check mergeable BEFORE polling CI. While the PR's mergeability reports a conflict, the forge runs no workflows. Integrate the default branch first, then poll
- A green review lane can mean nothing was reviewed. These lanes report on their session, not their output: a session that ends without error goes green even when it posted no review and no finding. No guard beside the lane judges what it posted; B2 (reference/monitor.md's per-iteration checklist) is the only productivity check, and billing is no signal, since the session is billed either way. Judge a review lane by what it produced (B2), never by its check row, and run the review locally when it produced nothing
- Never merge with unclassified FAILURE check runs. Every FAILURE must be investigated, classified (real failure vs informational), and documented before merge is even suggested. See readiness.md for the full 6-gate checklist
- "No comments" does NOT mean "ready." Comment-only actors post at unpredictable times; a 2-minute cooldown after the last check-run completion or comment arrival prevents the race. See readiness.md Gate 5
- Security scans are always blocking. Any check run or bot comment reporting security findings (secrets, vulnerabilities) triggers mandatory triage; even a false positive must be explicitly classified and documented before merge
- Discover actors, don't hardcode them. Security tools and AI reviewers change. Monitor discovers actors from the PR's checks and comments, classifies them by category (CI, security, review), and evaluates accordingly
- Uncommitted changes are silently lost on branch deletion.
git reflogrecovers only commits. Before staging (Phase 2.3.1) and before the post-merge worktree transition (Phase 4.3), checkgit status --porcelainfor unrelated uncommitted changes and stash them (git stash push -m "desc" -- <files>); stashes survive branch deletion. Never silently ignore uncommitted changes - Cloud sessions poll. Autonomous cloud sessions (
CLAUDE_CODE_REMOTE=true) poll the PR's checks and comment surfaces on a fixed 60-90s cadence, and subscribe to PR activity where offered so reviews and failed checks wake them sooner. The poll stays, since pushes and green checks produce no event (§3.0.0 of monitor.md holds the decision, its pointer and its recheck trigger) - Monitor checks the push channel first, then falls back. Three tiers on local CLI sessions: (1) push channel (when your environment ships a forge-events MCP channel; ~0 idle requests), (2) Monitor tool (a
Monitorwatch armed with an explicittimeout_msand re-armed at each deadline, per monitor.md §3.0.1; 60s poll fires on real CI/comment events; cancel viaTaskStop), (3) fixed-interval cron polling (deprecated, wasteful). Check for a channel before the Monitor tool: polling spends ~1 request per 30s interval vs ~0 idle with push delivery
04 同仓库更多 Skills
track
Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.
reviewer-media
Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
principles
Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.
write
Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').