Auto-generated from skills/create-pr/SKILL.md

Source: https://github.com/yonatangross/orchestkit

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 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").

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

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

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

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)