Create Pr

Create PR

Create a GitHub pull request with verification and Codex review. Runs .workstream/verify.sh (if available), auto-generates title and body from commits, runs Codex review (code or doc), and includes findings in the PR description.

When to Use

• You're ready to open a pull request for your branch
• You want cross-model review included in the PR automatically
• You want consistent PR formatting with auto-generated title/body

Prerequisites

• gh CLI installed and authenticated (gh auth status works)
• On a feature branch with commits ahead of base branch
• Git working tree clean (all changes committed)

Arguments

Additional gh pr create flags are passed through.

Workflow

Copy this checklist and track progress:

Create PR Progress:
- [ ] Step 1: Pre-flight checks
- [ ] Step 2: Run verification
- [ ] Step 3: Gather branch context
- [ ] Step 4: Auto-generate title and body
- [ ] Step 5: Run Codex review
- [ ] Step 6: Show preview and confirm
- [ ] Step 7: Create PR

Step 1: Pre-flight Checks

Check gh CLI

gh auth status

If not authenticated:

gh CLI is not authenticated.

Run: gh auth login

Check Branch State

CURRENT_BRANCH=$(git branch --show-current)

If on main or master:

CREATE PR: ABORTED
===================
You are on the main branch. Create a feature branch first.

Check Clean Working Tree

git status --porcelain

If dirty:

CREATE PR: WARNING
==================
You have uncommitted changes. Commit or stash them first.

Uncommitted files:
{list of files}

Use AskUserQuestion:

Question: "You have uncommitted changes. How would you like to proceed?"
Header: "Dirty tree"
Options:
  - Label: "Commit all changes"
    Description: "Stage and commit everything before creating PR (Recommended)"
  - Label: "Continue anyway"
    Description: "Create PR with current commits only"
  - Label: "Cancel"
    Description: "Stop and handle changes manually"

If "Commit all changes": stage all, commit with auto-generated message, then continue. If "Cancel": stop.

Check Commits Ahead

# Detect base branch
BASE_BRANCH="${BASE:-$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null || echo 'main')}"

# Count commits ahead
COMMITS_AHEAD=$(git rev-list --count $BASE_BRANCH..HEAD 2>/dev/null || echo "0")

If 0 commits ahead:

CREATE PR: ABORTED
===================
No commits ahead of {base_branch}. Nothing to create a PR for.

Push to Remote

# Check if remote tracking branch exists and is up to date
git rev-parse --abbrev-ref @{upstream} 2>/dev/null
UNPUSHED=$(git rev-list --count @{upstream}..HEAD 2>/dev/null || echo "all")

If unpushed commits (or no upstream):

git push -u origin $CURRENT_BRANCH

Step 2: Run Verification

If --skip-verify is set: Skip this step entirely, continue to Step 3.

Check for Verification Script

[[ -f .workstream/verify.sh ]]

If .workstream/verify.sh does not exist:

• Skip verification silently
• Continue to Step 3

Run Verification

bash .workstream/verify.sh

This runs the project's verification gate (typically: typecheck → lint → test → build).

Handle Results

If verification passes (exit code 0):

VERIFICATION: PASSED
====================
All checks passed (typecheck, lint, test, build).

Continue to Step 3.

If verification fails (non-zero exit code):

VERIFICATION: FAILED
====================

{verification output showing failures}

Fix the issues above before creating a PR.

Use AskUserQuestion:

Question: "Verification failed. How would you like to proceed?"
Header: "Verify failed"
Options:
  - Label: "Fix issues first"
    Description: "Stop PR creation, address the failures (Recommended)"
  - Label: "Create PR anyway"
    Description: "Proceed despite verification failures"
  - Label: "Cancel"
    Description: "Abort PR creation"

If "Fix issues first": stop and show what needs fixing. If "Create PR anyway": continue to Step 3 (note failure in PR body). If "Cancel": stop.

Step 3: Gather Branch Context

# Commits on this branch
git log --oneline $BASE_BRANCH..HEAD

# Full diff stat
git diff $BASE_BRANCH...HEAD --stat

# Changed files list (for review type detection)
git diff $BASE_BRANCH...HEAD --name-only

Detect Review Type

Check changed files to determine whether to use /codex-review (code) or /codex-consult (docs):

# Get list of changed file extensions
git diff $BASE_BRANCH...HEAD --name-only

Code file extensions: .ts, .tsx, .js, .jsx, .py, .go, .rs, .java, .rb, .php, .swift, .kt, .c, .cpp, .h, .cs, .sh, .bash, .zsh, .sql, .graphql, .vue, .svelte

Doc file extensions: .md, .txt, .json, .yaml, .yml, .toml, .xml, .csv, .env, .conf, .cfg, .ini

Rules:

• If ANY code files are in the diff: use /codex-review
• If ONLY doc/config files changed: use /codex-consult
• Default to /codex-review if unsure

Step 4: Auto-generate Title and Body

Title Generation

If --title not provided, generate from branch name and commit log:

1. Parse branch name: feature/add-auth -> Add auth
2. If branch name is unhelpful (e.g., fix-123), use the first commit subject
3. Keep under 70 characters

Body Generation

Generate PR body from commit log:

# Get commit subjects and bodies
git log --format="- %s%n%n%b" $BASE_BRANCH..HEAD

Structure the body:

## Summary
{2-4 bullet points summarizing the changes from commit messages}

## Changes
{For each commit:}
- {commit subject}

## Test plan
- [ ] {Inferred testing steps based on changes}

Step 5: Run Codex Review

If --skip-review is set:

• Skip this step entirely
• Add to PR body: **Codex Review:** SKIPPED (--skip-review)
• Continue to Step 6

If running inside Codex (CODEX_SANDBOX set):

• Skip this step
• Add to PR body: **Codex Review:** SKIPPED (running inside Codex)
• Continue to Step 6

Check Codex Availability

codex --version 2>/dev/null

If Codex not available:

• Skip review silently
• Add to PR body: **Codex Review:** SKIPPED (Codex CLI not available)
• Continue to Step 6

Run Review

Based on review type detected in Step 2:

For code changes: Invoke /codex-review with the optional focus area. The review runs against the current branch vs base branch.

For doc-only changes: Invoke /codex-consult on the diff content.

Handle Results

Parse the Codex output for severity levels (see EVALUATION_PRACTICES.md):

If critical issues found:

CODEX REVIEW: CRITICAL ISSUES
==============================

{List of critical issues}

Critical issues must be addressed before creating the PR.

Use AskUserQuestion:

Question: "Codex found critical issues. How would you like to proceed?"
Header: "Critical"
Options:
  - Label: "Fix issues first"
    Description: "Stop PR creation, address the issues (Recommended)"
  - Label: "Create PR anyway"
    Description: "Proceed with critical issues noted in PR body"
  - Label: "Cancel"
    Description: "Abort PR creation"

If "Fix issues first": stop and list what needs fixing. If "Create PR anyway": continue with issues in body.

If no critical issues (pass or pass_with_notes): Continue with findings in body.

Format Findings for PR Body

Append a Codex Review section to the PR body:

## Codex Review
**Status:** {PASS | PASS WITH NOTES | NEEDS ATTENTION}
**Model:** {model used}

{If recommendations:}
### Recommendations
{numbered list of recommendations}

{If positive findings:}
### Positive Findings
{bulleted list}

Step 6: Show Preview and Confirm

Display the complete PR before creating:

PR PREVIEW
==========

Title: {title}
Base:  {base_branch} <- {current_branch}
Type:  {regular | draft}

Body:
---
{full PR body}
---

Use AskUserQuestion:

Question: "Create this PR?"
Header: "Confirm PR"
Options:
  - Label: "Yes, create PR"
    Description: "Create the pull request as shown (Recommended)"
  - Label: "Edit title"
    Description: "Change the PR title before creating"
  - Label: "Cancel"
    Description: "Abort PR creation"

If "Edit title": ask for new title via AskUserQuestion, then re-preview. If "Cancel": stop.

Step 7: Create PR

gh pr create --title "$TITLE" --body "$(cat <<'EOF'
{full PR body}

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

Add flags as needed:

• --base $BASE_BRANCH if non-default base
• --draft if draft mode requested

Report Success

PR CREATED
==========

{PR URL from gh output}

Title: {title}
Base:  {base_branch} <- {current_branch}
Review: {PASS | PASS WITH NOTES | NEEDS ATTENTION | SKIPPED}

Error Handling

Configuration

Codex review uses existing configuration from .claude/settings.local.json:

{
  "codexReview": {
    "enabled": true,
    "codeModel": "gpt-5.3-codex"
  },
  "codexConsult": {
    "enabled": true,
    "researchModel": "gpt-5.2"
  }
}

If both codexReview.enabled and codexConsult.enabled are false, Codex review is skipped entirely.

Examples

Basic PR:

/create-pr

Skip verification (e.g., for doc-only changes):

/create-pr --skip-verify

Skip Codex review:

/create-pr --skip-review

Skip both verification and review (fastest):

/create-pr --skip-verify --skip-review

Security-focused review with custom base:

/create-pr security --base develop

Draft PR with custom title:

/create-pr --draft --title "WIP: Add authentication"