create-pr

Create a GitHub pull request from the current branch using gh CLI. Reads chalk.json for project context to generate better test instructions and embeds visual artifacts if available.

Workflow

1. Check prerequisites — Run git status to verify:

- Not on main/master (if so, warn and suggest creating a branch) - No uncommitted changes (if there are, suggest running /commit first) - Branch has commits ahead of base branch

1. Analyze changes — Run git log main..HEAD --oneline and git diff main...HEAD --stat to understand all changes.

1. Read project context — Read .chalk/chalk.json if it exists:

- test.command — for test plan instructions - dev.command — for setup instructions - routes — to identify affected pages - project.framework — for framework-specific review notes

1. Determine base branch — Default to main. If the user specifies a different target, use that.

1. Push the branch — Run git push -u origin <branch> if not already pushed.

1. Create the PR — Use gh pr create with:

- A concise title (under 70 characters) following conventional commit style - A structured body (see format below)

1. Report — Show the user the PR URL.

PR Body Format

## Summary
<1-3 bullet points describing what changed and why>

## Changes
<Bulleted list of specific changes, grouped by area>

## Test plan
<How to verify — include actual commands from chalk.json if available>
<e.g., "1. Run `npm run dev` 2. Navigate to /dashboard 3. Verify...">

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Visual Preview Section

After generating the body, check if .github/pr-screenshots/ exists and contains .png or .gif files. If it does, append a ## Visual Preview section before the footer:

## Visual Preview

### <Page Name>
![<page-name>](/.github/pr-screenshots/<page-name>.png)
![<page-name> interaction](/.github/pr-screenshots/<page-name>.gif)

• Group images by page/route with subheadings
• Include both screenshots and GIFs if both exist
• Use relative paths — GitHub renders these inline in PR descriptions
• If no screenshots exist, omit this section

If no screenshots exist and the branch has UI changes (changes to components, pages, styles, templates), suggest running /capture-pr-visuals first.

Title Convention

Match the conventional commit style of the primary change:

• feat(scope): description for feature branches
• fix(scope): description for bug fix branches
• If the branch has mixed types, use the most significant one

Rules

• NEVER force push
• NEVER create PRs to main without user confirmation if there are destructive changes
• Always use gh pr create (not the GitHub web UI)
• Pass the PR body via HEREDOC for proper formatting
• If gh is not authenticated, tell the user to run gh auth login
• Include relevant issue references (e.g., "Closes #34") if the branch name or commits reference an issue
• Test plan should use actual commands from chalk.json when available (e.g., real test.command, real dev.command)