create-pr

Create Pull Request

Comprehensive PR creation with validation. All output goes directly to GitHub PR.

Quick Start

create-pr
create-pr "Add user authentication"

CC ≥ 2.1.119 multi-host note (M122): PR creation works against GitHub, GitLab, Bitbucket, and GitHub Enterprise. Detect the target host from the configured remote (git remote -v) and branch on the host family for the right CLI:

Host family	CLI
github / github-enterprise	gh pr create (with GH_HOST=<host> for GHE)
gitlab / gitlab-self	glab mr create
bitbucket	bb pr create

Custom enterprise URLs: prUrlTemplate setting (see src/skills/configure/ and src/skills/chain-patterns/references/pr-from-platform.md).

Argument Resolution

TITLE = "$ARGUMENTS"  # Optional PR title, e.g., "Add user authentication"
# If provided, use as PR title. If empty, generate from branch/commits.
# $ARGUMENTS[0] is the first token (CC 2.1.59 indexed access)

Base Branch Resolution

Derive the base branch from the remote. Never hardcode dev or main; repos differ.

Every $BASE below refers to this value.

Stacked on another open PR

When the work depends on an open PR ("a PR that depends on PR #50"), that PR's head branch is the base, not $BASE:

Phase 1's guard still applies: never open from main or dev, never with a dirty tree. Record git rev-parse "origin/$PARENT_BRANCH" in the body; after the parent is squash-merged that sha is the upstream argument that git rebase --onto "origin/$BASE" <that-sha> <branch> needs, and the branch itself is gone. Squash recovery, depth cap, draft trap: Read("references/stacked-pr.md").

STEP 0: Verify User Intent

BEFORE creating tasks, clarify PR type:

Based on answer, adjust workflow:

• Feature: Full Phase 2 with 3 parallel agents + local tests
• Bug fix: Phase 2 with test-generator only + local tests
• Refactor: Phase 2 with code-quality-reviewer only + local tests
• Quick: Skip Phase 2, jump to Phase 3

Optional pre-flight: claude ultrareview (CC 2.1.120+, #1542)

If claude ultrareview --help succeeds, optionally run it before opening the PR and surface findings in the PR body's ## Pre-flight section. The CLI subcommand returns structured --json output that can be filtered to high/medium severity for the body and full results posted as a follow-up comment.

Skip on CC < 2.1.120 (the subcommand doesn't exist there). The .github/workflows/ultrareview.yml workflow runs the same command on PR open as a backstop, so this pre-flight is purely a feedback-loop accelerant.

Progressive Output (CC 2.1.76)

Output results incrementally during PR creation:

For feature PRs with 3 parallel agents, show each agent's result as it returns — don't wait for all agents before running local tests.

STEP 1: Create Tasks (MANDATORY)

BEFORE doing ANYTHING else, create tasks to track progress:

Workflow

Phase 1: Pre-Flight Checks

Load: Read("rules/preflight-validation.md") for the full checklist.

Phase 2: Parallel Validation (Feature/Bug fix PRs)

Launch agents in ONE message. Load Read("references/parallel-validation.md") for full agent configs.

After agents complete, run local validation:

Phase 3: Gather Context

Phase 3b: Agent Attribution (automatic)

Before creating the PR, check for the branch activity ledger at .claude/agents/activity/{branch}.jsonl. If it exists, generate agent attribution sections for the PR body:

1. Read .claude/agents/activity/{branch}.jsonl (one JSON object per line, full branch history)
2. Deduplicate by agent type (keep the entry with longest duration for each agent)
3. Generate the following sections to append to the PR body:
   • Badge row: shields.io badges for agent count, tests generated, vulnerabilities
   • Agent Team Sheet: Markdown table with Agent, Role, Stage (Lead/⚡ Parallel/Follow-up), Time
   • Credits Roll: Collapsible <details> section grouped by execution stage (Lead/Parallel/Follow-up)
4. Each agent entry has: agent (type), stage (0=lead, 1=parallel, 2=follow-up), duration_ms, summary

If the ledger doesn't exist or is empty, skip this step — create PR normally.

CC 2.1.183 — attribution.sessionUrl: Web and Remote Control sessions append a claude.ai session link to the PR body. For public repos where that link should not be exposed, set attribution.sessionUrl: false (/config attribution.sessionUrl=false) before creating the PR. ork's agent-attribution sections above are independent of this setting.

Phase 3c: CodeRabbit CLI pre-review (before gh pr create)

CodeRabbit PR reviews are rate limited per GitHub identity (Essentials: 5/hour refill under 30 reviews in 7 days, 1/hour at 60+), and every push to an open PR spends one. The CLI has a separate allowance, so review the branch diff locally first. Advisory only, never blocks.

Fix clear defects in lines this branch changed, commit, re-run Phase 2 local validation, then go to Phase 4 without re-running the CLI. Omitting --use-credits avoids spend only when the org's usage-based add-on is On demand or Off; Automatic bills overages. Detection, degrade table, billing modes, triage: Read("references/coderabbit-cli-prereview.md").

Phase 4: Create PR

Follow Read("rules/pr-title-format.md") and Read("rules/pr-body-structure.md"). Use HEREDOC pattern from Read("references/pr-body-templates.md").

Include agent attribution sections (from Phase 3b) after the Test Plan section in the PR body.

Phase 4b: PR Playground (REQUIRED, CI blocks without it)

On every non-bot PR, after Phase 4: Read("references/pr-playground.md") and follow it (archetype, commit to docs/{branch-dir}/, SHA-pinned Live Preview link in the body).

Phase 5: Verify

CI Monitoring (CC 2.1.71)

After PR creation, schedule CI status monitoring.

Budget: 60 minutes of CI polling (a 5-minute cron, so at most 12 fires). A cron job repeats one fixed prompt and cannot count its own fires, so the prompt carries a wall-clock deadline computed once at creation; stop when every check has finished or at the deadline, whichever comes first, and CronDelete the job at either stop.

CodeRabbit harvest

After CI is green and before gh pr merge or --auto, when the repo has .coderabbit.yaml and the PR is not a draft: Read("references/coderabbit-harvest.md").

Handoff File

Write PR details for downstream skills:

Rules

1. NO junk files — Don't create files in repo root
2. Run validation locally — Don't spawn agents for lint/test
3. All content goes to GitHub — PR body via gh pr create --body
4. Keep it simple — One command to create PR
5. Respect the gh rate-limit hint (CC ≥ 2.1.116) — when the Bash tool surfaces a GitHub rate-limit hint after a gh call (e.g. in a /loop 5m gh pr checks … watcher), stop the loop and wait for reset — do not blind-retry. See ork:github-operations for the full guidance.

Next Steps (suggest to user after PR creation)

Verification Gate

Before claiming PR is ready, apply: Read("${CLAUDE_PLUGIN_ROOT}/shared/rules/verification-gate.md"). All tests must pass with fresh evidence. All CI checks green. No "should be fine."

Quality Bar

Done means all of these hold:

• PR opened from a feature branch with a clean working tree against the correct base ($BASE, derived from origin/HEAD, or the detected host equivalent)
• Title uses conventional type(#issue): ... format matching the change
• Body carries Summary, Changes, and Test Plan sections; every closed issue has its own Closes #N keyword
• Pre-flight validation for the chosen PR type passed locally before creation (skipped only for the Quick type)
• CodeRabbit CLI pre-review ran once before gh pr create (Phase 3c), or its one-line skip reason is in the Test Plan
• Playground HTML exists at docs/{branch-dir}/*.html and the body links it, per references/pr-playground.md (required for non-bot PRs)
• gh pr view --json url returns the created PR URL
• On repos with .coderabbit.yaml and a non-draft PR: every CodeRabbit thread is resolved per references/coderabbit-harvest.md, with a reply naming the fix sha or the dismissal reason (scripts/coderabbit-harvest.sh --unresolved prints [])

Related Skills

• ork:commit — Create commits before PRs
• ork:review-pr — Review PRs after creation

Picker fallback (#1795)

If the AskUserQuestion picker stalls (schema break, not a CC input bug — orchestkit#1795, now guarded by tests/skills/structure/test-askuserquestion-schema.sh), set ORK_ASK_FALLBACK=text before starting CC. The lifecycle/ask-fallback-injector hook injects a reminder telling the assistant to pose options inline as a numbered list and ask the user to reply with the option number.

References

Load on demand with Read("references/<file>"):