Create Pr

Create Pull Request

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

Quick Start

/ork:create-pr
/ork: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= 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)

---

STEP 0: Verify User Intent

BEFORE creating tasks, clarify PR type:

AskUserQuestion(
  questions=[{
    "question": "What type of PR is this?",
    "header": "PR Type",
    "options": [
      {"label": "Feature (Recommended)", "description": "Full validation: security + quality + tests"},
      {"label": "Bug fix", "description": "Focus on test verification"},
      {"label": "Refactor", "description": "Code quality review, skip security"},
      {"label": "Quick", "description": "Skip validation, just create PR"}
    ],
    "multiSelect": false
  }]
)

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.

if claude ultrareview --help >/dev/null 2>&1; then
  claude ultrareview "origin/$BASE..HEAD" --json > /tmp/ultra.json
  # Bucket by severity, put HIGH in PR body, MEDIUM/LOW as comment
fi

Skip on CC /dev/null || git push -u origin "$BRANCH"

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

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

| PR Type | Agents to launch |
|---------|-----------------|
| Feature | security-auditor + test-generator + code-quality-reviewer |
| Bug fix | test-generator only |
| Refactor | code-quality-reviewer only |
| Quick | None |

After agents complete, run local validation:

```bash
# Adapt to project stack
npm run lint && npm run typecheck && npm test -- --bail
# or: ruff check . && pytest tests/unit/ -v --tb=short -x

Phase 3: Gather Context

BRANCH=$(git branch --show-current)
ISSUE=$(echo "$BRANCH" | grep -oE '[0-9]+' | head -1)
git log --oneline dev..HEAD
git diff dev...HEAD --stat

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 `` section grouped by execution stage (Lead/Parallel/Follow-up)

1. 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 4: Create PR

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

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

TYPE="feat"  # Determine: feat/fix/refactor/docs/test/chore
gh pr create --base dev \
  --title "$TYPE(#$ISSUE): Brief description" \
  --body "$(cat 
🎬 Agent Credits — 3 agents collaborated on this PR

**Lead**
- 🏗️ **backend-system-architect** — API design (2m14s)

**⚡ Parallel** (ran simultaneously)
- 🛡️ **security-auditor** — Dependency audit (0m42s)
- 🧪 **test-generator** — 47 tests, 94% coverage (2m01s)

---
Orchestrated by OrchestKit — 3 agents, 4m57s total

Closes #$ISSUE

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

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

Generate an interactive HTML playground visualizing the PR's changes. CI validates docs/{branch-name}/*.html exists.

> Requires the playground plugin (external): /plugin marketplace add anthropics/claude-plugins-official && /plugin install playground

First classify the archetype — a feature PR must not ship as a flat dashboard. Read("${CLAUDE_PLUGIN_ROOT}/skills/shared/rules/playground-visual-standard.md") and apply its §0 routing rule:

• Visual PR (adds/changes a user-facing feature, flow, or a prioritization/decision surface) →

USER-STORY PLAYER or DECISION BOARD. Build to the standard: adapt the matching exemplar at ${CLAUDE_PLUGIN_ROOT}/skills/shared/assets/playground-exemplars/ (user-story-player.template.html or decision-board.template.html), and bring full design firepower (the frontend-design skill / the ork:frontend-ui-developer agent). When delegating to playground:playground, brief it with the archetype + persona + tokens — never hand it a pre-built HTML blob.

• Non-visual PR (infra/CI/refactor/config/docs) → DASHBOARD — the default summary below is fine.

BRANCH=$(git branch --show-current)
BRANCH_DIR = BRANCH.replace("/", "--")  # feat/foo → feat--foo

# Invoke the playground skill with a summary of the PR changes.
# For a VISUAL PR, set archetype/persona/exemplar per playground-visual-standard.md instead of this default.
Skill("playground:playground", args=f"""
  {PR_TITLE} — visualize the key changes in this PR.
  Archetype:  per playground-visual-standard.md §0.
  For visual archetypes: follow that standard's tokens/glass/motion and adapt the matching exemplar.
  Show: architecture/data flow, before/after, key components changed; presets for the main change areas.
  Dark glass theme, OrchestKit brand accents.
""")

# The playground skill writes to a temp path — move it to the correct location
# Ensure file lands at: docs/{branch-dir}/.html
Bash(f"mkdir -p docs/{BRANCH_DIR}")
Bash(f"mv /tmp/*.html docs/{BRANCH_DIR}/playground.html 2>/dev/null || true")

# Force-add (docs/feat--*/ is gitignored by design)
Bash(f"git add -f docs/{BRANCH_DIR}/")
Bash(f'git commit -m "docs: add PR playground for {BRANCH}"')
Bash(f"git push origin {BRANCH}")

Add a "Live Preview" section to the PR body:

## Live Preview

**[Open Interactive Playground](https://htmlpreview.github.io/?https://github.com/{OWNER}/{REPO}/blob/{BRANCH}/docs/{BRANCH_DIR}/playground.html)**

> Why required: CI Stage 1d (playground-check) blocks merge if docs/{branch-dir}/*.html is missing. Bot PRs (dependabot, release-please) are exempt.

Phase 5: Verify

PR_URL=$(gh pr view --json url -q .url)
echo "PR created: $PR_URL"

CI Monitoring (CC 2.1.71)

After PR creation, schedule CI status monitoring:

# Guard: Skip cron in headless/CI (CLAUDE_CODE_DISABLE_CRON)
# if env CLAUDE_CODE_DISABLE_CRON is set, run a single check instead
CronCreate(
  schedule="*/5 * * * *",
  prompt="Check CI for PR #{pr_number}: gh pr checks {pr_number} --repo {repo}.
    All pass → CronDelete this job, report success.
    Any fail → alert with failure details."
)

Handoff File

Write PR details for downstream skills:

Write(".claude/chain/pr-created.json", JSON.stringify({
  "phase": "create-pr", "pr_number": N, "pr_url": "...",
  "branch": "...", "files_changed": [...], "related_issues": [...]
}))

---

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)

/ork:review-pr {PR_NUMBER}                # Self-review before requesting reviews
/loop 5m gh pr checks {PR_NUMBER}         # Watch CI until green
/loop 1h gh pr view {PR_NUMBER} --json reviewDecision  # Monitor review status

Verification Gate

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

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("${CLAUDE_SKILL_DIR}/references/"): | File | Content | |------|---------| | references/pr-body-templates.md | PR body templates | | references/parallel-validation.md | Parallel validation agent configs | | references/ci-integration.md | CI integration patterns | | references/multi-commit-pr.md | Multi-commit PR guidance | | assets/pr-template.md | PR template (legacy) |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yonatangross
• Source: yonatangross/orchestkit
• License: MIT
• Homepage: https://orchestkit.yonyon.ai

Install and usage instructions live in the source repository linked above.