--- name: push-pr version: 1.0.0 description: 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). license: MIT allowed-tools: Bash(git checkout -b:*), Bash(git switch -c:*), Bash(git add:*), Bash(git status:*), Bash(git push:*), Bash(git commit:*), Bash(python3:-I */pr/new_pr.py*), Bash(git diff:*), Bash(git branch:*), Bash(mkdir:-p .project-toolkit/scratch), Edit(.project-toolkit/scratch/pr-body-*.md) # Security note: python3 -I is the identity-hardened form (issue #4825). # The Edit entry above is scoped to the secure allocator's output file only. # The Bash tool executor must sanitize arguments to prevent command injection (CWE-78). # Shell metacharacters (; && | etc.) should be escaped/rejected before execution. user-invocable: true metadata: routing: role: front-door invoker: autoplan trigger: autoplan routes push-only requests to push-pr user-facing: true --- # 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: 1. Create a new branch if on main. 1. 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`). 2. 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. 3. Run the secure path allocator: ```bash python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --prepare-body-file ``` - 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 ``, 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 `` 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. 4. Check the title and body file before the push, which can take minutes: ```bash python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --preflight --title "" --body-file ".project-toolkit/scratch/pr-body-.md" ``` `--preflight` checks the title format and the body file name, mode, and marker. It makes no network call and creates nothing. The dash and escaped newline checks still run at step 6. Fix a rejection here. 5. Push the branch to origin. 6. Create a pull request using the new_pr skill script: ```bash python3 -I "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr/new_pr.py" --title "" --body-file ".project-toolkit/scratch/pr-body-.md" ``` - Branch checked out in a worktree outside the clone, and the command runs from another checkout (for example the primary clone): append `--head ""`. 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 names both rules at once: the file name pattern and mode 600. `--prepare-body-file` creates a file that meets both. - 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 #123`: auto-closes issue when PR merges - `Fixes #456`: auto-fixes issue when PR merges - `Resolves #789`: auto-resolves issue when PR merges - Ensure PR template sections are completed 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 - [ ] Branch created off main when the working branch was main, never a push to main - [ ] Title follows conventional commit format - [ ] Body written into the allocator's returned path, copied exactly, never through a shell variable - [ ] Every template section adapted from the real diff, with no placeholder comment left in - [ ] An `## Acceptance criteria` heading present with `- [ ]` bullets, checked only where met - [ ] Issue-linking keyword present, and a closing keyword used only when the diff delivers what the issue asks ## 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 4 and 5 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.