create-pr
Creates pull requests behind pre-push gates — branch-inferred target, size-matched description, draft vs final checks, specialist + two-axis (standards / spec) review, the configured review bot's mention (git config forge.reviewBot) — then triages review feedback. Use when shipping a branch as a PR, triaging review feedback on open PRs (`review`), sequencing several ready PRs (`merge-order`), or reviewing a branch against its spec and standards without opening a PR (`review-since <ref>`).
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- create-pr
- hooks
- { "Stop": [ { "hooks": [ { "type": "command", "command": "python3 $CLAUDE_PROJECT_DIR/.claude/hooks/validators/skills/create_pr_format.py --final" } ] } ] }
- description
- Creates pull requests behind pre-push gates — branch-inferred target, size-matched description, draft vs final checks, specialist + two-axis (standards / spec) review, the configured review bot's mention (git config forge.reviewBot) — then triages review feedback. Use when shipping a branch as a PR, triaging review feedback on open PRs (`review`), sequencing several ready PRs (`merge-order`), or reviewing a branch against its spec and standards without opening a PR (`review-since <ref>`).
02 资源文件 4
- 参考文档GATES.md10.9 KB
- 参考文档REVIEW.md3.9 KB
- 参考文档TEMPLATES.md8.0 KB
- 参考文档TWO-AXIS.md7.1 KB
03 SKILL.md 正文
Create PR Workflow
Opens a PR behind pre-push gates, then triages review feedback. Flow: Analyze → Target → Checks → Pre-push gates → Docs → Description → Create → Monitor → Merge-order.
Index
| File or section | Read when… |
|---|---|
TEMPLATES.md |
Step 4 — PR body templates, size thresholds, Pre-flight notes |
GATES.md |
Review-bot setup; Step 3.7 plugin check, review tier, specialist table; Step 3.8 mechanics and rationale |
TWO-AXIS.md |
Step 3.7 and review-since — Standards + Spec axes, smell baseline, dispatches, bucketing |
REVIEW.md |
Steps 6–7 — fetch commands, Codex endpoints, security re-review, merge-order procedure |
_shared/ci-failure-classifier.md |
Step 3.6 exits 3 — routing failures |
_shared/task-triage.md |
Deferring a finding as a follow-up task |
_shared/domain-docs.md |
PR wording: glossary terms |
Review bot configuration
git config forge.reviewBot (post-PR mention line) and forge.localReview (Step 3.8 command); set both ideally (GATES.md).
- Set — append the exact line to every PR body (draft or final) just before the Claude Code attribution; Step 6 reviews against that bot.
- Unset — no mention (never invent one); Step 6 triages human reviews + CI with the same buckets.
Output rules
- PR body — shortest template that fits the size (TEMPLATES.md).
- Chat output — ONLY the PR URL, title, and
/create-pr review <N>hint. Never echo the body.
Untrusted values (every command)
Branch names (git check-ref-format permits ;, $(…), &&), commit topics, review findings and the forge.reviewBot line may hold shell metacharacters. Never interpolate them into a command string.
- Pass values as separate arguments (
gh pr view "$n" --json body), never concatenated into one command string. - Prose goes through a file (
--body-file), never--body "…<finding>…"— it makes bot output inert and keeps @-mentions intact.
Invocation
/create-pr (final PR, full checks) · --draft (draft PR) · --preflight (adds Step 3.6) · review [PR#] (triage review feedback, Step 6) · merge-order (merge sequence, Step 7) · review-since <ref> (two-axis review of the branch, TWO-AXIS.md). review, merge-order and review-since do NOT create PRs.
Step 1: Analyze
Branch, commits since base, diff stats; PR type (--draft, or wip/draft/poc in branch/commits → suggest draft); size Small/Medium/Large (thresholds in TEMPLATES.md; conflicting signals → larger). Present for confirmation.
Step 2: Determine Target
Infer target from branch name and confirm with the user before proceeding: hotfix/* → latest release/* if one exists, else main; everything else → main.
Title <type>: <description> and issue links: TEMPLATES.md. Branch not on remote (git ls-remote --heads origin "<branch>", quoted) → push with -u.
Step 3: Run Checks
| PR type | Tests | Types | Lint | On fail |
|---|---|---|---|---|
| Draft | run | skip | skip | proceed with warning, list failures in body |
| Final | must pass | must pass | must pass | no PR — fix, downgrade to draft, or abort |
Detect commands from project config; ask if unclear. Tests → types → lint, fail fast for final PRs. --skip-checks needs explicit confirmation and adds a "created without running checks" note.
Step 3.6: Preflight CI mirror (when --preflight)
Runs the exact run: blocks of the PR-trigger jobs in .github/workflows/*.yml (/preflight-ci).
python3 .claude/scripts/preflight/preflight.py --project-root . --regenerate
| Exit | Behaviour |
|---|---|
| 0 (green) | Continue |
| 2 (drift) | Exit with error: workflow drift — run /preflight-ci --regenerate first |
| 3 (red) | Block PR creation. Per-job summary, route via _shared/ci-failure-classifier.md; user fixes or passes --skip-checks |
| 4 (degraded) | Warn preflight degraded — continuing without local mirror, continue |
| 5 (incomplete) | Block PR creation. Coverage did not run: jobs_skipped (infra absent → docker compose up -d, re-run) or jobs_incomplete (gating uses: step only CI can run — user decides). --skip-checks overrides. Stricter than the pre-push hook on purpose. |
Step 3.7: Specialist Review (pre-flight fan-out)
CI remains the gate of record. Check pr-review-toolkit is installed (GATES.md). Absent → cross-check first (a skip verdict earns more scrutiny): if pr-review-toolkit:code-reviewer is available, run it. Else emit Specialist review skipped (pr-review-toolkit not installed) and continue — do not block.
Door + blast radius set the review tier (GATES.md). Select specialists from the diff and tier (code-reviewer always) + the Standards and Spec axes (TWO-AXIS.md), in one message. A missing or wrong requirement (task, intent, ISA) is MUST-FIX; a smell never blocks alone; buckets: MUST-FIX / NICE-TO-HAVE / NO-ACTION.
Push gate: unresolved MUST-FIX blocks PR creation. Fix (re-run checks + 3.7), defer (forge task add after applying _shared/task-triage.md — default --epic E99; schema/auth/money/security never deferred), or --proceed-anyway (reason in Pre-flight notes). NICE-TO-HAVE → Pre-flight notes, no gate.
Step 3.8: Local review-bot gate (pre-push)
Runs forge.localReview (e.g. codex review --base {base}) before the push, so findings don't each cost an Actions run. Unset → skip silently. Mechanics: GATES.md.
- Presence: binary not on PATH (
command -v) → emitLocal review skipped (<binary> not on PATH), continue. Never block on a missing reviewer. - No prompt argument:
--basecannot be used with a[PROMPT]argument (codex-cli 0.144.1); put review guidance inAGENTS.mdat the repo root instead. - Resolve, then invoke — two steps, never one pipeline: read
git config forge.localReview; substitute{base}with the Step 2 target branch, shell-quoted (git check-ref-formatpermits;,$(…)and&&in branch names, so an unquoted branch can append a second command); show it, then run it as its own invocation — never piped to a shell oreval. - Run it in the background (
run_in_background) alongside 3.7; no polling. Do not edit files while a review is in flight — kill and re-run instead. - Triage as in 3.7; ambiguous severity → MUST-FIX.
- Push gate: unresolved MUST-FIX blocks PR creation, exactly as in 3.7. Fix → re-run Step 3 checks → re-run this step. Background execution does not relax this: never create the PR while a review is still running.
- Round cap: stop after 3 local review rounds and hand back to the user. Never run it unattended, in a hook, or in a
/loop.
Step 3.9: Documentation Verification (final PRs only)
Invoke /refresh-project-context (README, API docs, CHANGELOG Unreleased, doc examples). Issues → present, offer to fix.
Step 4: Generate Description
Size-matched template from TEMPLATES.md; see Output rules.
Step 5: Create PR
- Push the branch if needed.
- If
forge.reviewBotis set: the body MUST end with its line before the attribution. Create viagh pr create --body-file, then verify:gh pr view <N> --json body --jq .body | grep -qF -- "$(git config forge.reviewBot)" || echo MISSING. Missing →gh pr edit --body-file. - If unset: create via
gh pr create --body-filewith no bot mention. - Present the PR URL + the
/create-pr review <N>hint.
Step 6: Review Loop (/create-pr review [PR#])
- Targets:
<PR#>, else all the user's open PRs. Fetch reviews, comments, inline comments, CI (REVIEW.md). - Triage: MUST-FIX (bug, security, broken test, regression) / NICE-TO-HAVE (style, small refactor) / NO-ACTION.
- Each MUST-FIX:
gh pr checkout <N>→ fix → Step 3 checks → re-run Step 3.7 on the fix diff (skip only for a pure revert/typo) → commitfix(review): address review feedback on <topic> (PR #<N>)→ push. Same PR — never close-and-recreate. Comment viagh pr comment <N> --body-file <file>(Addressed in <sha>:per finding, then the bot line); never--body "…". Security finding →security-bossre-review first (REVIEW.md). - NICE-TO-HAVE: apply if cheap, else defer and note it in a PR comment.
- Status report: always emit, one line per PR, no prose; verdict
safe-to-merge/re-review-pending/blocked(format: REVIEW.md). - Wait condition: bot silent → suggest a
/loopor wakeup (REVIEW.md). No bot → no waiting.
Step 7: Multi-PR Merge Order (/create-pr merge-order)
Order safe-to-merge PRs by file overlap, risk and size (REVIEW.md). Never auto-merge.
Key Rules
- Always confirm target branch before creating.
- Never create a final PR with failing checks (offer draft instead).
- Consult the review bot locally BEFORE pushing (Step 3.8): max 3 rounds, never unattended.
- Review fixes go to the SAME PR; re-mention the bot to retrigger review.
- Always include the Claude Code attribution.
Project-specific overrides: if SKILL.local.md exists in this directory, read it — it is consumer-owned, survives framework refresh, and wins on conflict. A sidecar that relaxes a gate defined above must state how to prove the gate is wrong in that case. Doctrine: rules/framework-vs-project-root.md.
04 同仓库更多 Skills
wizard
Generates an interactive bash wizard that walks a human through steps only they can perform — opens each URL, says what to click and copy, captures values (hidden entry for secrets), writes .env and GitHub secrets, confirms before irreversible actions. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
vet-idea
Vets an idea, decision, or plan BEFORE it is built. Runs a single model through five fixed adversarial advisor roles, a peer-review pass, and a chairman synthesis that emits a halt-capable GO / NO-GO / RECONSIDER verdict. Advisory and non-mutating — outputs a report, never writes task state. Use when an idea, feature, or costly hard-to-reverse decision is of uncertain worth and the question is whether to build it at all. NOT FOR settled work (bug fixes, approved features) or for shaping how to build it (the ISA Interview workflow).
triage-incident
Production incident triage — from "something is broken for users" to fixed, verified, and learned-from. Pulls the error signal (Sentry/logs/user report), reproduces before touching code, routes the fix through /fix-bug's prod fast path, and closes with a postmortem entry. Use when something is broken for users in production — an outage, data corruption, a Sentry spike, or a crash-rate alert. NOT FOR bugs found in development (use /fix-bug directly) or CI failures (use /diagnose-ci).
setup-review-bot
Configures a repo's AI code reviewers — the post-PR mention bot and the pre-push local reviewer — and writes the AGENTS.md the reviewers read. Interviews the user for what the reviewer should weight, then sets git config forge.reviewBot / forge.localReview and populates AGENTS.md at the project root. Use when a repo has no reviewer configured, when review findings are consistently off-target, or when onboarding a new project.
security-review
Portable security review for a feature, endpoint, or change before it ships. Orchestrates the existing OWASP review (@security-boss) and secrets scan (security_secrets validator), then adds the pass they miss — an explicit business-logic-flaw walkthrough (IDOR, race/TOCTOU, state-machine bypass, privilege escalation, price/quantity tampering). Advisory and non-mutating — produces a findings report; real findings are filed as tasks. Use when a change touching money, access control, or multi-step state is about to ship, or when the auth looks fine but the flow could be abused. NOT FOR SAST or dependency-CVE scanning (consumer CI owns those).
run-epic
Autonomously drains every open task in a single epic. Pulls ready tasks via the forge CLI, executes the work in-context using the matching discipline (fix-bug / new-feature / refactor), files newly-discovered work as follow-up tasks without stopping to ask, opens a PR per completed task via /create-pr, and repeats until the epic has zero ready/in-progress/pending tasks. Use when the user says `/run-epic E##`, "run epic autonomously", "finish all remaining tasks for epic X", or "drive epic X to completion".