plan-build-verify

规划、构建、验证

按照顺序推进实现工作，其中 GitHub Issues 是规范的唯一可信来源。另外还有两种辅助模式：Triage 和 Migrate，用于管理路线图。

先阅读约定

开始任何模式前，请完整阅读 references/conventions.md。该文件定义了仓库预检、标签分类、Issue 正文模板、状态转换、子 Issue 机制、Issue 依赖关系、临时正文文件，以及如何与此技能包中的 pstack 和其他技能共存。所有其他参考文件都依赖于它。

与 pstack 和此技能包中的其他技能共存

GitHub Issues 仍是规范、优先级以及 Plan / Build / Verify 生命周期的唯一可信来源。对于使用 GitHub Issues 的产品仓库（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 Issues 的产品仓库

规则：

• 不要因为“最好的规范就是代码”而跳过未经批准的 Issue。
• 对于产品类工作，Plan 阶段的 architect 检查点仅用于调查。不要把 pstack 的“永不因等待人工而阻塞”立场当作越过未经批准规范进行构建的许可。
• 针对每个仓库的 verify-* 技能（斜杠形式为 /verify-<app>，通常位于 .cursor/skills/verify-*/ 下）及其功能映射，与 Issue 上的 ## Demonstration / ## Verification 配合使用，但不能替代验收标准。在 Verify 期间，优先查找并遵循 /verify-*，不要只依赖打包的 UAT 手册。不要在 Verify 期间生成此类技能。
• 不要另创第二套 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 技能包。

阶段约定

阶段	输入	输出	状态标签转换
规划	想法、模糊请求或新的构建请求	上下文探索 → 对齐对话 → 方法审批 → 纵向切片的规格 Issue，其中必须包含 ## Acceptance criteria	无 → status:draft → status:approved
构建	已批准的规格 Issue 编号，或用户明确覆盖要求	已实现的任务、提交、评审结果、已推送的分支、构建完成报告评论	status:approved → status:implemented
验证	已实现的规格 Issue，以及已完成的工作或构建报告	验收证据、持久化验收测试、拉取请求、通过的 CI、已解决的评审讨论串、签核建议	status:implemented → status:verified
分类	仓库 Issue 待办列表	整理报告，以及已执行的标签、拆分和关闭操作	按各 Issue 分别纠正
迁移	现有的 docs/specs/*.md 文件集	评估报告、规格 Issue、已归档的本地文件、重写的交叉链接、更新后的规格索引	根据各文件声明的状态确定

选择工作流

除非用户明确要求执行现有问题、验证已完成的工作、整理待办事项或迁移规格，否则默认选择 Plan。新的构建请求从 Plan 开始，即使用户说“构建”也是如此。

模式	参考文件	适用情况
Plan	references/plan.md	界定范围、设计或编写工作规格，或该请求没有 status:approved 问题。
Build	references/build.md	执行已命名且获批准的规格问题。
Verify	references/verify.md	证明已完成的工作符合问题的验收标准。
Triage	references/triage.md	整理待办事项，或回答“接下来应该做什么？”。
Migrate	references/migration.md	将 docs/specs/*.md 转换为问题。先评估，单向迁移。

先完整阅读 references/conventions.md，然后完整阅读所选参考文件，并遵循两者。只加载所需的工作流。

Build 和 Verify 是一次连续运行。 Build 不会停下来询问是否要验证，而是直接进入 Verify。随后 Verify 会自动运行证据收集、验收测试、创建 PR 和 CI 收敛流程，直到签署确认时才停止。请参阅 references/verify.md 中的自主执行约定。

硬性关卡：

• 除非用户明确覆盖审批关卡，否则不得从 status:draft 问题开始 Build。
• 没有证据时，Verify 不得声称已签署确认。
• Verify 绝不能合并 PR。是否签署确认和合并由用户决定。
• 由 Verify 创建 PR，而非 Build。PR 正文需包含验收标准矩阵。
• 在 Plan 中，用户尚未回答方向对齐问题或批准推荐方向前，不要起草规格问题。若即将起草，请停下来改为提问。
• Migration 必须先评估。运行 scripts/migrate_specs.sh --assess，并在进行任何写入前，与用户逐一解决所有未分类或有冲突的文件。

对于文案修改或单项配置调整等范围明确的小改动，不要强制执行完整的 Plan 工作流，也不要创建问题。说明所依据的假设，并询问用户是否希望采用完整流程。如果模式仍不明确，请提出一个有针对性的问题以消除歧义。

内置阶段参考

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

阶段	工作流	入口文件
Build	TDD	references/tdd/workflow.md
Verify	用户验收	如果存在项目本地的 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 读取线程；该循环不依赖此技能。

辅助脚本

• scripts/ensure_labels.sh：幂等地创建此技能的标签分类。--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。

根据运行时实际加载的技能目录解析脚本路径。如果配置的技能路径不存在，请停止并询问要使用哪个安装位置。绝不要为了让路径有效而将技能文件复制到项目工作树中。

要求

• gh CLI，并已通过身份验证且对目标仓库有 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 将其关联。
• 版本足够新的 gh，以支持 Issue 依赖项（gh issue edit --add-blocked-by）。这是内置功能；无需扩展。
• 一个指向拥有路线图的 GitHub 仓库的 git 远程地址。
• 用于读取 gh sub-issue list --json 输出的 jq。该扩展本身没有 -q 标志。
• python3，仅用于迁移期间重写链接。

在本次会话中首次执行 gh 写入操作前，先运行 references/conventions.md 中的预检。如果无法使用 gh 或尚未通过身份验证，请停止并告知用户。不要回退到在本地编写规格文件。

共同原则

• 在对项目结构、命令或现有工作作出判断前，检查仓库和 Issue 待办列表。
• 如果工作包含多个步骤，请使用待办列表。
• 在 Plan 阶段，先逐一提出有针对性的对齐问题，再起草 Issue。如果无需澄清事实，请让用户确认你的问题框定、假设和验收标准。
• 在 Plan 阶段，如果存在多个可行方向，请提出 2-3 种方案。如果某个方案显然最佳，请说明推荐方案，并等待用户批准或提出其他方向。
• 相较于范围广泛但未经验证的更改，优先选择用户可见、可用或可评估的最小端到端切片。这里的“用户”包括人员、操作员或 API/SDK 使用者。
• 按可演示的行为拆分史诗级任务，而非按架构层、组件或团队拆分。如果一个精简的垂直切片能够贯穿各环节，就不要将存储、后端、协议、前端和测试拆成独立的路线图阶段。
• 仅当没有技术准备工作就无法安全实现端到端切片时，才添加技术赋能子任务。将其控制在最低限度，说明为何不能将其纳入第一个切片，并指出它能立即解锁的面向用户切片。
• 每个面向用户的切片都必须通过公共边界端到端测试；视觉目标还必须提供规定的起始和最终截图。
• 视频是理想的时序证据，但不应成为无限制的门槛：限时尝试一次；若仍无法录制，则跳过并标记环境或工具链缺口。
• 将范围限定在选定的 Issue 及其验收标准内。
• 规格 Issue 必须包含准确的 ## Acceptance criteria 章节，其中列出可观察的通过/失败标准，以便 Build 阶段能够实现、Verify 阶段能够测试；否则该 Issue 就不完整。
• Issue 本身就是规格。仅将本地 Markdown 用作临时正文文件，并在 gh 写入成功后将其删除。
• 每次阶段转换都必须更新 Issue 的 status:* 标签。标签与 Issue 实际状态不符属于分诊缺陷。
• 明确指出不确定之处，不要用猜测填补空白。