plan-build-verify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plan Build Verify

Route implementation work through a sequential path where GitHub Issues are the source of truth for specs. Two supporting modes, Triage and Migrate, manage the roadmap.

将实现工作按顺序流转，其中GitHub Issues是规格的唯一可信来源。另外还有Triage（分类梳理）和Migrate（迁移）两种辅助模式用于管理路线图。

Read the conventions first

先阅读约定规范

Before any mode, read

references/conventions.md

completely. It defines the repo preflight, label taxonomy, issue body template, status transitions, sub-issue mechanics, issue dependencies, temporary body files, and coexistence with pstack and other skills in this pack. Every other reference file depends on it.

在使用任何模式之前，请完整阅读

references/conventions.md

。它定义了仓库预检查、标签分类体系、Issue正文模板、状态转换规则、子Issue机制、Issue依赖关系、临时正文文件，以及与pstack和此技能包中其他技能的共存规则。所有其他参考文件都依赖于此文档。

Coexistence with pstack and other skills in this pack

与pstack及技能包中其他技能的共存规则

GitHub Issues remain the source of truth for specs, priority, and the Plan / Build / Verify lifecycle. For GitHub-issue product repos (

devbox

kata-code

kata-agents

kata-symphony

), plan-build-verify is the only product OS.

Skill / layer	Role	Not its job
plan-build-verify	Only product OS: specs, priority, Plan / Build / Verify, labels	Implementation tactics inside a Build or Verify run
pstack (Cursor plugin)	Engineering execution and proof inside Build and Verify; investigation during Plan ( `architect` / `how` / `why` )	Planning, labels, approval, or a second issue lifecycle
ps ( `/ps` in this pack)	Historical port of pstack; unwieldy; do not install for product delivery	Substitute for the pstack plugin or a second product OS
okf / finalize's OKF step	Retired. Remains in the library for history only	Any live roadmap or docs-as-spec workflow
kata-linear	Linear-first repos only	These four GitHub-issue product repos

Rules:

Do not skip an unapproved issue because "the best spec is code."
For product-shaped work, an architect checkpoint during Plan is investigation only. Do not treat pstack's never-block-on-the-human stance as permission to build past an unapproved spec.
A per-repo verification skill and feature map complement
```
## Demonstration
```
/
```
## Verification
```
on the issue. They do not replace acceptance criteria.
Do not invent a second issue tracker or file-based specs. Do not create or maintain product specs under
```
docs/specs/
```
except the PBV migration index/archive described in
```
references/conventions.md
```
.
Do not run
```
okf init
```
,
```
okf update
```
, or finalize's OKF step. OKF is retired; it is not an alternative roadmap.
Do not install
```
ps
```
,
```
okf
```
, or
```
kata-linear
```
for these product repos. Install project-local skills with
```
scripts/install-skills.sh
```
(or the npx command in
```
references/conventions.md
```
). Never
```
npx skills add -g
```
, and never install the whole
```
gannonh/skills
```
pack.

GitHub Issues始终是规格、优先级以及Plan/Build/Verify生命周期的唯一可信来源。对于以GitHub Issue为核心的产品仓库（

devbox

、

kata-code

、

kata-agents

、

kata-symphony

），plan-build-verify是唯一的产品操作系统。

技能/层级	职责	非职责范围
plan-build-verify	唯一产品操作系统：规格、优先级、Plan/Build/Verify流程、标签	Build或Verify阶段内的实施策略
pstack（Cursor插件）	在Build和Verify阶段执行工程任务并验证成果；在Plan阶段开展调研（ `architect` / `how` / `why` ）	规划、标签管理、审批或独立的Issue生命周期管理
ps（此技能包中的 `/ps` ）	pstack的历史移植版本；操作繁琐；产品交付场景请勿安装	替代pstack插件或作为第二套产品操作系统
okf / finalize的OKF步骤	已停用。仅作为历史遗留保留在库中	任何活跃路线图或文档即规格的工作流
kata-linear	仅适用于以Linear为核心的仓库	上述四个以GitHub Issue为核心的产品仓库

规则：

不要跳过未审批的Issue，理由是“最好的规格就是代码”。
对于产品形态的工作，Plan阶段的架构师检查仅用于调研。请勿将pstack的“不依赖人工阻塞”原则视为越过未审批规格进行开发的许可。
仓库专属的验证技能和功能图是对Issue中
```
## 演示
```
/
```
## 验证
```
部分的补充，不能替代验收标准。
不要创建第二套Issue跟踪系统或基于文件的规格。除
```
references/conventions.md
```
中描述的PBV迁移索引/归档外，请勿在
```
docs/specs/
```
下创建或维护产品规格。
不要运行
```
okf init
```
、
```
okf update
```
或finalize的OKF步骤。OKF已停用，不能作为替代路线图。
请勿为这些产品仓库安装
```
ps
```
、
```
okf
```
或
```
kata-linear
```
。使用
```
scripts/install-skills.sh
```
（或
```
references/conventions.md
```
中的npx命令）安装项目本地技能。切勿使用
```
npx skills add -g
```
，也不要安装整个
```
gannonh/skills
```
技能包。

Phase contracts

阶段约定

Phase	Input	Output	Status label transition
Plan	Idea, vague request, or new build request	Context exploration → alignment dialogue → approach approval → vertically sliced spec issue with mandatory `## Acceptance criteria`	none → `status:draft` → `status:approved`
Build	Approved spec issue number, or explicit user override	Implemented tasks, commits, review results, pushed branch, Build completion report comment	`status:approved` → `status:implemented`
Verify	Implemented spec issue plus completed work or Build report	Acceptance evidence, durable acceptance tests, pull request, green CI, resolved review threads, signoff recommendation	`status:implemented` → `status:verified`
Triage	Repo issue backlog	Grooming report and applied label, decomposition, and closure actions	corrective, per issue
Migrate	Existing `docs/specs/*.md` bundle	Assessment report, spec issues, archived local files, rewritten cross-links, updated specs index	derived from each file's declared status

阶段	输入	输出	状态标签转换
Plan	想法、模糊需求或新开发请求	上下文探索 → 对齐沟通 → 方案审批 → 包含必填 `## 验收标准` 的垂直切片规格Issue	无 → `status:draft` → `status:approved`
Build	已审批的规格Issue编号，或用户明确覆盖指令	已完成的任务、提交记录、评审结果、推送的分支、Build完成报告评论	`status:approved` → `status:implemented`
Verify	已完成开发的规格Issue及成果或Build报告	验收证据、持久化验收测试、Pull Request、通过的CI、已解决的评审线程、签署建议	`status:implemented` → `status:verified`
Triage	仓库Issue待办列表	梳理报告及已应用的标签、拆分操作和关闭动作	针对单个Issue的修正性操作
Migrate	现有 `docs/specs/*.md` 文件包	评估报告、规格Issue、归档的本地文件、重写的交叉链接、更新后的规格索引	由每个文件声明的状态派生而来

Select the workflow

选择工作流

Default to Plan unless the user explicitly directs you to execute an existing issue, verify completed work, groom the backlog, or migrate specs. A new build request starts at Plan even when the user says "build".

Mode	Reference	Enter when
Plan	`references/plan.md`	Scoping, designing, or specifying work, or no `status:approved` issue exists for the request.
Build	`references/build.md`	Executing a named, approved spec issue.
Verify	`references/verify.md`	Proving completed work meets the issue's acceptance criteria.
Triage	`references/triage.md`	Grooming the backlog, or answering "what should we work on next?".
Migrate	`references/migration.md`	Converting `docs/specs/*.md` into issues. Assess-first, one-way.

Read

references/conventions.md

and then the selected reference file completely, and follow both. Only load the workflow you need.

Build and Verify are one continuous run. Build does not stop to ask whether to verify; it enters Verify directly. Verify then runs unattended through evidence, acceptance tests, PR creation, and CI convergence, stopping only at signoff. See the autonomy contract in

references/verify.md

Hard gates:

Build must not start from a
```
status:draft
```
issue unless the user explicitly overrides the approval gate.
Verify must not claim signoff without evidence.
Verify must never merge the PR. Signoff and merge are the user's decision.
Verify opens the PR, not Build. The PR body carries the acceptance-criteria matrix.
In Plan, do not draft a spec issue before the user has answered an alignment question or approved a recommended direction. If you are about to, stop and ask instead.
Migration is assess-first. Run
```
scripts/migrate_specs.sh --assess
```
and settle every unclassified or conflicting file with the user before any write.

For tiny, clearly bounded edits such as a copy change or single config tweak, do not force the full Plan workflow and do not open an issue. State the assumption and ask whether the user wants the full process. If the mode remains ambiguous, ask one focused question that resolves it.

默认使用Plan模式，除非用户明确指示你执行现有Issue、验证已完成工作、梳理待办列表或迁移规格。即使用户说“构建”，新的开发请求也要从Plan阶段开始。

模式	参考文档	适用场景
Plan	`references/plan.md`	范围界定、设计或制定规格，或请求对应的 `status:approved` Issue不存在时。
Build	`references/build.md`	执行指定的已审批规格Issue。
Verify	`references/verify.md`	证明已完成工作符合Issue的验收标准。
Triage	`references/triage.md`	梳理待办列表，或回答“我们下一步应该做什么？”的问题。
Migrate	`references/migration.md`	将 `docs/specs/*.md` 转换为Issue。先评估，再执行，单向迁移。

请完整阅读

references/conventions.md

和所选的参考文档，并严格遵循两者的要求。仅加载你需要的工作流。

Build和Verify是连续运行的流程。Build不会中途询问是否要进入Verify，而是直接进入Verify阶段。Verify会自动完成证据收集、验收测试、PR创建和CI收敛，仅在签署环节停止。详情请见

references/verify.md

中的自主执行约定。

硬性限制：

除非用户明确覆盖审批限制，否则Build不能从
```
status:draft
```
的Issue开始。
Verify不能在没有证据的情况下声称已签署。
Verify绝对不能合并PR。签署和合并是用户的决策。
由Verify而非Build创建PR。PR正文需包含验收标准矩阵。
在Plan阶段，用户回答对齐问题或批准推荐方案之前，请勿起草规格Issue。如果即将这么做，请停止并询问用户。
迁移需先评估。运行
```
scripts/migrate_specs.sh --assess
```
，在执行任何写入操作前，与用户确认所有未分类或有冲突的文件。

对于微小、边界清晰的修改（如文案变更或单一配置调整），无需强制使用完整的Plan工作流，也无需创建Issue。请说明你的假设，并询问用户是否需要完整流程。如果模式仍不明确，请提出一个聚焦的问题来明确模式。

Bundled phase references

内置阶段参考

Build and Verify load bundled workflows from this skill directory. Read the entry point completely; follow linked files and scripts under the same subtree.

Phase	Workflow	Entry point
Build	TDD	`references/tdd/workflow.md`
Verify	User acceptance	`references/user-acceptance/workflow.md`

Verify's convergence loop (Step 7) drives CI with

gh pr checks --watch

and

gh run

directly. For review threads it uses one sibling skill, resolved against the installed skills directory:

Purpose	Skill	Entry point
Review-thread inventory and fixes	`address-pr-comments`	`<path-to-skills-directory>/address-pr-comments/SKILL.md`

If it is not installed, Verify reads threads with

gh api graphql

instead; the loop does not depend on it.

Build和Verify会加载此技能目录中的内置工作流。请完整阅读入口文件；遵循同一子目录下的链接文件和脚本。

阶段	工作流	入口文件
Build	TDD	`references/tdd/workflow.md`
Verify	用户验收	`references/user-acceptance/workflow.md`

Verify的收敛循环（第7步）通过

gh pr checks --watch

和

gh run

直接驱动CI。对于评审线程，它会使用一个同级技能，基于已安装的技能目录解析：

用途	技能	入口文件
评审线程盘点与修复	`address-pr-comments`	`<path-to-skills-directory>/address-pr-comments/SKILL.md`

如果未安装该技能，Verify会改用

gh api graphql

读取线程；收敛循环不依赖此技能。

Helper scripts

辅助脚本

```
scripts/ensure_labels.sh
```
: idempotently creates this skill's label taxonomy.
```
--dry-run
```
reports what would change.
```
scripts/install-skills.sh
```
: project-local, non-interactive install of
```
plan-build-verify
```
and
```
address-pr-comments
```
only. Product repos can copy it. Never
```
-g
```
; never installs
```
ps
```
,
```
okf
```
, or
```
kata-linear
```
.
```
scripts/migrate_specs.sh
```
: bulk-converts
```
docs/specs/*.md
```
into spec issues, archives the sources, rewrites cross-links, and updates the specs index. Run
```
--assess
```
, then
```
--dry-run
```
, then apply.
```
scripts/rewrite_spec_links.py
```
: repoints Markdown links after files move into the archive. Called by the migration script; requires
```
python3
```
.

Resolve script paths against the skill directory the runtime actually loaded. If a configured skill path does not exist, stop and ask which installation to use. Never copy skill files into the project working tree to make a path resolve.

```
scripts/ensure_labels.sh
```
：幂等创建本Skill的标签分类体系。
```
--dry-run
```
参数会报告将要做出的更改。
```
scripts/install-skills.sh
```
：仅在项目本地非交互式安装
```
plan-build-verify
```
和
```
address-pr-comments
```
。产品仓库可复制此脚本。切勿使用
```
-g
```
参数；切勿安装
```
ps
```
、
```
okf
```
或
```
kata-linear
```
。
```
scripts/migrate_specs.sh
```
：批量将
```
docs/specs/*.md
```
转换为规格Issue，归档源文件，重写交叉链接，并更新规格索引。请依次运行
```
--assess
```
、
```
--dry-run
```
，最后执行迁移。
```
scripts/rewrite_spec_links.py
```
：文件移入归档后重写Markdown链接。由迁移脚本调用；需要
```
python3
```
环境。

请根据运行时实际加载的技能目录解析脚本路径。如果配置的技能路径不存在，请停止并询问用户使用哪个安装版本。切勿将技能文件复制到项目工作目录来解决路径问题。

Requirements

依赖要求

```
gh
```
CLI, authenticated with issue write access for the target repo.
```
gh sub-issue
```
extension (
```
yahsan2/gh-sub-issue
```
) for decomposed specs. If absent, install with
```
gh extension install yahsan2/gh-sub-issue
```
or use the task-list fallback in
```
references/conventions.md
```
. Its
```
create
```
subcommand has no
```
--body-file
```
, so children are created with
```
gh issue create
```
and then attached with
```
gh sub-issue add
```
.
A
```
gh
```
recent enough for issue dependencies (
```
gh issue edit --add-blocked-by
```
). Native; no extension required.
A git remote pointing at the GitHub repository that owns the roadmap.
```
jq
```
, for reading
```
gh sub-issue list --json
```
output. The extension has no
```
-q
```
flag of its own.
```
python3
```
, for link rewriting during migration only.

Run the preflight in

references/conventions.md

before the first

gh

write of a session. If

gh

is unavailable or unauthenticated, stop and tell the user. Do not fall back to writing spec files locally.

```
gh
```
命令行工具，已通过认证且拥有目标仓库的Issue写入权限。
```
gh sub-issue
```
扩展（
```
yahsan2/gh-sub-issue
```
），用于拆分规格。如果未安装，请使用
```
gh extension install yahsan2/gh-sub-issue
```
安装，或遵循
```
references/conventions.md
```
中的任务列表替代方案。其
```
create
```
子命令没有
```
--body-file
```
参数，因此需先使用
```
gh issue create
```
创建子Issue，再用
```
gh sub-issue add
```
关联。
支持Issue依赖的
```
gh
```
版本（
```
gh issue edit --add-blocked-by
```
）。原生支持；无需扩展。
指向拥有路线图的GitHub仓库的Git远程仓库。
```
jq
```
，用于读取
```
gh sub-issue list --json
```
的输出。该扩展本身没有
```
-q
```
参数。
```
python3
```
，仅用于迁移过程中的链接重写。

在会话中首次执行

gh

写入操作前，请运行

references/conventions.md

中的预检查。如果

gh

不可用或未认证，请停止并告知用户。切勿退回到本地编写规格文件。

Shared principles

共享原则

Inspect the repo and the issue backlog before making claims about project structure, commands, or existing work.
Use a todo list when the work has multiple steps.
In Plan, ask focused alignment questions one at a time before drafting the issue. If no factual clarification is needed, ask the user to confirm your framing, assumptions, and acceptance criteria.
In Plan, propose 2-3 approaches when more than one viable direction exists. If one is clearly best, state the recommendation and wait for approval or redirection.
Prefer the smallest end-to-end slice a user can see, use, or evaluate over broad unverified changes. “User” includes a human, operator, or API/SDK consumer.
Decompose epics by demonstrable behavior, not by architecture layer, component, or team. Do not make storage, backend, protocol, frontend, and testing separate roadmap phases when one thin vertical slice can cross them.
Use a technical-enablement child only when no safe end-to-end slice is feasible without it. Keep it minimal, explain why it cannot be folded into the first slice, and name the user-facing slice it immediately unlocks.
Require a passing public-boundary E2E test for every user-facing slice and required starting/final screenshots for visual targets.
Treat video as ideal temporal evidence, not an unbounded gate: make one bounded attempt, then skip and flag the environment/tooling gap when recording remains unavailable.
Keep scope tied to the selected issue and its acceptance criteria.
A spec issue is incomplete unless it has an exact
```
## Acceptance criteria
```
section with observable pass/fail criteria that Build can implement and Verify can test.
The issue is the spec. Local Markdown exists only as a temporary body file and is removed after the
```
gh
```
write succeeds.
Every phase transition updates the issue's
```
status:*
```
label. An issue whose label does not match its real state is a triage defect.
Surface uncertainty instead of filling gaps with guesses.

在对项目结构、命令或现有工作做出断言前，请先检查仓库和Issue待办列表。
当工作包含多个步骤时，使用待办清单。
在Plan阶段，起草Issue前请逐个提出聚焦的对齐问题。如果无需事实澄清，请让用户确认你的框架、假设和验收标准。
在Plan阶段，当存在多个可行方案时，提出2-3种方案。如果某一方案明显最优，请说明推荐理由并等待用户批准或调整。
优先选择用户可见、可用或可评估的最小端到端切片，而非宽泛的未验证变更。“用户”包括人类、运维人员或API/SDK消费者。
按可演示的行为拆分史诗任务，而非按架构层、组件或团队拆分。当一个薄垂直切片可以跨越多层时，不要将存储、后端、协议、前端和测试拆分为独立的路线图阶段。
仅当无法实现安全的端到端切片时，才创建技术赋能子任务。请保持其最小化，解释为何无法融入第一个切片，并指明它将直接解锁的面向用户的切片。
每个面向用户的切片都需要通过公共边界的E2E测试，视觉目标需要起始和最终截图。
将视频视为理想的时序证据，但不要作为无限制的关卡：尝试一次录制，如果仍然无法录制，请跳过并标记环境/工具缺口。
保持范围与所选Issue及其验收标准绑定。
规格Issue必须包含精确的
```
## 验收标准
```
部分，其中包含Build可实现、Verify可测试的可观察通过/失败标准，否则视为不完整。
Issue就是规格。本地Markdown仅作为临时正文文件，
```
gh
```
写入成功后需删除。
每个阶段转换都要更新Issue的
```
status:*
```
标签。标签与实际状态不符的Issue属于分类梳理缺陷。
遇到不确定性时请明确提出，不要用猜测填补空白。