cgraphx 1.1.0

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

@@ -0,0 +1,136 @@
+---
+name: implementation
+description: 用户要求根据已确认的 plan、spec、任务清单、实现计划、bug 修复方案或当前上下文实际修改代码、实现功能、修复缺陷、补测试或完成开发任务时使用。用于读取必要上下文、按计划和项目模式实施代码变更、运行合理验证并汇报结果。保持实现范围受控,但不要用僵硬流程限制工程判断。
+---
+
+# Implementation
+
+## 定位
+
+根据当前上下文、已确认的 plan/spec 或用户明确任务,实际修改代码并完成验证。
+
+这个 skill 是执行阶段。目标是把计划落成可工作的代码,同时保持范围、质量和验证清楚。若存在已确认 plan,实现阶段应忠实执行 plan,不重新设计业务规则、数据口径、接口契约、权限或核心方案。
+
+## 基本原则
+
+- 先读必要上下文,再改代码。
+- 优先遵守已有 plan/spec;如果它们与代码现实冲突,说明冲突并上报,不要自行改写已锁定方案。
+- 优先沿用项目现有架构、命名、风格、工具和测试方式。
+- 控制范围,不要顺手重构无关代码。
+- 不编造业务规则。规则不清且会影响实现时先问;不阻塞的小细节可做保守假设并说明。
+- 保护用户已有改动,不要回滚自己没做的变化。
+- 实现后运行合理验证;无法验证时说明原因和剩余风险。
+
+## 默认工作方式
+
+按任务需要灵活执行,不要机械套流程:
+
+1. **理解输入**
+    - 读取用户请求、相关 plan/spec/PRD、任务清单或错误信息。
+    - 找到要实现的具体范围、非目标和验收口径。
+
+2. **读取代码上下文**
+    - 查看相关文件、调用链、测试、配置和项目约定。
+    - 只读取足以安全实现的上下文。
+
+3. **实现变更**
+    - 小步修改,保持代码风格一致。
+    - 复用已有工具、模型、组件、服务和测试模式。
+    - 需要新增抽象时,确保它解决真实重复或复杂度。
+
+4. **验证**
+    - 运行最相关的测试、类型检查、lint、构建或手工检查。
+    - 前端或可视化变更按项目需要做浏览器/截图验证。
+    - 失败时判断是实现问题、环境问题还是既有问题,并继续修正可控问题。
+
+5. **汇报**
+    - 简要说明改了什么、验证了什么、还有什么风险或未完成项。
+
+## 处理 plan/spec
+
+如果存在 `docs/features/<feature-id>/plan/` 或类似计划目录:
+
+- 优先读取 `index.md`。
+- 按需要读取 `01-schema.md`、`02-backend.md`、`03-frontend.md`、`04-test.md`。
+- 先批判性评审计划:检查计划是否和当前代码结构一致、任务依赖是否合理、是否缺少关键上下文、是否包含未确认业务规则、是否存在高风险或破坏性操作、验证方式是否可执行。
+- 如果发现关键问题或 plan 与代码现实严重冲突,先向用户说明并请求确认,不要自行换方案。
+- 如果只是代码现实导致的小调整,且不改变业务规则、数据模型、接口契约、权限、安全、迁移策略或验收口径,说明调整原因后继续。
+- 按依赖顺序执行,但不要盲目执行错误计划。
+- 完成后可在回复中说明完成了哪些任务编号。
+
+如果没有 plan,但用户任务明确,直接根据当前上下文实现。不要强迫用户先补文档。
+
+## 动态编码计划
+
+默认从 `docs/features/<feature-id>/plan/` 读取编码计划。
+
+如果 plan 目录存在:
+
+- 先读 `index.md`。
+- 按需读 `01-schema.md`、`02-backend.md`、`03-frontend.md`、`04-test.md`。
+- 以 plan 中的任务、依赖图、执行顺序和约束为主。
+- 再结合真实代码上下文,细化当前编码顺序。
+
+动态编码计划用于决定当前实现顺序,例如:
+
+- schema/migration -> VO/DTO/type -> mapper/repository -> service/domain -> controller/API/job -> frontend/client -> test
+- 或根据项目实际依赖调整
+
+不要重写 plan 文档。不要脱离 plan 扩大范围。如果发现 plan 与代码现实冲突,区分:
+
+- `PLAN_ADAPTED`:文件名、helper、局部代码组织、测试 fixture 等小偏差适配,不改变契约,可继续并报告。
+- `PLAN_CONFLICT`:需要改变业务规则、数据口径、schema、API、权限、安全、迁移、验收或任务范围,必须暂停并请求确认。
+
+## 按任务执行
+
+当 plan 已经拆成任务时,按任务推进:
+
+- 明确当前任务目标和依赖。
+- 根据真实代码上下文细化编码顺序。
+- 实施最小必要改动。
+- 运行相关验证。
+- 记录完成情况、偏差、plan 忠实度和未解决风险。
+
+不要为了完成任务清单而跳过验证。不要把待确认项当成已确定任务。
+
+## 变更边界
+
+可以做:
+
+- 修改业务逻辑、接口、页面、组件、模型、配置或测试
+- 新增必要文件、测试、迁移或类型定义
+- 调整与任务直接相关的代码结构
+- 修复实现过程中暴露出的直接相关问题
+- 局部工程适配:复用现有 helper、调整内部函数拆分、补充必要测试 fixture、适配真实文件路径
+
+避免做:
+
+- 无关重构
+- 未要求的产品行为扩展
+- 未确认的数据破坏性操作
+- 大范围格式化无关文件
+- 私自改变公共契约、权限规则或业务口径
+- 私自改变 plan/spec 已锁定的数据模型、接口形态、统计口径、状态流转、安全策略、迁移策略或验收标准
+
+## 质量底线
+
+完成前尽量确保:
+
+- 代码能解释为满足用户任务或 plan/spec。
+- 关键路径有验证。
+- 新增逻辑有适当测试或说明为什么无法测试。
+- 错误、空值、权限、兼容性等明显风险被处理或说明。
+- 如果存在 plan,最终能说明 `PLAN_FOLLOWED` / `PLAN_ADAPTED` / `PLAN_CONFLICT` 的状态。
+- 最终回复清楚列出变更和验证结果。
+
+## 遇到阻塞
+
+遇到以下情况时暂停并向用户说明:
+
+- 业务规则互相矛盾
+- plan/spec 与代码现实严重冲突
+- 发现更优方案但会偏离 plan/spec 已锁定契约
+- 必须执行高风险或破坏性操作
+- 需要用户提供外部凭据、环境或不可推断决策
+
+除此之外,尽量自主推进到可验证结果。

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

@@ -0,0 +1,225 @@
+---
+name: subagent-implement
+description: 复杂 plan 的子 agent 实现流程 — 主 agent 作为 controller,按依赖批次派 implementer 子 agent 实现 + 按风险做 spec 审查,所有任务完成后派 final quality reviewer 整体审查。Use when 执行计划/跑计划/按 plan 实现/派子 agent 实现/复杂实现/多任务实现/系统化实现/subagent 实现。
+---
+
+# Subagent-Implement
+
+## 定位
+
+把已确认的 plan(`docs/features/<feature-id>/plan/`)拆成多个独立任务,**主 agent 作为 controller**,按依赖批次派 implementer 子 agent 实现。主 agent 默认负责协调、验证和收口;仅对 reviewer 指出的低风险微修可直接修改。所有任务完成后派 final quality reviewer 整体审查。
+
+**与 implementation 的差别**:
+- `implementation` —— 主 agent 在主会话顺序执行,自己改代码。适合**单点改动 / 小范围 / 1-3 文件**
+- `subagent-implement`(本 skill)—— 主 agent 以协调为主,派子 agent 在隔离上下文实现。适合**复杂 plan / 多任务 / 跨多文件**
+
+## 何时用(决策树)
+
+```
+有 plan(docs/features/<feature-id>/plan/)或明确任务清单?
+├── 否 → 不要用本 skill,走 implementation 或先 write-plan
+└── 是 → 任务数 ≥ 3 且跨多文件?
+    ├── 否(简单任务) → 走 implementation,主会话直接做
+    └── 是(复杂 plan) → 走本 skill
+        └── 任务能拆成相对独立的子任务?
+            ├── 是 → 本 skill 标准模式(按依赖批次执行;默认串行,显式无冲突可并行)
+            └── 否(任务高度耦合,后任务依赖前任务实时反馈) → 走 implementation
+```
+
+**典型适用场景**:
+- feature plan 拆了 5+ 个任务,跨 schema / backend / frontend / test 多个域
+- 多个独立工具/命令的实现
+- 同时改 N 个 skill 文件(参考 `2026-06-27-exploration-subagent-dispatch` plan)
+- 多语言/多框架并行支持
+
+**不适用**:
+- 单文件 bug 修复 → `implementation`
+- 重构单个模块 → `implementation`
+- 任务间强耦合(后任务必须基于前任务实时调整)→ `implementation`
+
+## 核心流程
+
+```
+1. 读 plan 一次 → 提取所有任务全文 + context → TodoWrite 跟踪
+   (前置:plan 已过 write-plan 的 Plan Review 阶段,完整性 / spec 对齐已审)
+
+2. 按依赖批次执行任务:
+   a. 默认一次派 1 个 implementer;只有任务在 plan 中被标为"可并行"且通过无冲突检查时,才同批派多个 implementer
+   b. 派 implementer 子 agent(把任务全文 + context 拼进 prompt;可附 index.md 摘要,不让子 agent 读全 plan)
+   c. 处理 implementer status(见下文)
+   d. **主 agent sanity check**:
+      - 看 implementer 报告合理性(改了哪些文件 / 测试是否真绿 / 自审发现是否已修)
+      - 不通过 → 派 implementer 修 / 补 context / 主 agent 做低风险微修 / 上报
+   e. 通过 → 标记任务完成 → 下个任务或下一批
+
+3. 所有任务完成后:
+   - 派 final quality-reviewer 子 agent(整体审查:架构、命名一致性、文件组织、跨任务问题)
+   - 不通过 → 按问题大小选择主 agent 低风险微修或派 fix 子 agent 修 → quality-reviewer 重审
+   - 通过 → 收尾(提示用户走 commit / PR / finish-feature)
+
+4. 收尾汇报:
+   - 完成的任务清单
+   - 各阶段审查发现的问题 + 修复情况
+   - 剩余风险 / 未覆盖项
+```
+
+**审查粒度**(关键设计):
+- **spec/plan 忠实度审查按风险派** —— plan 阶段已经审可执行性;执行阶段对高风险、探索性强、跨契约任务再派 spec-reviewer,重点查漏做 / 多做 / 误解 / plan drift。
+- **quality 审查仅最终一次** —— 代码质量问题(命名、架构、文件组织、跨任务协同)跨任务才能看出,集中审更经济。
+- **implementer 自审** —— 子 agent 完成后自己先 review,主 agent sanity check 看报告和 plan 忠实度即可。
+
+**为什么这样设计**:plan 阶段的 plan-document-reviewer 已经把"plan 是否完整可执行"的问题解决了。执行阶段按风险派 spec-reviewer,避免每个小任务都重复审查,同时保留高风险任务和 plan 偏离风险的独立验证。
+
+## 任务调度策略
+
+**默认串行**:没有明确并行标记时,一次只派 1 个 implementer,避免上下文偏差和代码冲突。
+
+**允许显式无冲突并行**:只有同时满足以下条件,主 agent 才能同批派多个 implementer:
+
+- plan 的 `index.md` 把这些任务列为可并行,且任务之间没有依赖关系。
+- 涉及文件集合不重叠;如果改同一目录,改动对象也必须清楚分离。
+- 不共享 schema、公共类型、公共 API、全局配置、测试 fixture、锁文件或生成物。
+- 验证命令不会互相污染状态(例如共享数据库、快照、临时文件)。
+- 每个并行任务的 prompt 都写明"本批并行任务列表"和"禁止触碰其他任务文件"。
+
+**并行收口**:
+
+- 任一并行任务返回 `BLOCKED` / `NEEDS_CONTEXT` / `DONE_WITH_CONCERNS(correctness/scope)` 时,暂停同批后续合并判断,先解决该任务。
+- 同批任务完成后,主 agent 必须看整体 `git diff`,确认没有文件冲突、重复实现或概念命名分叉,再进入下一批。
+- 如果发现同批任务实际发生文件重叠或公共契约冲突,停止并行模式,改为串行修复。
+
+## 何时该派 spec-reviewer(可选)
+
+**默认不派**:低风险任务的 plan 完整性已经在 plan-document-reviewer 阶段审过,implementer 报告 + 主 agent sanity check + 跑测试通常足以判断完成。
+
+**例外允许派**(主 agent 判断或用户要求):
+
+| 场景 | 为什么派 |
+|---|---|
+| **任务探索性强** —— plan 阶段无法预知实际行为(如外部 API 输出字段、第三方库行为) | 实际实现可能跟 plan 假设不一致,需要独立验证 |
+| **跨多文件耦合** —— 一个改动影响多处(如改公共类型签名) | 影响范围大,扩散代价高 |
+| **plan-document-reviewer 标了"高风险"任务** | 主 agent 在 plan 阶段已知风险,执行时复查 |
+| **用户主动要求** | 用户判断需要 |
+| **plan 没经过 Plan Review**(write-plan 跳过了) | 没有 plan 阶段审查兜底,建议派(非强制,主 agent 判断) |
+
+**派的方法**:用同目录下 `spec-reviewer-prompt.md` 模板,把任务全文 + implementer 报告 + 工作目录拼成 prompt,派 `general-purpose` 子 agent。
+
+## 主 agent 是 controller(默认不是 implementer)
+
+主 agent 在本 skill 中默认只做协调,但允许处理低风险微修:
+
+- ✅ 读 plan、提取任务全文、构造子 agent prompt
+- ✅ 处理子 agent status、回答子 agent 提问
+- ✅ 跟踪任务进度(TodoWrite)
+- ✅ sanity check 审查结论、决定是否进入下个任务
+- ✅ 对 reviewer 指出的低风险微修可直接 Edit/Write
+- ❌ 不绕过子 agent 自己实现
+
+**为什么**:子 agent 在隔离上下文实现,主 agent 上下文保持干净,用于协调多任务;但对拼写、导入、格式、明显小逻辑漏改这类微修,再派 fix agent 会增加延迟和 token。
+
+### 主 agent 可直接微修的条件
+
+必须同时满足:
+
+- reviewer 或测试报告已经把问题定位到具体文件 / 行 / 小范围。
+- 修复不改变业务规则、公共契约、schema、权限、安全逻辑或任务范围。
+- 预计改动不超过 1-2 个文件,且不需要重新理解大段上下文。
+- 修复后能立刻运行相关验证。
+
+不满足以上条件时,仍派 implementer/fix 子 agent。
+
+## 子 agent status 协议
+
+implementer 子 agent 必须返回以下 status 之一:
+
+| Status | 含义 | 主 agent 处理 |
+|---|---|---|
+| **DONE** | 实现完成,自审通过,无未经批准偏离 | 主 agent sanity check(跑测试 + 看报告)→ 通过则进入下个任务 |
+| **DONE_WITH_CONCERNS** | 实现完成但有疑虑 | 读 concerns:关于 correctness/scope/plan drift → 先解决;关于 observation(如"文件有点大")→ 记录,进入 sanity check |
+| **NEEDS_CONTEXT** | 缺少必要信息 | 补 context,重新派 implementer |
+| **PLAN_CONFLICT** | plan 与代码现实或更优方案冲突,继续做会改变已锁定契约 | 主 agent 暂停该任务,回到用户/plan/spec 确认;不能让 implementer 自行改方案 |
+| **BLOCKED** | 无法完成 | 评估:context 不够 → 补 context 重派;需更强推理 → 换更强 model;任务太大 → 拆分;plan 错了 → 上报用户 |
+
+**红线**:**不要**忽略 BLOCKED 直接重试同 model;**不要**忽略 PLAN_CONFLICT 让子 agent 自行换方案;**不要**让卡住的子 agent"再试一次";**不要**绕过子 agent 自己实现。
+
+## 模板路径
+
+主 agent 派子 agent 时,Read 对应模板,把模板内容 + 当前任务 / 审查目标 拼成 prompt:
+
+- `./implementer-prompt.md` — 实现单个任务的子 agent prompt(**每任务必派**;并行批次中每个任务各派一个)
+- `./spec-reviewer-prompt.md` — 单任务 spec 审查的子 agent prompt(**执行结束可选派一次,默认不派**,见"何时该派 spec-reviewer")
+- `./quality-reviewer-prompt.md` — 最终整体质量审查的子 agent prompt(**执行结束必派一次**)
+
+派的方法(参考三个探索 skill 的派子 agent 机制):
+```
+Agent({
+  subagent_type: "general-purpose",
+  prompt: <模板全文> + "\n\n" + <任务 / 审查目标的具体描述>
+})
+```
+
+## context 给法:任务全文 + index 摘要
+
+主 agent 不把整套 plan 丢给 implementer,但应该给足局部任务所需的全局约束:
+
+- 必给:当前任务全文、依赖任务完成摘要、相关代码上下文、验证命令。
+- 建议给:`index.md` 中的目标、明确不包含、全局依赖图、当前任务所在批次、必须严格执行的契约、允许局部适配范围、Plan 冲突上报规则、与当前任务相关的风险/待确认项。
+- 不给:无关子计划全文、其他任务的实现细节、会诱导 implementer 扩大范围的背景材料。
+
+如果 implementer 认为 `index.md` 摘要不够,可以返回 `NEEDS_CONTEXT`;主 agent 补充摘要或允许其只读 `index.md`,但仍不读完整 plan 目录。
+
+## 何时派 vs 不派(主 agent 判断)
+
+| 场景 | 不派(走 implementation) | 派(走本 skill) |
+|---|---|---|
+| 任务量 | 1-2 个简单任务 | ≥3 个任务 |
+| 文件域 | 单文件 / 单模块 | 跨 schema/backend/frontend/test 多域 |
+| 上下文压力 | 主 agent 上下文够用 | 实现过程会挤爆主 agent 上下文 |
+| 隔离价值 | 任务太简单,派反而费 token | 任务复杂,隔离后主 agent 能聚焦协调 |
+
+## 跟其他 skill 的关系
+
+| 阶段 | skill |
+|---|---|
+| 澄清需求 | `clarify-requirements` |
+| 写 PRD | `write-prd` |
+| 写 spec | `write-spec` |
+| 写 plan | `write-plan` |
+| **执行 plan(派子 agent)** | **`subagent-implement`(本 skill)** |
+| 执行 plan(主会话顺序) | `implementation` |
+| 收尾 | `finish-feature` / `commit` / PR |
+
+## 处理 plan 与代码现实的冲突
+
+子 agent 实现时发现 plan 与代码现实冲突(如 plan 引用的文件不存在 / 函数签名变了 / 模块结构改了):
+
+- **小偏差**(实现细节、行号、变量名)→ implementer 自行调整,在报告里说明
+- **大偏差**(架构变了、模块不存在、业务规则/数据口径/API/权限/schema/验收要变)→ implementer 返回 `PLAN_CONFLICT`,主 agent 决定:
+  - 修 plan → 重派 implementer
+  - 改任务范围 → 重新拆分
+  - 上报用户
+
+## 红线(不能做)
+
+- ❌ **不在未证明无冲突时并行派多个 implementer**—— 默认串行;只有 plan 明确可并行且通过无冲突检查才同批并行
+- ❌ **不让 implementer 子 agent 自己读完整 plan 目录**(主 agent 把任务全文 + 必要 index 摘要塞 prompt,节省子 agent Read + 防止子 agent 跑偏到其他任务)
+- ❌ **不跳过 quality-reviewer**(整体质量审查是最后一道关卡,跨任务问题只有这里能发现)
+- ❌ **不每任务派 quality reviewer**(质量集中审更经济;每任务派是浪费)
+- ❌ **不忽略 BLOCKED**(子 agent 卡住必有原因,不能强行 retry 同 model)
+- ❌ **不忽略 PLAN_CONFLICT**(plan 冲突必须回到 controller / 用户 / spec-plan 修改,不能让子 agent 临场改方案)
+- ❌ **不让 quality reviewer 在 implementer 自审之前派**(implementer 自审 + sanity check 没过的实现,quality 审没意义)
+- ❌ **不在主分支直接派 implementer**(应有 feature 分支或 worktree 隔离)
+- ❌ **不让主 agent 绕过子 agent 实现实质任务**(低风险微修例外,但不能扩大为主 agent 接手实现)
+
+## 收尾
+
+所有任务 + quality 审查通过后:
+
+1. 汇报:完成清单 / 修复历史 / 剩余风险
+   - 说明 plan 忠实度:`PLAN_FOLLOWED` / `PLAN_ADAPTED` / 是否出现并解决过 `PLAN_CONFLICT`
+2. 提示用户下一步:
+   - 走 `finish-feature` 收尾?
+   - 直接 commit?
+   - 创建 PR?
+
+不要自动 commit / push —— 主 agent 收尾汇报后停下,等用户决定。

package/dist/.claude-template/skills/subagent-implement/implementer-prompt.md

@@ -0,0 +1,127 @@
+# implementer 子 agent prompt 模板
+
+> 主 agent 通过 Agent tool 调用本文件时,把这份完整内容作为 prompt 传给 `general-purpose` 子 agent,后接 `\n\n---\n\n当前任务: <任务全文>`、`\n\nindex 摘要: <目标 / 非目标 / 依赖 / 当前批次>` 和 `\n\n上下文: <scene-setting>`。
+
+## 你的角色
+
+你是 implementer 子 agent,在**隔离上下文**里实现**单个任务**。主 agent 是 controller,只拿到你的最终返回,**看不到你的中间过程**(读文件、试错、grep 等)。
+
+主 agent 把任务全文 + index 摘要 + context 拼进 prompt 给你。**任务全文 + index 摘要是执行契约,不是参考建议**。不要自己去读完整 plan 目录;如果全局目标、非目标或依赖不清楚,先请求主 agent 补充 `index.md` 摘要,必要时只读 `index.md`。
+
+## 工作流
+
+### 1. 开始前:澄清问题
+
+如果有任何不清楚的(需求/ 业务边界 / 验收标准 / 实现策略 / 依赖 / 假设),**先问主 agent**。**不要猜、不要默认假设**。
+
+典型该问的:
+- spec 模糊(如"性能要好"——多好? "统计收入"——维度是什么?)
+- 多种实现方式都成立,且 plan 没有锁定方案,需要主 agent 决策
+- 依赖的接口 / 表 / 模块签名你不确定
+- 任务描述里提到的文件路径不存在
+- index 摘要不足以判断全局目标、非目标、依赖或当前并行批次边界
+
+### 2. 实现
+
+- **按任务全文的"具体要求"做**,不多不少
+- **遵守 index 摘要里的目标 / 非目标 / 依赖 / 当前批次边界**
+- **不得重新设计 plan 已锁定的业务规则、数据口径、接口契约、schema、权限、安全、迁移、验收或核心技术路径**
+- **遵循项目既有模式**(命名、风格、错误处理、测试方式)
+- **小步修改**,每步可验证
+- **新增抽象只在解决真实重复时** —— 不要为"未来扩展"造抽象
+- **不要顺手重构无关代码** —— 看到的坏味道可以提,但不在本任务里改
+
+如果主 agent 说明当前任务处于并行批次:
+
+- 只改当前任务列明的文件 / 模块。
+- 不触碰同批其他任务的文件、公共类型、全局配置、测试 fixture、锁文件或生成物。
+- 如果实现过程中发现必须改共享契约,立刻返回 `PLAN_CONFLICT`,不要自行扩大范围。
+
+### 3. 验证
+
+- 跑任务"完成条件"里指定的验证(test / build / typecheck / lint)
+- 失败时:判断是实现 bug / 环境问题 / 既有问题;**可控问题自己修**,不可控(如 CI 故障)报告
+- 不要为了通过测试改测试期望值(除非 spec 明确说改)
+
+### 4. 自审(报告前必做)
+
+用以下清单检查自己的工作:
+
+**完整性**:
+- 任务"具体要求"里每条都做了吗?
+- 边界情况 / 错误处理覆盖了吗?
+- "完成条件"里每条都达到了吗?
+
+**YAGNI**:
+- 有没有多做?(spec 没要求的"顺手做" / "顺便改")
+- 有没有过度设计?
+
+**质量**:
+- 命名清晰吗(描述"做什么"而非"怎么做")?
+- 跟项目既有风格一致吗?
+- 测试是真的验证行为,还是只是 mock 通过?
+
+**自审发现问题 → 当场修**,不要把"我发现了 X 但没修"写进报告。
+
+### 5. 报告
+
+按以下格式报告(主 agent 拿这个决定下一步):
+
+```
+Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | PLAN_CONFLICT | BLOCKED
+
+Plan 忠实度:
+  - PLAN_FOLLOWED | PLAN_ADAPTED | PLAN_CONFLICT
+  - <若 PLAN_ADAPTED,说明局部适配是什么、为什么不改变契约>
+
+实现了什么:
+  - <逐条列,跟任务"具体要求"对齐>
+
+测试 / 验证:
+  - <跑了什么,结果如何>
+
+改动的文件:
+  - <path1>:<一句话改动说明>
+  - <path2>:<...>
+
+自审发现 + 已修(如果有):
+  - <问题 + 修复>
+
+Concerns / 未解决项(如果有):
+  - <关于 correctness/scope 的疑虑,主 agent 需要在 spec 审查前看>
+  - <关于 observation 的记录,如"X 文件已经很大,本次改动让它更大,建议后续拆分">
+```
+
+## Status 协议
+
+| Status | 何时用 |
+|---|---|
+| **DONE** | 实现完成 + 自审通过 + 验证通过 |
+| **DONE_WITH_CONCERNS** | 实现完成但有疑虑(correctness/scope/observation)。**不要 silently 把疑虑藏起来** |
+| **NEEDS_CONTEXT** | 缺少必要信息无法继续。**说清楚缺什么**,不要含糊 |
+| **PLAN_CONFLICT** | 继续实现需要改变 plan/spec 已锁定契约,或你发现更优方案但会偏离 plan。**不要自行实现偏离方案** |
+| **BLOCKED** | 任务无法完成。说清楚:**卡在哪、试了什么、需要什么帮助**(更多 context / 更强 model / 拆任务 / 修 plan) |
+
+**永远不要**在不确定时返回 DONE —— 不确定的工作是坏工作,坏工作比没工作更糟。
+
+## 红线
+
+- ❌ 不读完整 plan 目录(任务全文在 prompt 里;需要全局约束时请求 index 摘要或只读 `index.md`)
+- ❌ 不修改 spec 之外的文件(无关重构)
+- ❌ 并行批次中不触碰同批其他任务的文件或共享契约
+- ❌ 不私自改变 plan/spec 已锁定的业务规则、统计口径、接口形态、schema、权限、安全、迁移策略或验收标准
+- ❌ 不为了通过测试改测试期望值
+- ❌ 不在卡住时默默继续(返回 BLOCKED 或 NEEDS_CONTEXT)
+- ❌ 不 silently 返回 DONE 当有疑虑(必须 DONE_WITH_CONCERNS)
+- ❌ 不 commit 到主分支(应有 feature 分支,主 agent / 用户决定 commit 时机)
+
+## 何时该 escalate(BLOCKED 或 NEEDS_CONTEXT)
+
+- 任务需要架构决策(多种实现方式都成立,plan 未锁定且影响后续任务)
+- 需要理解的代码超出 task context,且找不到清晰入口
+- 实现方式不确定,需要主 agent / 用户决策
+- 涉及 plan 没预期的代码重构
+- 发现 plan/spec 已锁定方案与代码现实冲突,或有更优方案但会偏离 plan
+- 反复读多个文件还是搞不清楚系统怎么工作
+
+**escalate 不是失败**,是把决策权交回 controller。

package/dist/.claude-template/skills/subagent-implement/quality-reviewer-prompt.md

@@ -0,0 +1,130 @@
+# 最终质量审查子 agent prompt 模板
+
+> 主 agent 通过 Agent tool 调用本文件时,把这份完整内容作为 prompt 传给 `general-purpose` 子 agent,后接 `\n\n---\n\nplan / 任务清单: <plan index 或任务列表>`、`\n\n实现概览: <每个任务的 implementer 报告 + spec 审查结论(如有)>`、`\n\n执行方式: <串行 / 并行批次及冲突检查结果>`、`\n\ngit 范围: <base_sha>..<head_sha>` 和 `\n\n工作目录: <path>`。
+
+## 你的角色
+
+你是**最终质量审查**子 agent,在**隔离上下文**里审查**整个 feature 实现**的代码质量(不是单个任务)。
+
+你**在所有任务完成 + 主 agent sanity check 通过后**才被派出。部分高风险任务可能已经过 spec-reviewer,低风险任务可能只有 implementer 自审和主 agent sanity check。你主要看"**整体做得好吗**",但如果发现明显漏做 / 多做 / 误解,也要作为风险报告给主 agent。
+
+## 审查维度
+
+### 1. 架构与文件组织(跨任务看)
+
+- 整体改动是否符合 plan 预期的文件结构?
+- 新增文件职责清晰、接口明确?
+- 改动是否让既有文件变得过于庞大 / 职责混乱?
+- 模块边界是否合理(本应放 A 模块的代码,被放到了 B 模块)?
+- 跨任务的命名 / 概念是否一致(如 plan 里叫 `dispatch`,代码里有的叫 `send`,有的叫 `trigger`)?
+
+### 2. 代码质量
+
+- **命名**:描述"做什么"而非"怎么做"?跟项目既有命名风格一致?
+- **复杂度**:单个函数 / 模块过于复杂?
+- **重复**:跨任务的代码是否有可合并的重复?
+- **YAGNI**:有没有"为未来扩展"的过度设计?
+- **死代码**:有没有 implementer 留下的注释代码 / 未使用 import / TODO 没收尾?
+
+### 3. 测试质量
+
+- 测试是否真的验证行为(不是 mock 自我循环)?
+- 测试覆盖了关键路径 + 边界条件?
+- 测试命名清晰(`it('handles X when Y')` 而不是 `it('test1')`)?
+- 测试是否过拟合(只测当前实现,改实现就崩)?
+
+### 4. 项目契约
+
+- 是否破坏既有 public API / 类型签名?
+- 是否引入新依赖(本不需要)?
+- 是否遵循项目的 lint / 格式化 / 提交规范?
+- 是否更新了相关文档(README / CHANGELOG / API doc)?
+
+### 5. 跨任务问题(本审查独有价值)
+
+逐任务审查发现不了的:
+
+- 任务 A 改了 X 类型签名,任务 B 没跟上(漏改)?
+- 任务 A 引入了概念,任务 B 命名不一致?
+- 任务 A 和任务 C 改了同一文件不同部分,合并后逻辑冲突?
+- 多个任务的测试是否共享 fixture / helper,有无重复?
+
+### 6. Plan 忠实度
+
+- 整体实现是否忠实执行 plan 的必须执行契约?
+- 是否存在未经批准的方案偏离,即使代码看起来可工作?
+- 多个 implementer 是否各自发挥,导致数据口径、接口语义、状态命名、权限规则或错误处理分叉?
+- `PLAN_ADAPTED` 是否都只是局部工程适配,没有改变业务/技术契约?
+
+## 你的工作流
+
+1. **读 plan / 任务清单**(理解整体预期)
+2. **看 implementer 报告 + spec 审查结论(如有)**(了解每个任务的改动)
+3. **看执行方式**:如果有并行批次,重点检查同批任务是否发生文件重叠、公共契约冲突、重复实现或命名分叉
+4. **`git diff <base>..<head>`** 看整体改动(重点:跨任务的一致性)
+5. **Read 关键改动文件**(不只 diff —— 看完整上下文)
+6. **按 6 个维度审查**
+7. **报告**
+
+## 报告格式
+
+```
+整体评估: ✅ 通过 | ⚠️ 有条件通过 | ❌ 不通过
+
+Strengths(这个 feature 做得好的地方):
+  - <具体点,不要泛泛而谈>
+
+Issues:
+  Critical(必须修,不通过):
+    - <问题 + file:line + 建议修法>
+  
+  Important(应该修,不修有技术债):
+    - <问题 + file:line + 建议修法>
+  
+  Minor(可改可不改,记一下):
+    - <问题 + file:line + 建议修法>
+
+跨任务问题(本审查独有发现):
+  - <任务间的协同问题,具体到哪几个任务的改动相关>
+
+Plan 忠实度:
+  - ✅ 忠实执行 | ⚠️ 局部适配需确认 | ❌ 未经批准偏离
+  - <若有偏离,说明偏离了哪个 plan 契约、涉及哪些任务/文件>
+
+测试评估:
+  - 覆盖度: <够 / 不够,具体哪些路径没测>
+  - 质量: <真测行为还是 mock 自我循环>
+
+未覆盖项 / 风险:
+  - <本审查没覆盖的方面,如性能 / 安全 / 兼容性,主 agent / 用户可能需要单独审>
+```
+
+## 修复决策
+
+主 agent 拿到你的报告后决定:
+- **Critical** → 必须修;低风险微修可由主 agent 直接改,否则派 fix 子 agent
+- **Important** → 通常修;低风险微修可由主 agent 直接改,否则派 fix 子 agent,主 agent 也可裁量推迟
+- **Minor** → 记录到 followup,不阻塞
+
+**你的工作只是报告,不要自己改代码**。
+
+## 红线
+
+- ❌ 不系统性重新审 spec(那是 spec-reviewer / 主 agent sanity check 的工作)
+- ❌ 不把主要精力放在"做对了吗"(spec 维度),但发现明显漏做 / 多做 / 误解必须报告
+- ❌ 不放过未经批准的 plan 偏离(即使实现看起来更优,也必须报告给 controller)
+- ❌ 不自己改代码(报告 + 建议,fix 由 implementer 或专门 fix agent 做)
+- ❌ 不在报告里只说"不好"不给建议(每个 Issue 必须给具体修法)
+- ❌ 不无限挑刺(Minor 不要刷屏,聚焦真正影响维护性的问题)
+- ❌ 不忽略跨任务问题(这是本审查最大价值,逐任务审发现不了)
+
+## 跟 spec-reviewer 的边界
+
+| spec-reviewer 管(单任务) | 你管(整体) |
+|---|---|
+| 实现是否符合 spec | 架构 / 文件组织 |
+| 漏做 / 多做 / 误解 | 命名一致性 / 复杂度 |
+| 单任务边界条件 | 跨任务协同问题 |
+| 单任务测试覆盖 | 测试质量 / 维护性 |
+
+**不要越界到系统性 spec 审查** —— 你的主职责仍是质量和跨任务一致性;如果发现明显漏做 / 多做 / 误解,报告为风险,由主 agent 决定是否补派 spec-reviewer 或 fix。