create-pr

name	create-pr
description	Stage, commit, push, and open a pull request following project conventions and the Conventional Commits spec. Accepts optional skip-checks argument to bypass validation when called from /build.
when_to_use	Use when user says "create a PR", "open a PR", "ship it", "submit a pull request", or "open a merge request", or when work on a branch is complete and ready to publish for review.
argument-hint	[optional: skip-checks | ticket/issue number e.g. VGV-123 | short description]
disable-model-invocation	true
allowed-tools	Bash(git push *) Bash(git add *) Bash(git commit *) Bash(gh *) Bash(glab *)
compatibility	Designed for Claude Code (or similar products with git access)

Create a pull request

Stage uncommitted changes, commit them, push the branch, and open a pull request on the project's Git hosting platform.

Steps checklist

• Step 0: Parse arguments
• Step 1: Validate (skip if SKIP_CHECKS)
• Step 2: Assess git state and determine base branch
• Step 3: Stage and commit
• Step 4: Push
• Step 5: Run CI checks (skip if SKIP_CHECKS)
• Step 6: Open PR

Important

• Do not push before the user confirms the commit.
• Use the current branch as the source; target is BASE_BRANCH (determined in Step 2).

Context

$ARGUMENTS

This may include skip-checks, a ticket number (e.g. VGV-123), a short description, or be empty.

Step 0: Parse arguments

Check whether the argument contains skip-checks. Store as SKIP_CHECKS (boolean).

Extract the ticket number or short description from the remaining argument text (if any).

Step 1: Validate (conditional)

Skip this step if SKIP_CHECKS is true.

Detect and run the project's formatter, linter, and test runner.

If any command fails, report the error and stop. Do not proceed until all checks pass.

Step 2: Assess git state and determine base branch

Run in parallel:

git branch --show-current
git status --short
git diff --cached
git diff

• If the branch is main or master, warn the user and stop.
• If there are no staged or unstaged changes:
  • Run git log <BASE_BRANCH>..HEAD --oneline. If there are no commits ahead of BASE_BRANCH, inform the user there is nothing to commit or push, and stop.
  • Otherwise, inform the user there is nothing new to commit and skip to Step 5.

Determine base branch

Use AskUserQuestion:

Question: "Which branch should this PR target?"

Options:

1. main (default)
2. develop
3. Other — let the user type a custom branch name

Store as BASE_BRANCH.

Step 3: Stage and commit

Produce a single conventional commit covering all changes.

• Never stage secret files: .env, *.key, *.pem, *secret*, *credential*, *.p12, *.jks.
• Stage the remaining changes with git add.
• Propose one commit message following Conventional Commits (type(scope): subject). Consult references/conventional-commits.md for the full spec. Infer type from a plan file in docs/plan/ if present; otherwise infer from the diff. Extract the ticket number from the branch name (e.g. feat/VGV-59-... → VGV-59) into a Refs: line.

Use AskUserQuestion to confirm before committing (Yes / No / Edit). On confirm, commit with a HEREDOC to preserve formatting. Do not push yet.

Step 4: Push

Consult references/push.md to push the branch and handle any failures.

Step 5: Run CI checks (conditional)

Skip this step if SKIP_CHECKS is true.

Consult references/ci-checks.md to discover and run checks locally from .github/workflows/ci.yaml.

If any check fails, report the errors and stop. Do not proceed until all checks pass.

Step 6: Open PR

Gather commit context

Run in parallel:

git log <BASE_BRANCH>..HEAD --oneline
git log <BASE_BRANCH>..HEAD --format="%s%n%b"
git diff <BASE_BRANCH>..HEAD --stat

Extract the ticket number from the branch name (e.g. feat/VGV-59-... → VGV-59) or from the argument.

PR title

Follow Conventional Commits summarizing the overall change:

type(scope): short description

• Max 72 characters. Imperative mood, no period, no capital after colon.

PR description

Check for a template:

cat .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null

• Template exists: use it as structure; strip HTML comments; pre-fill the Type of Change section by checking the checkbox matching the commit type:
  • feat → ✨ New feature
  • fix → 🛠️ Bug fix
  • refactor → ♻️ Refactor
  • docs → 📝 Documentation
  • test → 🧪 Tests
  • chore/build/ci → 🔧 Maintenance
• No template: consult references/pull-request-template.md for the default template and filling rules.

Output the proposed PR:

## Proposed PR

**Title:** `type(scope): short description`

**Description:**

...

Confirm and create

Use AskUserQuestion:

Question: "Do you want me to create this PR?"

Options:

1. Yes — consult references/pr-cli.md to detect the available CLI tool, check for an existing PR, and create it.
2. No — stop; the Markdown above is ready for manual use.
3. Edit — ask what to change, revise, ask again.