GravionLabs/deliver

deliver 是做什么的？

逐个交付开放的PBI和Bug（工作项 = 带有 pbi 或 bug 标签的开放问题；Bug 运行相同的流程，分支类型为 fix，使用 Closes #<nr>）：一个子代理负责实现，一个子代理负责审查，当前会话创建 PR，等待 CI 通过并合并。此流程在所有支持的平台（Claude Code、OpenCode、Copilot CLI）上一致执行。状态仅存储在 GitHub 中（问题、子问题、分支、PR），因此执行可以随时中断，使用 /deliver <nr> 命令可以从中断处继续。其核心限制是 release/next 分支上的规则集：如果有红色或缺失的必要检查，无论当前会话如何操作，都无法合并。

输入

help (或 --help、-h)：原样打印 references/help.md，不执行其他操作。

/deliver status --milestone <name>：打印状态块 (## Status block) 并停止，不进行任何交付。

/deliver <nr> [<nr> …] [--milestone <name>] [--unattended] [--inline] [--max <n>]：每个数字代表一个 PBI、Bug、Feature 或 Epic；--milestone <name>（一个版本，M<n> 或一个旧式标题）会添加该里程碑中开放的工作项（通过一次批量读取里程碑：pwsh <skill-dir>/../github-milestone/scripts/Get-Milestones.ps1 -Mode issues -Name <name> -State open：使用 REST API，读取所有页面，不包括 PR；github-milestone 查找会将 M4 解析为标题 M4，或在 close 之后解析为 M4 (0.2.0)；通过标签过滤返回的列表：pbi、bug），以及该里程碑中 Feature 和 Epic 下的工作项。读取到的 milestone.title 用于 gh issue create --milestone；<key> 是其 M<n> 或子编号 M<n>.<m>（旧式：标题），用于命名状态文件和提示。如果缺少，则询问一次。--max <n> 在交付、阻塞或暂停了 n 个 PBI 后停止，并打印报告（scripts/Invoke-DeliverLoop.ps1 在每个新的会话中使用 --max 1，参见 references/loop.md）。

• 交互式（默认）：暂停规则会在聊天中询问用户；被阻塞的 PBI 会询问：重试、跳过或提供一个指令。
• 控制会话：当 PBI 数量超过 deliver.loopThreshold（默认为 3）时使用交互式模式，例如，对于每个 --milestone：不要在此处交付它们，而是启动 Invoke-DeliverLoop.ps1 并保持一个精简的会话用于决策、处理交互式 PBI 和步骤 9（参见 references/control.md）。--inline 在当前会话中交付所有 PBI（步骤 1 到 9）。--no-preflight 跳过起始步骤 3。
• --unattended（claude -p、opencode run、copilot -p）：从不询问。如果暂停，则在该问题上添加评论，添加 needs-decision 标签，并继续处理下一个不依赖于它的 PBI。

开始

1. gh auth status 工作正常，并且仓库包含 release/next 分支。
2. gh api repos/{owner}/{repo}/rules/branches/release/next --jq '.[].type'：如果输出中没有 required_status_checks → 则警告红色 CI 在此处是可合并的（github-release 的规则集），然后继续。
3. 预检（由 --no-preflight 跳过）：pwsh <skill-dir>/scripts/Test-DeliverPreflight.ps1 -Harness <claude|opencode|copilot> [-Unattended] -Text 每项检查打印一行：通过 / 已修复 / 需要操作：技能栈、允许列表（git、gh、pwsh <skill-dir>/scripts/*、AGENTS.md 中的验证命令；每个平台的条目：references/permissions.md，否则无人值守运行会在提示处挂起）、过时的工作树；反应参见 references/preflight.md。请勿在命令中使用带引号的 $(…)；权限检查无法识别它们。
4. 进度事件：如果没有 AGENT_EVENTS_RUN，则运行 pwsh <skill-dir>/scripts/Report-Progress.ps1 -Type run.started -Source session 并保留打印的运行 ID。将 -Run <id> 添加到每个后续调用中（step.finished、attention、issue.finished、run.finished）：Bash 调用不共享 shell 状态，并且 AGENT_EVENTS_RUN 作为前缀也无法匹配允许列表。每条进度行、关注原因和结束都通过 Report-Progress.ps1 处理；它会将会话运行所在的终端上显示这些信息（references/terminal-backends.md）。

步骤

在聊天中每步打印一行：#<nr> <step>: <result>（例如，#12 review: 1 blocking → fix 1/2）。报告每行：pwsh <skill-dir>/scripts/Report-Progress.ps1 -Type step.finished -Issue <nr> -Step <step> -Result "<result>" [-Pr <url>]。此外，-Type attention（-Kind pr_opened 在步骤 6 后附带 -Pr <url>、review_fix 当审查或 CI 轮次开始修复轮次时、ci_red 当步骤 7 为红色时；附带 -Reason）：循环的通知仅来自这些事件。暂停、被阻塞的 PBI 或需要用户介入的点：使用 -Type attention（附带 -Kind paused、blocked 或 needs_you 和 -Reason）代替。在每个 PBI 之后使用 -Type issue.finished -Issue <nr> -Outcome <outcome>。

聊天中提到的每个 PR 和问题都必须写为完整的 URL（https://github.com/<owner>/<repo>/pull/<n>、.../issues/<n>），而不是裸露的 #<n>：裸露的编号在终端中不是链接。此规则适用于进度行、向用户提出的问题以及报告，特别是版本 PR（步骤 9），用户需要手动合并。URL 必须从 gh 获取（html_url），绝不要拼凑记忆。

1. 选择。 对每个编号及其子问题（github-issue references/sub-issues.md，递归到 PBI 和 Bug）运行 gh api repos/{owner}/{repo}/issues/<nr> --jq '{number,title,state,labels:[.labels[].name],body}'。收集所有编号以及里程碑中的开放工作项（pbi 或 bug），去除重复项，保留那些没有 needs-decision 标签的（其正文符合 ADR 标准的项会被报告为 #<nr> select: decision, write the ADR with adr）；通过它们之间（所有工作项中）的 blocked-by 链接进行排序，平局则保持参数的顺序。使用 --milestone 时，通过里程碑中的 Feature 或 Epic 访问但没有或具有其他里程碑的 PBI 或 Bug 不会被交付（#<nr> select: outside M<n>, skipped，提示：设置里程碑，github-issue references/milestones.md）；不带 --milestone 的 /deliver <feature> 会交付其所有 PBI。某个 PBI 的阻塞项仍然打开且不在集合中时，会进行等待并报告（里程碑之外的阻塞项永远不会被交付）。具有 needs-refinement 的 PBI 或 Bug，或者没有复现步骤或验收标准的 Bug，会被跳过（#<nr> select: needs refinement, skipped，提示 planner refine <nr>）；对此类项使用 /deliver <nr> 会拒绝执行。无人值守模式下，具有 interactive 标签的 PBI 会被跳过（#<nr> select: interactive, skipped，提示 /deliver <nr> 在会话中）；交互模式会交付它，即使通过 Feature、Epic 或里程碑也是如此。带有 release-test 标签的开放 PBI（里程碑的 RC 测试）绝不会被选为工作项，不包括在步骤 1 到 8 或控制会话中，即使使用 interactive 或作为显式的 <nr>：#<nr> select: release test, left for step 9（在开放项之前：release test, waits for <n> open items；等待，不标记为需要你介入；references/loop.md）。它保持开放以用于步骤 9 和人工操作（RC 测试在 RC 版本上运行）。跳过其他会话已声明的 PBI（#<nr> select: claimed, skipped），接管过时的声明（references/claim.md）；直接对 PBI 本身使用 /deliver <nr> 会继续处理它，无论其声明状态如何。宣布下一个要处理的 PBI 并声明它：gh issue edit <nr> --add-assignee @me；选择行会命名其层级和模型（#<nr> select: next (tier standard → sonnet/medium)；如果没有 Tier: 行，则为 tier from size M 或 default；references/roles.md）。
   • 没有 PBI 子项的 Feature 或 Epic：在当前会话中加载 planner（交互式）和 grill-me，创建问题，然后再次选择。无人值守模式：改为评论并添加 needs-decision 标签。
2. 恢复。 分支 <type>/<nr>-<slug>（github-issue）。git ls-remote --heads origin <branch> 和 gh api "repos/{owner}/{repo}/pulls?head=<owner>:<branch>&state=open" --jq '.[].number'（head 需要所有者前缀）：已存在的分支会继续处理，已存在的 PR 会跳过到步骤 7。
3. 实现。 一个具有全新上下文的子代理：“加载 implementation，角色 implement。在你自己的工作树上实现 PBI #（如果是 Bug：先加载 diagnose，然后加载 implementation），分支为 <branch>，从 origin/release/next 开始（如果分支已存在：切换到它并变基）。验收标准：<来自问题>。提交、推送，最多用 10 行报告：完成或阻塞、提交、测试运行，以及 notes[]（每行一个）；匹配的 specMap 条目如果没有 spec 变更，则给出注释 no spec change needed: <spec> — <reason>（implementation references/specs.md）。”
4. 审查。 一个具有全新上下文的子代理：“加载 code-review，角色 review。审查 git diff origin/release/next...origin/<branch>，对照这些验收标准：。使用 governance：运行 Get-GovernanceMatches.ps1 -Head origin/<branch>；问题标签 和实现者 notes[] 。只读：不要在现有检出中执行 stash、checkout、switch 或 commit；如果需要文件，请使用你自己的临时工作树。仅返回 JSON：code-review 的 review.schema.json 格式的结果（包含 blocking[]，其中包含 file、line、title、why；notes[]，最多 5 个）以及 unmet[]（未满足的标准）。”只有阻塞性发现和未满足的标准才计入。每次轮次后，当前会话（不是子代理）会写入文件 <git-common-dir>/.agents/state/review-<nr>.json（使用 git rev-parse --git-common-dir，与所有工作树共享同一文件，永不提交），覆盖之前的轮次：{ pbi, branch, sha, round, unmet, review }，sha = git rev-parse origin/<branch>，round = 基于 1 的审查轮次，review = 子代理的结果；架构 schema/deliver-review.schema.json。同时运行 pwsh <skill-dir>/../code-review/scripts/ConvertTo-Findings.ps1 -Review <result with unmet> -Sha <sha> -Worktree <pbi-worktree> 将结果写入 <pbi-worktree>/.agents/state/findings.json 供 poimen 使用（永不提交，本地排除；references/findings.md）。
5. 修复。 某些内容被计数：一个具有全新上下文的子代理加载 implementation，角色 fix，切换到其自己的工作树上的 <branch>（git fetch origin <branch>，git switch -C <branch> origin/<branch>），获取确切的发现（blocking[] 和 unmet[]），提交并推送。然后返回步骤 4。每个 PBI 最多进行 2 轮修复，由审查和 CI 共享；第三次是一个暂停。
6. PR。 github-pull-request（其标题是问题标题去除层级前缀后附加 (#<nr>)）使用 issue_number、branch: <branch>（工作已从另一个工作树推送，此检出保持不变）、review_notes（步骤 4 的 notes[]）、以及 governance 的 spec_notes（实现者 notes[] 中以 no spec change needed: 开头的行）和子代理的测试结果。
7. CI。 直接运行 gh pr checks <pr> --watch --required --interval 60（每次轮询都是一次 GraphQL 查询；默认的 10 秒间隔会耗尽预算），不要使用管道或输出过滤器（例如 tail、head 或 grep），以便会话能够看到 watch 进度。
   • 因为此变更而变红（diff 中文件的测试、lint 或构建错误）：修复轮次（步骤 5），然后再次执行步骤 4 和 7。
   • 因为其他原因变红（不稳定、在 release/next 上也变红）：在 PR 上评论，该 PBI 被阻塞。
8. 合并。 两种模式下均无需询问：最后一次审查没有阻塞性发现或未满足的标准，并且必需的检查为绿色。运行 gh pr merge <pr> --squash --delete-branch，然后运行 gh issue close <nr> --comment "Delivered in #<pr>"（Closes 不会在 release/next 上触发）；同时关闭 PBI 的开放旧式 [Task] 子问题（github-issue references/sub-issues.md，“旧式 Task 问题”）；然后运行 gh issue edit <nr> --remove-assignee @me。使用本技能的脚本 scripts/Remove-PbiWorktrees.ps1（位于技能目录 ~/.claude/skills/deliver/ 全局或 .claude/skills/deliver/ 项目安装）从仓库中清理子代理的工作树和分支：pwsh <skill-dir>/scripts/Remove-PbiWorktrees.ps1 -Pr <pr> -Issue <nr>；打印 #<nr> cleanup: <n> removed 并保留其 left 条目（路径或分支、原因、命令）用于报告。处理下一个 PBI：返回步骤 1。
9. 版本。 仅在使用 --milestone 时，在报告之前（也在 --max 之后），当没有 PBI 剩余可供选择时执行。读取一次里程碑，Get-Milestones.ps1 -Mode issues -Name <name> -State all（包括打开和关闭的）；开放工作检查、标记、轮次计数和已关闭问题的标准均来自此列表。里程碑中没有标记为 pbi 或 bug 的开放问题，除了 release-test 问题（没有阻塞、暂停、等待或跳过的项）；RC 测试从不阻塞。
   • 里程碑中标记为 needs-decision 的已关闭 PBI 或 Bug 是第三轮版本审查的暂停标记：跳过审查，打印 release: paused in round 3, waits for a decision。
   • 版本审查（references/release-review.md）：一个具有全新上下文的子代理加载 code-review，角色 review，针对 git diff origin/main...origin/release/next，使用里程碑关闭的 PBI 和 Bug 的验收标准，关注跨 PBI 的一致性，并按照 review.schema.json 返回 JSON，只读（不要在现有检出中执行 stash、checkout、switch 或 commit；如果需要文件则使用自己的临时工作树）；当前会话写入 <git-common-dir>/.agents/state/release-review-<key>.json。
   • 阻塞性发现：每项发现创建一个 [Bug] fix: … 问题（交互式：显示它们并首先询问），不创建版本 PR；打印 release: <n> blocking → #a, #b。每个里程碑最多进行 2 轮版本审查；第三次有阻塞性发现时暂停，并使用该标记记录，同时添加评论说明两种处理方式（references/release-review.md，“暂停标记”）。
   • 干净（无阻塞性发现）：创建 RC，在 release-test 问题上发布并关闭旧版（references/release-review.md，“RC 测试”）；release.test.gate: true 会在此处停止，显示 needs you: RC test <issue URL>，直到问题被关闭。否则，加载 github-release 并运行 finish，附带 release_review_notes（notes[]，最多 5 个）：它会从 release/next 创建到 main 的版本 PR（auto_merge: false）或报告现有的版本 PR；当 main 不是 release/next 的祖先时，它会停止（需要先反向合并，github-release），报告该停止。打印 release: release PR #<nr>。
   • 输出。 最多 5 个 notes[] 行，使用子代理的 JSON 中的键翻译，并跳过空值。

输出

/deliver <nr> 生成一个最终报告，格式为 H2 标题 ## Report — <key>（key = 里程碑的键或编号列表）。报告包含：

• Summary：<n> 已交付、<n> 已暂停、<n> 阻塞、<n> 已跳过。
• Delivered：每个 PBI 一行，包含 #<nr> <title> 及 PR URL。
• Paused / Blocked / Skipped：每项一行，包含 #<nr> <title> 及原因。
• Left：Remove-PbiWorktrees.ps1 -Left 的条目（无特殊格式）。

如果运行时中断（--max），报告仍会打印。在干净退出时（所有 PBI 交付或释放 PR 已就绪），报告以 ## Report — <key> 为结尾。如果没有任何 PBI 被交付、暂停、阻塞或跳过，则不会打印报告。

在控制会话中，在报告之后：

• 打印 **Tip** Use "/deliver status --milestone <name>" to check the status.
• 打印 **Tip** The release PR is at <url>. Merge it when the RC test passes.（如果适用）

引用

此技能引用位于 <skill-dir>/references/ 的文件，例如 control.md、loop.md、preflight.md、permissions.md、terminal-backends.md、help.md、claim.md、sub-issues.md、milestones.md、roles.md、findings.md、specs.md、release-review.md。引用文件包含详细文档和典型的助手对话，这些对话不在此概要中。

是根据安装位置确定的技能目录。全局安装：~/.claude/skills/deliver/。项目本地安装：.claude/skills/deliver/。