create-pr

What this skill does

# Create Pull Request

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

## Quick Start

```bash
/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=<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

```python
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:

```python
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.

```bash
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 < 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:

| After Step | Show User |
|------------|-----------|
| Pre-flight | Branch status, remote sync result |
| Each agent | Agent validation result as it returns |
| Tests | Test results, lint/typecheck status |
| PR created | PR URL, CI status link |

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:**

```python
# 1. Create main task IMMEDIATELY
TaskCreate(subject="Create PR for {branch}", description="PR creation with validation", activeForm="Creating pull request")

# 2. Create subtasks for each phase
TaskCreate(subject="Pre-flight checks", activeForm="Running pre-flight checks")        # id=2
TaskCreate(subject="Run validation agents", activeForm="Validating with agents")       # id=3
TaskCreate(subject="Run local tests", activeForm="Running local tests")                # id=4
TaskCreate(subject="Create PR on GitHub", activeForm="Creating GitHub PR")             # id=5
TaskCreate(subject="Generate PR playground", activeForm="Generating playground")       # id=6

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Agents need pre-flight to pass
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Tests run after agent validation
TaskUpdate(taskId="5", addBlockedBy=["4"])  # PR creation needs tests to pass
TaskUpdate(taskId="6", addBlockedBy=["5"])  # Playground after PR (needs title/summary)

# 4. Before starting each task, verify it's unblocked
task = TaskGet(taskId="2")  # Verify blockedBy is empty

# 5. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask
```

---

## Workflow

### Phase 1: Pre-Flight Checks

Load: `Read("${CLAUDE_SKILL_DIR}/rules/preflight-validation.md")` for the full checklist.

```bash
BRANCH=$(git branch --show-current)
[[ "$BRANCH" == "dev" || "$BRANCH" == "main" ]] && echo "Cannot PR from dev/main" && exit 1
[[ -n $(git status --porcelain) ]] && echo "Uncommitted changes" && exit 1

git fetch origin
git rev-parse --verify "origin/$BRANCH" &>/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

```bash
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 `<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.

### 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.

```bash
TYPE="feat"  # Determine: feat/fix/refactor/docs/test/chore
gh pr create --base dev \
  --title "$TYPE(#$ISSUE): Brief description" \
  --body "$(cat <<'EOF'
## Summary
[1-2 sentence description]

## Changes
- [Change 1]
- [Change 2]

## Test Plan
- [x] Unit tests pass
- [x] Lint/type checks pass

## Agent Team Sheet
| Agent | Role | Stage | Time |
|-------|------|-------|------|
| 🏗️ **backend-system-architect** | API design | Lead | 2m14s |
| 🛡️ **security-auditor** | Dependency audit | ⚡ Parallel | 0m42s |
| 🧪 **test-generator** | 47 tests, 94% coverage | ⚡ Parallel | 2m01s |

<details>
<summary><strong>🎬 Agent Credits</strong> — 3 agents collaborated on this PR</summary>

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

**⚡ Parallel** (ran simultaneously)
- 🛡️ **security-auditor** — Dependency audit (0m42s)
- 🧪 **test-gene