Pull Request Workflow¶

Cub provides the cub pr command to create and manage pull requests for your completed work. PRs include auto-generated descriptions based on the tasks completed and can integrate with CI/CD workflows.

Prerequisites¶

GitHub CLI¶

The cub pr command requires the GitHub CLI (gh) to be installed and authenticated:

# Install GitHub CLI
brew install gh                    # macOS
sudo apt install gh               # Ubuntu/Debian
winget install GitHub.cli         # Windows

# Authenticate with GitHub
gh auth login

# Verify authentication
gh auth status

Repository Requirements¶

• Repository must have a GitHub remote configured
• Branch must be pushed to the remote (or use --push flag)
• For epic-based PRs, the epic must have a branch binding

Basic Usage¶

Create PR for Current Branch¶

cub pr

This creates a PR from your current branch to its base branch (main by default).

Create PR for an Epic¶

cub pr cub-vd6

Uses the epic's branch binding to determine source and target branches.

Create Draft PR¶

cub pr --draft

Creates a draft PR that isn't ready for review yet.

Command Options¶

Auto-Generated PR Body¶

When creating a PR, cub generates a comprehensive body that includes:

Summary Section¶

## Summary

Automated changes from cub session.

- Implemented user authentication system
- Added login form component
- Created API endpoints for auth flow

Commits Section¶

## Commits

Footer¶

---
Generated by cub post-loop hook

PR Templates¶

Customizing PR Templates¶

Create .github/PULL_REQUEST_TEMPLATE.md in your repository. Cub will use this as the base template.

Example template:

## Summary
<!-- Describe what this PR does -->

## Changes
<!-- List the changes made -->

## Test Plan
<!-- How to test these changes -->

## Checklist
- [ ] Tests pass
- [ ] Documentation updated
- [ ] No breaking changes

Epic-Based Templates¶

When creating a PR for an epic, cub includes task completion information:

## Summary

Implemented [Epic Title]

## Completed Tasks

- [x] cub-001: Add login form
- [x] cub-002: Create auth endpoints
- [x] cub-003: Add tests

## Test Plan

Verify the following acceptance criteria:

- [ ] Login form renders correctly
- [ ] Authentication flow works
- [ ] Tests pass

CI Integration¶

By default, cub pr creates the PR and then invokes Claude to:

1. Wait for CI checks to complete
2. Address review comments
3. Report when ready to merge

Skipping CI Handling¶

Use --no-ci to just create the PR and exit:

cub pr --no-ci

This returns immediately after PR creation, without waiting for CI or handling reviews.

CI Workflow¶

The default workflow:

cub pr
   |
   +-> Create PR
   |
   +-> Invoke Claude to:
       |
       +-> Monitor CI status
       |
       +-> Address failing checks
       |
       +-> Respond to review comments
       |
       +-> Report when ready

Checking PR Status¶

View the status of an existing PR:

cub pr status

Output:

PR #45: Implement user authentication

  State: open
  feature/cub-vd6 -> main
  URL: https://github.com/user/repo/pull/45

CI Checks:
  [green] tests: success
  [green] lint: success
  [dim] deploy-preview: in_progress

Status by Target¶

# Status for epic
cub pr status cub-vd6

# Status for PR number
cub pr status 45

# Status for branch
cub pr status feature/my-branch

Examples¶

Standard Workflow¶

# Complete some tasks
cub run --epic cub-vd6

# Push and create PR
cub pr cub-vd6 --push

# View result
# PR #45 created: https://github.com/user/repo/pull/45

Draft Workflow¶

# Create draft while still working
cub pr --draft --title "WIP: New feature"

# Later, mark ready for review
gh pr ready 45

Preview Changes¶

# See what would be created
cub pr --dry-run

Output:

Would create PR:
  Title: task(cub-vd6): Implement authentication
  Base: main
  Head: feature/cub-vd6
  Draft: false

Body:
  ## Summary
  ...

Using the PR Prompt Hook¶

For sessions using the auto-branch hook, the PR prompt hook offers to create a PR at session end.

Setup¶

# Copy both hooks
mkdir -p .cub/hooks/pre-loop.d .cub/hooks/post-loop.d
cp examples/hooks/pre-loop.d/10-auto-branch.sh .cub/hooks/pre-loop.d/
cp examples/hooks/post-loop.d/90-pr-prompt.sh .cub/hooks/post-loop.d/
chmod +x .cub/hooks/*/[0-9]*.sh

Behavior¶

At session end, you see:

==========================================
[pr-prompt] Ready to create Pull Request
==========================================

Branch:  cub/porcupine/20260111-114543
Base:    main
Commits: 3 ahead

Title:   Cub: Porcupine session (3 commits)

[pr-prompt] Create PR? [y/N/e(dit)]

Options: - y: Create PR with auto-generated title and body - n: Skip PR creation - e: Open interactive editor for customization

Troubleshooting¶

"gh: command not found"¶

Install the GitHub CLI:

brew install gh    # macOS

"Not authenticated"¶

Run GitHub authentication:

gh auth login

"Branch not pushed to origin"¶

Either push manually or use --push:

cub pr --push

"PR already exists"¶

Check existing PR:

cub pr status
gh pr view

"No branch binding found"¶

For epic-based PRs, create a binding first:

cub branch cub-vd6 --bind-only
cub pr cub-vd6

Or create PR from branch directly:

cub pr --base main

Best Practices¶

1. Use Draft PRs for Work in Progress¶

cub pr --draft --title "WIP: Feature X"

2. Review Before Merging¶

Even with AI-generated code, human review is valuable:

# View changes
gh pr diff 45

# Add reviewers
gh pr edit 45 --add-reviewer teammate

3. Use Descriptive Titles¶

cub pr --title "feat(auth): Add OAuth2 login flow"

4. Link to Issues¶

Include issue references in the PR body or comments:

gh pr comment 45 --body "Closes #123"