plot-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plot: Cut a Release

Plot：创建版本化发布

Create a versioned release from delivered plans. 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).

Input:

$ARGUMENTS

is optional. Can be:

```
rc
```
— cut a release candidate tag and generate a verification checklist
A version number (e.g.,
```
1.2.0
```
) or bump type (
```
major
```
,
```
minor
```
,
```
patch
```
) — cut the final release

Examples:

/plot-release rc

/plot-release minor

/plot-release 1.2.0

基于已交付的计划创建版本化发布。此工作流可手动运行（使用git和forge CLI）、由AI Agent解读本skill执行，或通过工作流脚本运行（待上线）。

输入：

$ARGUMENTS

为可选参数，可选值包括：

```
rc
```
— 创建发布候选版本（RC）标签并生成验证检查清单
版本号（如
```
1.2.0
```
）或版本升级类型（
```
major
```
、
```
minor
```
、
```
patch
```
） — 创建正式最终发布版本

示例：

/plot-release rc

、

/plot-release minor

、

/plot-release 1.2.0

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
- **项目看板：** <你的项目名称> (#<编号>) <!-- 可选，用于`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. Determine Version	Mid	Heuristic: plan types → bump suggestion
2A. RC Path	Small	Git tag, template generation
2B. Release Notes	Mid	Discovery logic, changelog collection
3. Cross-check Notes	Frontier (orchestrator) + Small (subagents)	Orchestrator compares; small subagents can gather commit messages and plan changelogs in parallel
4-6. Next Steps through Summary	Small	Template list, no-ops, formatting

步骤	最低模型等级	备注
1. 确定版本号	Mid	启发式规则：根据计划类型建议版本升级类型
2A. RC发布路径	Small	Git标签、模板生成
2B. 发布笔记生成	Mid	发现逻辑、变更日志收集
3. 交叉检查笔记	Frontier（编排器）+ Small（子Agent）	编排器负责对比；小型子Agent可并行收集提交信息和计划变更日志
4-6. 后续步骤至总结	Small	模板列表、无操作、格式整理

1. Determine Version

1. 确定版本号

Check for the latest git tag:

bash

git tag --sort=-v:refname | head -1

$ARGUMENTS

rc

Determine the target version (same rules as below — check delivered plans, suggest bump type)
Check for existing RC tags for this version:
```
git tag --list "v<version>-rc.*"
```
Next RC number: if no existing RCs, use
```
rc.1
```
; otherwise increment
Proceed to step 2A (RC path)

$ARGUMENTS

specifies a version (e.g.,

1.2.0

Use it directly (validate it's valid semver)
Proceed to step 2B (final release path)

$ARGUMENTS

specifies a bump type (

major

minor

patch

Calculate the new version from the latest tag
Proceed to step 2B (final release path)

$ARGUMENTS

is empty:

Check if there's an open RC checklist (
```
docs/releases/v*-checklist.md
```
) with all items checked
If yes: propose cutting the final release for that version
If no: look at delivered plans since the last release to suggest a bump type:
- Any features → suggest
```
minor
```
- Only bug fixes → suggest
```
patch
```
- Breaking changes noted in changelogs → suggest
```
major
```
If unable to determine bump type from plan metadata, ask the user to specify the version directly
Propose the version and confirm with the user

Smaller models: Skip the automatic bump type suggestion. Instead, list the delivered plans with their types and ask the user: "What version should this release be? (major/minor/patch or exact version)" Let the human decide.

检查最新的git标签：

bash

git tag --sort=-v:refname | head -1

若

$ARGUMENTS

为

rc

：

确定目标版本号（遵循以下规则：检查已交付计划，建议版本升级类型）
检查该版本是否已有RC标签：
```
git tag --list "v<version>-rc.*"
```
下一个RC编号：若尚无RC标签，使用
```
rc.1
```
；否则递增编号
进入步骤2A（RC发布路径）

若

$ARGUMENTS

指定了版本号（如

1.2.0

）：

直接使用该版本号（验证其是否符合语义化版本规范）
进入步骤2B（正式发布路径）

若

$ARGUMENTS

指定了版本升级类型（

major

、

minor

、

patch

）：

根据最新标签计算新版本号
进入步骤2B（正式发布路径）

若

$ARGUMENTS

为空：

检查是否存在已完成所有项的RC检查清单（
```
docs/releases/v*-checklist.md
```
）
若存在：建议为该版本创建正式最终发布版本
若不存在：查看上次发布以来的已交付计划，建议版本升级类型：
- 包含新功能 → 建议
```
minor
```
- 仅包含Bug修复 → 建议
```
patch
```
- 变更日志中注明有破坏性变更 → 建议
```
major
```
若无法通过计划元数据确定升级类型，请求用户直接指定版本号
提出版本号建议并等待用户确认

小型模型说明： 跳过自动版本升级类型建议。取而代之，列出所有已交付计划及其类型，并询问用户：“本次发布应使用哪个版本？（major/minor/patch或具体版本号）” 由人工决定。

2A. RC Path — Cut Release Candidate

2A. RC发布路径 — 创建发布候选版本

Tag the RC:

bash

git tag -a v<version>-rc.<n> -m "Release candidate v<version>-rc.<n>"
git push origin v<version>-rc.<n>

Generate verification checklist:

Collect all delivered plans since the last release (via

docs/plans/delivered/

— check the Delivered date in each plan's Status section against the last release tag date). For each delivered feature or bug plan, extract the

## Changelog

section and create a checklist item. If a plan has a

Sprint: <name>

field, include the sprint name alongside the checklist item for context. Sprint completion is informational — it does not block the release.

bash

mkdir -p docs/releases

Write

docs/releases/v<version>-checklist.md

markdown

undefined

为RC打标签：

bash

git tag -a v<version>-rc.<n> -m "Release candidate v<version>-rc.<n>"
git push origin v<version>-rc.<n>

生成验证检查清单：

收集上次发布以来的所有已交付计划（通过

docs/plans/delivered/

目录 — 对比每个计划状态章节中的“已交付日期”与上次发布标签的日期）。对于每个已交付的功能或Bug修复计划，提取

## Changelog

章节内容并创建检查清单项。若计划包含

Sprint: <名称>

字段，需在检查清单项旁注明迭代名称以提供上下文。迭代完成情况仅作信息参考，不阻塞发布流程。

bash

mkdir -p docs/releases

写入

docs/releases/v<version>-checklist.md

文件：

markdown

undefined

Release Checklist — v<version>

发布检查清单 — v<version>

RC: v<version>-rc.<n> (YYYY-MM-DD)

RC版本：v<version>-rc.<n>（YYYY-MM-DD）

Verification

验证项

<feature/bug slug> — <changelog summary>
<feature/bug slug> — <changelog summary>

<功能/Bug修复标识> — <变更日志摘要>
<功能/Bug修复标识> — <变更日志摘要>

Automated Tests

自动化测试

CI passes on RC tag

RC标签对应的CI流水线执行通过

Sign-off

签字确认

All items verified by: ___
Final release approved by: ___


```bash
git add docs/releases/v<version>-checklist.md
git commit -m "release: v<version>-rc.<n> checklist"
git push

Summary (RC):

RC tag:
```
v<version>-rc.<n>
```
Checklist:
```
docs/releases/v<version>-checklist.md
```
Plans included: list of slugs
Next: test against checklist. If bugs found, fix via normal
```
bug/
```
branches, merge, then run
```
/plot-release rc
```
again for next RC. When all items pass, run
```
/plot-release
```
to cut the final release.

所有项已由___验证通过
最终发布已由___批准


```bash
git add docs/releases/v<version>-checklist.md
git commit -m "release: v<version>-rc.<n> checklist"
git push

RC发布总结：

RC标签：
```
v<version>-rc.<n>
```
检查清单：
```
docs/releases/v<version>-checklist.md
```
包含的计划：标识列表
下一步：根据检查清单进行测试。若发现Bug，通过常规
```
bug/
```
分支修复并合并，然后再次运行
```
/plot-release rc
```
命令生成下一个RC版本。所有项验证通过后，运行
```
/plot-release
```
命令创建正式最终发布版本。

2B. Final Release Path — Generate Release Notes

2B. 正式发布路径 — 生成发布笔记

Check for project-specific release note tooling, then either run it or fall back to manual collection.

Discover tooling — check in this order:

Changesets: Does
```
.changeset/config.json
```
exist? If so, the project uses
```
@changesets/cli
```
.
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 tooling is found: remind the user to run it (e.g.,

pnpm exec changeset version

for changesets). Do not run release tooling automatically — the user controls when and how versions are bumped. Then proceed to step 3 (cross-check).

If no tooling is found: collect changelog entries from delivered plans and present them to the user:

bash

undefined

检查项目专属的发布笔记工具，优先使用工具生成，若无则手动收集。

工具发现顺序：

Changesets： 检查是否存在
```
.changeset/config.json
```
文件，若存在则项目使用
```
@changesets/cli
```
工具。
项目规则： 阅读
```
CLAUDE.md
```
和
```
AGENTS.md
```
文件获取发布笔记生成说明（如自定义脚本、特定命令）。
自定义脚本： 检查
```
package.json
```
文件中的发布相关脚本（如
```
release
```
、
```
version
```
、
```
changelog
```
）。

若找到工具： 提醒用户运行对应工具（如使用Changesets时运行

pnpm exec changeset version

）。请勿自动运行发布工具 — 由用户控制版本升级的时间和方式。之后进入步骤3（交叉检查）。

若未找到工具： 从已交付计划中收集变更日志条目并呈现给用户：

bash

undefined

Get the date of the last release tag (exclude RC tags)

获取上次正式发布标签的日期（排除RC标签）

LAST_TAG=$(git tag --sort=-v:refname | grep -v '-rc.' | head -1) if [ -n "$LAST_TAG" ]; then LAST_RELEASE_DATE=$(git log -1 --format=%ai "$LAST_TAG" | cut -d' ' -f1) else LAST_RELEASE_DATE="1970-01-01" fi

Find delivered plans newer than the last release

查找上次发布以来的已交付计划

ls docs/plans/delivered/ 2>/dev/null


For each delivered plan since the last release:
1. Read the `## Changelog` section
2. Read the `## Status` section for the **Type** (feature/bug/docs/infra)
3. Collect the changelog entries

Only include feature and bug plans in the release notes (docs/infra are live when merged — they don't need release).

Present the collected entries to the user and suggest they add them to `CHANGELOG.md`. Do not write to `CHANGELOG.md` directly.

ls docs/plans/delivered/ 2>/dev/null


对于上次发布以来的每个已交付计划：
1. 读取`## Changelog`章节内容
2. 读取`## Status`章节中的**类型**（feature/bug/docs/infra）
3. 收集变更日志条目

仅在发布笔记中包含功能和Bug修复计划（文档/基础设施计划在合并后即生效，无需纳入发布笔记）。

将收集到的条目呈现给用户，并建议他们添加到`CHANGELOG.md`文件中。请勿直接写入`CHANGELOG.md`。

3. Cross-check Release Notes

3. 交叉检查发布笔记

Model tiers for this step:

Frontier (e.g., Opus): Full cross-check — compare changelog entries against delivered plans and commit messages. Can delegate data gathering (reading plans, collecting commit messages) to small subagents. Flag significant gaps (missing features, phantom entries). Don't nitpick wording.

Mid (e.g., Sonnet): Compare changelog entry count against delivered plan count. Can delegate plan reading to small subagents. Flag obvious mismatches (plan with no corresponding entry, entry with no corresponding plan). Skip semantic content comparison.

Small (e.g., Haiku): Skip gap detection. Present the generated release notes and ask: "Do these release notes look complete?" Human review is the final gate.

Whether generated by tooling or manually constructed, compare the changelog against the actual work:

Collect the list of delivered plans and commit messages since the last tag
Compare against the generated changelog entries
Only flag significant gaps or errors — e.g., a delivered feature completely missing from the changelog, or a changelog entry that doesn't match any actual work
Don't nitpick wording or minor omissions — offer improvements only if there are clear, meaningful gaps
If gaps are found, show them to the user and ask whether to fix before proceeding

This cross-check is the primary value of

/plot-release

— verifying that release notes accurately reflect delivered work.

本步骤适用模型等级：

Frontier（如Opus）： 完整交叉检查 — 对比变更日志条目与已交付计划及提交信息。可将数据收集工作（读取计划、收集提交信息）委托给小型子Agent。标记重大遗漏（如已交付功能完全未出现在变更日志中）或错误（如变更日志条目与实际工作不符）。无需纠结措辞细节。

Mid（如Sonnet）： 对比变更日志条目数量与已交付计划数量。可将读取计划的工作委托给小型子Agent。标记明显不匹配（如计划无对应条目，或条目无对应计划）。跳过语义内容对比。

Small（如Haiku）： 跳过遗漏检测。呈现生成的发布笔记并询问用户：“这些发布笔记是否完整？” 人工审核为最终确认环节。

无论发布笔记由工具生成还是手动收集，都需与实际完成的工作进行对比：

收集上次标签以来的已交付计划列表和提交信息
与生成的变更日志条目进行对比
仅标记重大遗漏或错误 — 例如已交付功能完全未出现在变更日志中，或变更日志条目与实际工作不符
无需纠结措辞或次要遗漏 — 仅当存在明确、有意义的遗漏时提供改进建议
若发现遗漏，向用户展示并询问是否需要在继续前修复

交叉检查是

/plot-release

命令的核心价值 — 确保发布笔记准确反映已交付的工作内容。

4. Recommended Next Steps

4. 推荐后续步骤

Present a numbered list of actions for the user to confirm:

Update
```
CHANGELOG.md
```
with the collected entries (if not already done by tooling)

Bump version in

package.json

(if applicable):

pnpm version <version> --no-git-tag-version

Commit:
```
git commit -am "release: v<version>"
```

Tag:

git tag -a v<version> -m "Release v<version>"

Push:

git push origin main && git push origin v<version>

Offer to execute these steps only if the user confirms. Do not run them automatically.

向用户呈现可确认的编号操作列表：

将收集到的条目更新到
```
CHANGELOG.md
```
中（若工具未自动完成）

若适用，在

package.json

中升级版本：

pnpm version <version> --no-git-tag-version

提交变更：
```
git commit -am "release: v<version>"
```

打标签：

git tag -a v<version> -m "Release v<version>"

推送变更：

git push origin main && git push origin v<version>

仅在用户确认后执行上述步骤 — 请勿自动运行。

5. Clean Up RC Artifacts

5. 清理RC相关产物

If RC tags exist for this version, they remain in git history (don't delete them — they're part of the release record). The checklist file at

docs/releases/v<version>-checklist.md

stays committed as documentation of what was verified.

若该版本存在RC标签，需保留在git历史中（请勿删除 — 它们是发布记录的一部分）。

docs/releases/v<version>-checklist.md

检查清单文件需保留在提交记录中，作为验证内容的文档。

6. Summary

6. 发布总结

Print:

Version:
```
v<version>
```
Plans included:
- ```
<slug>
```
  — <type>
- ```
<slug>
```
  — <type>
Cross-check result: complete / gaps found
RC iterations: <count> (if any)
Status: what remains to be done (version bump, tag, push, etc.)

打印以下信息：

版本号：
```
v<version>
```
包含的计划：
- ```
<标识>
```
  — <类型>
- ```
<标识>
```
  — <类型>
交叉检查结果：完整/存在遗漏
RC迭代次数：<数量>（如有）
状态：待完成事项（版本升级、打标签、推送等）