version: "1.0.0" name: create-pr description: 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.

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

/pocketto:create-pr <plan_dir> [<phase_file>]

Examples:

/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

• <plan_dir> — directory containing log.json and execution plan file(s).
• <phase_file> — 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

<HARD-GATE>

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.

</HARD-GATE>

Preflight

Run ALL steps before any git add or gh call.

Step 1: Enterprise mode

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)

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 <plan_dir>/log.json first. Canonical phase identity:

phase_file = phase.file
phase_key  = phase-${phase.order}

Confirm log.json exists under plan_dir. Use log.phases[] order to determine finalPhase (last phase in the array).

Step 4: Linked issue

npx -y pocketto-pi meta get <spec_dir> 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

git rev-parse --abbrev-ref HEAD

Record as <branch>. This is the only branch reference used for PR discovery and creation. Do not change branches.

PR Discovery (idempotent — no duplicates)

Step A — meta:

npx -y pocketto-pi meta get <spec_dir> phases.<phase_key>.github_pr.number --json --contract 2

If data.value is a positive PR number → fetch URL via meta get … phases.<phase_key>.github_pr.url (or gh pr view <N> --json url) and report reuse. Stop — do not create a duplicate.

Step B — GitHub by branch (recovery when meta write was lost):

gh pr list --head <branch> --json number,url

If any PR is returned → reuse the first match, record via 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.

git add -f <plan_dir>/log.json <plan_dir> <spec_dir>
git diff --cached --quiet || git commit -m "chore(pocket): traveling state for <phase_key>"

• 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):

finalPhase drives the issue link keyword: closes #N (final/sole phase) vs refs #N (non-final multi-phase).

Format and create

npx -y pocketto-pi format pr --input <pr-input.json> --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.

gh pr create --head <branch> --title "<phase title>" --body-file <data.bodyFile>

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:

npx -y pocketto-pi meta set <spec_dir> phases.<phase_key>.github_pr.number <N> --json --contract 2
npx -y pocketto-pi meta set <spec_dir> phases.<phase_key>.github_pr.url "<url>" --json --contract 2

Completion Report

PR_READY: <phase_key>
Branch: <branch>
PR: #<N> <url>
Issue link: <refs|closes> #<issue>
fileWarning: <true|false>

If reused (meta or gh pr list): report PR_REUSED instead of PR_READY.

Red Flags