cgraphx 2.0.1 → 2.0.3

package/dist/.claude-template/FLOW-MAP.md

@@ -26,14 +26,15 @@
         ▼               ▼                        ▼
   write-api        write-unit-test-spec     交付收尾:
   → run-api-test   → write-unit-test-code   沉淀提示 → knowledge-write
-  (接口测试)     (单元测试,代码完成后)     commit 门禁 → git-standards.md
+  (接口测试)     (单元测试,代码完成后)     交付讲解提示 → write-delivery-guide
+                                           commit 门禁 → git-standards.md
 
   ── 推荐发布后 · 按需(不在主链,不参与门禁); 原因: 发布前写 PRD:写的是预期,实现过程中一定会漂移,发布后 PRD 就过期了,给业务方看反而误导 ──────────────────
   write-prd(业务方/客户审阅,任意时刻可执行,推荐发布后)
   write-design-doc(设计文档,自测通过后)
   write-api-doc(接口文档,接口开发完毕后)
 
-guides:write-plan 读取并结晶 + 任务打「强制引用」标注(implementation / subagent-implement 执行标注,仅无 plan 时自识别)· write-api 独立读接口规范 · commit 门禁 → git-standards;缺失 → init-project-guides 先补(中断)
+guides:write-plan 读取并结晶 + 任务打「强制引用」标注(implementation / subagent-implement 执行标注,仅无 plan 时自识别)· write-api 独立读接口规范 · write-unit-test-code 独立读测试规范 · commit 门禁 → git-standards;缺失 → init-project-guides 先补(中断)
 ```
 
 ## 设计流程
@@ -50,7 +51,7 @@ guides:write-plan 读取并结晶 + 任务打「强制引用」标注(implementa
 - **前置**:spec 必有;subagent-implement 需 plan
 - **强制读**:规范由 plan 打「强制引用」标注(write-plan 按任务类型机械标:schema → data-standards.md;接口 → interface-standards.md;动码 → coding-standards.md);有 plan 时 implementation / subagent-implement 只读标注,无 plan 时 implementation 自行识别;**缺失 → 中断,先 `/init-project-guides` 补齐**
 - **小步提交**:plan 把可独立提交的任务(完成后仓库可工作)标「独立提交」并把 `git-standards.md` 提交规范结晶进 index「提交规范」节;implementation / subagent-implement 每完成一个标注任务并按规范自查后提交(原子历史,好 review / revert / bisect),precommit 门禁退化为兜底。未标注的任务不擅自提交,push 永远归用户。
-- **收尾**:沉淀提示(新增/变更实体、坑、隐式约束 → `/knowledge-write`);commit 门禁由 precommit-check hook 指向 `docs/guides/git-standards.md`,被拦 → 按 plan 已结晶的「提交前检查点」自查 staged diff(plan 无结晶时才 Read 原文件)
+- **收尾**:沉淀提示(新增/变更实体、坑、隐式约束 → `/knowledge-write`);交付讲解提示(有实质代码改动 → `/write-delivery-guide` 生成本次交付的故事线讲解,也可单独触发重生成);commit 门禁由 precommit-check hook 指向 `docs/guides/git-standards.md`,被拦 → 按 plan 已结晶的「提交前检查点」自查 staged diff(plan 无结晶时才 Read 原文件)
 
 ## 接口测试流程
 
@@ -63,6 +64,7 @@ guides:write-plan 读取并结晶 + 任务打「强制引用」标注(implementa
 
 - **链**:`/write-unit-test-spec`(零代码依赖,从 spec 派生场景)→ `/write-unit-test-code`(填实测试 + 跑 + 出报告;找不到测试规格直接退出要求先跑前者)
 - **前置**:spec + 实现完成(代码写完后独立流程,与接口测试同节奏)
+- **强制读**:write-unit-test-code 执行前读 `docs/guides/testing-standards.md`(缺失 → `/init-project-guides` 中断)
 - **产物**:feature 目录下测试规格与报告 + 项目测试目录的测试代码
 
 ## 知识库
@@ -87,9 +89,9 @@ guides:write-plan 读取并结晶 + 任务打「强制引用」标注(implementa
 | `data-standards.md` | schema 任务(含「Schema 变更约定」) |
 | `interface-standards.md` | 接口任务 |
 | `coding-standards.md` | 所有任务(契约部分) |
-| `testing-standards.md` | plan 不读;由测试流程(`write-unit-test-code` / `run-api-test`)自读 |
+| `testing-standards.md` | plan 不读;`write-unit-test-code` 执行前自读(内容全是单测向);接口测试规范由 `write-api` 读 `interface-standards.md` 送达 |
 | `git-standards.md` | 有「独立提交」任务时结晶进 index「提交规范」节(plan 级,一次)+ precommit-check 门禁兜底(deny → 按已结晶的检查点自查) |
-- **执行期送达**:任务按映射打「强制引用」标注(schema → data-standards.md;接口 → interface-standards.md;动码 → coding-standards.md);有 plan 时 implementation / subagent-implement 只读标注、不自行识别,无 plan 时 implementation 自行识别;write-api 不依赖 plan,执行前独立读 interface-standards.md(自有门禁)。**git-standards.md 例外**:不是每任务强制引用,而是 plan 级结晶进 index「提交规范」节,实施期提交时直接用、门禁仅兜底——消除多次小步提交的重复读取成本。**testing-standards.md 也不走 plan 标注**:测试不进 plan,由独立测试流程(`write-unit-test-code` / `run-api-test`)自读。
+- **执行期送达**:任务按映射打「强制引用」标注(schema → data-standards.md;接口 → interface-standards.md;动码 → coding-standards.md);有 plan 时 implementation / subagent-implement 只读标注、不自行识别,无 plan 时 implementation 自行识别;write-api 不依赖 plan,执行前独立读 interface-standards.md(自有门禁)。**git-standards.md 例外**:不是每任务强制引用,而是 plan 级结晶进 index「提交规范」节,实施期提交时直接用、门禁仅兜底——消除多次小步提交的重复读取成本。**testing-standards.md 也不走 plan 标注**:测试不进 plan,内容全是单测向(框架/目录命名/单测集成边界/Mock/fixture/覆盖),由 `write-unit-test-code` 执行前自读(缺失 → 提示 `/init-project-guides` 补齐);接口测试规范走 `write-api` 读 `interface-standards.md`,`run-api-test` 不另读规范。
 
 ## 事后文档(发布后 · 按需,不在开发主链)
 

package/dist/.claude-template/commands/end.md

@@ -16,7 +16,7 @@
 ---
 req_id: <簇名>
 簇: <目标标识/路径>
-status: 未收口
+status: 已收口
 mode: poor
 created: "<YYYY-MM-DD>"
 git_range: "<首SHA>..<末SHA>"

package/dist/.claude-template/skills/cgraphx-guide/SKILL.md

@@ -34,7 +34,7 @@ cgraphx 是本地优先的 AI agent 研发工具,把**markdown 知识库 + 数
 | **机器级 · 每机器一次** | `npm install -g cgraphx` |
 | **项目级 · 每项目一次** | `cgraphx install`(建 `.cgraphx/` 数据目录 + 部署 skills/commands 到 `.claude/` + 写 hooks/statusLine)、`/knowledge-init`(接手陌生项目时建业务知识库) |
 | **日常做需求 · 必经 2 步** | `/clarify-requirements` 澄清 → `/implementation`(简单)或 `/subagent-implement`(复杂)实现 |
-| **日常做需求 · 复杂按需** | `/write-prd`、`/write-spec`、`/write-plan`、`/knowledge-write`(沉淀到 `docs/knowledge/`) |
+| **日常做需求 · 复杂按需** | `/write-prd`、`/write-spec`、`/write-plan`、`/knowledge-write`(沉淀到 `docs/knowledge/`)、`/write-delivery-guide`(交付讲解,实现收尾提示触发) |
 | **工作回顾 · 按需** | `/developer-timeline`(日/周/月报)、`/write-design-doc`(发布后合成设计文档) |
 | **卸载 · 可选** | `cgraphx uninstall`(清项目 `.claude/` 内包自带的 skills/配置 + 删 `.cgraphx/`)、`npm uninstall -g cgraphx` |
 
@@ -53,6 +53,7 @@ cgraphx 是本地优先的 AI agent 研发工具,把**markdown 知识库 + 数
 | `/knowledge-init` | 接手陌生项目,派子 agent 自动探索、建业务知识库 |
 | `/knowledge-write` | 把业务决策 / 概念沉淀成 md 到 `docs/knowledge/` |
 | `/write-design-doc` | 发布后按需,从知识库合成面向人类阅读的设计文档(HTML 或 Markdown) |
+| `/write-delivery-guide` | 交付后生成/重生成「交付讲解」——业务故事线讲解,让人看懂 AI 写的代码(实现收尾自动提示) |
 | `/developer-timeline` | 生成日报 / 周报 / 月报 / 阶段总结 / 交付汇报 |
 
 ### agent 自动调用(用户不主动敲,agent 用来加载项目上下文)

package/dist/.claude-template/skills/cgraphx-guide/how-to-use.html

@@ -406,7 +406,7 @@ footer p { margin: 0; }
   <div class="pipeline">
     <div class="step">
       <h4>立规范 · <code>/init-project-guides</code></h4>
-      <p>生成 <code>docs/guides/</code> 五份规范(编码/接口/数据/测试/Git)。规范 = 项目对默认做法的<strong>有意偏离</strong>——「SQL 禁止 ORDER BY」「金额一律 decimal(12,2)」这类最容易偏离又没有工具兜底的约定。这些 guide 是后续任务的<strong>强制读点</strong>:编码/接口/数据三份会被 <code>/write-plan</code> 结晶成契约(测试规范不走 plan,由测试流程 <code>write-unit-test-code</code>/<code>run-api-test</code> 自读;Git 结晶进 plan 提交规范节)。</p>
+      <p>生成 <code>docs/guides/</code> 五份规范(编码/接口/数据/测试/Git)。规范 = 项目对默认做法的<strong>有意偏离</strong>——「SQL 禁止 ORDER BY」「金额一律 decimal(12,2)」这类最容易偏离又没有工具兜底的约定。这些 guide 是后续任务的<strong>强制读点</strong>:编码/接口/数据三份会被 <code>/write-plan</code> 结晶成契约(测试规范不走 plan,由 <code>write-unit-test-code</code> 执行前自读,内容全是单测向,接口测试规范由 <code>write-api</code> 读 <code>interface-standards.md</code> 送达;Git 结晶进 plan 提交规范节)。</p>
     </div>
     <div class="step">
       <h4>聊业务 · 和 Claude Code 聊项目</h4>
@@ -440,7 +440,7 @@ footer p { margin: 0; }
    ▼              ▼                   ▼
 /write-api    /write-unit-test-spec  交付收尾:
 → /run-api-test → /write-unit-test-code  /knowledge-write 沉淀
-  接口测试       单元测试              commit 门禁
+  接口测试       单元测试              /write-delivery-guide 讲解 + commit 门禁
 
 ── 发布后 · 按需(不在主链,不参与门禁)──────────────────
 /write-prd(业务方审阅)  /write-design-doc(设计文档)  /write-api-doc(接口文档)</div>
@@ -469,6 +469,7 @@ footer p { margin: 0; }
       <li><strong style="color:var(--color-primary);">核心</strong> <code>/write-spec</code> 写技术规格——唯一契约<em>(归档业务行为/规则/接口/数据/权限/异常/验收)</em></li>
       <li><span class="opt">可选</span> <code>/write-plan</code> 拆执行计划<em>(大需求/跨模块;手段选型在这一步结合代码定——纯工程手段 plan 自主,有业务可观察后果的回跳 spec 业务拍板)</em></li>
       <li><strong style="color:var(--color-primary);">必经</strong> <code>/implementation</code><em>(简单:1-3 文件/单模块)</em>或 <code>/subagent-implement</code><em>(复杂:≥3 任务跨域,派子 agent 隔离上下文)</em></li>
+      <li><span class="opt">收尾</span> 沉淀 → <code>/knowledge-write</code>;交付讲解 → <code>/write-delivery-guide</code> <em>(有实质代码改动时提示确认,故事线讲解、可重生成)</em></li>
     </ul>
     <div class="highlight">
       <p>日常默认 2 步:澄清 + 实现。spec 是唯一契约——「没有任何业务义务存在于 spec 之外」,变更时只改 spec 一处,下游重新派生。</p>
@@ -571,6 +572,7 @@ footer p { margin: 0; }
 │       ├── &lt;前缀&gt;-测试验证.jsonl      <span class="skill">/run-api-test</span>         <span class="opt">可选</span>  <span class="ann">自动产出</span>
 │       ├── &lt;前缀&gt;-单元测试-spec.md    <span class="skill">/write-unit-test-spec</span> <span class="opt">可选</span>  <span class="ann">开发完成后</span>
 │       ├── &lt;前缀&gt;-单元测试报告.md     <span class="skill">/write-unit-test-code</span> <span class="opt">可选</span>  <span class="ann">开发完成后</span>
+│       ├── &lt;前缀&gt;-交付讲解.md         <span class="skill">/write-delivery-guide</span> <span class="opt">可选</span>  <span class="ann">交付时</span>
 │       └── &lt;前缀&gt;-设计文档.md         <span class="skill">/write-design-doc</span>     <span class="post">发布后</span>  <span class="ann">按需</span>
 │
 ├── <b>knowledge/</b>   业务知识库(跨需求共享)

package/dist/.claude-template/skills/cgraphx-guide/how-to-use.md

@@ -45,7 +45,7 @@ npm uninstall -g cgraphx  # 卸载 CLI
 
 **1. 立规范 · `/init-project-guides`**
 
-生成 `docs/guides/` 五份规范(编码/接口/数据/测试/Git)。规范 = 项目对默认做法的**有意偏离**——「SQL 禁止 `ORDER BY`」「金额一律 `decimal(12,2)`」这类最容易偏离又没有工具兜底的约定。新项目立起步默认(注明「待演进」);已有项目从代码/git 历史挖既有约定固化成文。这些 guide 是后续任务的**强制读点**:编码/接口/数据三份会被 `/write-plan` 结晶成契约(测试规范不走 plan,由测试流程 `write-unit-test-code`/`run-api-test` 自读;Git 结晶进 plan 提交规范节)。
+生成 `docs/guides/` 五份规范(编码/接口/数据/测试/Git)。规范 = 项目对默认做法的**有意偏离**——「SQL 禁止 `ORDER BY`」「金额一律 `decimal(12,2)`」这类最容易偏离又没有工具兜底的约定。新项目立起步默认(注明「待演进」);已有项目从代码/git 历史挖既有约定固化成文。这些 guide 是后续任务的**强制读点**:编码/接口/数据三份会被 `/write-plan` 结晶成契约(测试规范不走 plan,由 `write-unit-test-code` 执行前自读,内容全是单测向,接口测试规范由 `write-api` 读 `interface-standards.md` 送达;Git 结晶进 plan 提交规范节)。
 
 **2. 聊业务 · 和 Claude Code 聊项目**
 
@@ -76,7 +76,7 @@ knowledge-recall(自动召回)
    ▼              ▼                   ▼
 /write-api    /write-unit-test-spec  交付收尾:
 → /run-api-test → /write-unit-test-code  /knowledge-write 沉淀
-  接口测试       单元测试              commit 门禁
+  接口测试       单元测试              /write-delivery-guide 讲解 + commit 门禁
 
 ── 发布后 · 按需(不在主链,不参与门禁)──────────────────
 /write-prd(业务方审阅)  /write-design-doc(设计文档)  /write-api-doc(接口文档)
@@ -99,6 +99,8 @@ knowledge-recall(自动召回)
 
 > 日常默认 2 步:澄清 + 实现。spec 是唯一契约——「没有任何业务义务存在于 spec 之外」,变更时只改 spec 一处,下游重新派生。
 
+> **交付收尾**:实现收尾会提示两件事——沉淀(`/knowledge-write`,沉淀业务决策/实体到 `docs/knowledge/`)和讲解(`/write-delivery-guide`,有实质代码改动时提示生成本次交付的故事线讲解,归档进需求目录、可重生成)。
+
 ---
 
 ### 接口测试流程
@@ -180,6 +182,7 @@ docs/
 │       ├── <前缀>-测试验证.jsonl      /run-api-test         可选  自动产出
 │       ├── <前缀>-单元测试-spec.md    /write-unit-test-spec 可选  开发完成后
 │       ├── <前缀>-单元测试报告.md     /write-unit-test-code 可选  开发完成后
+│       ├── <前缀>-交付讲解.md         /write-delivery-guide 可选  交付时
 │       └── <前缀>-设计文档.md         /write-design-doc     可选  发布后按需
 │
 ├── knowledge/   业务知识库(跨需求共享)

package/dist/.claude-template/skills/iboc-check/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: iboc-check
+disable-model-invocation: true
+description: 代码开发完成后的文档收口补账:核实 docs/features/ 下本人 git 提交过的需求,补主 spec 头部(feature-id/负责人/日期),再循环补全缺失的单元测试规格/单元测试报告/设计文档/收口档案。Use when 开发完成后补文档 / 老需求补头部 / 补单测产物 / 补设计文档 / 补收口档案 / 文档收口 / iboc-check.
+---
+
+# IBOC Check(文档收口补账)
+
+## 定位
+
+局方项目代码开发完成后的**事后文档补账**:老需求多在规范建立前做,spec 无头部、单测产物、设计文档与收口档案参差。两步走——先**纠正**(只给本人提交过的需求补头部),再**补全**(按清单循环补缺的文档)。
+
+**主 agent 是统帅不是先锋**:归属核实、补头部、清单、提交留在主 agent;补全重活(读 spec/实现代码、写测试、跑测试、写档案)逐需求派隔离上下文的 filler 子 agent——单需求 spec→测试代码→收口档案全链不占主上下文,多需求互不累积。
+
+## HARD-GATE
+
+- **只动头部块** —— 补缺失行 + 删多余字段(如状态);不碰正文、不改文件名、不新建 spec;无主 spec 的需求只提示「无法补充」,补 spec 是 `/write-spec` 的事
+- **只处理有 git 提交记录的需求** —— `docs/features/<目录>` 未提交的不处理,不猜归属
+- **归属清单必须用户确认** —— git 作者命中只是候选,是不是自己的由用户最终拍板
+- **不覆盖既有头部行** —— 头部行已存在则跳过该行,只补缺失的
+- **子 skill 守各自边界** —— filler 子 agent 只在自己需求内编排执行,不越权替子 skill 做判断
+- **一需求一子 agent,串行派任** —— git index 与测试运行是共享资源,不并行
+- **子 agent 不提交** —— 提交点必须和 sanity check 闸门同侧,主 agent 验证通过后才提交
+
+## 流程
+
+### 1. 归属核实
+
+- 取当前用户:`git config user.name`
+- 对 `docs/features/` 每个目录跑 `git log --format='%an' -- docs/features/<目录名>` 取作者集:
+  - 无提交记录 → 跳过,不处理
+  - 作者集含当前用户 → 进候选清单
+- **候选清单显示给用户确认**(目录名 + 日期 + 提交作者),用户剔除的移出清单
+
+### 2. 补头部(只加不改)
+
+对确认后的每个需求目录,找主 spec(`<前缀>-spec.md` 或 `spec.md`):
+
+- **无主 spec** → 记入「无法补充清单」,收尾时提示,不创建文件
+- **有主 spec** → 在文件头部(标题行后,对齐既有 `> ` 块)补缺失的行:
+
+```markdown
+> feature-id: 2026-08-03-审批引擎会签与重发能力
+> 负责人: liulongfei
+> 日期: 2026-08-03
+```
+
+三行取值:需求目录名 / `git config user.name` / 目录名日期前缀(**不是当前日期**), 同时删除其他多余字段,比如状态。
+
+### 3. 生成工作清单
+
+执行 `cgraphx features sync`,读 `.cgraphx/my-features.md`——头部补对后,这里应包含当前 git 用户的全部需求。为每个需求建一条待办,进入补全循环。
+
+### 4. 补全循环(逐需求派 filler 子 agent)
+
+逐需求核四样,缺什么补什么:
+
+| 产物 | 文件名 | 缺失时调用 |
+|---|---|---|
+| 单元测试规格 | `<前缀>-单元测试-spec.md` | `/write-unit-test-spec` |
+| 单元测试报告 | `<前缀>-单元测试报告.md` | `/write-unit-test-code`(依赖规格;规格刚补完接着跑) |
+| 设计文档 | `<前缀>-设计文档.md` | `/write-design-doc` |
+| 收口档案 | `收口档案.md` 或 `<前缀>-收口档案.md` | `/end` |
+
+每条待办是独立任务,补全重活不进主上下文——**派 filler 子 agent**:
+
+- 四样齐全 → 待办直接完成,不派
+- 有缺失 → Read `./filler-prompt.md` + 拼任务三件套(需求 / 缺失产物 / 上下文)→ Agent tool 派 `general-purpose`,在隔离上下文按依赖顺序补全(规格 → 报告 → 设计文档 → 档案)
+- **串行**:一需求一子 agent,跑完一个再派下一个(git index 与测试运行是共享资源,不并行)
+- **status 协议**:DONE → sanity check → 提交;DONE_WITH_CONCERNS → 辨因处理(correctness/scope 先解决,observation 记录);NEEDS_CONTEXT → 补 context 重派;BLOCKED → 记「受阻」进下一条(补账任务相互独立,一个卡住不拖其他)
+- **sanity check(主 agent,每需求)**:声称补出的产物真实存在 + git status 只含该需求的文件;不过 → 派修或记录,不提交
+
+**小步提交(每需求独立,主 agent 提交)**:sanity check 通过后,主 agent 按子 agent 报告的「改动文件」清单精确 stage,独立提交,再进下一条:
+
+- 提交范围:该需求 `docs/features/<目录>/` 下本次改动(补的头部 + 补出的规格/报告/设计文档/收口档案)+ write-unit-test-code 产出的测试文件;不混入其他需求、不夹带无关文件
+- commit message:项目有 `docs/guides/git-standards.md` 按其规范;没有则参考 `docs: <需求标题> 文档补账`
+- 被 precommit 门禁拦截 → 按提示自查 staged diff 后重试(`CGRAPHX_PRECOMMIT_REVIEWED=1`)
+- 该需求无任何改动(四样齐全且头部已全)→ 不产生提交
+
+### 5. 收尾汇报
+
+- 补了头部的需求数;「无法补充清单」(无主 spec 的,提示可走 `/write-spec` 补)
+- 每条待办的补全结果:补了什么 / 已齐全跳过 / 子 skill 报告的失败与待确认项 / 受阻跳过
+- 提交清单:每需求一笔(需求 + commit message);push 归用户
+- 下一步交用户,不自动继续
+
+## 派任模板
+
+Read 模板 + 拼任务三件套成 prompt,派 `general-purpose`:
+
+- `./filler-prompt.md` —— 每条有缺失产物的待办派一次;三件套 = ① 需求(feature-id + 目录 + 文件前缀)② 缺失产物清单 ③ 上下文(git 用户名、对该需求的已知说明)
+
+## 边界场景
+
+- **未提交的需求目录** → 不处理,不猜归属
+- **无主 spec** → 提示无法补充,不代写
+- **头部行部分存在** → 只补缺失行,不改已有值(负责人已有值也不覆盖)
+- **git 作者命中但用户否认** → 移出清单,不处理
+- **补了头部仍不在 my-features.md** → 提示用户检查头部行格式,不硬改
+- **filler 子 agent BLOCKED** → 记「受阻」进下一条,不卡死整队
+
+## 不做的事
+
+- 不新建 spec、不改正文、不改文件名(纠正只在头部块:补缺失行 + 删多余字段)
+- 不处理未提交的需求目录
+- 不自动确认归属清单
+- 不写业务实现代码(子 skill 也不写)
+- 不碰他人需求(归属过滤 + 用户确认双保险)
+- 不 push(只提交,push 归用户)
+
+## 和其他 skill 的关系
+
+- **implementation / subagent-implement**:上游,代码开发完成后才轮到本 skill
+- **write-unit-test-spec / write-unit-test-code / write-design-doc / end**:由 filler 子 agent 在隔离上下文内按需调用
+- **subagent-implement**:同款 controller/子 agent 模式(隔离派任 + 提交归 controller);这里更轻——无 plan/spec 审查,一需求一子 agent
+- **features sync**:头部补正是它的数据修正——负责人取自 spec 头部,头部缺失时「按人找需求」失效

package/dist/.claude-template/skills/iboc-check/filler-prompt.md

@@ -0,0 +1,75 @@
+# filler 子 agent prompt 模板
+
+> 主 agent 通过 Agent tool 调用本文件时,把这份完整内容作为 prompt 传给 `general-purpose` 子 agent,后接任务三件套:`\n\n---\n\n① 需求: <feature-id + 需求目录路径 + 文件前缀>`、`\n\n② 缺失产物: <单元测试规格 / 单元测试报告 / 设计文档 / 收口档案 中缺哪些>`、`\n\n③ 上下文: <git 用户名;对该需求的已知说明,如实现代码位置、备注>`。
+
+## 你的角色
+
+你是 filler 子 agent,在**隔离上下文**里补全**单个需求**缺失的文档产物。主 agent 是 controller,只拿到你的最终返回,**看不到你的中间过程**(读文件、跑测试、试错等)。
+
+补账背景:该需求代码已完成,但文档产物(单元测试规格/报告、设计文档、收口档案)在规范建立前没产——你的职责是补齐产物,不是重新开发。
+
+## 工作流
+
+### 1. 复核缺失项
+
+controller 已核过四样,缺失清单在 prompt 里。开工前再验一次文件是否真不存在(防误报);已存在的产物**不重产、不覆盖**。
+
+### 2. 按依赖顺序补全
+
+| 缺失产物 | 调用 |
+|---|---|
+| 单元测试规格 | `/write-unit-test-spec` |
+| 单元测试报告 | `/write-unit-test-code`(依赖规格;规格是本次刚补的,接着跑) |
+| 设计文档 | `/write-design-doc` |
+| 收口档案 | `/end` |
+
+逐个调用对应 skill,**完整遵循该 skill 自己的规则**——它怎么要求你怎么做:实现缺失的场景 `it.skip` 占位、测试失败如实报告、不写业务实现代码、不修实现 bug、不假装通过。skill 的边界就是你的边界,不越权替它判断。
+
+### 3. 范围约束
+
+- 只改本需求 `docs/features/<目录>/` 下的文件 + 补全产生的测试文件
+- 不碰其他需求的文件,不顺手重构无关代码
+
+### 4. 不提交
+
+- **不跑 `git add` / `git commit`** —— 你只改文件;提交由 controller 在你返回并 sanity check 通过后处理(提交点必须和验证闸门同侧,你返回时验证还没跑)
+
+### 5. 报告
+
+```
+Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+
+补了什么:
+  - <逐产物列:补出 / 已存在跳过>
+
+skill 执行结果:
+  - <测试通过/失败/跳过数;实现与 spec 偏差;skill 报的待确认项>
+  - 注意:「补全完成」≠「测试必须通过」——测试失败是实现问题,如实报告仍算 DONE
+
+改动的文件(controller 据此精确 stage 后提交,务必列全列准——漏列 = 提交丢文件,多列 = 提交进无关改动):
+  - <path1>:<一句话改动说明>
+  - <path2>:<...>
+
+Concerns / 未解决项(如果有):
+  - <...>
+```
+
+## Status 协议
+
+| Status | 何时用 |
+|---|---|
+| **DONE** | 缺失产物全部补出 + 各 skill 如实报告(含测试失败的如实报告) |
+| **DONE_WITH_CONCERNS** | 补完但有疑虑(如 spec 质量存疑、偏差较大)。**不要 silently 藏疑虑** |
+| **NEEDS_CONTEXT** | 缺必要信息(如找不到需求目录/主 spec)。**说清缺什么** |
+| **BLOCKED** | 无法完成(如 write-unit-test-spec 依赖的主 spec 不存在、测试基建探测不到且无法确认)。**说清卡在哪、试了什么** |
+
+**永远不要**在不确定时返回 DONE。
+
+## 红线
+
+- ❌ 不跑 `git add` / `git commit`
+- ❌ 不写业务实现代码、不修实现 bug(那是 skill 的边界,也是你的)
+- ❌ 不碰其他需求的文件
+- ❌ 不重产 / 覆盖已存在的产物
+- ❌ 不假装通过(断言不调假绿、收口档案不编内容)
+- ❌ 卡住不默默继续(返回 BLOCKED / NEEDS_CONTEXT)

package/dist/.claude-template/skills/implementation/SKILL.md

@@ -22,6 +22,7 @@ description: 用户要求根据已确认的 plan、spec、任务清单、实现
 5. **验证** —— 最相关的测试 / 类型检查 / lint / 构建 / 手工检查;前端或可视化变更按项目需要浏览器/截图验证;失败时判断是实现/环境/既有问题,继续修正可控部分。
 6. **汇报** —— 改了什么 / 验证了什么 / 风险与未完成项;有 plan 则说明 `PLAN_FOLLOWED` / `PLAN_ADAPTED` / 是否出现过 `PLAN_CONFLICT`。
 7. **沉淀提示** —— 确有内容才问(见下)。
+8. **交付讲解提示** —— 有实质代码改动才问(见下)。
 
 > **独立提交**:若 plan 把任务标了「独立提交:是」,每完成一个并通过验证后按 plan「提交规范」节(从 `git-standards.md` 结晶)提交——小步原子提交,规范已在 plan 上下文,precommit 门禁自查按 plan 检查点过后用 `CGRAPHX_PRECOMMIT_REVIEWED=1` 重试即可。未标注的任务不擅自提交,交用户决定;push 永远归用户。
 
@@ -45,6 +46,12 @@ description: 用户要求根据已确认的 plan、spec、任务清单、实现
 
 用户同意 → 走 `knowledge-write` 完整流程(查概念 → 写 → validate → 合并检查 → 询问扫描);拒绝或无内容 → 不提。
 
+## 交付讲解(实现结束后)
+
+本次实现有**实质代码改动**(新增接口/流程,或改动既有逻辑)→ 在汇报末尾问一句("这次交付有实质代码改动,是否用 write-delivery-guide 生成交付讲解——业务故事线讲解,可归档、可重生成?")。
+
+用户同意 → 走 `write-delivery-guide` 完整流程(收集事实 → 识别形态 → 读模板 → 生成 → 落盘);拒绝,或无实质改动(琐碎修复/纯探索/配置微调)→ 不提。
+
 ## 质量底线
 
 - 代码能解释为满足用户任务或 plan/spec;关键路径有验证;新增逻辑的测试覆盖由独立测试流程(代码完成后 `write-unit-test-spec` → `write-unit-test-code` / `write-api` → `run-api-test`)负责,实现期不写新测试,改动弄红的既有测试已同步修正;错误 / 空值 / 权限 / 兼容性风险被处理或说明。

package/dist/.claude-template/skills/init-project-guides/SKILL.md

@@ -15,7 +15,7 @@ description: 为项目初始化 docs/guides/ 规范文件模板。根据技术
 | `coding-standards.md` | 风格/命名/目录/错误处理 | 所有动码任务 |
 | `interface-standards.md` | API 路径/参数/返回值/兼容 | 接口任务 · write-api |
 | `data-standards.md` | 模型层 + DDL 层 + ORM 映射 + **schema 变更约定** | schema 任务 |
-| `testing-standards.md` | 框架/单测集成边界/mock/fixture/覆盖 | 测试任务 |
+| `testing-standards.md` | 框架/单测集成边界/mock/fixture/覆盖 | 单测任务 · write-unit-test-code |
 | `git-standards.md` | commit 消息规范 + 提交前检查点 | precommit-check 门禁 |
 
 两种模式:新项目起步立起步默认(文件内显式注明"待演进,有代码后重跑校准");已有项目从代码与 git 历史挖既有约定固化成文。**你只提发现和建议,决策归用户。**

package/dist/.claude-template/skills/run-api-test/references/db-verification.md

@@ -73,8 +73,8 @@ write-api S3 生成 .bru 时,在 tests 段写 DB 副作用预期注释(格式见
 ```
 tests {
     ...
-    # DB 预期:users 表新增一行,name=测试用户,email=test@example.com
-    # DB 预期:user_profile 表同步新增一行,user_id=本次返回的 id
+    // DB 预期:users 表新增一行,name=测试用户,email=test@example.com
+    // DB 预期:user_profile 表同步新增一行,user_id=本次返回的 id
 }
 ```
 

package/dist/.claude-template/skills/subagent-implement/SKILL.md

@@ -24,7 +24,7 @@ description: 复杂 plan 的子 agent 实现流程 — 主 agent 作为 controll
 3. 全部完成 → 派 quality-reviewer 整体审查(必派、仅一次、在自审+sanity check 之后)
    → 不通过:主 agent 微修或派 fix 子 agent → 重审
 
-4. 收尾:汇报 + 沉淀提示 + 未提交任务的 commit/PR 交用户决定(push 永远归用户)
+4. 收尾:汇报 + 沉淀提示 + 交付讲解提示 + 未提交任务的 commit/PR 交用户决定(push 永远归用户)
 ```
 
 ### 派任:四件套注入
@@ -88,7 +88,8 @@ Read 模板 + 任务/审查目标拼成 prompt,派 `general-purpose`:
 
 1. 汇报:完成清单 / 修复历史 / 剩余风险 / plan 忠实度(`PLAN_FOLLOWED` / `PLAN_ADAPTED` / 是否出现并解决过 `PLAN_CONFLICT`)
 2. 知识沉淀提示(确有内容才问):本次交付让某业务实体参与了新业务或出现新实体(实体 = 名词可指代、有属性和生命周期的业务对象)→ 新建/更新实体主条目(`business-entity`),流程条目在 concepts 声明该实体;或踩坑/隐式约束/取舍决策/跨文件关系值得复用。列候选清单问用户;确认 → 走 `knowledge-write` 完整流程。不要自己直接 Write .md
-3. 提示收尾:已按 plan「独立提交」标注提交的任务清单 + 未提交任务的 commit / PR 交用户决定;push 永远归用户。停下等用户
+3. 交付讲解提示(有实质代码改动才问):整体交付含新增接口/流程或改动既有逻辑 → 问"是否用 write-delivery-guide 生成本次整体交付的讲解?"确认 → 对**本次整体交付**(不是单个子任务)走 `write-delivery-guide` 完整流程;琐碎改动不提
+4. 提示收尾:已按 plan「独立提交」标注提交的任务清单 + 未提交任务的 commit / PR 交用户决定;push 永远归用户。停下等用户
 
 ## 红线(绝对不能做)
 

package/dist/.claude-template/skills/write-api/assets/template-request.bru

@@ -62,9 +62,9 @@ tests {
         expect(body.data).to.exist;
     });
 
-    # 写接口额外写 DB 副作用预期注释,供 S6 AI 核实参考:
-    # DB 预期:users 表新增一行,name=测试用户,email=test@example.com
-    # DB 预期:user_profile 表同步新增一行,user_id=本次返回的 id
+    // 写接口额外写 DB 副作用预期注释,供 /run-api-test R4 AI 核实参考:
+    // DB 预期:users 表新增一行,name=测试用户,email=test@example.com
+    // DB 预期:user_profile 表同步新增一行,user_id=本次返回的 id
 }
 
 docs {

package/dist/.claude-template/skills/write-api/references/bru-format.md

@@ -78,17 +78,17 @@ tests {
         expect(body.data).to.exist;
     });
 
-    # 写接口额外写 DB 副作用预期注释,供下游 /run-api-test 的 R4 AI 核实参考:
-    # DB 预期:users 表新增一行,name=测试用户,email=test@example.com
-    # DB 鄄期:user_profile 表同步新增一行,user_id=本次返回的 id
+    // 写接口额外写 DB 副作用预期注释,供下游 /run-api-test 的 R4 AI 核实参考:
+    // DB 预期:users 表新增一行,name=测试用户,email=test@example.com
+    // DB 预期:user_profile 表同步新增一行,user_id=本次返回的 id
 }
 ```
 
 ### 断言内容要求
 
-- **HTTP 状态码断言** — 每个场景都要(正常场景通常 200/201,异常场景可能 400/404/409)
-- **响应体关键字段断言** — 从 spec 接口语义或代码返回结构提取,用 `JSON.parse(res.getBody())` 取 body
-- **写接口额外写 DB 副作用预期注释** — 用 `#` 注释,写预期会写/改/删哪些表哪些字段,供 `/run-api-test` R4 AI 核实参考
+- **HTTP 状态码断言** — 每个场景都要;正常场景通常 200/201;**异常场景不得默认 200**——状态码从 interface-standards.md 错误码约定取(可能是 400/404/409,也可能是项目特有业务码,如虎翼业务异常返回 HTTP 510),约定没写标【待确认】交用户,不拍脑袋
+- **响应体关键字段断言** — 从 spec 接口语义或代码返回结构提取,用 `JSON.parse(res.getBody())` 取 body;字段名与嵌套层级以代码实际返回结构为准(含 `opp_key` 这类 snake_case、封装层是否还有一层嵌套),不凭驼峰习惯猜
+- **写接口额外写 DB 副作用预期注释** — 用 `//` 注释,写预期会写/改/删哪些表哪些字段,供 `/run-api-test` R4 AI 核实参考
 
 ## 入参写真实值,不变量化
 

package/dist/.claude-template/skills/write-delivery-guide/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: write-delivery-guide
+disable-model-invocation: true
+description: 生成「交付讲解」—— AI 交付代码后人类能读懂的故事线讲解文档。触发来源:交付收尾提示后确认(implementation / subagent-implement),或用户要求生成/重生成/补交付讲解(讲一下这次交付了什么 / 重新生成需求 X 的讲解)。定位是派生视图:从 spec + diff + 代码现实生成,过期整体重生成,不人工维护一致性。按业务场景故事线组织(识别形态 → 读场景模板 → 生成 → 结尾导读入口)。不是契约,不重定义 spec。
+---
+
+# 生成交付讲解 (Write Delivery Guide)
+
+## 定位
+
+- **让交付的代码对人可读**:读者是没写这批代码的技术接收者;目标是看懂代码(「像自己写过一样」),不是验收汇报。
+- **派生视图,不是维护对象**:从 spec + diff + 代码现实生成;过期 → 重跑本 skill 整体重生成;永不人工维护与代码的一致性。
+- **不是契约**:不重定义 spec 已锁定的契约;spec 与代码现实不符 → 标【待确认】并上报,不自行解释。
+- **边界**:发布后设计文档合成 → `write-design-doc`;业务知识沉淀 → `knowledge-write`;工作量汇报 → `write-workload`。
+
+## 依赖
+
+- 存在代码改动(diff);无代码改动 → 不生成。
+- spec / 知识库非必需但影响质量:无 spec → 从任务上下文 + diff 生成,文档头部标注「spec: 缺省」;知识库为空 → 跳过锚点法,不编造锚点。
+
+## 流程
+
+1. **确定范围**:feature-id(用户显式指定 > 从 cwd 向上探测最近的 `docs/features/<feature-id>/` > 都失败则询问);输出默认 `docs/features/<feature-id>/<前缀>-交付讲解.md`,用户可覆盖;无 feature 目录(临时任务)→ 不建目录,讲解直接在回复中输出。
+2. **收集事实**:
+   - 读 spec(场景/角色/状态/接口章节)→ 形态识别与故事线素材;
+   - 读 diff → 本次交付的新增/修改清单;
+   - 读改动文件的相关代码 → 每个入口的实际逻辑、调用关系;
+   - `cgraphx docs find` 召回相关知识库条目(实体/流程)→ 锚点素材。
+3. **识别用法形态**:见「形态 → 故事线主轴」;一次交付含多种形态 → 多条故事线各成一节;**拿不准 → 问用户,不猜**。
+4. **读场景模板**:本 skill 目录存在 `template-<形态>.md` → 按模板生成(含其参考案例与常见讲错);不存在 → 按通用骨架生成 + 沉淀提示(见下)。
+5. **生成**:按通用骨架 + 模板维度,执行「讲法底线」。
+6. **自检**:每个结论有代码指针;本次交付的每个组件都挂进了故事线(无遗漏);四问齐全;mermaid 语法可渲染;未重定义 spec 契约;矛盾处已标【待确认】。
+7. **落盘 + 导读入口**:写入路径;文档结尾给导读入口 + 示例问题(通用骨架第 7 节)。
+
+## 通用骨架(七节,按此顺序)
+
+| 节 | 内容 |
+|---|---|
+| 1. 30 秒看懂 | 一两句:解决了什么业务问题、在现有系统的哪个位置 |
+| 2. 全景 | 本次交付参与的业务流程图(mermaid),**高亮本次新增/修改的部分** |
+| 3. 场景故事线 | 按用法形态分节(可多条);主轴见下节 |
+| 4. 组件挂接 | 每个接口/入口/模块按四问展开 |
+| 5. 改动定位 | 仅当改动已有流程:改在哪个部位(引全景图标出)、前后对比、波及范围(哪些调用方/场景的行为受影响) |
+| 6. 已验证与已知边界 | 验证跑通的路径 + 已知限制(业务确认砍掉的、暂不支持的) |
+| 7. 导读入口 | 提示任意章节可追问,并给出针对本次交付的示例问题 |
+
+## 形态 → 故事线主轴
+
+| 用法形态 | 故事线主轴 | 图表类型 |
+|---|---|---|
+| 多角色流程(审批/退款类) | 角色 × 环节:谁在第几步干什么 | sequenceDiagram |
+| 单入口管道(导入/同步任务) | 处理步骤:输入如何一步步变成输出 | flowchart |
+| 管理 CRUD(配置管理类) | 对象生命周期:状态 + 每个操作推动到哪 | stateDiagram |
+| 后台作业(定时任务/事件消费) | 触发时机:何时触发 / 干了什么 / 结果落哪 | flowchart |
+| 改动型 | 原流程中的部位:原故事线第 N 步,前后对比 | stateDiagram / flowchart |
+
+形态判断取材于 spec 的场景/角色/状态章节 + 代码接口形状。模板文件:`template-multi-role-flow.md`(多角色流程)、`template-change-type.md`(改动型);其余形态暂无模板,走通用骨架。
+
+## 组件四问(每个组件必答)
+
+1. **何时用**:谁触发、前置条件(哪个环节之后才轮到它);
+2. **做什么**:核心逻辑,业务语言,3 句以内;
+3. **用了之后使什么成为可能**:解锁的下一环节 + 副作用(写什么表、发什么事件、调谁);
+4. **挂点**:前置环节 → 本组件 → 后续环节。
+
+协议细节(参数/返回值字段)降级为附录或指向 spec,不占故事线主线。
+
+## 讲法底线(所有内容适用)
+
+- **锚点法**:新东西先挂在读者已知的事物上(知识库实体/既有流程/相似既有模式);知识库为空 → 用通用讲法,不编造锚点;
+- **目的优先**:每个部分先答「你为解决什么问题而存在」,再讲结构;
+- **请求走查**:至少一次带真实数据的完整请求/任务走查(故事式,非清单式);
+- **代码指针**:每个结论指向代码(文件:行号 或 文件:符号);无法回代码验证的结论不写进讲解;
+- **图优先 mermaid**:对齐 write-design-doc 的图表规范(flowchart / sequenceDiagram / stateDiagram 等)。
+
+## 模板未覆盖形态的兜底 + 沉淀提示
+
+无对应模板 → 按通用骨架生成;生成后问一句:「本次交付属于 <形态> 形态,尚无场景模板。若这份讲解有效,是否沉淀为新模板(写入 `template-<形态>.md`)?」用户同意 → 按统一六项结构写入(判断特征 / 故事线主轴 / 讲解维度要求 / 图表类型 / 完整参考案例 / 常见讲错),参考案例用本次交付;拒绝 → 不提。
+
+## 重生成与回写
+
+- 对同一 feature 重跑 = 整体重生成,替换旧文档;
+- 旧文档含导读回写的内容 → 重生成前合并保留,不得静默覆盖。
+
+## 模板进化
+
+用户发现讲解不满足理解 → 导读先解决当次问题;再判断是个例(这次没讲好)还是模板缺陷(这类形态的讲法整体不对);模板缺陷 → 提示更新对应模板(经用户确认后写入)。
+
+## 红线(绝对不能做)
+
+1. ❌ **不编造** —— 无法回代码/spec/diff 验证的结论不写进讲解。
+2. ❌ **不重定义 spec 契约** —— spec 与代码现实不符 → 标【待确认】并上报。
+3. ❌ **不人工维护与代码的一致性** —— 派生视图,过期重生成。
+4. ❌ **不猜形态** —— 拿不准就问用户。
+5. ❌ **不编造锚点** —— 知识库为空用通用讲法。
+6. ❌ **不静默丢失回写内容** —— 重生成时合并保留。
+7. ❌ **不擅自创建 feature 目录** —— 临时任务直接在回复中输出。