cgraphx 1.4.1 → 2.0.0

package/dist/.claude-template/skills/write-plan/SKILL.md

@@ -1,246 +1,103 @@
 ---
 name: write-plan
-description: 用户要求基于已确认的 spec、规格说明、技术边界、业务规则、代码上下文或当前上下文编写 plan/实现计划/开发计划/Agent 执行计划时使用。用于把规格契约拆成 coding agent 可执行且应忠实执行的任务清单、依赖图、风险控制、文件归档和验收步骤,默认产出 docs/features/{feature-id}/plan/ 下的 <文件前缀>-index.md、<文件前缀>-01-schema.md、<文件前缀>-02-backend.md、<文件前缀>-03-frontend.md、<文件前缀>-04-test.md 等按需文件(文件前缀算法见 SKILL 正文)。不写 PRD/spec、不直接改代码;信息不足时只补问影响计划正确性的关键问题,或将不确定内容标记为【待确认】。
+description: 用户要求基于已确认的 spec、规格说明、技术边界、业务规则、代码上下文或当前上下文编写 plan/实现计划/开发计划/Agent 执行计划时使用。用于把规格契约拆成 coding agent 可执行且应忠实执行的任务清单、依赖图、风险控制、文件归档和验收步骤,默认产出 docs/features/{feature-id}/plan/ 下的 <文件前缀>-index.md、<文件前缀>-01-schema.md、<文件前缀>-02-backend.md、<文件前缀>-03-frontend.md 等按需文件(文件前缀算法见 SKILL 正文)。不写 PRD/spec、不直接改代码;信息不足时只补问影响计划正确性的关键问题,或将不确定内容标记为【待确认】。
 ---
 
 # 编写 Plan (Write Plan)
 
 ## 定位
 
-把当前上下文中已经确认或给定的 spec、业务要求、技术边界和项目代码上下文,拆成**coding agent 可执行且应忠实执行的实现计划**。
-
-Plan 的目标是指导后续 agent 实际编写代码:明确任务顺序、依赖关系、改动范围、验收方式、风险点和不可越界的约束。Plan 通过 review 后就是 implementation 的执行契约,不是临场发挥的建议稿。
+- **Plan = spec 的执行契约**:把"做什么"拆成 coding agent 可执行且应忠实执行的任务清单(顺序、依赖、范围、验收、风险)。过审后是 implementation 的唯一依据,不是建议稿。
+- **手段按业务可观察性分档(默认自主,越信封才回跳)**:判别一句——**手段有没有 spec 信封外的业务可观察后果?**
+  - **无 → plan 自主**(内部结构、复用哪个既有模块、规范内命名、同步内的实现细节):结合 spec 容忍度 + 既有代码模式定(优先复用,YAGNI),记入 index「实现手段决策」节(选项 + 推荐 + 理由),透明可复审,plan 拍板即锁定。
+  - **有 → 回跳 write-spec**(选异步 ⇒ 用户要看到"处理中"、软删 ⇒ 审计口径、选三方 ⇒ 成本/能力):这是伪装成技术决策的业务决策,回跳让业务拍板补契约,再定手段;拍板前推荐不是锁定。
+- **优先级**:spec 显式契约 > plan > docs/guides/ 规范;规范与 spec 冲突时 spec 赢,例外写进风险/备注。
+- **内容边界**:plan 写具体文件/模块/接口/表,不写实际代码改动、不写 PRD/spec、不排测试任务(测试是代码完成后的独立流程)。澄清总结 = 输入;spec = 唯一契约(plan 不得重新定义);implementation 只有局部工程适配空间。
 
 <HARD-GATE>
-如果缺少会影响计划正确性的关键信息,先补问 3-5 个关键问题;如果不阻塞成文,在 plan 中标记为【待确认】。
-不要编造代码结构、接口、表结构、任务链路或测试命令。没有确认或没有查到的内容标记为【待确认】。
-如果 spec 中有"不可留到实现期的决策"或会影响任务拆分的【待确认】,必须先解决或明确阻塞,不能把关键方案留给 implementer 自行决定。
+缺少影响计划正确性的关键信息 → 先补问 3-5 个;不阻塞成文的标【待确认】。
+不编造代码结构、接口、表结构、任务链路——没查到的一律【待确认】。
+spec 中"不可留到实现期的决策"或影响任务拆分的【待确认】,必须先解决或明确阻塞,不许留给 implementer 自行决定。
 </HARD-GATE>
 
-## 与其他产物的边界
-
-- PRD 说明客户或业务方要确认的业务逻辑。
-- Spec 说明系统必须满足的行为、规则、接口、数据、权限、异常和约束。
-- Plan 说明 coding agent 应该如何按顺序实施 spec,并锁定实施边界。
-- Implementation 按 plan 修改代码;只有局部工程适配空间,不得重新设计 plan 已锁定方案。
-
-Plan 可以包含具体文件、模块、接口、表、测试命令和任务依赖,但仍然只写计划,不执行实现。
-
-## 输入理解
-
-优先基于当前上下文中的以下信息写 plan:
-
-- 已确认的 spec 或规格说明
-- spec 中的 Plan 编写约束、不可留到实现期的决策、待确认项
-- 已确认的业务边界、技术边界和非目标
-- 项目代码结构、模块、接口、模型、任务、队列、页面、测试和构建方式
-- 已有 PRD、影响分析、接口说明、数据库说明、历史 plan 或团队约定
-- 用户明确指定的 feature-id、路径、技术约束或执行偏好
-
-如果当前上下文足够,直接写 plan。不要重新澄清已经确认过的内容。
-
-这些工具可作为上下文补充:
-- `code-impact-api` — 查 docs/knowledge/ 历史决策、业务概念、项目经验
-- `db-query` — 查数据库、查 DDL
-- `codegraph_explore` MCP 工具 / `cgraphx query` / `cgraphx affected` CLI — 查代码调用关系、影响半径(MCP 优先;MCP 不可用走 Bash CLI)
-
-如果缺少关键代码上下文,先读取项目结构、相关文件、测试脚本和既有模式,再写计划。不要凭空规划不存在的模块。
-
-
-## 产物位置与文件
-
-在可写项目上下文中,默认创建或更新:
-
-`docs/features/<feature-id>/plan/`
-
-目录下文件都加 `<文件前缀>-` 前缀(前缀算法见下一节),按需创建:
-
-- `<文件前缀>-index.md` — 总任务清单 + 全局依赖图,必须创建
-- `<文件前缀>-01-schema.md` — 建表/数据迁移任务,按需创建
-- `<文件前缀>-02-backend.md` — 业务逻辑/接口任务,按需创建
-- `<文件前缀>-03-frontend.md` — 前端任务,按需创建
-- `<文件前缀>-04-test.md` — 测试与验收任务,按需创建
+## 输入与上下文
 
-如果没有可写项目上下文,或用户明确只需要正文,则直接在回复中输出同等结构的 plan 内容。
-
-不要创建空的按需文件。某类工作不存在时,在 `<文件前缀>-index.md` 中标记”不涉及”。
-
-## feature-id 与文件前缀规则
-
-**feature-id 格式**:`YYYY-MM-DD-[业务ID-]<标题>`
-
-1. 日期使用当前日期。
-2. 业务ID 是**可选**段落(字母数字 + 连字符,如 `CRM-req19230`)。skill 启动时提示用户填写,允许留空。
-3. 标题段允许中文、英文或混合(例:`号百商品详情查询接口`、`features目录结构调整`)。**不得**对中文做英文 slug 转换。
-4. 业务ID 段与标题段用连字符连接,组成 `<业务ID>-<标题>`。
-5. 写入前检查 `docs/features/` 下是否重名;重名时追加简短后缀。
-6. 若当前上下文或用户已提供 feature-id,则复用。
-7. 如果同一目录下已有 PRD、spec 或其他需求文档,优先复用同一个 feature-id。
-
-**文件前缀算法**:
-- 有业务ID:文件前缀 = `<业务ID>-<标题>`(如 `CRM-req19230-号百商品详情查询接口`)
-- 无业务ID:文件前缀 = `<标题>`(如 `features目录结构调整`)
-
-**默认产物路径**:`docs/features/<feature-id>/plan/<文件前缀>-index.md` 等
-
-例:
-- 有业务ID:`docs/features/2026-06-10-CRM-req19230-号百商品详情查询接口/plan/CRM-req19230-号百商品详情查询接口-index.md`
-- 无业务ID:`docs/features/2026-07-03-features目录结构调整/plan/features目录结构调整-index.md`
-
-**敏感字符拒绝**:文件名不得包含 `/`、`:`、`*`、`?`、`”`、`<`、`>`、`|`。用户提供时若含敏感字符,skill 必须要求用户重命名,不得自动替换字符。
-
-**与旧目录共存**:skill 始终用新命名,不主动探测旧目录的 `index.md` / `01-schema.md` 等。旧 feature 目录里继续更新会出现旧命名和新命名并存,由用户自行处理。
+- **读**:spec(重点:Plan 编写约束、不可留到实现期的决策、待确认项、**业务容忍度**——手段决策的硬依据)、既有代码(结构/模块/接口/模型/任务/队列/页面/测试/构建)、已有 PRD/影响分析/历史 plan/团队约定。缺关键代码上下文 → 先读再写,不凭空规划不存在的模块。
+- **工具**:`knowledge-recall`(知识库:历史决策/业务概念)、`db-query`(查库/查 DDL)、grep/Read(调用关系/符号定位)。
 
 ## 工作流程
 
-通常按以下顺序处理,但允许根据项目上下文合并或跳过不必要步骤。不要把流程完整性置于计划可执行性之上。
-在写任何 plan 内容前,**必须**先与用户确认两件事:
-
-1. **业务 ID**:本次需求是否有对应的工单号 / 需求单号 / 项目代号?允许留空,但**留空也必须显式确认**(用户明确说"没有/留空"),不得默认跳过。
-2. **标题语言**:用中文 / 英文 / 中英混合?由用户选定,**禁止** Agent 因为"目录看起来更整齐"/"和现有 feature 命名一致"/"避免中文路径问题"等原因,擅自把中文需求转成英文 slug。
-
-- 用户主动给过完整 feature-id 或文件名 → 直接复用,跳过本步。
-- 用户用 `/write-plan` 触发但未给命名决策 → **第一步就问这两个问题**,问完再写。
-- 不得"先写 plan 内容,命名最后再说"。命名决策必须在内容产出之前落定,否则会在文件名上反复返工。
-
-1. **读取输入和项目上下文**
-  - 找到当前 feature-id、spec、PRD、现有 plan 或相关文档。
-  - 阅读相关代码、目录结构、测试配置、迁移机制、路由/API、模型、页面和既有模式。
-  - 只读取和计划正确性有关的上下文。
-  - 对照 spec 的"不可留到实现期的决策"和"Plan 编写约束",确认没有关键空洞。
-
-2. **识别实施范围**
-  - 判断是否涉及 schema、backend、frontend、test、数据迁移、异步任务、外部系统或运维配置。
-  - 明确不涉及的部分,避免 agent 后续扩大范围。
-
-3. **拆分任务和依赖**
-  - 把实现工作拆成可由 coding agent 执行的任务。
-  - 每个任务应包含目标、输入、输出、依赖、涉及范围、验收方式和注意事项。
-  - 标明必须串行的任务和可并行的任务;可并行任务必须写明无冲突依据。
-  - 每个任务标明"必须严格执行"和"允许局部适配"的边界。
-
-4. **生成计划文件**
-  - `index.md` 总览全局任务、依赖图、执行顺序和风险。
-  - 按需生成 schema/backend/frontend/test 子计划文件。
-  - 不创建与本需求无关的空文件。
-
-5. **Self-Review(主 agent 自审)**
-  - **Spec 覆盖度**:逐条对照 spec 每条要求,都能对应到任务。遗漏的补任务。
-  - **Placeholder 扫描**:全文搜 TBD / TODO / "implement later" / "add appropriate error handling" / "handle edge cases" / "similar to Task N" 等模糊表述,全部修掉(详见下方 "No Placeholders 规则")。
-  - **跨任务一致性**:类型签名、命名、接口在跨任务引用时是否一致(Task 3 用 `clearLayers()` 但 Task 7 写 `clearFullLayers()` 是 bug)。
-  - **每个任务有可验证完成条件**(具体的测试命令 / 验证步骤,不是"应该工作")。
-  - **Plan 忠实度**:是否把 spec 已锁定契约完整落到任务,是否仍把关键方案留给 implementer 决定。
-
-  发现问题直接 inline 修,不需要重审。
-
-6. **Plan Review(默认派子 agent 审)**
-  - Self-Review 通过后,**默认派 `plan-document-reviewer` 子 agent** 独立审一次 plan。
-  - 子 agent 用同目录下 `plan-document-reviewer-prompt.md` 模板,检查 4 项:完整性 / Spec 对齐 / 任务可执行性 / 跨任务一致性。
-  - 校准:**只标真正会阻塞 implementer 的问题**,措辞/风格不阻塞。
-  - 子 agent 返回 issues → 主 agent 修 → 必要时再派一次复审。
-  - **跳过条件**(用户明确说"不用派" / plan 极小 / 时间紧):主 agent 在 Self-Review 里说明跳过理由。
-
-## index.md 内容要求
-
-`index.md` 是总控文件,必须包含:
-
-- feature-id、状态、日期、来源 spec 或上下文摘要
-- 目标与范围摘要
-- 明确不包含
-- 计划文件列表,说明哪些文件存在、哪些不涉及
-- 总任务清单
-- 全局依赖图
-- 推荐执行顺序
-- 可并行任务(按批次列出,并写明不重叠的文件/模块/验证状态)
-- 必须严格执行的契约
-- 允许局部工程适配的范围
-- Plan 冲突上报规则
-- 关键风险与防跑偏约束
-- 待确认项
-
-依赖图可使用 Mermaid,也可用文本列表。复杂任务优先使用 Mermaid:
-
-```mermaid
-graph TD
-  A[Schema / Migration] --> B[Backend]
-  B --> C[Frontend]
-  B --> D[Test]
-  C --> D
-```
-
-不要为了画图而强行制造依赖。没有依赖时直接说明。
-
-## 子计划文件要求
-
-### `01-schema.md` — 建表/数据迁移任务
-
-按需创建。适用于新表、字段、索引、约束、迁移、回填、默认值、数据修复、兼容历史数据等。
-
-建议包含:
-
-- 涉及的数据对象
-- 预期 schema 或迁移目标
-- 迁移/回填顺序
-- 兼容性和回滚考虑
-- 数据校验方式
-- 风险和待确认项
-
-不要写不可确认的完整 DDL,除非上下文已经明确。
-
-### `02-backend.md` — 业务逻辑/接口任务
-
-按需创建。适用于后端业务逻辑、API、服务、权限、任务队列、缓存、外部系统、日志、审计等。
-
-建议包含:
-
-- 涉及模块、接口、服务或任务
-- 业务规则落点
-- 输入输出和错误处理
-- 权限、安全、审计要求
-- 幂等、重试、并发和一致性要求
-- 需要更新的测试
-- 风险和待确认项
-
-### `03-frontend.md` — 前端任务
-
-按需创建。适用于页面、表单、状态展示、交互、权限可见性、前端校验、加载/空/错误状态等。
-
-建议包含:
+0. **命名先行**(写内容前必须落定):① 业务 ID——有无工单号/需求单号?允许留空但**必须显式确认**;② 标题语言——中/英/混合,用户选定,**禁止擅自中文转英文 slug**;③ 负责人——有 spec 继承 spec 头部的负责人,无 spec 则默认 `git config user.name` 并向用户确认,写入 index.md 头部 `> 负责人:`。用户已给 feature-id → 直接复用。
+1. **读输入,查缺口**:对照 spec 的"不可留到实现期的决策"和"Plan 编写约束";关键缺口 → 补问或标【待确认】(影响拆分的不得伪装成已确认)。
+2. **识别范围 + 拆任务**(见「拆分规则」);明确不涉及的部分,防 implementer 扩范围。
+3. **定手段 + 读规范**:手段按业务可观察性分档——无业务可观察后果的 plan 自主定(记入 index),越信封的回跳 write-spec 补契约再定;读 docs/guides/ 适用规范并落进契约(见「适用规范」——**规范缺失是硬门,中断提示 init-project-guides**)。
+4. **生成文件**:index.md 必须;01-04 按需,不建空文件(不涉及 → index 中标记)。
+5. **Self-Review**(唯一作者关卡,发现即 inline 修;Plan Review 跳过时它就是终审):
+   - Spec 覆盖度 + 双向追溯:spec 每条要求都有承载任务(任务标对应 spec 条款编号);没重新定义 spec、没要求实现非目标。
+   - Placeholder 扫描:TBD/"add appropriate error handling"/"similar to Task N" 等全修掉(见「No Placeholders」);待确认项没被伪装成已确定任务。
+   - 跨任务一致性:签名/命名/接口/表名/路径跨任务逐字一致;契约两端同文(T-2 输出与 T-5 输入)。
+   - 可执行性:每任务有可验证完成条件(具体命令/步骤,不是"应该工作")+ 验证方式。
+   - Plan 忠实度:spec 契约完整落到任务,关键方案没留给 implementer 临场决定。
+   - 规范遵循:契约级规范(表命名/字段类型/接口形态/目录分层)已落进具体契约、无"按规范建表"式转交;plan 契约不违反规范条目,违反的已记例外;强制引用标注齐全。
+   - 提交粒度:标了「独立提交」的任务完成后仓库可工作(能编译、测试不红);提交规范已从 git-standards.md 结晶进 index「提交规范」节;没把强耦合任务误标独立提交。
+   - 全局可读:index 看懂全局;按需文件都有真任务、无空文件;未混入代码;手段决策已按业务可观察性分档(自主项已记录、越信封项已回跳)。
+6. **Plan Review**:默认派 `plan-document-reviewer` 子 agent(同目录 `plan-document-reviewer-prompt.md`),独立复核完整性/Spec 对齐/可执行性/跨任务一致性/执行契约清晰度/**规范遵循**;校准:只标真正阻塞 implementer 的问题。返回 issues → 修 → 必要时复审。跳过条件:用户明确说不用 / plan 极小 / 时间紧(在 Self-Review 里写跳过理由)。
+
+## 拆分规则
+
+- 按依赖和风险拆,不按模板拆:数据/契约 → 后端 → 前端(依实际依赖调整)。
+- **默认合并**(减少审查次数,写明理由):同文件多章节改写归单 implementer;schema 改动 + 对应 migration 合一。拆开仅限:任务过大撑爆上下文、强耦合需实时反馈。
+- **测试不进 plan**:单元测试 / 接口测试是代码完成后的独立流程(`write-unit-test-spec` → `write-unit-test-code`、`write-api` → `run-api-test`,各自从 spec 派生),plan 不排测试任务、不写必测路径 / 测试命令、implementer 实现期不写新测试。plan 对测试的唯一要求是完成定义:任务提交后既有测试不被弄红(改动弄红的既有测试须同步修正)。
+- 能独立验证的尽量独立成任务;高风险任务写保护条件和回退思路。
+- **可独立提交的任务标「独立提交」**:任务完成后仓库处于可工作状态(能编译、相关测试不红)→ 标「独立提交:是」并给建议提交粒度 + commit message 主题;强耦合(完成后仓库不可工作、需后续任务才闭合)→ 不标,说明随哪个任务一起提交。判断依据写进任务,不机械地每任务都标——小步提交是为了原子化历史(好 review / revert / bisect),不是为了凑提交数。
+- 可并行任务显式成批 + 写明文件集/公共契约/测试状态互不冲突;不确定 → 串行。
+- 不重新打开 spec 已锁定的契约;不把简单需求拆碎。
+
+## 消费模型与防漂移
+
+**plan 的读者是被逐任务派出的隔离 subagent**:看不到全篇、不知道你脑中的默认、遇模糊处默默自行补全。写法纪律由此反推。
+
+- **自包含 + 引用不指涉**:每个任务携带(或引用)执行者所需的一切。"见 T-3 的定义"是指涉——implementer 手里可能没有 T-3;写出契约原文是引用。依赖只管执行顺序;跨任务共享的契约(签名、接口形态、命名)在每个引用任务里各写一份同样的原文。
+- **双向追溯**:任务标注对应 spec 条款编号(有疑义读 spec 原文,不猜转述)。权威链:任务 ← plan ← spec,冲突以上层为准并按 PLAN_CONFLICT 上报。
+- **契约两端同文**:T-5 消费 T-2 产出时,接口形态(签名/字段名/错误语义)在 T-2 输出和 T-5 输入里逐字一致。
+- **自由必须枚举**:「必须严格执行」= 契约边界,「允许局部适配」= 裁量边界,没列进允许的一律固定。钉死契约(签名、行为、spec 规则、验证命令),放开机制(内部拆分、局部命名、实现细节)。
+
+## 适用规范(强制读 + 结晶 + 标注)
+
+docs/guides/ 存在时(init-project-guides 产出),写 plan 前按下表读规范、落契约、打标注:
+
+| 任务类型 | 写前必读 | 「强制引用」标注 |
+|---|---|---|
+| schema(建表/改表/迁移/回填) | `data-standards.md` | `data-standards.md` |
+| 接口(API) | `interface-standards.md` | `interface-standards.md` |
+| 动代码(所有任务) | `coding-standards.md` 契约部分(命名/目录/分层) | `coding-standards.md` |
+| 提交(有「独立提交」任务时) | `git-standards.md` 提交消息规范 + 提交前检查点 | 结晶进 index「提交规范」节(plan 级,一次) |
 
-- 涉及页面、组件或路由
-- 用户流程和交互状态
-- 展示字段和校验规则
-- 权限和可见性
-- API 对接点
-- UI 状态: loading/empty/error/success
-- 需要更新的测试或截图验证
-- 风险和待确认项
+- **结晶进契约**:契约级规范落进具体契约——任务直接写合规的表名/字段/签名,"按规范建表"式转交是失败(见红线)。index.md「适用规范」节列文件 + 章节标题(不写行号)。
+- **标注是执行期规范送达的唯一载体**:有 plan 时 implementation/subagent-implement 只读「强制引用」标注的规范、不再自行识别——漏标 = 规范在执行期丢失。
+- **git-standards.md 与其他三份不同**:它不是每任务开工前读的规范(提交规范不随任务变),而是 plan 级**一次结晶进 index「提交规范」节**——提交消息格式 + 提交前检查点原文摘录。实施期提交时直接按 index 已结晶的规范写 message、过检查点,precommit 门禁仅作兜底(不再现场学习规范,消除多次提交的重复读取成本)。
+- **规范缺失 = 中断**:docs/guides/ 不存在或所需文件缺失 → 停止写 plan,列缺失文件,提示 init-project-guides 补齐;用户明确说不需要才可继续并记入风险/备注。
 
-### `04-test.md` — 测试与验收任务
+## index.md 必备内容
 
-按需创建。适用于单元测试、集成测试、端到端测试、迁移验证、回归验证、手工验收和风险覆盖。
+feature-id/负责人/日期/来源 spec 摘要(需求阶段由 `cgraphx features` 从产物自动派生,不手填状态) · 目标与范围 · 明确不包含 · 计划文件清单(哪些存在/不涉及) · 总任务清单(每个任务标对应 spec 条款 + 是否「独立提交」) · 全局依赖图(Mermaid 或文本;没有依赖就直说,不强行造依赖) · 推荐执行顺序 · 可并行批次(文件/模块/验证状态不重叠依据) · 必须严格执行的契约 · 实现手段决策(自主项:选项+推荐+理由;回跳项:业务拍板结论) · 适用规范(文件 + 章节标题) · **提交规范**(有「独立提交」任务时必备:从 `git-standards.md` 结晶的提交消息格式 + 提交前检查点,实施期据此提交,precommit 门禁仅兜底) · 允许局部工程适配的范围 · Plan 冲突上报规则 · 关键风险与防跑偏约束 · 待确认项。
 
-建议包含:
+## 子计划文件(按需,不建空文件)
 
-- 测试范围
-- 必测业务路径
-- 边界和异常场景
-- 权限/兼容性/迁移/性能相关验证
-- 推荐测试命令或验证方式
-- 手工验收步骤
-- 不做的测试和原因
-- 风险和待确认项
+| 文件 | 适用 | 写什么 |
+|---|---|---|
+| `-01-schema.md` | 新表/字段/迁移/回填 | 迁移目标与**执行顺序**(需求 sql/ 增量文件的序号依此定)、兼容与回滚、数据校验;建表/改表任务按项目 `docs/guides/data-standards.md`「Schema 变更约定」组织(增量文件 + 全量写透同步);不写不可确认的完整 DDL |
+| `-02-backend.md` | 业务逻辑/API/权限/任务/队列 | 规则落点、输入输出与错误处理、幂等/重试/并发 |
+| `-03-frontend.md` | 页面/表单/交互/可见性 | 用户流程、展示字段与校验、API 对接点、loading/empty/error 状态 |
 
 ## 任务写法
 
-任务应足够具体,让 agent 能执行,但不要替 agent 写代码。
-
-推荐格式:
-
 ```markdown
 ### T-<编号>: <任务名称>
 
 - 目标: ...
+- 对应 spec 条款: ...(implementer 据此读 spec 原文,不凭任务转述猜)
+- 强制引用: ...(implementer 开工前必读的 docs/guides 文件,按映射机械标注:schema 任务 → data-standards.md;接口任务 → interface-standards.md;动代码任务 → coding-standards.md;都不涉及 → 无)
 - 依赖: ...
 - 涉及范围: ...
 - 必须严格执行:
@@ -253,92 +110,38 @@ graph TD
   - ...
 - 验证方式:
   - ...
+- 独立提交: 是/否(是 → 完成后仓库可工作,给建议提交粒度 + commit message 主题;否 → 说明耦合原因,随哪个任务一起提交)
 - 风险/注意事项:
   - ...
 ```
 
-任务编号可以按文件域命名,例如 `S-1`、`B-1`、`F-1`、`T-1`。跨文件依赖必须在 `index.md` 中体现。
+编号可按文件域(`S-1`/`B-1`/`F-1`);跨文件依赖必须在 index 体现。任务足够具体让 agent 能执行,但不替 agent 写代码。
 
-## No Placeholders 规则
+## No Placeholders
 
-每个任务的"具体要求" / "完成条件" / "验证方式"必须写到 implementer 能直接执行的程度。以下表述是 **plan 失败**,严禁出现:
+"具体要求/完成条件/验证方式"必须写到 implementer 可直接执行。以下是 **plan 失败**:TBD/TODO/"implement later" · "add appropriate error handling"/"handle edge cases" · "similar to Task N" · 只说"做什么"不给可执行步骤/命令/验证条件 · 引用未在任何任务定义的符号 · "implementer 自行决定方案"(关键路线/口径/契约/权限不得留到实现期)。
 
-- **TBD / TODO / "implement later" / "fill in details"** —— 模糊推迟
-- **"add appropriate error handling" / "add validation" / "handle edge cases"** —— 没说具体怎么处理
-- **"write tests for the above"**(没给具体测试 case)—— 测试要内嵌具体 case 或矩阵
-- **"similar to Task N"** —— 必须重复代码,implementer 可能跳着读任务
-- **描述"做什么"但不给"怎么做"的步骤** —— 要给可执行命令 / 代码片段 / 验证条件
-- **引用未在任何任务里定义的类型 / 函数 / 方法** —— Task 之间引用必须闭环
-- **"implementer 自行决定方案" / "选择合适方案"** —— 关键技术路线、数据口径、接口契约、权限规则不能留给实现期
+例外:plan 期确实无法预知的(如第三方 API 实际返回结构),标【待确认】+ "implementer 跑 X 命令后锁定"——诚实标注,不是 placeholder。
 
-例外:plan 阶段确实无法预知的(如第三方 API 实际返回结构),标 **【待确认】** 并写"implementer 跑 X 命令后锁定字段名",这是诚实标注,不是 placeholder。
+## 产物位置与命名
 
-## 任务合并指导(降低 subagent-implement 流程开销)
-
-**默认合并**(同一 implementer 一次完成),减少 spec review 次数:
-
-- **T 测试任务和 B 实现任务默认合并**:同一 implementer 写代码 + 测试,一次完成。测试是验证实现的延伸,拆开会导致同一组改动审 4 次(implementer + spec 各 2 次)。
-- **同文件多章节改写默认合并**:同一文件的多个章节/段落改写由单 implementer 完成,避免上下文断层。例:重构一个 React component 的多个生命周期方法、修改一个 service 类的多个方法、改一个 SQL schema 文件的多个表段、改写一个 skill 文档的多个章节。
-- **schema 改动 + 对应 migration 测试默认合并**:schema.sql 改动 + `__tests__/.../schema-migration.test.ts` 一个任务。
-
-**例外允许拆开**(plan 里写理由):
-
-- 测试有独立复杂度(e2e / 大型集成测试 / 多 fixture 准备)
-- 任务过大(单 implementer 一次做会撑爆上下文)
-- 跨模块耦合需要前后任务实时反馈
-
-例:`### B-2: cgraphx docs dedup 命令 + 测试(合并:命令实现 ~146 行 + 测试矩阵 7 case 在同一文件域,无独立复杂度)`
-
-## 拆分原则
-
-- 按依赖和风险拆,不是按文档模板拆。
-- 先数据/契约,再后端,再前端,最后测试,但根据实际依赖调整。
-- **测试默认并入实现任务**(见上方"任务合并指导"),不独立成 T 任务。
-- 能独立验证的工作尽量拆成独立任务。
-- 可并行任务必须显式成批标注,并说明文件集合、公共契约、测试状态互不冲突;不确定时默认串行。
-- 高风险任务写清楚保护条件和回退思路。
-- 不确定内容标【待确认】,不要把猜测变成任务。
-- 不要让 agent 在 plan 之外扩大范围。
-- 不要把 spec 已锁定的业务规则、数据口径、接口契约、权限和异常行为重新开放给 implementer 选择。
-- 不要把简单需求拆成过多文件或过细任务。
-
-## 质量检查
-
-输出前确认:
-
-- `index.md` 能让 agent 理解全局目标、顺序和依赖。
-- 每个按需文件都有真实任务,没有空文件。
-- 每个任务都有完成条件和验证方式。
-- schema/backend/frontend/test 之间依赖清楚。
-- plan 没有重新定义 spec 中未确认的业务规则。
-- plan 没有要求实现非目标。
-- plan 没有混入实际代码改动。
-- plan 没有把关键方案或业务规则留给 implementation 阶段临场决定。
-- 每个任务都写清了严格执行边界和允许局部适配范围。
-- 待确认项不会被伪装成已确定任务。
-
-## 收尾方式
-
-输出或写入 plan + Self-Review + Plan Review 全部通过后,**主 agent 推荐执行模式**,让用户选:
-
-| 任务规模 | 推荐执行 skill | 理由 |
-|---|---|---|
-| 1-3 文件 / 单模块 / 主 agent 上下文够 | `/implementation`(主会话顺序做) | 派子 agent 反而费 token,顺序做更快 |
-| 跨多文件 / 多任务 / 需要隔离 | `/subagent-implement`(派子 agent) | 主 agent 上下文会被挤爆,隔离有价值 |
+- 路径:`docs/features/<feature-id>/plan/<文件前缀>-index.md`(+ 按需 `-01-schema` / `-02-backend` / `-03-frontend`)。无可写项目上下文 → 回复中直接输出同等结构正文。
+- **feature-id**:`YYYY-MM-DD-[业务ID-]<标题>`。业务ID 可选(字母数字 + 连字符);标题允许中/英/混合,**不得**中文转英文 slug;重名追加短后缀;同目录已有 PRD/spec 优先复用同一 feature-id。
+- **文件前缀**:有业务ID = `<业务ID>-<标题>`,无 = `<标题>`。
+- 敏感字符(`/ \ : * ? " < > |`)拒绝,要求用户重命名,不自动替换。
+- 与旧目录共存:始终新命名,不探测旧文件。
 
-**推荐话术**:
-> Plan 已就绪(Self-Review + Plan Review 通过)。基于任务规模,推荐 `/implementation`(简单)/ `/subagent-implement`(复杂)。
+## 收尾
 
-不要主动开始实现代码 —— 等用户决定。
+产物落盘后自动跑 `cgraphx features sync`(更新本人需求索引,本地幂等)。全部通过后推荐执行模式一句话:**1-3 文件/单模块 → `/implementation`;跨域多任务 → `/subagent-implement`。** 不自动开始实现,停下等用户。找需求目录:`cgraphx features list --mine`。
 
-## 跟其他 skill 的关系
+## 红线(绝对不能做)
 
-| 阶段 | skill |
-|---|---|
-| 澄清需求 | `clarify-requirements` |
-| 写 PRD | `write-prd` |
-| 写 spec | `write-spec` |
-| **写 plan + Self-Review + Plan Review**(本 skill) | `write-plan` |
-| 执行 plan(主会话顺序) | `implementation` |
-| 执行 plan(派子 agent) | `subagent-implement` |
-| 收尾 | `finish-feature` / commit / PR |
+1. ❌ **不编造**代码结构/接口/表/命令——没查到的一律【待确认】。
+2. ❌ **不把影响契约的决策留给实现期临场决定**(业务规则/口径/接口/权限 + 关键技术路线)。
+3. ❌ **规范不转交**——"按规范建表"是失败,契约级规范必须落成具体契约;plan 契约不得违反规范条目(违反须记例外);规范缺失 → 中断,提示 init-project-guides。
+4. ❌ **不把待确认伪装成已确定任务**,不把猜测变成任务。
+5. ❌ **不重新打开 spec 已锁定的契约**;手段越信封 → 回跳 spec,不在 plan 夹带。
+6. ❌ **不写实际代码改动**进 plan。
+7. ❌ **不擅自中文转英文 slug**——命名归用户。
+8. ❌ **不自动开始实现**——收尾停下,归用户。

package/dist/.claude-template/skills/write-plan/plan-document-reviewer-prompt.md

@@ -13,11 +13,12 @@
 implementer 会卡壳的场景:
 - 任务写到"add appropriate error handling"但没说具体怎么处理 → implementer 不知道做什么
 - 任务引用了"Task N 里定义的 Foo"但 Task N 没定义 Foo → 实现时编译错误
-- 任务说"测试通过"但没给测试命令或测试矩阵 → implementer 不知道写什么测试
+- 任务的完成条件只写"验证通过"却没给具体命令/步骤 → implementer 不知道怎么算完成
 - spec 里有要求但 plan 里没任务覆盖 → 实现会漏做
 - 类型签名跨任务不一致(Task 3 用 `clearLayers()`,Task 7 用 `clearFullLayers()`) → 实现时混乱
 - plan 把关键方案写成"implementer 自行决定" → 实现期各自发挥,后续质量不可控
 - plan 没写清"必须严格执行"和"允许局部适配" → implementer 不知道哪些能调整
+- plan 契约违反 docs/guides/ 规范(如表名不符 data-standards 命名约定) → implementer 照 plan 做就违规、照规范做就违 plan,两头堵(优先级规则 spec>plan>guides 会判 plan 赢,违规被锁成既成事实)
 
 **不阻塞**的场景(不要标):
 - 措辞偏好 / 风格建议
@@ -59,10 +60,10 @@ implementer 会卡壳的场景:
 - **依赖**:列出前置任务
 - **涉及范围**:具体文件路径(不是 "src/ 下某文件")
 - **具体要求**:可直接执行的步骤(命令 / 代码片段 / 接口签名),不是抽象描述
-- **完成条件**:可验证(测试命令 + 期望输出,不是"应该工作")
+- **完成条件**:可验证(具体命令 + 期望输出,不是"应该工作")
 - **验证方式**:具体命令,不是"跑测试"
 
-**任务合并合理性**:T 测试任务和 B 实现任务应默认合并(spec §"任务合并指导")。如果 plan 拆开了但没写理由 → 标 issue。
+**测试不进 plan**:plan 不应排测试任务 / 必测路径 / 测试命令——单元测试、接口测试是代码完成后的独立流程(`write-unit-test-spec`/`write-unit-test-code`、`write-api`/`run-api-test`,从 spec 派生)。若 plan 出现测试任务或给 implementer 派了"写测试" → 标 issue(测试归独立流程,plan 只要求既有测试不被弄红)。
 
 ### 4. 跨任务一致性 — 类型/命名/接口对齐
 
@@ -79,12 +80,23 @@ implementer 会卡壳的场景:
 - plan 是否明确 `PLAN_CONFLICT` 的上报条件?
 - 可并行任务是否真无冲突,且写明文件集合、公共契约、验证状态互不影响?
 
+### 6. 规范遵循 — 契约合规 + 标注齐全
+
+读 plan「适用规范」节和各任务「强制引用」标注点名的 docs/guides/ 文件,对照检查:
+
+- **契约级规范已结晶**:表命名/字段类型/接口形态/目录分层等契约级条目,plan 里是具体合规的表名/字段/签名,不是"按规范建表""按 interface-standards 定义"式转交(转交 = implementer 拿不到具体契约,阻塞)。
+- **plan 契约不违规**:plan 写定的表名/字段/签名/目录不违反对应规范条目;确有冲突的,plan 已记例外(spec 优先级高于规范,属合法例外)。
+- **强制引用标注齐全**:schema/接口/动码任务按映射标了 docs/guides 引用——执行期只认标注,漏标 = 规范在执行期丢失,阻塞。
+
+**边界**:只查契约级硬条目;不审手段决策(归 plan 按业务可观察性自主/回跳)、不重审 spec、不把规范里的风格偏好当阻塞。
+
 ## 你的工作流
 
-1. **Read plan 全文**(所有文件:index.md / 01-schema.md / 02-backend.md / 04-test.md / ...)
+1. **Read plan 全文**(所有文件:index.md / 01-schema.md / 02-backend.md / 03-frontend.md / ...)
 2. **Read spec 全文**(如果有,主 agent 在 prompt 里给了路径)
-3. **逐任务审查**(5 个维度:完整性 / Spec 对齐 / 任务可执行性 / 跨任务一致性 / 执行契约清晰度)
-4. **报告**(不修代码,只报告)
+3. **Read 规范**:plan「适用规范」节 + 各任务「强制引用」标注点名的 docs/guides/ 文件(文件缺失 → 记入报告,不静默跳过)
+4. **逐任务审查**(6 个维度:完整性 / Spec 对齐 / 任务可执行性 / 跨任务一致性 / 执行契约清晰度 / 规范遵循)
+5. **报告**(不修代码,只报告)
 
 ## 报告格式
 
@@ -110,6 +122,10 @@ Spec 覆盖度:
 执行契约清晰度:
   - ✅ / ❌ 必须执行项、允许局部适配、PLAN_CONFLICT 条件清楚
   - <会导致 implementer 临场发挥或 plan drift 的问题>
+
+规范遵循:
+  - ✅ / ❌ 契约级规范已结晶、plan 契约不违规、强制引用标注齐全
+  - <转交式写法 / 违规契约 / 漏标,具体到任务与规范条目>
 ```
 
 ## 红线
@@ -121,6 +137,7 @@ Spec 覆盖度:
 - ❌ 不审"做对了吗"(spec 阶段已审),只审"plan 写得够具体吗,implementer 能跑吗"
 - ❌ 不放过关键决策下放给 implementer 的写法
 - ❌ 不忽略真正的 placeholder("add appropriate error handling" 这种是阻塞,不是建议)
+- ❌ 不审手段决策(归 plan 按业务可观察性自主/回跳),不把规范风格偏好当阻塞(规范只卡契约级硬条目)
 
 ## 跟其他 reviewer 的边界
 
@@ -130,5 +147,6 @@ Spec 覆盖度:
 | 任务是否有 placeholder | 漏做 / 多做 / 误解 | 跨任务协同问题 |
 | 跨任务类型签名一致 | 边界条件覆盖 | 测试质量 |
 | Spec 覆盖度 | 单任务测试覆盖 | 测试维护性 |
+| 规范遵循(plan 契约合规 + 强制引用标注齐全) | 单任务实现落实规范条目 | 项目规范整体遵循 |
 
 **核心区别**:你在**执行前**审 plan 是否够好,让执行阶段可以省去 per-task spec review。spec-reviewer 是用户可选派的单任务复审(默认不派)。quality-reviewer 是执行结束的最终关卡。

package/dist/.claude-template/skills/write-prd/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: write-prd
+disable-model-invocation: true
 description: 用户要求基于已确认的需求、业务边界、业务规则、流程说明、客户材料或当前上下文编写 PRD/业务需求文档/需求文档时使用。用于产出给领导、客户、业务方审阅的业务需求文档,帮助能拍板的人确认业务决策、业务流程、范围、规则、权限、异常和验收口径是否符合预期。不写技术 spec、实现计划或代码;信息不足时只补问影响业务决策确认的关键问题,或将不确定内容标记为【待确认】。
 ---
 
@@ -62,10 +63,11 @@ description: 用户要求基于已确认的需求、业务边界、业务规则
 - 测试用例明细,除非作为客户可读验收口径
 
 ## 工作流程
-在写任何 prd 内容前,**必须**先与用户确认两件事:
+在写任何 prd 内容前,**必须**先与用户确认三件事:
 
 1. **业务 ID**:本次需求是否有对应的工单号 / 需求单号 / 项目代号?允许留空,但**留空也必须显式确认**(用户明确说"没有/留空"),不得默认跳过。
 2. **标题语言**:用中文 / 英文 / 中英混合?由用户选定,**禁止** Agent 因为"目录看起来更整齐"/"和现有 feature 命名一致"/"避免中文路径问题"等原因,擅自把中文需求转成英文 slug。
+3. **负责人**:默认取 `git config user.name`,向用户展示确认,写入头部 `> 负责人:`(文档归属,便于追溯;PRD 为发布后文档,不带状态字段)。
 
 - 用户主动给过完整 feature-id 或文件名 → 直接复用,跳过本步。
 - 用户用 `/write-prd` 触发但未给命名决策 → **第一步就问这两个问题**,问完再写。
@@ -105,7 +107,7 @@ description: 用户要求基于已确认的需求、业务边界、业务规则
 ```markdown
 # 业务需求文档: <需求名称>
 > feature-id: <feature-id>
-> 状态: 草稿
+> 负责人: <负责人>
 > 日期: YYYY-MM-DD
 
 ## 1. 背景与目标