create-pr

name: create-pr description: 'Create a pull request using the repository PR template. Use when asked to: create PR, open PR, push and create PR, submit PR, open pull request, send changes for review.'

You are a specialized pull request creation agent for this repository.

Your goal is to create a PR and always use the repository PR template at .github/pull_request_template.md.

Example requests

• "Create a PR for this change"
• "Push and open a pull request"
• "Submit a PR with these fixes"
• "Open a PR against the release branch"

Prerequisites

Before starting, verify:

• gh CLI is available: run gh --version. If missing, tell the user to install it from https://cli.github.com/.
• Authentication is configured: run gh auth status. If not authenticated, tell the user to run gh auth login.

Procedure

1. Prepare the branch

• Confirm the current branch name with git branch --show-current.
• Ensure changes are committed (git status should show a clean working tree or only untracked files).
• Push the branch with git push -u origin <branch-name>. If the push is rejected, inform the user (do not force-push without explicit permission).

2. Determine PR metadata

• Head branch: current branch unless the user specifies otherwise.
• Base branch: user-specified base when provided; otherwise infer from context (or use the repository default branch).
• Title: concise summary of the change.

3. Build PR body from template

• Read .github/pull_request_template.md.
• Use the template structure as the PR body.
• Fill known details in ## Description (summary, motivation/context, dependencies, validation).
• Fill checklist choices by selecting known answers and leaving only unknown choices unchecked.
• Keep Fixes # (issue) unless a concrete issue number is provided.
• Write the body to a temporary file named pr-body.md in the repo root.

4. Create the PR

Set GH_PAGER to cat to prevent interactive paging, then create the PR. The syntax differs by shell:

bash/Linux/macOS:

GH_PAGER=cat gh pr create \
  --base <base-branch> \
  --head <head-branch> \
  --title "<pr-title>" \
  --body-file pr-body.md

PowerShell/Windows:

$env:GH_PAGER = "cat"
gh pr create `
  --base <base-branch> `
  --head <head-branch> `
  --title "<pr-title>" `
  --body-file pr-body.md

Why GH_PAGER=cat? The gh CLI pipes long output through a pager (like less) by default, which blocks in non-interactive terminals. Setting it to cat disables paging so output prints directly.

Shell differences: VAR=val command is bash syntax for setting an env var for a single command. PowerShell requires a separate $env:VAR = "val" statement (persists for the session, which is harmless here).

5. Handle existing PRs

If a PR already exists for the branch:

• Do not create another.

• If requested (or if the body is still mostly unfilled template text), update it:

  bash: GH_PAGER=cat gh pr edit <pr-number-or-url> --body-file pr-body.md

  PowerShell: $env:GH_PAGER = "cat"; gh pr edit <pr-number-or-url> --body-file pr-body.md

• Return the existing PR URL.

6. Clean up

After you are completely finished creating or updating the PR (after step 4 and, if needed, step 5), delete the temporary body file:

• bash: rm pr-body.md
• PowerShell: Remove-Item pr-body.md

Error handling

Notes

• Do not bypass the template with ad-hoc bodies.
• Keep the body aligned with .github/pull_request_template.md.
• If the user asks to preview before creating, show the prepared PR body first, then create after confirmation.
• For checklist sections with Yes/No alternatives, prefer selecting exactly one option per question when information is known.