Push PR
Commit, push, and open a pull request whose body is adapted from the real diff
rather than copied from the template.
Migrated from .claude/commands/push-pr.md under ADR-064, which makes skills the
single user-invocable surface. The scoped allowed-tools grant, the
identity-hardened python3 -I form, and both vendor-portability declarations
carry over unchanged: they are the security contract, not formatting.
Triggers
push and open a PR, open a pull request, push this branch,
commit and push
Context
- Current git status: !
git status
- Current git diff (staged and unstaged changes): !
git diff HEAD
- Current branch: !
git branch --show-current
Process
Based on the above changes:
Create a new branch if on main.
- Determine the type of change that maps to a conventional commit type
followed by a 3-5 word description (for example,
fix/parser-log-enrichment).
Read @.github/PULL_REQUEST_TEMPLATE.md. Step 3 seeds it into the body file; use this copy only when the seeded file holds the marker alone.
Run the secure path allocator:
python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --prepare-body-file
- On Windows the allocator refuses to run. Follow the
Windows PR Body Fallback section below for steps 3, 4, 5, and 7.
- Copy the returned path exactly. Do not store it in a shell variable because
each tool call runs in a fresh shell.
- The file starts with the line
<!-- replace with PR body -->, followed by the
repository PR template. Use the Edit tool to fill the template sections in
that exact file, then delete the marker line. A body that still contains the
marker text anywhere is rejected.
- If the file holds only the marker, the repository has no usable template.
Replace it with the template you read in step 2, adapted to the change.
- Fill in all sections with actual change information from git diff
- Replace placeholder comments with substantive content
- Check appropriate Type of Change boxes based on actual changes
- List specific files changed, test coverage added, security impacts
- Do NOT leave template comments like
<!-- Brief description --> unfilled
- Do NOT copy the template verbatim - adapt every section to your changes
- Include an
## Acceptance criteria heading with - [ ] or * [ ] bullets. The Validate Spec Coverage job reads these from the PR body, not the linked issue. When the PR links a spec or an issue, an unchecked box or a missing section makes the deterministic check report FAIL, and that FAIL does not block the merge, so check a box only once the criterion is actually met. Numbered criteria are not recognized.
Check the title and body file before the push, which can take minutes:
python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --preflight --title "<conventional commit title>" --body-file ".project-toolkit/scratch/pr-body-<returned-uuid>.md"
--preflight checks the title format and the body file: its path, that it is a regular UTF-8 file, and that the placeholder line is gone.
It makes no network call and creates nothing. The dash and escaped newline
checks still run at step 7. Fix a rejection here.
Check that the body names only files the diff touches, before the push. The
required Validate PR check fails on a path the diff does not touch, and the
fix costs a CI round after the PR opens. Commit first: local mode reads
committed HEAD only, so an uncommitted file reads as not in the diff. Run
the local mode, which reads the same body file and
git diff origin/main...HEAD with no network call:
uv run --frozen python -I scripts/validation/pr_description.py --body-file ".project-toolkit/scratch/pr-body-<returned-uuid>.md" --base origin/main
- Exit 1 means a CRITICAL finding, usually
File mentioned but not in diff.
Stop. If every flagged path appears in git status, commit instead of
editing the body. Otherwise edit the body file (remove the path, move it
out of the change heading, or wrap it in a code fence), then re-run until
it exits 0.
- Exit 2 means the check could not run: an unreadable or non-UTF-8 body
file, an unknown or invalid base ref, or git unavailable. For a missing
origin/main, pass --base with the ref the PR targets, such as
<remote>/<default-branch>. Do not skip the step.
- Do not apply the
description-validation-bypass label. A human maintainer
decides that.
- A checkout without
scripts/validation/pr_description.py, such as a plugin
install, cannot run this step. Say it was not run, and compare every
path under the change heading (inline code, bold, list item, or link) to
git diff --name-only origin/main...HEAD by hand.
Push the branch to origin.
Create a pull request using the new_pr skill script:
python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --title "<conventional commit title>" --body-file ".project-toolkit/scratch/pr-body-<returned-uuid>.md"
- Branch checked out in a worktree outside the clone, and the command runs from another checkout (for example the primary clone): append
--head "<branch>". Running the command from the worktree itself needs no --head, because new_pr.py uses the current branch. Never remove the worktree to open the PR. Push the branch first, since gh resolves the head on the remote. new_pr.py exits 2 and prints the push command when origin lacks the branch.
- A rejected body file fails one of these checks: the path must resolve under the repo root, a temp directory, or the git dir; it must be a regular UTF-8 file; and it must no longer hold the
<!-- replace with PR body --> line. --prepare-body-file creates a unique path that passes the path check.
- Title MUST follow conventional commit format (e.g.,
feat: Add feature, fix(auth): Resolve bug)
- Body SHOULD include GitHub issue linking keywords to auto-close issues:
Closes #<number>: auto-closes issue when PR merges
Fixes #<number>: auto-fixes issue when PR merges
Resolves #<number>: auto-resolves issue when PR merges
- Ensure PR template sections are completed
Windows PR Body Fallback
Use this only on Windows, and only when step 3 exits 2 with
ERROR: secure PR body files are not supported on Windows. Every other
platform keeps the allocator mandatory. The allocator needs directory file
descriptors and owner-only modes that Windows does not provide.
new_pr.py accepts --body '<text>' in place of --body-file. That path
never calls the allocator or its file reader. The helper still runs the same
title, dash, and escaped newline checks, then hands the body to gh on
stdin, never as a command-line argument to gh.
Skip --prepare-body-file. Fill the PR template from step 2 into the body
text yourself, with the same rules as step 3.
Step 4 preflight: pass --body '<body text>' instead of --body-file. It
checks the title only, since there is no file to check.
Step 5: pr_description.py --body-file reads any readable file. Run
mkdir -p .project-toolkit/scratch first, because the allocator refused
before it created that directory. Create pr-body-windows.md in it with
Write and expect one permission prompt. Later Edit fixes after a step 5
exit 1 stay inside the scoped Edit grant.
Step 7: run the same command with the body text inline:
python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --title "<conventional commit title>" --body '<body text>'
- Paste the file's final contents, unchanged, as the
--body text. Step 5
checked the file, so every edit made there must reach this command.
- Quote the body so the shell passes it literally. In bash or Git Bash,
use single quotes and write each apostrophe as
'''. In PowerShell,
use a single-quoted here-string (@' ... '@). Never use double quotes:
bash runs each backtick code span as a command and expands $name, and
PowerShell treats the backtick as an escape and also expands $.
- Write the body literally in the command. Do not build it from a shell
variable, for the same fresh-shell reason as step 3.
- Use real line breaks inside the quoted text, never
\n. If the escaped
newline check fails, its message says to pass --body-file. That is the
refused path on Windows, so fix the line breaks instead.
- Windows caps a command line near 8191 characters in cmd.exe and 32767
through CreateProcess. The body rides on argv twice: to
new_pr.py, then
to validate_pr_description.py. If the command fails for length, trim
the body and keep every required template section.
- Do not add
--skip-validation. The fallback changes how the body arrives,
not which checks it must pass.
You have the capability to call multiple tools in a single response. You MUST do all of the above in a single message. Do not use any other tools or do anything else. Do not send any other text or messages besides these tool calls.
Verification
Anti-Patterns
| Avoid |
Why |
Instead |
| Storing the allocator path in a shell variable |
Each tool call runs a fresh shell, so the variable is empty on the next call and the body lands nowhere |
Copy the returned path literally into the next call |
| Copying the template verbatim |
Ships placeholder comments as the PR description, and the spec-coverage job reads them |
Adapt every section from the diff |
| Numbered acceptance criteria |
The Validate Spec Coverage job reads - [ ] and * [ ] only, so numbered items are invisible to it |
Use checkbox bullets |
| Checking a criterion box before it is met |
The signal reports a pass the PR does not have, and the FAIL it should have shown does not block merge |
Check a box only once the criterion holds |
Widening the allowed-tools grant to bare Bash |
Removes the CWE-78 argument scoping that makes this skill safe to auto-approve |
Add a specific scoped entry |
Extension Points
- Other forges. Steps 3, 4, and 7 call
new_pr.py. A non-GitHub forge swaps that
helper; the template-adaptation rules in step 4 are forge-independent.
- Template changes. Step 4's section list follows the repository PR
template read in step 3. When that template gains a parsed section, add it to
step 4 and to the Verification list together.
- Branch naming. Step 1's conventional-type mapping is the repository
convention; a project with a different scheme changes that sub-step alone.
1---2name: push-pr-33description: Commit the working tree, push the branch, and open a pull request with the repository template filled in from the real diff. Use when you say `push and open a PR`, `open a pull request`, or `push this branch`. Do NOT use to run the pre-ship review gates (use ship), and do NOT use to validate PR metadata alone (use validate-pr-description).4metadata:5 source: https://skillmd.com/skills/rjmurillo/push-pr-36---78# Push PR910Commit, push, and open a pull request whose body is adapted from the real diff11rather than copied from the template.1213Migrated from `.claude/commands/push-pr.md` under ADR-064, which makes skills the14single user-invocable surface. The scoped `allowed-tools` grant, the15identity-hardened `python3 -I` form, and both vendor-portability declarations16carry over unchanged: they are the security contract, not formatting.1718## Triggers1920`push and open a PR`, `open a pull request`, `push this branch`,21`commit and push`2223## Context2425- Current git status: !`git status`26- Current git diff (staged and unstaged changes): !`git diff HEAD`27- Current branch: !`git branch --show-current`2829## Process3031Based on the above changes:32331. Create a new branch if on main.34 1. Determine the type of change that maps to a conventional commit type35 followed by a 3-5 word description (for example, `fix/parser-log-enrichment`).362. Read @.github/PULL_REQUEST_TEMPLATE.md. Step 3 seeds it into the body file; use this copy only when the seeded file holds the marker alone.373. Run the secure path allocator:3839 ```bash40 python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --prepare-body-file41 ```4243 - On Windows the allocator refuses to run. Follow the44 Windows PR Body Fallback section below for steps 3, 4, 5, and 7.45 - Copy the returned path exactly. Do not store it in a shell variable because46 each tool call runs in a fresh shell.47 - The file starts with the line `<!-- replace with PR body -->`, followed by the48 repository PR template. Use the Edit tool to fill the template sections in49 that exact file, then delete the marker line. A body that still contains the50 marker text anywhere is rejected.51 - If the file holds only the marker, the repository has no usable template.52 Replace it with the template you read in step 2, adapted to the change.53 - **Fill in** all sections with actual change information from git diff54 - **Replace** placeholder comments with substantive content55 - **Check** appropriate Type of Change boxes based on actual changes56 - **List** specific files changed, test coverage added, security impacts57 - **Do NOT** leave template comments like `<!-- Brief description -->` unfilled58 - **Do NOT** copy the template verbatim - adapt every section to your changes59 - **Include** an `## Acceptance criteria` heading with `- [ ]` or `* [ ]` bullets. The Validate Spec Coverage job reads these from the PR body, not the linked issue. When the PR links a spec or an issue, an unchecked box or a missing section makes the deterministic check report FAIL, and that FAIL does not block the merge, so check a box only once the criterion is actually met. Numbered criteria are not recognized.604. Check the title and body file before the push, which can take minutes:6162 ```bash63 python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --preflight --title "<conventional commit title>" --body-file ".project-toolkit/scratch/pr-body-<returned-uuid>.md"64 ```6566 `--preflight` checks the title format and the body file: its path, that it is a regular UTF-8 file, and that the placeholder line is gone.67 It makes no network call and creates nothing. The dash and escaped newline68 checks still run at step 7. Fix a rejection here.695. Check that the body names only files the diff touches, before the push. The70 required `Validate PR` check fails on a path the diff does not touch, and the71 fix costs a CI round after the PR opens. Commit first: local mode reads72 committed `HEAD` only, so an uncommitted file reads as not in the diff. Run73 the local mode, which reads the same body file and74 `git diff origin/main...HEAD` with no network call:7576 ```bash77 uv run --frozen python -I scripts/validation/pr_description.py --body-file ".project-toolkit/scratch/pr-body-<returned-uuid>.md" --base origin/main78 ```7980 - Exit 1 means a CRITICAL finding, usually `File mentioned but not in diff`.81 Stop. If every flagged path appears in `git status`, commit instead of82 editing the body. Otherwise edit the body file (remove the path, move it83 out of the change heading, or wrap it in a code fence), then re-run until84 it exits 0.85 - Exit 2 means the check could not run: an unreadable or non-UTF-8 body86 file, an unknown or invalid base ref, or git unavailable. For a missing87 `origin/main`, pass `--base` with the ref the PR targets, such as88 `<remote>/<default-branch>`. Do not skip the step.89 - Do not apply the `description-validation-bypass` label. A human maintainer90 decides that.91 - A checkout without `scripts/validation/pr_description.py`, such as a plugin92 install, cannot run this step. Say it was not run, and compare every93 path under the change heading (inline code, bold, list item, or link) to94 `git diff --name-only origin/main...HEAD` by hand.956. Push the branch to origin.967. Create a pull request using the new_pr skill script:9798 <!-- vendor-portability: declared. This skill reads the consumer's99 `.github/PULL_REQUEST_TEMPLATE.md` and writes the consumer's100 `.project-toolkit/scratch/` body file. It resolves the helper from the installed101 Copilot or Claude plugin root. The `.claude` fallback is only for this102 repository's self-hosted source checkout; `scripts/pr/` is inside the103 shipped github skill, not the upstream-only top-level scripts/ tree.104 -->105106 ```bash107 python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --title "<conventional commit title>" --body-file ".project-toolkit/scratch/pr-body-<returned-uuid>.md"108 ```109110- Branch checked out in a worktree outside the clone, and the command runs from another checkout (for example the primary clone): append `--head "<branch>"`. Running the command from the worktree itself needs no `--head`, because `new_pr.py` uses the current branch. Never remove the worktree to open the PR. Push the branch first, since `gh` resolves the head on the remote. `new_pr.py` exits 2 and prints the push command when origin lacks the branch.111- A rejected body file fails one of these checks: the path must resolve under the repo root, a temp directory, or the git dir; it must be a regular UTF-8 file; and it must no longer hold the `<!-- replace with PR body -->` line. `--prepare-body-file` creates a unique path that passes the path check.112- Title MUST follow conventional commit format (e.g., `feat: Add feature`, `fix(auth): Resolve bug`)113- Body SHOULD include GitHub issue linking keywords to auto-close issues:114 - `Closes #<number>`: auto-closes issue when PR merges115 - `Fixes #<number>`: auto-fixes issue when PR merges116 - `Resolves #<number>`: auto-resolves issue when PR merges117- Ensure PR template sections are completed118119## Windows PR Body Fallback120121Use this only on Windows, and only when step 3 exits 2 with122`ERROR: secure PR body files are not supported on Windows`. Every other123platform keeps the allocator mandatory. The allocator needs directory file124descriptors and owner-only modes that Windows does not provide.125126`new_pr.py` accepts `--body '<text>'` in place of `--body-file`. That path127never calls the allocator or its file reader. The helper still runs the same128title, dash, and escaped newline checks, then hands the body to `gh` on129stdin, never as a command-line argument to `gh`.1301311. Skip `--prepare-body-file`. Fill the PR template from step 2 into the body132 text yourself, with the same rules as step 3.1332. Step 4 preflight: pass `--body '<body text>'` instead of `--body-file`. It134 checks the title only, since there is no file to check.1353. Step 5: `pr_description.py --body-file` reads any readable file. Run136 `mkdir -p .project-toolkit/scratch` first, because the allocator refused137 before it created that directory. Create `pr-body-windows.md` in it with138 Write and expect one permission prompt. Later Edit fixes after a step 5139 exit 1 stay inside the scoped `Edit` grant.1404. Step 7: run the same command with the body text inline:141142 ```bash143 python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --title "<conventional commit title>" --body '<body text>'144 ```145146 - Paste the file's final contents, unchanged, as the `--body` text. Step 5147 checked the file, so every edit made there must reach this command.148 - Quote the body so the shell passes it literally. In bash or Git Bash,149 use single quotes and write each apostrophe as `'''`. In PowerShell,150 use a single-quoted here-string (`@'` ... `'@`). Never use double quotes:151 bash runs each backtick code span as a command and expands `$name`, and152 PowerShell treats the backtick as an escape and also expands `$`.153 - Write the body literally in the command. Do not build it from a shell154 variable, for the same fresh-shell reason as step 3.155 - Use real line breaks inside the quoted text, never `\n`. If the escaped156 newline check fails, its message says to pass `--body-file`. That is the157 refused path on Windows, so fix the line breaks instead.158 - Windows caps a command line near 8191 characters in cmd.exe and 32767159 through CreateProcess. The body rides on argv twice: to `new_pr.py`, then160 to `validate_pr_description.py`. If the command fails for length, trim161 the body and keep every required template section.162 - Do not add `--skip-validation`. The fallback changes how the body arrives,163 not which checks it must pass.164165You have the capability to call multiple tools in a single response. You MUST do all of the above in a single message. Do not use any other tools or do anything else. Do not send any other text or messages besides these tool calls.166167## Verification168169- [ ] Branch created off main when the working branch was main, never a push to main170- [ ] Title follows conventional commit format171- [ ] Local `pr_description.py --body-file` run exited 0 before the push, or its absence stated172- [ ] Body written into the allocator's returned path, copied exactly, never through a shell variable (Windows: the `--body` fallback, with step 5 still run)173- [ ] Every template section adapted from the real diff, with no placeholder comment left in174- [ ] An `## Acceptance criteria` heading present with `- [ ]` bullets, checked only where met175- [ ] Issue-linking keyword present, and a closing keyword used only when the diff delivers what the issue asks176177## Anti-Patterns178179| Avoid | Why | Instead |180|-------|-----|---------|181| Storing the allocator path in a shell variable | Each tool call runs a fresh shell, so the variable is empty on the next call and the body lands nowhere | Copy the returned path literally into the next call |182| Copying the template verbatim | Ships placeholder comments as the PR description, and the spec-coverage job reads them | Adapt every section from the diff |183| Numbered acceptance criteria | The Validate Spec Coverage job reads `- [ ]` and `* [ ]` only, so numbered items are invisible to it | Use checkbox bullets |184| Checking a criterion box before it is met | The signal reports a pass the PR does not have, and the FAIL it should have shown does not block merge | Check a box only once the criterion holds |185| Widening the `allowed-tools` grant to bare `Bash` | Removes the CWE-78 argument scoping that makes this skill safe to auto-approve | Add a specific scoped entry |186187## Extension Points188189- **Other forges.** Steps 3, 4, and 7 call `new_pr.py`. A non-GitHub forge swaps that190 helper; the template-adaptation rules in step 4 are forge-independent.191- **Template changes.** Step 4's section list follows the repository PR192 template read in step 3. When that template gains a parsed section, add it to193 step 4 and to the Verification list together.194- **Branch naming.** Step 1's conventional-type mapping is the repository195 convention; a project with a different scheme changes that sub-step alone.196197<!-- vendor-portability: .project-toolkit/scratch is created in the consumer workspace198for one-run PR body files. It is not an upstream repository dependency. -->199200<!-- vendor-portability-exec: step 5 runs scripts/validation/pr_description.py, an upstream-only validator the plugin install does not ship. Step 5 states the fallback. -->201<!-- vendor-portability: step 5 reads scripts/validation/pr_description.py only when the consumer checkout carries it, and reports the step as not run otherwise. -->