Git Pull Request Creation

Enhance pull request creation with automatic fork detection, PR template discovery, and proper base branch targeting.

Quick Reference

Workflow:

1. •✓ Check uncommitted changes (commit if needed)
2. •✓ Verify not on mainline (must be on feature branch)
3. •✓ Detect fork setup (origin vs upstream)
4. •✓ Find PR templates
5. •✓ Push branch (if not already pushed)
6. •✓ Create PR using GitHub MCP tools

Sections: Current Git State • Core Workflow • Examples

Current Git State

• •Current branch: !git rev-parse --abbrev-ref HEAD
• •Mainline branch: !${CLAUDE_PLUGIN_ROOT}/skills/pr/scripts/detect-mainline.sh
• •Has uncommitted changes: !git diff-index --quiet HEAD -- 2>/dev/null && echo "no" || echo "yes"
• •Remotes: !git remote -v
• •Commits since mainline: !mainline=$(${CLAUDE_PLUGIN_ROOT}/skills/pr/scripts/detect-mainline.sh); git log ${mainline}..HEAD --oneline 2>/dev/null || echo "unable to determine"

Core Workflow

Follow these steps when the user requests PR creation:

1. Pre-Flight Checks

Use git state from dynamic context above.

Verify branch is not mainline:

If current branch equals mainline branch, error and suggest creating a feature branch first.

If uncommitted changes exist:

1. •Ask user: "You have uncommitted changes. Would you like to commit them first?"
2. •If yes, invoke /git:commit skill using the Skill tool
3. •After commit succeeds, continue with PR process

2. Detect Fork Setup

Use remotes from dynamic context above.

Fork detection:

If both origin and upstream remotes exist, this is a fork setup:

• •Push to: origin (your fork)
• •PR targets: upstream (original repo)
• •head format: username:branch

Direct repository:

If only origin remote exists:

• •Push to: origin
• •PR targets: origin
• •head format: branch

Extract owner/repo from remote URLs for use with GitHub MCP tools.

3. Gather Context

Review commits:

Use commits since mainline from dynamic context above to understand what will be in the PR.

Check if branch is pushed:

# Check if current branch exists on remote
if git ls-remote --heads $push_remote $current_branch | grep -q .; then
  echo "Branch exists on remote"

  # Check if up to date
  local_sha=$(git rev-parse HEAD)
  remote_sha=$(git rev-parse $push_remote/$current_branch)

  if [ "$local_sha" != "$remote_sha" ]; then
    echo "Local branch ahead of remote - need to push"
  fi
else
  echo "Branch not on remote - need to push"
fi

4. Find PR Templates

Search for PR templates:

# Common PR template locations
templates=(
  ".github/PULL_REQUEST_TEMPLATE.md"
  ".github/pull_request_template.md"
  ".github/PULL_REQUEST_TEMPLATE/*.md"
  "docs/PULL_REQUEST_TEMPLATE.md"
  "PULL_REQUEST_TEMPLATE.md"
)

# Check which exist
for template in "${templates[@]}"; do
  if [ -f "$template" ] || ls $template 2>/dev/null; then
    echo "Found template: $template"
  fi
done

If template found:

1. •Read template content
2. •Use template structure for PR description
3. •Fill in relevant sections based on changes

If multiple templates:

• •Check .github/PULL_REQUEST_TEMPLATE/ directory
• •Templates may be categorized (bug_fix.md, feature.md, etc.)
• •Ask user which template applies

5. Push Branch (if needed)

If branch not pushed or outdated:

# Push with upstream tracking
git push -u $push_remote $current_branch

If fork setup:

Verify pushing to correct remote:

• •Should push to origin (your fork)
• •NOT to upstream (original repo)

6. Create Pull Request

Prefer GitHub MCP tools over gh CLI:

Use mcp__plugin_github_github__create_pull_request tool:

owner: {pr_base_owner}  # upstream owner if fork, else origin owner
repo: {pr_base_repo}     # repository name
title: {pr_title}        # Descriptive title
head: {your_username}:{current_branch}  # If fork: user:branch
base: {mainline}         # Target branch (main/master)
body: {pr_description}   # PR description with template

For fork PRs:

• •head format: your-username:branch-name
• •base repository: upstream repository
• •Verify you have permission to create PR to upstream

For direct repository PRs:

• •head format: branch-name
• •base repository: same repository

PR description structure:

If template found, follow it. Otherwise use:

## Summary
- Brief overview of changes (3-5 bullet points)

## Changes
- Detailed list of modifications
- What was added/removed/changed

## Testing
- How changes were tested
- Test cases covered

## Related Issues
Closes #{issue_number}

7. Return PR URL

After PR created:

1. •Report success to user
2. •Provide PR URL for viewing
3. •Mention any next steps (request reviewers, run CI, etc.)

Examples

Example 1: Create PR from Fork

User request: "Create a pull request for my authentication changes"

Steps:

1. •Check uncommitted: None ✓
2. •Current branch: feat/auth, not mainline ✓
3. •Detect fork: Has origin + upstream → Yes, is fork
4. •Push target: origin, PR base: upstream
5. •Check commits: 3 commits since main
6. •Find template: Found .github/PULL_REQUEST_TEMPLATE.md
7. •Push: git push -u origin feat/auth
8. •Create PR using GitHub MCP:
   • •owner: upstream-org
   • •repo: project
   • •head: myusername:feat/auth
   • •base: main
   • •body: Template filled with changes
9. •Return: "PR created: https://github.com/upstream-org/project/pull/123"

Example 2: PR with Uncommitted Changes

User request: "Open a PR for the bug fix"

Steps:

1. •Check uncommitted: Has unstaged changes in login.js
2. •Ask: "You have uncommitted changes. Commit them first?"
3. •User: "Yes"
4. •Invoke /git:commit skill → Creates commit
5. •Detect fork: No (single remote)
6. •Find template: None found
7. •Push: git push -u origin fix/login-bug
8. •Create PR using GitHub MCP:
   • •owner: my-org
   • •repo: my-project
   • •head: fix/login-bug
   • •base: main
   • •body: Auto-generated from commits
9. •Return PR URL

Example 3: PR to Non-Main Branch

User request: "Create PR targeting the develop branch"

Steps:

1. •Pre-flight checks: Pass ✓
2. •Detect fork: No
3. •Base branch: User specified develop (override mainline)
4. •Push branch
5. •Create PR with base: develop
6. •Return PR URL

Task Coordination

At workflow start:

• •Create coordination task with TaskCreate:
  • •subject: "Create pull request"
  • •activeForm: "Creating pull request"
  • •metadata: { workflow: "pr", branch: "<current-branch>", base: "<target-branch>", startedAt: "<timestamp>" }

During workflow:

• •Update task metadata for significant events (push, template found, etc.)

At workflow end:

• •Update task status to completed
• •Add result metadata: { result: { prUrl: "<url>", prNumber: <number> } }

Integration with Other Skills

This skill invokes:

• •/git:commit - When uncommitted changes exist

This skill is invoked by:

• •Users directly when ready to create PR