plot-deliver

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plot: Deliver Plan

Plot：交付计划

Verify all implementation is done, then deliver the plan. This workflow can be run manually (using git and forge CLI), by an AI agent interpreting this skill, or via a workflow script (once available).

For docs/infra work, this is the end — live when merged. For features/bugs,

/plot-release

follows when the team is ready to cut a versioned release.

Input:

$ARGUMENTS

is the

<slug>

of a plan on main.

Example:

/plot-deliver sse-backpressure

验证所有实现工作已完成，然后交付计划。此工作流可手动运行（使用git和forge CLI）、由解读该技能的AI agent运行，或通过工作流脚本运行（脚本上线后可用）。

对于文档/基础设施类工作，这就是终点——合并后即生效。对于功能开发/ bug修复类工作，当团队准备好发布版本时，后续将执行

/plot-release

流程。

输入：

$ARGUMENTS

为主分支上某个计划的

<slug>

。

示例：

/plot-deliver sse-backpressure

Setup

配置步骤

Add a

## Plot Config

section to the adopting project's

CLAUDE.md

## Plot Config
- **Project board:** <your-project-name> (#<number>)  <!-- optional, for `gh pr edit --add-project` -->
- **Branch prefixes:** idea/, feature/, bug/, docs/, infra/
- **Plan directory:** docs/plans/
- **Active index:** docs/plans/active/
- **Delivered index:** docs/plans/delivered/

在接入项目的

CLAUDE.md

中添加

## Plot Config

章节：

## Plot Config
- **项目看板**：<your-project-name> (#<number>)  <!-- 可选，用于`gh pr edit --add-project`命令 -->
- **分支前缀**：idea/, feature/, bug/, docs/, infra/
- **计划目录**：docs/plans/
- **活跃计划索引**：docs/plans/active/
- **已交付计划索引**：docs/plans/delivered/

Model Guidance

模型指导

Steps	Min. Tier	Notes
1-4. Parse through Verify PRs	Small	Git/gh commands, helper script, state checks
5. Verify Completeness	Frontier (orchestrator) + Small (subagents)	Orchestrator extracts deliverables and consolidates; small subagents gather PR diffs in parallel
6. Release Note Check	Small	File existence checks
7-8. Deliver and Summary	Small	File ops, git commands, template

Step 5 is the prime example of subagent delegation: a frontier orchestrator handles the judgment (extracting deliverables, consolidating Done/Partial/Missing), while small subagents handle the data collection (running

gh pr diff

, reading PR metadata) in parallel. Without subagents, the frontier model does everything sequentially.

步骤	最低模型层级	说明
1-4. 解析并验证PR	Small	Git/gh命令、辅助脚本、状态检查
5. 验证完整性	Frontier（编排器）+ Small（子代理）	编排器提取交付项并整合结果；小型子代理并行收集PR差异
6. 发布说明检查	Small	文件存在性检查
7-8. 交付与总结	Small	文件操作、Git命令、模板

步骤5是子代理委托的典型示例：前沿模型编排器负责决策（提取交付项、整合完成/部分完成/未完成状态），而小型子代理负责并行收集数据（运行

gh pr diff

、读取PR元数据）。如果没有子代理，前沿模型将按顺序完成所有工作。

1. Parse Input

1. 解析输入

$ARGUMENTS

is empty or missing:

List active plans:
```
ls docs/plans/active/ 2>/dev/null
```
If exactly one exists, propose: "Found plan
```
<slug>
```
. Deliver it?"
If multiple exist, list them and ask which one to deliver
If none exist, explain: "No active plans found in
```
docs/plans/active/
```
."

Extract

slug

from

$ARGUMENTS

(trimmed, lowercase, hyphens only).

如果

$ARGUMENTS

为空或缺失：

列出活跃计划：
```
ls docs/plans/active/ 2>/dev/null
```
如果仅存在一个计划，提议："找到计划
```
<slug>
```
，是否交付？"
如果存在多个计划，列出所有计划并询问要交付哪一个
如果没有找到任何计划，说明："在
```
docs/plans/active/
```
目录下未找到活跃计划。"

从

$ARGUMENTS

中提取

slug

（去除首尾空格、转为小写、仅保留连字符）。

2. Verify Plan Exists

2. 验证计划存在性

Check that an active plan exists for this slug:

ls docs/plans/active/<slug>.md

on main.

If not in
```
active/
```
, check
```
docs/plans/delivered/<slug>.md
```
— if found there: "Already delivered."
Also check the Phase field in the plan file — if already
```
Delivered
```
, stop.
If not found anywhere: "No plan found for
```
<slug>
```
."

Resolve the symlink to find the actual plan file path (e.g.,

docs/plans/YYYY-MM-DD-<slug>.md

检查主分支上是否存在该slug对应的活跃计划：

ls docs/plans/active/<slug>.md

。

如果不在
```
active/
```
目录中，检查
```
docs/plans/delivered/<slug>.md
```
——如果找到，提示："计划已交付。"
同时检查计划文件中的Phase字段——如果已标记为
```
Delivered
```
，则终止流程。
如果在任何位置都未找到，提示："未找到
```
<slug>
```
对应的计划。"

解析符号链接以找到实际计划文件路径（例如：

docs/plans/YYYY-MM-DD-<slug>.md

）。

3. Read and Parse Plan

3. 读取并解析计划

Read the plan file (resolved from the

active/

symlink) and parse the

## Branches

section for PR references. If the plan has a

Sprint: <name>

field in its Status section, extract it for the summary.

Expected format after

/plot-approve

markdown

- `feature/name` — description → #12

读取从

active/

目录符号链接解析得到的计划文件，解析

## Branches

章节中的PR引用。如果计划的Status章节包含

Sprint: <name>

字段，提取该字段用于总结。

/plot-approve

后的预期格式：

markdown

- `feature/name` — 描述 → #12

4. Verify All PRs Merged

4. 验证所有PR已合并

Run the helper:

bash

../plot/scripts/plot-impl-status.sh <slug>

Or for each PR number found in the Branches section:

bash

gh pr view <number> --json state,isDraft --jq '{state: .state, isDraft: .isDraft}'

If all are
```
MERGED
```
: proceed to step 5
If any are
```
OPEN
```
:
- If any open PRs have
```
isDraft: true
```
  , list them and run
```
gh pr ready <number>
```
  to mark each one ready for review — this is part of the delivery flow, not optional
- List all remaining open PRs and ask the user: "These PRs are still open. Merge them first, or deliver anyway?"
- If user declines, stop and list the unfinished PRs
If any are
```
CLOSED
```
(not merged): warn — these need manual attention

运行辅助脚本：

bash

../plot/scripts/plot-impl-status.sh <slug>

或者针对Branches章节中找到的每个PR编号执行：

bash

gh pr view <number> --json state,isDraft --jq '{state: .state, isDraft: .isDraft}'

如果所有PR状态均为
```
MERGED
```
：进入步骤5
如果存在状态为
```
OPEN
```
的PR：
- 如果任何开放PR的
```
isDraft: true
```
  ，列出这些PR并运行
```
gh pr ready <number>
```
  将其标记为可审核状态——这是交付流程的一部分，不可跳过
- 列出所有剩余的开放PR并询问用户："这些PR仍处于开放状态。是否先合并它们，或直接交付计划？"
- 如果用户拒绝，终止流程并列出未完成的PR
如果存在状态为
```
CLOSED
```
（未合并）的PR：发出警告——这些PR需要人工处理

5. Verify Plan Completeness

5. 验证计划完整性

Model tiers for this step:

Frontier (e.g., Opus): Full deliverable extraction, parallel PR diff review via subagents (small-model subagents gather diffs, frontier consolidates), Done/Partial/Missing checklist.

Mid (e.g., Sonnet): Extract deliverables and check PR titles/descriptions (skip full diff review). Can delegate PR metadata collection to small subagents. Present a simplified checklist based on PR metadata rather than code changes. Ask user to verify.

Small (e.g., Haiku): Skip entirely. Verify all PRs are merged (step 4), then ask: "All implementation PRs are merged. Ready to deliver this plan?" Human judgment is the final gate.

Compare what the plan promised against what was actually delivered.

Extract deliverables from the plan file. Look for actionable items in sections like
```
## Design
```
,
```
## Branches
```
, or bulleted lists that describe what should be built. Number each deliverable for reference.
Gather PR evidence using parallel subagents. Launch one Task agent per merged PR to review what was implemented:
- Each agent receives the PR number and the full list of deliverables.
- Each agent runs
```
gh pr diff <number>
```
  and reads the PR body via
```
gh pr view <number> --json title,body,files
```
  .
- Each agent returns: which deliverables (by number) are addressed by that PR, with a one-line summary of the evidence for each.
- Launch all PR agents in parallel since they are independent.
Consolidate results. Merge the per-PR reports into a single checklist. For each deliverable, mark it:
- Done — clear evidence in one or more PRs
- Partial — some work done but not fully matching the plan
- Missing — no evidence found in any PR
Present the checklist to the user and ask to confirm the plan is complete enough to deliver.
- If all items are done: "All deliverables verified. Proceed with delivery?"
- If any are partial/missing: list them and ask "Deliver anyway, or hold off?"
- If the user declines, stop — do not deliver.

此步骤的模型层级要求：

前沿模型（如Opus）： 完整提取交付项，通过子代理并行审核PR差异（小型模型子代理收集差异，前沿模型整合结果），生成完成/部分完成/未完成检查清单。

中端模型（如Sonnet）： 提取交付项并检查PR标题/描述（跳过完整差异审核）。可将PR元数据收集任务委托给小型子代理。基于PR元数据而非代码变更生成简化的检查清单，并请求用户验证。

小型模型（如Haiku）： 完全跳过此步骤。验证所有PR已合并（步骤4）后，询问："所有实现PR已合并，是否准备好交付此计划？"最终由人工判断是否继续。

对比计划承诺的内容与实际交付的成果。

从计划文件中提取交付项。在
```
## Design
```
、
```
## Branches
```
等章节或描述待构建内容的项目符号列表中查找可执行项。为每个交付项编号以便引用。
通过并行子代理收集PR证据。为每个已合并的PR启动一个任务代理，审核已实现的内容：
- 每个代理将收到PR编号和完整的交付项列表。
- 每个代理运行
```
gh pr diff <number>
```
  并通过
```
gh pr view <number> --json title,body,files
```
  读取PR正文。
- 每个代理返回：该PR解决了哪些交付项（按编号），并为每个交付项提供一行证据摘要。
- 由于各PR代理相互独立，可并行启动所有PR代理。
整合结果。将每个PR的报告合并为单一检查清单。为每个交付项标记状态：
- 已完成 — 一个或多个PR中存在明确证据
- 部分完成 — 已开展部分工作，但未完全符合计划要求
- 未完成 — 任何PR中均未找到相关证据
向用户展示检查清单并请求确认计划已足够完整可交付：
- 如果所有项均已完成："所有交付项已验证，是否继续交付？"
- 如果存在部分完成/未完成项：列出这些项并询问"是否直接交付，或暂缓交付？"
- 如果用户拒绝，终止流程——不执行交付操作

6. Check for Release Note Entries

6. 检查发布说明条目

For feature and bug plans, check whether release note entries exist:

Discover release note tooling — check in this order, stop at first match:

Changesets: Does
```
.changeset/config.json
```
exist? If so, the project uses
```
@changesets/cli
```
. Check if
```
.changeset/*.md
```
files (excluding README.md) exist on main.
Project rules: Read
```
CLAUDE.md
```
and
```
AGENTS.md
```
for release note instructions (e.g., custom scripts, specific commands).
Custom scripts: Check
```
package.json
```
for release-related scripts (e.g.,
```
release
```
,
```
version
```
,
```
changelog
```
).

If no tooling is found, skip this step.

If tooling was found but no release note entries exist for this plan's work, warn the user: "No release note entries found for this feature. Consider adding one before releasing."

This is a warning, not a blocker — proceed with delivery regardless.

Skip this step entirely for docs/infra plans (they don't need release notes).

对于功能开发和bug修复类计划，检查是否存在发布说明条目：

发现发布说明工具 — 按以下顺序检查，找到第一个匹配项后停止：

Changesets：是否存在
```
.changeset/config.json
```
？如果存在，说明项目使用
```
@changesets/cli
```
。检查主分支上是否存在
```
.changeset/*.md
```
文件（排除README.md）。
项目规则：读取
```
CLAUDE.md
```
和
```
AGENTS.md
```
以获取发布说明相关指令（如自定义脚本、特定命令）。
自定义脚本：检查
```
package.json
```
中的发布相关脚本（如
```
release
```
、
```
version
```
、
```
changelog
```
）。

如果未找到任何工具，跳过此步骤。

如果找到工具，但该计划的工作未对应任何发布说明条目，向用户发出警告："未找到此功能对应的发布说明条目，建议在发布前添加。"

此为警告而非阻塞项——无论如何都将继续交付流程。

文档/基础设施类计划完全跳过此步骤（此类计划无需发布说明）。

7. Deliver Plan

7. 交付计划

The plan file stays in place — only the symlink moves from

active/

delivered/

bash

git checkout main && git pull origin main

计划文件保留在原位置——仅将符号链接从

active/

目录移动到

delivered/

目录。

bash

git checkout main && git pull origin main

Update Phase field in the plan file

更新计划文件中的Phase字段

Change Phase: Approved → Phase: Delivered

将Phase: Approved 改为 Phase: Delivered

Add - Delivered: YYYY-MM-DD to the Status section

在Status章节添加 - Delivered: YYYY-MM-DD

DELIVER_DATE=$(date -u +%Y-%m-%d)

Move symlink from active/ to delivered/

将符号链接从active/移动到delivered/

git rm docs/plans/active/<slug>.md ln -s ../YYYY-MM-DD-<slug>.md docs/plans/delivered/<slug>.md git add docs/plans/delivered/<slug>.md docs/plans/YYYY-MM-DD-<slug>.md git commit -m "plot: deliver <slug>" git push


(Replace `YYYY-MM-DD-<slug>.md` with the actual date-prefixed filename from the resolved symlink.)


（将`YYYY-MM-DD-<slug>.md`替换为从符号链接解析得到的实际日期前缀文件名。）

8. Summary

8. 总结

Print:

Delivered:
```
<slug>
```
Plan file:
```
docs/plans/YYYY-MM-DD-<slug>.md
```
(unchanged location)
Index: moved from
```
active/
```
to
```
delivered/
```
All implementation PRs: merged
If the plan has a Sprint field: show sprint progress ("N/M sprint items delivered")
Type reminder:
- If feature/bug: "Run
```
/plot-release
```
  when ready to cut a versioned release."
- If docs/infra: "Live on main — no release needed."

打印以下内容：

已交付：
```
<slug>
```
计划文件：
```
docs/plans/YYYY-MM-DD-<slug>.md
```
（位置未变）
索引：从
```
active/
```
目录移动到
```
delivered/
```
目录
所有实现PR：已合并
如果计划包含Sprint字段：展示冲刺进度（"已交付N/M个冲刺项"）
类型提示：
- 如果是功能开发/bug修复类计划："准备好发布版本时，运行
```
/plot-release
```
  命令。"
- 如果是文档/基础设施类计划："已在主分支生效——无需发布。"