# Create Pr > Opens a GitHub PR for the current branch linked to the Pocket issue (Pocket Enterprise). User-triggered recorder — commits traveling state, formats a structured PR body, discovers or creates the PR, and records it in .pocket-meta.json. Trigger on "create-pr", "open a PR", "create pull request", or when pocket-development offers it after a phase completes in enterprise mode. - Skill: `rfxlamia/create-pr` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add rfxlamia/create-pr` - Raw SKILL.md: https://api.skillmd.com/api/skills/rfxlamia/create-pr/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: rfxlamia (https://skillmd.com/u/rfxlamia) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/rfxlamia/create-pr --- # Create PR Standalone Pocket Enterprise skill. Opens (or reuses) a GitHub pull request on the **current branch** for a completed development phase. Pocket does **not** manage git branches — no checkout, create, or switch. **Core principle:** Recorder only. The PR is created or discovered; warnings (e.g. >20 files) are surfaced but never block. Enforcement stays with CI and the human supervisor. **Use this when:** Pocket Enterprise is enabled, phase tasks are DONE on the current branch, and you need the structured PR gate (what / why / how-to-test, issue link via `refs` or `closes`). **Do NOT use when:** Enterprise mode is off — run `pocketto-pi mode` first; this skill will explain and stop. --- ## Invocation ```text /pocketto:create-pr [] ``` Examples: ```text /pocketto:create-pr docs/pocket/plans/2026-06-09-github-trace-loop/ /pocketto:create-pr docs/pocket/plans/2026-06-09-github-trace-loop/ execution-plan/phase-1.md ``` - `` — directory containing `log.json` and execution plan file(s). - `` — optional. When omitted, select the unique `log.phases[]` entry with `status == REVIEW`. Zero or multiple REVIEW phases → **STOP** and request an explicit phase file. --- ## Hard Constraints 1. **NO branch management** — never `git checkout`, `git switch`, `git branch`, or `git worktree` for PR creation. PR opens on whatever branch `git rev-parse --abbrev-ref HEAD` returns. 2. **Traveling state BEFORE `gh pr create`** — `git add -f` + commit `log.json`, plan docs, and spec docs first (no-op if nothing to commit). 3. **Always `--body-file`** — never inline multi-line `gh pr create --body "…"` (cross-shell quoting hazard). 4. **Recorder / non-blocking** — `fileWarning` (>20 files) is surfaced to the user; PR creation still proceeds. --- ## Preflight Run ALL steps before any git add or `gh` call. ### Step 1: Enterprise mode ```bash npx -y pocketto-pi mode --json --contract 2 ``` Parse the JSON envelope: - If `ok` is `false` → **STOP.** Explain the mode error and how to fix Pocket Enterprise config. - If `data.enterprise` is not strictly `true` → **STOP.** Explain that `create-pr` requires Pocket Enterprise (`pocketto-pi mode init` or a `## Pocket Enterprise` heading in `AGENTS.md`). Do not call `gh`. ### Step 2: gh authentication (skill layer) ```bash gh auth status ``` If not authenticated → **STOP** with an actionable `gh auth login` error. No partial meta write, no commit, no PR. ### Step 3: Resolve paths Read `/log.json` first. Canonical phase identity: ```text phase_file = phase.file phase_key = phase-${phase.order} ``` | Input | Resolution | |-------|------------| | `plan_dir` | Absolute path to the plan directory | | `phase_file` | Explicit arg → resolve to `log.phases[].file` (exact or basename) and require `status == REVIEW`. Omitted → the unique `log.phases[]` entry with `status == REVIEW`. Zero matches → **STOP** ("No phase in REVIEW"). Multiple matches → **STOP** and request an explicit phase file. Never infer from a root `execution-plan.md` or a legacy `execution-plan-phase-N.md` filename. | | `spec_dir` | `docs/pocket/spec//` where `` matches the plan directory basename (e.g. `2026-06-09-github-trace-loop`) | | `phase_key` | `phase-${phase.order}` from the resolved `log.json` entry | Confirm `log.json` exists under `plan_dir`. Use `log.phases[]` order to determine `finalPhase` (last phase in the array). ### Step 4: Linked issue ```bash npx -y pocketto-pi meta get github_issue.number --json --contract 2 ``` If no issue number → **STOP.** Explain that issue creation must run first (pocket-grinding Story 1 handoff). No PR without a linked issue. --- ## Current Branch ```bash git rev-parse --abbrev-ref HEAD ``` Record as ``. This is the **only** branch reference used for PR discovery and creation. Do not change branches. --- ## PR Discovery (idempotent — no duplicates) **Step A — meta:** ```bash npx -y pocketto-pi meta get phases..github_pr.number --json --contract 2 ``` If `data.value` is a positive PR number → fetch URL via `meta get … phases..github_pr.url` (or `gh pr view --json url`) and report reuse. **Stop** — do not create a duplicate. **Step B — GitHub by branch (recovery when meta write was lost):** ```bash gh pr list --head --json number,url ``` If any PR is returned → reuse the first match, record via [Record PR](#record-pr) below, report reuse. **Stop** — do not create a duplicate. --- ## Commit Traveling State (before `gh pr create`) Enterprise mode requires `log.json` and plan/spec docs on the PR so pocket-development's phase-level pass can compute per-task SHA scope. ```bash git add -f /log.json git diff --cached --quiet || git commit -m "chore(pocket): traveling state for " ``` - Use `git add -f` so gitignored paths (e.g. `log.json` under `docs/`) are included. - If the index is unchanged after `git add`, skip commit (no-op). - Push is **not** required by this skill — the recorder commits locally; the user or CI may push. If `gh pr create` needs the branch on the remote, surface that as a prerequisite failure from `gh`, not by branching. --- ## Build PR Body ### Structured input Write a temp JSON file (Node `fs` — no shell heredocs): | Field | Source | |-------|--------| | `issue` | Issue number from meta (Step 4) | | `finalPhase` | `true` if this is the **last** phase in `log.json` (or the only phase in a flat plan); `false` for non-final phases in a multi-phase plan | | `fileCount` | Count of files changed for this phase: `git diff --name-only ..HEAD` (use `log.json` phase `baseline_sha` or first task's range; dedupe paths) | | `what` | What this phase delivers — from phase file / task summaries | | `why` | Why this work — from spec or plan context | | `howToTest` | Verification steps — from plan acceptance criteria / test commands | `finalPhase` drives the issue link keyword: `closes #N` (final/sole phase) vs `refs #N` (non-final multi-phase). ### Format and create ```bash npx -y pocketto-pi format pr --input --json --contract 2 ``` Parse `data.bodyFile` and `data.fileWarning`. If `data.fileWarning` is `true` → surface a one-line warning to the user (≤20-file-per-PR rule). **Continue** — non-blocking. ```bash gh pr create --head --title "" --body-file ``` Derive `--title` from the phase file heading or plan slug. Parse `gh` output for PR number and URL. --- ## Record PR Only after successful create or reconcile — never before: ```bash npx -y pocketto-pi meta set phases..github_pr.number --json --contract 2 npx -y pocketto-pi meta set phases..github_pr.url "" --json --contract 2 ``` --- ## Completion Report ``` PR_READY: Branch: PR: # Issue link: # fileWarning: ``` If reused (meta or `gh pr list`): report `PR_REUSED` instead of `PR_READY`. --- ## Red Flags | Thought | Counter | |---------|---------| | "I'll create a feature branch first" | **STOP.** This skill never manages branches. PR opens on the current branch. | | "Skip the traveling-state commit" | **STOP.** Review needs `log.json` + docs on the PR. Commit before `gh pr create`. | | "23 files — don't open the PR" | Recorder is non-blocking. Warn and create anyway. | | "I'll inline the PR body" | Always `format pr` → `--body-file`. Deterministic and cross-OS safe. | | "No issue yet — create PR anyway" | **STOP.** Issue-first is a hard gate. Run pocket-grinding issue creation first. |