Create Pull Request Skill

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"

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", "markdown": "```\nFeature PR\n──────────\n  Pre-flight ──▶ 3 agents ──▶ Tests ──▶ PR\n  ┌────────────┐ ┌─────────────────────┐\n  │ Branch OK? │ │ security-auditor    │\n  │ Clean tree?│ │ test-generator      │\n  │ Remote?    │ │ code-quality-review │\n  └────────────┘ └─────────────────────┘\n  Full validation, ~5 min\n```"},
      {"label": "Bug fix", "description": "Focus on test verification", "markdown": "```\nBug Fix PR\n──────────\n  Pre-flight ──▶ test-generator ──▶ Tests ──▶ PR\n\n  Agent: test-generator only\n  Verifies regression test exists\n  ~2 min\n```"},
      {"label": "Refactor", "description": "Code quality review, skip security", "markdown": "```\nRefactor PR\n───────────\n  Pre-flight ──▶ code-quality ──▶ Tests ──▶ PR\n\n  Agent: code-quality-reviewer only\n  Checks: no behavior change,\n  complexity reduction, patterns\n  ~2 min\n```"},
      {"label": "Quick", "description": "Skip validation, just create PR", "markdown": "```\nQuick PR (~30s)\n───────────────\n  Pre-flight ──▶ PR\n\n  No agents, no tests\n  Just create the PR\n```"}
    ],
    "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

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)

Create tasks immediately to show progress:

TaskCreate(subject="Create PR for {branch}", description="PR creation with validation", activeForm="Creating pull request")
TaskCreate(subject="Pre-flight checks", activeForm="Running pre-flight checks")
TaskCreate(subject="Run validation agents", activeForm="Validating with agents")
TaskCreate(subject="Run local tests", activeForm="Running local tests")
TaskCreate(subject="Create PR on GitHub", activeForm="Creating GitHub PR")

Workflow

Phase 1: Pre-Flight Checks

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

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:

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

Read .claude/agents/activity/{branch}.jsonl (one JSON object per line, full branch history)
Deduplicate by agent type (keep the entry with longest duration for each agent)
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)
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.

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-generator** — 47 tests, 94% coverage (2m01s)

---
<sub>Orchestrated by <a href="https://github.com/yonatangross/orchestkit">OrchestKit</a> — 3 agents, 4m57s total</sub>

</details>

Closes #$ISSUE

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

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

NO junk files — Don't create files in repo root
Run validation locally — Don't spawn agents for lint/test
All content goes to GitHub — PR body via gh pr create --body
Keep it simple — One command to create PR

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

Related Skills

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

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"): | 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) |

Agent Skills: Create Pull Request

Install this agent skill to your local

Skill Files