create-pr

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:

main (default)
develop
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