From d3192bf577e11d2a3133b9426d9c528b7092d463 Mon Sep 17 00:00:00 2001 From: dafang Date: Mon, 29 Jun 2026 17:17:34 +0800 Subject: [PATCH] docs: clarify task agent review rules --- cs-code-review/SKILL.md | 12 ++++++------ cs-feat-design-review/SKILL.md | 22 +++++++++++----------- cs-roadmap-review/SKILL.md | 22 +++++++++++----------- 3 files changed, 28 insertions(+), 28 deletions(-) diff --git a/cs-code-review/SKILL.md b/cs-code-review/SKILL.md index 6d99d97..941b697 100644 --- a/cs-code-review/SKILL.md +++ b/cs-code-review/SKILL.md @@ -43,7 +43,7 @@ description: 横切代码审查 gate——任何流程（feature / issue / refac - diff 涉及的人写代码文件和相邻关键调用点 - spec 指向的 architecture / requirement / roadmap 相关文档（只读，判断改动是否会影响归并；feature 即 design 第 4 节） - goal / gate 模式下的 evidence pack、gate results、DoD results；缺失时回 implementation gate 补证据，不现场猜测 -- independent reviewer 输出（如果本轮启用了 Paseo 或其他外部 reviewer） +- 独立 Task agent reviewer 输出（如果本轮启用了 Paseo 或其他 reviewer） 如果工作区有本轮范围外的既有 dirty 文件，先记录为 baseline/无关变更；审查结论只针对本轮可归因的改动。无法区分归因时写成 `residual-risk`，不要把不确定当通过。 @@ -63,7 +63,7 @@ description: 横切代码审查 gate——任何流程（feature / issue / refac --- -## 独立 reviewer（双环节） +## 独立 Task agent reviewer（双环节） 本阶段是**双环节 review**，两个环节互补： @@ -78,9 +78,9 @@ description: 横切代码审查 gate——任何流程（feature / issue / refac ### 环节 A：独立隔离上下文 agent review（gate 必需） -主 agent 按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent；都没有则记 `local-only`，不能伪装启动。gate 默认不放行，需用户明确降级（见 `reviewer` 字段）。 +主 agent 按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 Task agent reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent；都没有则记 `local-only`，不能伪装启动。gate 默认不放行，需用户明确降级（见 `reviewer` 字段）。 -独立 reviewer prompt（只给原始材料，不透露主 agent 的任何 review 结论）： +独立 Task agent reviewer prompt（只给原始材料，不透露主 agent 的任何 review 结论）： ```text 你是 CodeStable 本次改动的独立代码审查 agent。只读，不修改文件，不更新 checklist/design。 @@ -208,9 +208,9 @@ gate 默认要求 `subagent` 或 `subagent+ocr`；`ocr` 和 `self` 需配 `CODES - `passed`：没有 blocking；important 已修复、无重要项、或用户明确接受延后。 - `changes-requested`：有 blocking，或 important 多到会影响验收可信度。 -- `blocked`：缺少关键输入、diff 归因无法判断、设计/实现状态不满足 review 前置条件，或本轮已启动 independent reviewer 但结果仍 pending / failed / blocked 且用户尚未确认降级。 +- `blocked`：缺少关键输入、diff 归因无法判断、设计/实现状态不满足 review 前置条件，或本轮已启动独立 Task agent reviewer 但结果仍 pending / failed / blocked 且用户尚未确认降级。 -**`reviewer` 字段（gate 锚点）**：`{slug}-review.md` 的 frontmatter `reviewer` 决定下游 worktree / commit / finish gate 是否放行，按「独立 reviewer（双环节）」实际完成情况写 `subagent+ocr` / `subagent` / `ocr` / `self`（语义见上节表）。任一已启动环节仍 pending / failed / blocked 时不定稿 `passed`，也不写 `subagent`。 +**`reviewer` 字段（gate 锚点）**：`{slug}-review.md` 的 frontmatter `reviewer` 决定下游 worktree / commit / finish gate 是否放行，按「独立 Task agent reviewer（双环节）」实际完成情况写 `subagent+ocr` / `subagent` / `ocr` / `self`（语义见上节表）。任一已启动环节仍 pending / failed / blocked 时不定稿 `passed`，也不写 `subagent`。 --- diff --git a/cs-feat-design-review/SKILL.md b/cs-feat-design-review/SKILL.md index 7925a8f..6c7f552 100644 --- a/cs-feat-design-review/SKILL.md +++ b/cs-feat-design-review/SKILL.md @@ -31,7 +31,7 @@ description: feature design 人工确认前的方案审查 gate。对照 {slug}- - design 第 4 节指向的 architecture 文档 - 相关 compound 沉淀：用项目搜索工具按 feature 关键词检索 decision / learning / explore / trick - design 中引用到的关键代码位置、接口、类型、组件、命令、配置 -- independent reviewer 输出（如果本轮启用了 Paseo 或其他外部 reviewer） +- 独立 Task agent reviewer 输出（如果本轮启用了 Paseo 或其他 reviewer） 没有代码引用时不强行扫全仓库；但 design 声称复用、修改、挂载或约束某个现有模块时，必须读对应代码或文档事实核验。 @@ -50,13 +50,13 @@ description: feature design 人工确认前的方案审查 gate。对照 {slug}- --- -## 独立 reviewer 增强项 +## 独立 Task agent reviewer 增强项 -本阶段默认由当前 agent 做本地方案审查；独立 reviewer 是增强项，不是硬依赖。检测不到 Task agent、provider 未配置或用户明确要求快速完成时，可以继续本地 review，并在报告里记录 `Independent reviewer: local-only` / `skipped-by-user`。 +本阶段默认由当前 agent 做本地方案审查；独立 Task agent reviewer 是增强项，不是硬依赖。检测不到 Task agent、provider 未配置或用户明确要求快速完成时，可以继续本地 review，并在报告里记录 `Independent reviewer: local-only` / `skipped-by-user`。 -但一旦本轮已经启动 independent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 independent reviewer 返回前定稿 `{slug}-design-review.md`、不能给出 `passed`、不能把 design 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。 +但一旦本轮已经启动独立 Task agent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 reviewer 返回前定稿 `{slug}-design-review.md`、不能给出 `passed`、不能把 design 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。 -**检测由主 agent 在运行时自检自己的工具**，按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent。都没有则本地 review，记录 `local-only`，不要伪装启动。不要无限轮询运行中的 agent；若已启动但未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。 +**检测由主 agent 在运行时自检自己的工具**，按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 Task agent reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent。都没有则本地 review，记录 `local-only`，并写入 `approval-report.md` 请 owner 授权降级；不要伪装启动。不要无限轮询运行中的 agent；若已启动但未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。 Task agent prompt 必须只给原始材料和边界，不透露本地 review 结论： @@ -77,7 +77,7 @@ Task agent prompt 必须只给原始材料和边界，不透露本地 review 结 不要写 {slug}-design-review.md；只把审查结果回传给主 agent。 ``` -主 agent 仍是最终审查责任方：必须逐条核验 independent reviewer 的 finding，去重、定级、合并进 `{slug}-design-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。 +主 agent 仍是最终审查责任方：必须逐条核验 reviewer 的 finding，去重、定级、合并进 `{slug}-design-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。 --- @@ -96,7 +96,7 @@ Task agent prompt 必须只给原始材料和边界，不透露本地 review 结 ### 2. 独立审查合并 - 记录主 agent 自检结果：`paseo` / `native-agent` / `local-only`。 -- 没有启动 independent reviewer 时，记录原因，本地 review 可以定稿。 +- 没有启动独立 Task agent reviewer 时，记录原因，本地 review 可以定稿。 - 启动 Task agent 后，最终 verdict 必须等 reviewer 返回。 - reviewer 返回后逐条做本地事实核验；能用 design / checklist / 文档 / 代码证据支撑才合并。 - reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。 @@ -247,7 +247,7 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。 ## 7. Verdict - Status: passed|changes-requested|blocked -- Next: 交给用户整体 review | 回 `cs-feat-design` 修订后重跑 `cs-feat-design-review` | 等 independent reviewer 完成 / 用户确认降级后重跑 +- Next: 交给用户整体 review | 回 `cs-feat-design` 修订后重跑 `cs-feat-design-review` | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑 ``` 没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。 @@ -259,8 +259,8 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。 - [ ] 已读取 attention、design、checklist、相关 intent / brainstorm / roadmap / req / arch / compound。 - [ ] 已按 design 声明核验必要代码、接口、类型、组件或命令事实。 - [ ] 已确认 checklist 可解析，steps/checks 都可追溯。 -- [ ] 已运行 independent reviewer 检测，或记录为什么跳过。 -- [ ] 如果启动了 independent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。 +- [ ] 已运行独立 Task agent reviewer 检测，或记录为什么跳过。 +- [ ] 如果启动了独立 Task agent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。 - [ ] 已审查需求边界、术语、名词层、编排层、挂载点、结构健康度、验收契约、steps/checks、基线、交付物、清洁度。 - [ ] 已检查 Acceptance Coverage Matrix、Feature Design Review Invariants 和 Evidence Confidence Ledger。 - [ ] 核心检查 H-only 时没有静默 passed。 @@ -277,6 +277,6 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。 - roadmap 起头时不检查接口契约，导致 feature 偷偷绕开 roadmap。 - 现状段没读代码就放过，implement 阶段才发现设计站不住。 - steps 出现"和 / 以及 / 同时"却不复查是否该拆。 -- 启动 independent reviewer 后结果还没回来，就把本地 review 定稿为 passed。 +- 启动独立 Task agent reviewer 后结果还没回来，就把本地 review 定稿为 passed。 - 外部 reviewer 的结论没经本地事实核验就照抄。 - review 报告没有落盘，导致用户 review 和后续实现没有可追溯输入。 diff --git a/cs-roadmap-review/SKILL.md b/cs-roadmap-review/SKILL.md index a16b841..8b1092e 100644 --- a/cs-roadmap-review/SKILL.md +++ b/cs-roadmap-review/SKILL.md @@ -30,7 +30,7 @@ description: roadmap 人工确认前的规划审查 gate。对照 roadmap 主文 - 相关 compound 沉淀：用项目搜索工具按大需求关键词检索 decision / learning / explore / trick - items.yaml 中已存在 `feature` 字段的 feature design / acceptance（update 模式或复审时） - roadmap 中接口契约或模块拆分引用到的关键代码位置 -- independent reviewer 输出（如果本轮启用了 Paseo 或其他外部 reviewer） +- 独立 Task agent reviewer 输出（如果本轮启用了 Paseo 或其他 reviewer） 没有代码引用时不强行扫全仓库；但 roadmap 声称复用现有模块、接口、命令、配置或数据结构时，必须读对应代码或文档事实核验。 @@ -49,13 +49,13 @@ description: roadmap 人工确认前的规划审查 gate。对照 roadmap 主文 --- -## 独立 reviewer 增强项 +## 独立 Task agent reviewer 增强项 -本阶段默认由当前 agent 做本地规划审查；独立 reviewer 是增强项，不是硬依赖。检测不到 Task agent、provider 未配置或用户明确要求快速完成时，可以继续本地 review，并在报告里记录 `Independent reviewer: local-only` / `skipped-by-user`。 +本阶段默认由当前 agent 做本地规划审查；独立 Task agent reviewer 是增强项，不是硬依赖。检测不到 Task agent、provider 未配置或用户明确要求快速完成时，可以继续本地 review，并在报告里记录 `Independent reviewer: local-only` / `skipped-by-user`。 -但一旦本轮已经启动 independent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 independent reviewer 返回前定稿 `{slug}-roadmap-review.md`、不能给出 `passed`、不能把 roadmap 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。 +但一旦本轮已经启动独立 Task agent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 reviewer 返回前定稿 `{slug}-roadmap-review.md`、不能给出 `passed`、不能把 roadmap 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。 -**检测由主 agent 在运行时自检自己的工具**，按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent。都没有则本地 review，记录 `local-only`，不要伪装启动。不要无限轮询运行中的 agent；若已启动但未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。 +**检测由主 agent 在运行时自检自己的工具**，按 `.codestable/reference/execution-conventions.md` 的 Task agent 选择规则启动独立 Task agent reviewer：Paseo subagent 优先，否则用当前宿主的原生 Codex/Claude Task/Agent。都没有则本地 review，记录 `local-only`，并写入 `approval-report.md` 请 owner 授权降级；不要伪装启动。不要无限轮询运行中的 agent；若已启动但未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。 Task agent prompt 必须只给原始材料和边界，不透露本地 review 结论： @@ -76,7 +76,7 @@ Task agent prompt 必须只给原始材料和边界，不透露本地 review 结 不要写 {slug}-roadmap-review.md；只把审查结果回传给主 agent。 ``` -主 agent 仍是最终审查责任方：必须逐条核验 independent reviewer 的 finding，去重、定级、合并进 `{slug}-roadmap-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。 +主 agent 仍是最终审查责任方：必须逐条核验 reviewer 的 finding，去重、定级、合并进 `{slug}-roadmap-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。 --- @@ -93,7 +93,7 @@ Task agent prompt 必须只给原始材料和边界，不透露本地 review 结 ### 2. 独立审查合并 - 记录主 agent 自检结果：`paseo` / `native-agent` / `local-only`。 -- 没有启动 independent reviewer 时，记录原因，本地 review 可以定稿。 +- 没有启动独立 Task agent reviewer 时，记录原因，本地 review 可以定稿。 - 启动 Task agent 后，最终 verdict 必须等 reviewer 返回。 - reviewer 返回后逐条做本地事实核验；能用文档 / 代码 / items 证据支撑才合并。 - reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。 @@ -239,7 +239,7 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。 ## 7. Verdict - Status: passed|changes-requested|blocked -- Next: 交给用户 review | 回 `cs-roadmap` 修订后重跑 `cs-roadmap-review` | 等 independent reviewer 完成 / 用户确认降级后重跑 +- Next: 交给用户 review | 回 `cs-roadmap` 修订后重跑 `cs-roadmap-review` | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑 ``` 没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。 @@ -251,8 +251,8 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。 - [ ] 已读取 attention、roadmap、items、相关 req / arch / compound / drafts。 - [ ] 已按 roadmap 声明核验必要代码或命令事实。 - [ ] 已确认 items.yaml 可解析，依赖图无未知节点；有问题已列 finding。 -- [ ] 已运行 independent reviewer 检测，或记录为什么跳过。 -- [ ] 如果启动了 independent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。 +- [ ] 已运行独立 Task agent reviewer 检测，或记录为什么跳过。 +- [ ] 如果启动了独立 Task agent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。 - [ ] 已审查目标、范围、模块、接口、feature 原子性、依赖、最小闭环、验证、风险、知识回写。 - [ ] 已检查 Granularity Gate、Goal Coverage Matrix 和 Roadmap Review Invariants。 - [ ] 已写 Evidence Confidence Ledger；核心检查 H-only 时没有静默 passed。 @@ -269,6 +269,6 @@ Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。 - 不读 requirement / architecture，导致规划和现状冲突没发现。 - 接口契约写着"待定"也放过，后续每条 feature 各自发明接口。 - 子 feature 里塞多个可独立验收的交付，却只当一条。 -- 启动 independent reviewer 后结果还没回来，就把本地 review 定稿为 passed。 +- 启动独立 Task agent reviewer 后结果还没回来，就把本地 review 定稿为 passed。 - 外部 reviewer 的结论没经本地事实核验就照抄。 - review 报告没有落盘，导致用户 review 和后续 design 没有可追溯输入。