/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

<context>$ARGUMENTS</context>

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.