create-pr · git:20260821.23469f0 · 2026-08-21 · sha256 5b68ad73a67aa253
create-pr git:20260821.23469f0A
Immutable. This exact content is served forever at /api/v1/blob/5b68ad73a67aa253.
--- 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 ```text /pocketto:create-pr <plan_dir> [<phase_file>] ``` 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 ``` - `<plan_dir>` — directory containing `log.json` and execution plan file(s). - `<phase_file>` — optional; defaults to the sole plan file (flat) or must be supplied for phased plans (`execution-plan/phase-N.md` for indexed layout, or legacy `execution-plan-phase-N.md`). --- ## 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 ```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 | Input | Resolution | |-------|------------| | `plan_dir` | Absolute path to the plan directory | | `phase_file` | Explicit arg, or the only `execution-plan*.md` in `plan_dir` (flat), or `execution-plan/phase-N.md` / legacy `execution-plan-phase-N.md` when phased | | `spec_dir` | `docs/pocket/spec/<slug>/` where `<slug>` matches the plan directory basename (e.g. `2026-06-09-github-trace-loop`) | | `phase_key` | `phase-N` from the phase file basename (`execution-plan/phase-N.md` or `execution-plan-phase-N.md` → `phase-N`); flat single-file plan → `phase-1` | Confirm `log.json` exists under `plan_dir`. Read it to determine phase position for `finalPhase` (see below). ### Step 4: Linked issue ```bash 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 ```bash 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:** ```bash 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):** ```bash gh pr list --head <branch> --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 <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): | 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 <phase_baseline>..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 <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. ```bash 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: ```bash 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 | 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. |