create-pr
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCreate PR
创建 PR
Enterprise-owned recorder for opening or reusing a pull request for a completed development phase. It has two paths selected from :
log.json- Stacked plans (): a manual repair recorder that runs
header.phase_branches.mode == "stacked"against the recorded phase branch. The phase branch is read by ref and is never checked out.publish-phase - Other plans (or no
noneheader): creates or reuses the PR for the current branch.phase_branches
It does not own phase-verdict reporting.
Core principle: This is an explicit user-triggered recorder. It creates or discovers a PR, records its identity, and surfaces preflight warnings verbatim. Phase summaries and inline verdicts belong to the Enterprise adapter, not this skill or Core.
v4 boundary: Package uses , , lifecycle schema , adapter contract , and surface manifest . This skill is part of the additive Enterprise role and requires matching Core. Core is local-first: it does not call , it does not merge pull requests, and it does not close issues. This recorder may call GitHub only after explicit user invocation and successful Enterprise preflight; it never merges a PR or closes an issue.
4.2.1CONTRACT=3PIPELINE=5221ghUse this when: The user requests a phase PR, or explicitly confirms an Enterprise offer. For a non-stacked plan the target phase is in . For a stacked plan the target phase is and its event exists (created by , see pocket-closing's Stacked Handoff).
REVIEWDONEphase-closedlog handoffDo NOT use when: Enterprise is disabled, a compatible Core/adapter preflight fails, or there is no linked issue.
Enterprise 层负责的记录器,用于为已完成的开发阶段创建或复用 pull request。它包含两条路径,根据 进行选择:
log.json- 堆叠式计划():手动修复型记录器,针对已记录的阶段分支运行
header.phase_branches.mode == "stacked"。阶段分支按 ref 读取,绝不执行 checkout。publish-phase - 其他计划(或不存在
noneheader):为当前分支创建或复用 PR。phase_branches
它不负责 phase-verdict 报告。
核心原则: 这是一个由用户显式触发的记录器。它负责创建或发现 PR、记录 PR 身份,并原样呈现 preflight 警告。阶段摘要和内联 verdict 属于 Enterprise adapter,而不属于此 skill 或 Core。
v4 边界: 包 使用 、、lifecycle schema 、adapter contract 和 surface manifest 。此 skill 是增量 Enterprise role 的一部分,并要求匹配对应的 Core。Core 采用 local-first 模式:不调用 ,不合并 pull request,也不关闭 issue。此记录器仅可在用户显式调用且 Enterprise preflight 成功后调用 GitHub;它绝不合并 PR 或关闭 issue。
4.2.1CONTRACT=3PIPELINE=5221gh适用场景: 用户请求 phase PR,或明确确认 Enterprise offer。对于非堆叠式计划,目标阶段应为 。对于堆叠式计划,目标阶段应为 ,并且必须存在由 创建的 事件(参见 pocket-closing 的 Stacked Handoff)。
REVIEWDONElog handoffphase-closed禁止使用场景: Enterprise 已禁用、兼容的 Core/adapter preflight 失败,或不存在关联 issue。
Invocation
调用
text
/pocketto:create-pr <plan_dir> [<phase_file>]Examples:
text
/pocketto:create-pr docs/pocket/plans/2026-09-19-feature/
/pocketto:create-pr docs/pocket/plans/2026-09-19-feature/ execution-plan/phase-1.md- contains
<plan_dir>and the execution-plan files.log.json - is optional. When omitted, select the unique
<phase_file>entry that is eligible for the plan's path:log.phases[]for non-stacked plans, orstatus == REVIEWfor stacked plans. Zero or multiple matches require an explicit phase file.status == DONE
text
/pocketto:create-pr <plan_dir> [<phase_file>]示例:
text
/pocketto:create-pr docs/pocket/plans/2026-09-19-feature/
/pocketto:create-pr docs/pocket/plans/2026-09-19-feature/ execution-plan/phase-1.md- 包含
<plan_dir>和 execution-plan 文件。log.json - 为可选参数。省略时,选择符合计划路径的唯一
<phase_file>条目:非堆叠式计划要求log.phases[],堆叠式计划要求status == REVIEW。出现零个或多个匹配项时,必须显式提供 phase file。status == DONE
Hard Constraints
硬性约束
<HARD-GATE>
1. **No branch management** — on the non-stacked path never check out, create, switch, or remove a branch; use the current branch. The stacked path reads the recorded phase branch by ref and never checks it out.
2. **Preflight before GitHub** — verify Enterprise mode, compatible Core contract 3, lifecycle schema 2, and registered adapter contract 2 before any GitHub operation.
3. **Traveling state before PR creation (non-stacked only)** — commit `log.json`, plan docs, and spec docs before `gh pr create`. On the stacked path `log handoff` has already committed the phase's traveling state to its phase branch; this recorder does not stage or commit.
4. **Always `--body-file`** — never pass a multiline PR body inline (non-stacked path; the stacked body is built by `publish-phase`).
5. **Recorder only** — never merge the PR or close the linked issue; `closes #N` is a GitHub link that takes effect only if a human later merges the final PR.
6. **Recorder only** — do not post verdict summaries, inline findings, or tasklist comments from this skill.
7. **Never rebase, never force-push, never retarget** — do not run any rebase, do not perform any forced push of any kind, and do not change a PR base. Stacked pushes are fast-forward only and are performed by `publish-phase` itself. If a push, divergence, or base conflict blocks the run, stop and report it for manual resolution.
</HARD-GATE>
<HARD-GATE>
1. **禁止分支管理**——在非堆叠路径中,绝不 checkout、创建、切换或删除分支;应使用当前分支。在堆叠路径中,按 ref 读取已记录的阶段分支,绝不将其 checkout。
2. **先执行 preflight,再访问 GitHub**——在任何 GitHub 操作之前,验证 Enterprise 模式、兼容的 Core contract 3、lifecycle schema 2 和已注册的 adapter contract 2。
3. **创建 PR 前提交 traveling state(仅限非堆叠路径)**——在执行 `gh pr create` 前,提交 `log.json`、计划文档和 spec 文档。在堆叠路径中,`log handoff` 已将阶段的 traveling state 提交到其阶段分支;此记录器不会执行 stage 或 commit。
4. **始终使用 `--body-file`**——绝不以内联方式传入多行 PR 正文(非堆叠路径;堆叠路径的正文由 `publish-phase` 构建)。
5. **仅作记录**——绝不合并 PR 或关闭关联 issue;`closes #N` 只是一个 GitHub 链接,只有在人工之后合并最终 PR 时才会生效。
6. **仅作记录**——此 skill 不得发布 verdict 摘要、内联 findings 或 tasklist comments。
7. **绝不 rebase、绝不 force-push、绝不 retarget**——不得执行任何 rebase、任何形式的强制 push,也不得更改 PR base。堆叠式 push 只能采用 fast-forward,并由 `publish-phase` 本身执行。如果 push、divergence 或 base conflict 阻塞运行,停止并报告,以便人工处理。
</HARD-GATE>
Preflight
Preflight
Run these checks before staging files or making a GitHub call. They apply to both paths.
在暂存文件或调用 GitHub 之前运行以下检查。两条路径均适用。
Step 1: Enterprise mode
第 1 步:Enterprise 模式
bash
npx -y pocketto-pi mode --json --contract 3Stop unless the envelope succeeds and is strictly .
data.enterprisetruebash
npx -y pocketto-pi mode --json --contract 3除非 envelope 成功且 严格为 ,否则停止。
data.enterprisetrueStep 2: Core and adapter compatibility
第 2 步:Core 和 adapter 兼容性
enterprise/cli.jsbash
node enterprise/cli.js preflight <project-root> --jsonA project that depends on the npm package runs .
node node_modules/pocketto-pi/enterprise/cli.js preflight <project-root> --jsonContinue only when preflight succeeds and confirms the compatible Core contract, lifecycle schema 2, adapter contract 2, and registration. On failure, stop before GitHub and follow the actionable install/upgrade guidance. A registration written under adapter contract 1 fails preflight with ; the user must reinstall the adapter (see ).
ENTERPRISE_ADAPTER_CONTRACT_MISMATCHskills/pocket-enterprise/references/onboarding.mdPreflight returns , an array of ignored-artifact warnings. Keep this array for the report (see Completion Report).
data.warningsenterprise/cli.jsbash
node enterprise/cli.js preflight <project-root> --json依赖 npm 包的项目运行:
bash
node node_modules/pocketto-pi/enterprise/cli.js preflight <project-root> --json仅当 preflight 成功,并确认兼容的 Core contract、lifecycle schema 2、adapter contract 2 和 registration 时方可继续。失败时,在访问 GitHub 前停止,并遵循可操作的安装或升级指南。使用 adapter contract 1 写入的 registration 会以 失败;用户必须重新安装 adapter(参见 )。
ENTERPRISE_ADAPTER_CONTRACT_MISMATCHskills/pocket-enterprise/references/onboarding.mdPreflight 返回 ,它是一个 ignored-artifact 警告数组。保留该数组,供报告使用(参见“完成报告”)。
data.warningsStep 3: Authentication
第 3 步:认证
bash
gh auth statusIf authentication is unavailable, stop with the corrective action. Do not stage or commit traveling state before preflight and authentication pass.
gh auth loginbash
gh auth status如果认证不可用,停止并给出 修正操作。在 preflight 和认证均通过前,不得暂存或提交 traveling state。
gh auth loginStep 4: Resolve paths, path, and linked issue
第 4 步:解析路径、执行路径和关联 issue
Read . Determine the path from :
<plan_dir>/log.jsonheader.phase_branches.mode- → Stacked Path.
"stacked" - anything else, including an absent header → Non-Stacked Path.
phase_branches
Resolve and from the matching entry, requiring the status for that path (see Invocation).
phase_filephase_keylog.phases[]- is
spec_dir, withdocs/pocket/spec/<slug>/matching the plan directory basename.<slug> - is
phase_keyfromphase-${phase.order}.log.json - Use order to determine whether this is the final phase.
log.phases[]
Read the linked issue:
bash
npx -y pocketto-pi meta get <spec_dir> github_issue.number --json --contract 3If no positive issue number exists, stop. Run the approved-spec issue reconciliation through the Enterprise lifecycle adapter before requesting a phase PR.
读取 。根据 确定执行路径:
<plan_dir>/log.jsonheader.phase_branches.mode- → 堆叠路径。
"stacked" - 其他任何值,包括不存在 header → 非堆叠路径。
phase_branches
从匹配的 条目解析 和 ,并要求其状态符合该路径的要求(参见“调用”)。
log.phases[]phase_filephase_key- 为
spec_dir,其中docs/pocket/spec/<slug>/与计划目录的 basename 匹配。<slug> - 为
phase_key中的log.json。phase-${phase.order} - 使用 的顺序判断是否为最后一个阶段。
log.phases[]
读取关联 issue:
bash
npx -y pocketto-pi meta get <spec_dir> github_issue.number --json --contract 3如果不存在有效的正数 issue number,则停止。请求 phase PR 前,必须通过 Enterprise lifecycle adapter 执行已批准 spec 的 issue 对账流程。
Stacked Path
堆叠路径
Use this path when records . The phase must be , and must already have committed its event. does the remote work and its own identity recording, so this path does not build a PR body, call , or write metadata itself.
log.jsonheader.phase_branches.mode == "stacked"DONElog handoffphase-closedpublish-phasegh pr creategithub_pr当 记录 时,使用此路径。该阶段必须为 ,并且 必须已提交其 事件。 负责远程操作和自身的身份记录,因此此路径不会构建 PR 正文、调用 ,也不会自行写入 metadata。
log.jsonheader.phase_branches.mode == "stacked"DONElog handoffphase-closedpublish-phasegh pr creategithub_prRun publish-phase
运行 publish-phase
From a checkout of this repository:
bash
node enterprise/cli.js publish-phase <project-root> <spec_dir> <phase_key> --jsonFor a project that depends on the npm package, replace with . Do not add ; this command does not accept it.
node enterprise/cli.jsnode node_modules/pocketto-pi/enterprise/cli.js--contractpublish-phasepush_consentinstall --push-consent phase-branchesIts envelope is .
{ ok, command: "enterprise-publish-phase", data: { phase_key, pr_number, pr_url, created, notices }, error }- → report
created: true.PR_READY→ reportcreated: false.PR_REUSED - Relay each as written (
notices[].messageorPR_CREATED).PR_REUSED
从检出的此仓库运行:
bash
node enterprise/cli.js publish-phase <project-root> <spec_dir> <phase_key> --json对于依赖 npm 包的项目,将 替换为 。不要添加 ;此命令不接受该参数。
node enterprise/cli.jsnode node_modules/pocketto-pi/enterprise/cli.js--contractpublish-phaseinstall --push-consent phase-branchespush_consent其 envelope 为 。
{ ok, command: "enterprise-publish-phase", data: { phase_key, pr_number, pr_url, created, notices }, error }- → 报告
created: true。PR_READY→ 报告created: false。PR_REUSED - 原样转发每个 (
notices[].message或PR_CREATED)。PR_REUSED
Stacked error handling
堆叠路径错误处理
| Code | Action |
|---|---|
| Stop and show the exact |
| No |
| The plan is not stacked. Use the Non-Stacked Path. |
| Manual resolution. The message names the reason: base retargeted on GitHub, duplicate open PR for the same head and base, a foreign PR for the head, an unrecorded root base, an unpublished parent branch, or a merged or closed parent PR. Pocket does not retarget, close duplicates, or rebase; the user fixes it on GitHub, then reruns. For a merged parent PR, open or retarget the child PR against the base the parent merged into, then rerun: Pocket reuses that PR. A closed parent PR cannot be fixed by a rerun, so its repair is a manual decision. |
| Retryable. Report it and rerun after the condition clears. Do not work around it with a rebase or a forced push. |
| Follow the install/upgrade guidance in the message. |
| Any other code | Report the code and message verbatim and stop. |
A failed run leaves no lifecycle state changed. Report the code; do not retry in a loop.
| 代码 | 操作 |
|---|---|
| 停止,并显示错误消息中的确切 |
| 该阶段不存在 |
| 计划不是堆叠式。使用非堆叠路径。 |
| 需要人工处理。消息会指明原因:GitHub 上的 base 已被 retarget;同一 head 和 base 存在重复的开放 PR;该 head 存在外部 PR;缺少已记录的 root base;父分支尚未发布;或父 PR 已合并或关闭。Pocket 不会 retarget、关闭重复 PR 或 rebase;用户在 GitHub 上修复后,再重新运行。若父 PR 已合并,则针对父 PR 合并到的 base 打开或 retarget 子 PR,然后重新运行;Pocket 会复用该 PR。父 PR 已关闭无法通过重跑修复,因此需要人工决定。 |
| 可重试。报告问题,并在相关条件解除后重新运行。不要通过 rebase 或 force-push 绕过问题。 |
| 遵循消息中的安装或升级指南。 |
| 其他任何代码 | 原样报告代码和消息并停止。 |
失败的运行不会改变任何 lifecycle state。报告错误代码;不要循环重试。
Non-Stacked Path
非堆叠路径
Use this path when the plan does not record stacked phase branches. Behavior is unchanged from earlier releases.
当计划未记录堆叠式阶段分支时,使用此路径。其行为与早期版本相同。
Current Branch
当前分支
bash
git rev-parse --abbrev-ref HEADRecord the result as . Do not change branches.
<branch>bash
git rev-parse --abbrev-ref HEAD将结果记录为 。不要切换分支。
<branch>PR Discovery
PR 发现
First check Enterprise metadata:
bash
npx -y pocketto-pi meta get <spec_dir> phases.<phase_key>.github_pr.number --json --contract 3If it contains a positive number, read its URL and reuse it. Otherwise search for a PR on the current branch:
bash
gh pr list --head <branch> --json number,urlReuse one exact match and record its identity. If no match exists, continue to explicit creation. If the target is ambiguous or belongs to a different plan/phase, stop for manual resolution.
首先检查 Enterprise metadata:
bash
npx -y pocketto-pi meta get <spec_dir> phases.<phase_key>.github_pr.number --json --contract 3如果其中包含有效的正数,则读取其 URL 并复用。否则搜索当前分支上的 PR:
bash
gh pr list --head <branch> --json number,url复用唯一精确匹配项,并记录其身份。如果不存在匹配项,则继续显式创建。如果目标不明确或属于其他 plan/phase,则停止并转人工处理。
Commit Traveling State
提交 Traveling State
Before creating a PR, include the plan and its review evidence:
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>"If no staged change exists, skip the commit. Push is not performed by this skill.
创建 PR 前,应包含计划及其 review evidence:
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>"如果不存在 staged change,则跳过 commit。此 skill 不执行 push。
Build and Create the PR
构建并创建 PR
Write a temporary structured input file using Node (not a shell heredoc) with:
fs| Field | Source |
|---|---|
| Linked issue number from metadata |
| Whether this is the last phase in |
| Deduplicated paths changed in this phase |
| Phase file and task summaries |
| Approved spec or plan context |
| Acceptance criteria and task verification commands |
Format the body:
bash
npx -y pocketto-pi format pr --input <pr-input.json> --json --contract 3Read and . If is true, tell the user but continue; it is not a creation gate.
data.bodyFiledata.fileWarningfileWarningbash
gh pr create --head <branch> --title "<phase title>" --body-file <data.bodyFile>Use for the final phase and for an earlier phase. The reference does not close the issue when the PR is created; a human-controlled merge is required. Parse the resulting PR number and URL.
closes #Nrefs #N使用 Node (不要使用 shell heredoc)写入临时结构化输入文件,包含:
fs| 字段 | 来源 |
|---|---|
| metadata 中的关联 issue number |
| 是否为 |
| 此 phase 中已去重的变更路径数 |
| Phase 文件和 task 摘要 |
| 已批准的 spec 或 plan 上下文 |
| 验收标准和 task 验证命令 |
格式化正文:
bash
npx -y pocketto-pi format pr --input <pr-input.json> --json --contract 3读取 和 。如果 为 true,则告知用户但继续执行;它不是创建门禁。
data.bodyFiledata.fileWarningfileWarningbash
gh pr create --head <branch> --title "<phase title>" --body-file <data.bodyFile>最后一个阶段使用 ,较早的阶段使用 。该引用不会在创建 PR 时关闭 issue;必须由人工控制的 merge 才会生效。解析生成的 PR number 和 URL。
closes #Nrefs #NRecord PR Identity
记录 PR 身份
Only after a successful create or discovery, record the PR under the phase key:
bash
npx -y pocketto-pi meta set <spec_dir> phases.<phase_key>.github_pr.number <N> --json --contract 3
npx -y pocketto-pi meta set <spec_dir> phases.<phase_key>.github_pr.url "<url>" --json --contract 3仅在成功创建或发现 PR 后,将 PR 记录在 phase key 下:
bash
npx -y pocketto-pi meta set <spec_dir> phases.<phase_key>.github_pr.number <N> --json --contract 3
npx -y pocketto-pi meta set <spec_dir> phases.<phase_key>.github_pr.url "<url>" --json --contract 3Completion Report
完成报告
Warnings: Report the preflight entries verbatim under , in the same text and order preflight produced. Do not summarize, reword, or drop them. Write only when the array is empty.
data.warningsWarnings:noneStacked path:
text
PR_READY: <phase_key> (or PR_REUSED when created is false)
Path: stacked (publish-phase)
PR: #<pr_number> <pr_url>
Warnings: <verbatim preflight warnings, or none>Non-stacked path:
text
PR_READY: <phase_key> (or PR_REUSED when the PR was reused)
Path: non-stacked
Branch: <branch>
PR: #<N> <url>
Issue link: <refs|closes> #<issue>
fileWarning: <true|false>
Warnings: <verbatim preflight warnings, or none>警告: 按照 preflight 产生的相同文本和顺序,在 下原样报告 条目。不要总结、改写或省略。仅当数组为空时写 。
Warnings:data.warningsnone堆叠路径:
text
PR_READY: <phase_key> (or PR_REUSED when created is false)
Path: stacked (publish-phase)
PR: #<pr_number> <pr_url>
Warnings: <verbatim preflight warnings, or none>非堆叠路径:
text
PR_READY: <phase_key> (or PR_REUSED when the PR was reused)
Path: non-stacked
Branch: <branch>
PR: #<N> <url>
Issue link: <refs|closes> #<issue>
fileWarning: <true|false>
Warnings: <verbatim preflight warnings, or none>Red Flags
危险信号
| Thought | Counter |
|---|---|
| "I'll create a feature branch first" | STOP. This recorder never manages branches. |
| "Skip the traveling-state commit" | STOP. Review needs the plan log and artifacts on the PR. This applies to the non-stacked path; on the stacked path |
| "This recorder should post phase verdicts" | STOP. The registered Enterprise lifecycle adapter owns phase reporting when a |
| "The push was rejected, so force it" | STOP. Pocket never force-pushes. Divergence is blocked for manual resolution. |
| "Rebase the phase branch to clear the conflict" | STOP. This recorder never rebases. |
| "Point the PR at the root to fix the base" | STOP. Pocket does not retarget. Fix the base on GitHub, then rerun. |
| "Run consent-push myself so it goes through" | STOP. Show the user the exact command and wait for their approval of that SHA. |
| "I'll inline the PR body" | Use |
| "No issue yet — create the PR anyway" | STOP. Reconcile the approved spec issue first. |
| 想法 | 对策 |
|---|---|
| “我先创建一个功能分支” | STOP. 此记录器绝不管理分支。 |
| “跳过 traveling-state commit” | STOP. 评审需要 PR 中包含 plan log 和相关产物。这适用于非堆叠路径;在堆叠路径中, |
| “此记录器应该发布 phase verdict” | STOP. 当 |
| “push 被拒绝了,所以 force push” | STOP. Pocket 绝不 force-push。divergence 会阻塞运行,等待人工处理。 |
| “rebase phase branch 以解决冲突” | STOP. 此记录器绝不 rebase。 |
| “将 PR 指向 root 以修复 base” | STOP. Pocket 不会 retarget。在 GitHub 上修复 base,然后重新运行。 |
| “我自己运行 consent-push 让它通过” | STOP. 向用户显示确切命令,并等待其批准该 SHA。 |
| “我会内联 PR 正文” | 使用 |
| “还没有 issue——仍然创建 PR” | STOP. 先完成已批准 spec 的 issue 对账。 |