update review loop skill

Author: hiyuki

.agents/skills/review-loop/SKILL.md

@@ -1,99 +1,78 @@
 ---
 name: review-loop
-description: Use this skill whenever the user asks for a review loop, self-review workflow, planner/reviewer/coder/code-reviewer collaboration, plan-before-code process, multi-round agent review, or a stable subagent workflow that must produce a plan, wait for user confirmation, implement code, review the diff, and preserve revision records. This skill requires real subagent support and must not fall back to single-agent roleplay.
-protocolVersion: 2.0.0
+description: 当用户要求评审循环、自评审工作流、planner/reviewer/coder/code-reviewer 协作、先方案后编码、多轮 Agent 评审，或要求稳定的子 Agent 工作流依次产出方案、等待用户确认、实现代码、评审差异并保留修订记录时，使用此 Skill。此 Skill 必须使用真实子 Agent，不得退化为单 Agent 角色扮演。
 ---
 
-# Review Loop
-
-Use this skill to run a two-phase workflow:
-
-1. Plan loop: `planner` writes or revises `plan.md`; `plan-reviewer` reviews it.
-2. Code loop: after user confirmation, `coder` implements the confirmed plan; `code-reviewer` reviews the resulting diff.
-
-The workflow requires real planner, reviewer, and coder subagents. If the
-current environment cannot create fresh native subagents, stop and tell the
-user that `review-loop` cannot run in this session. Codex and Claude Code use
-host-native subagents for all four roles.
-
-## Required Setup
-
-Before doing task work:
-
-1. Read `references/protocol.md`, `references/state-machine.md`, and `references/role-contracts.md`.
-2. Read `references/codex.md` or `references/claude-code.md` when that platform applies.
-3. Create a task id.
-4. Run `scripts/init-workspace.js` to create `.agent-workflows/review-loop/<task-id>/`.
-5. Run `scripts/prepare-agent-roles.js` to prepare the platform's real subagent roles.
-6. Run `scripts/validate-state.js` before advancing.
-
-Default `maxRounds` is `3`. If the user specifies a maximum loop count, pass it to `init-workspace.js`.
-
-## Hard Rules
-
-- Do not implement code until the plan loop has ended and the user explicitly confirms the plan.
-- Do not let reviewer roles modify repository files. Reviewers return one strict
-  JSON object; the orchestrator persists and validates it through
-  `scripts/review-manager.js --finalize`.
-- Start every reviewer in a fresh context that does not inherit planner/coder conversation history.
-- On Codex or Claude Code, run `scripts/review-manager.js --prepare`, pass the
-  returned paths-only prompt to a fresh native reviewer subagent, save its one
-  JSON response to a temporary file outside the repository, then run
-  `scripts/review-manager.js --finalize --input <file> --agent-id <id>`. Prepare
-  binds every input and the Git tree; finalize rejects drift, writes the
-  immutable reviewer-run, and persists the canonical review. Do not invoke
-  `scripts/persist-review-json.js` directly.
-- Use `scripts/validate-review-json.js` for later read-only revalidation.
-- Use `scripts/snapshot-diff.js` after every code loop implementation round.
-- `coder-complete` reconstructs the current Git tree, path partitions, and
-  patches; rerun `snapshot-diff.js` if any code changes after snapshotting.
-- Once the current code reviewer-run artifact exists, do not replace its bound
-  snapshot even when canonical review persistence has not completed.
-- Use `scripts/advance-state.js` for every state transition; never hand-edit `state.json`.
-- Stop a loop when the reviewer returns `approved` or when the loop reaches `state.json.maxRounds`.
-- When a loop stops because `maxRounds` is reached, summarize remaining findings and ask the user whether to continue, accept, or revise.
-- If reviewed plan/code changes while waiting at a confirmation gate, prefer a
-  new review round. Override only after the user's current message explicitly
-  accepts the changed content; pass `--accept-changed-inputs true` with a
-  non-empty `--override-reason`. The transition records the accepted drift in
-  `state.json.confirmationOverrides`.
-- Increase `maxRounds` only from that `max_rounds_reached` confirmation gate;
-  rejecting at that gate cannot resume drafting until the limit is increased,
-  after a current user message explicitly supplies a higher limit. Pass
-  `--user-confirmed true`; never reuse an earlier general instruction to bypass
-  the configured limit.
-- Preserve every round's revision record in `plan.md`.
-
-## Workflow Roles
-
-The four required roles are:
+# 评审循环
+
+使用此 Skill 执行两个阶段的工作流：
+
+1. 方案循环：`planner` 编写或修订 `plan.md`，`plan-reviewer` 对其进行评审。
+2. 代码循环：用户确认方案后，`coder` 实施已确认方案，`code-reviewer` 评审产生的差异。
+
+该工作流必须使用真实的 planner、reviewer 和 coder 子 Agent。如果当前环境无法创建新的原生子 Agent，停止并告知用户本次会话无法运行 `review-loop`。Codex 和 Claude Code 的四个角色都使用宿主原生子 Agent。
+
+## 必需准备
+
+开始任务前：
+
+1. 读取 `references/protocol.md`、`references/state-machine.md` 和 `references/role-contracts.md`。
+2. 根据当前平台读取 `references/codex.md` 或 `references/claude-code.md`。
+3. 创建任务 ID。
+4. 运行 `scripts/init-workspace.js`，创建 `.agent-workflows/review-loop/<task-id>/`。
+5. 运行 `scripts/prepare-agent-roles.js`，准备当前平台的真实子 Agent 角色。
+6. 在推进流程前运行 `scripts/validate-state.js`。
+
+`maxRounds` 默认为 `3`。如果用户指定最大循环轮数，将其传给 `init-workspace.js`。
+
+## 强制规则
+
+- 在方案循环结束且用户明确确认方案前，不得实现代码。
+- 所有面向用户或需要用户确认的自然语言中间产物必须使用中文，包括技术方案、评审摘要与结论、问题说明与修改建议、方案修订记录、代码执行记录、角色日志、验证结果说明、剩余风险，以及确认节点的汇总和提问。命令、路径、代码符号、Markdown 固定字段名、协议枚举值和工具原始输出可保留原文。
+- 不得让 reviewer 角色修改仓库文件。Reviewer 只返回一份符合固定格式的 Markdown 文档；编排者通过 `scripts/review-manager.js --finalize` 解析、持久化并校验该文档。
+- `plan-reviewer` 和 `code-reviewer` 的每一轮评审都必须创建全新、独立的原生子 Agent 实例；即使角色和评审类型相同，也不得恢复或复用任何之前轮次创建的 reviewer，且不得继承父级会话、planner 或 coder 的任何上下文。`review-manager.js --finalize` 会拒绝与历史 reviewer-run 重复的 `--agent-id`。
+- `planner` 和 `coder` 可以跨轮复用各自之前创建的子 Agent 实例，以保留方案修订或代码实现上下文；二者不得相互复用实例。
+- 在 Codex 或 Claude Code 中，运行 `scripts/review-manager.js --prepare`，将返回的仅含路径的提示词交给新的原生 reviewer 子 Agent，把其唯一纯 Markdown 响应保存到仓库外的临时文件，再运行 `scripts/review-manager.js --finalize --input <file> --agent-id <id>`。Prepare 会绑定全部输入和 Git 树；finalize 会拒绝漂移、直接校验 Markdown、写入不可变的 reviewer-run 并将规范评审持久化为 `reviews/*-review-N.md`。不得直接调用 `scripts/persist-review-markdown.js`。
+- 后续只读复验使用 `scripts/validate-review-markdown.js`，该命令直接解析和校验 `.md` 文档。
+- 每轮代码实现和验证完成后直接执行 `coder-complete`。该转换只校验初始基线与当前工作树可以安全重建，不生成差异文件或轮次范围文件。
+- Prepare 会把初始基线到绑定工作树的完整 diff 写入 `diffs/code-diff-N.patch`，作为代码 reviewer 与人工共同使用的评审交接产物，并将其内容摘要绑定到 reviewer 请求。
+- 不得生成、传递或记录相邻代码轮次间的增量 patch；`code-diff-N.patch` 始终表示初始基线到当前评审版本的差异。
+- Prepare 会在 reviewer-run 中绑定当前工作树摘要；评审期间代码发生变化时 finalize 会拒绝结果，必须重新开始当前评审轮次。
+- 所有状态转换都使用 `scripts/advance-state.js`，不得手动编辑 `state.json`。
+- reviewer 返回 `approved` 或循环达到 `state.json.maxRounds` 时停止当前循环。
+- 因达到 `maxRounds` 而停止时，用中文汇总剩余问题，并询问用户要继续、接受还是修订。
+- 在确认节点等待期间，如果已评审的方案或代码发生变化，优先开启新一轮评审。只有用户当前消息明确接受变化时才可覆盖，并传入 `--accept-changed-inputs true` 和非空的 `--override-reason`。转换会把接受的漂移记录到 `state.json.confirmationOverrides`。
+- 只能在 `max_rounds_reached` 确认节点增加 `maxRounds`；在该节点拒绝结果后，必须由用户当前消息明确给出更高上限，才能恢复起草。传入 `--user-confirmed true`；不得复用更早的笼统指令绕过已配置上限。
+- 在 `plan.md` 中保留每轮修订记录，并以中文书写记录内容。
+
+## 工作流角色
+
+四个必需角色是：
 
 - `planner`
 - `plan-reviewer`
 - `coder`
 - `code-reviewer`
 
-Use the templates under `templates/roles/` as role definitions. On Codex and
-Claude Code all four roles are native subagents, and reviewer roles must start
-with no inherited planner/coder conversation.
+使用 `templates/roles/` 下的模板作为角色定义。在 Codex 和 Claude Code 中，四个角色都必须是原生子 Agent。Planner/coder 后续轮次可以继续使用各自已有实例；plan-reviewer/code-reviewer 每一轮必须新建实例，并禁用父级会话上下文继承。
 
-## User Confirmation Gates
+## 用户确认节点
 
-After the plan loop ends, show the user:
+方案循环结束后，用中文向用户展示：
 
-- `plan.md` path
-- plan loop termination reason
-- review summary by round
-- unaccepted findings and reasons
+- `plan.md` 路径
+- 方案循环终止原因
+- 按轮次整理的评审摘要
+- 未接受的问题及理由
 
-Ask whether to enter the code loop. Only after explicit confirmation, run `advance-state.js --event confirm-plan`.
+用中文询问是否进入代码循环。只有用户明确确认后，才运行 `advance-state.js --event confirm-plan`。
 
-After the code loop ends, show the user:
+代码循环结束后，用中文向用户展示：
 
-- `plan.md` path
-- diff summary
-- code loop termination reason
-- validation commands and results
-- remaining risks
+- `plan.md` 路径
+- 差异摘要
+- 代码循环终止原因
+- 验证命令及结果
+- 剩余风险
 
-Ask whether to accept the final result. Only after explicit confirmation, run `advance-state.js --event confirm-final`.
+用中文询问是否接受最终结果。只有用户明确确认后，才运行 `advance-state.js --event confirm-final`。

.agents/skills/review-loop/evals/evals.json

@@ -4,19 +4,19 @@
     {
       "id": 1,
       "prompt": "使用 review-loop 工作流实现一个小的 bugfix，先产出方案并 review，等我确认后再写代码。",
-      "expected_output": "Creates a review-loop workspace, initializes state.json with maxRounds=3, enters plan loop, and waits for user confirmation before code loop.",
+      "expected_output": "创建 review-loop 工作区，以 maxRounds=3 初始化 state.json，进入方案循环，并在代码循环开始前等待用户确认；全部待确认中间产物使用中文；reviewer 只输出摘要、已检查文件、评审问题和剩余风险，不记录过程证据；Prepare 写入初始基线到绑定工作树的 code-diff-N.patch，并将其作为 reviewer 与人工共同使用的评审交接产物，但不记录中间轮次变化。",
       "files": []
     },
     {
       "id": 2,
       "prompt": "使用 review-loop 工作流实现需求，最多 review 5 轮。",
-      "expected_output": "Initializes state.json with maxRounds=5 and uses that value to stop plan/code loops.",
+      "expected_output": "以 maxRounds=5 初始化 state.json，并使用该值停止方案/代码循环；全部待确认中间产物使用中文；评审产物写入 reviews/*-review-N.md 并直接按 Markdown 契约校验。",
       "files": []
     },
     {
       "id": 3,
       "prompt": "继续上次中断的 review-loop 任务。",
-      "expected_output": "Runs recoverability/state checks, reads state.json, and resumes from the recorded phase instead of starting over.",
+      "expected_output": "运行可恢复性与状态检查，读取 state.json，并从记录的阶段恢复而不是重新开始；全部待确认中间产物使用中文；拒绝旧 JSON review。",
       "files": []
     }
   ]

.agents/skills/review-loop/references/claude-code.md

@@ -1,13 +1,10 @@
-# Claude Code Integration
+# Claude Code 集成
 
-Claude Code support uses real native subagents for `planner`, `plan-reviewer`,
-`coder`, and `code-reviewer`. Do not run any role as single-agent roleplay and
-do not start standalone `claude -p` reviewer processes.
+Claude Code 使用真实的原生子 Agent 承担 `planner`、`plan-reviewer`、`coder` 和 `code-reviewer`。不得把任何角色作为单 Agent 角色扮演运行，也不得启动独立的 `claude -p` reviewer 进程。
 
-## Role Discovery
+## 角色发现
 
-Prepare all four roles with `scripts/prepare-agent-roles.js` either as temporary
-task roles or project agents:
+使用 `scripts/prepare-agent-roles.js` 把全部四个角色准备为临时任务角色或项目 Agent：
 
 ```text
 .claude/agents/planner.md
@@ -16,38 +13,27 @@ task roles or project agents:
 .claude/agents/code-reviewer.md
 ```
 
-Temporary roles are valid only when the host can register them for the current
-session. Project roles require explicit user confirmation and a `/agents`
-reload or session restart.
-
-## Starting Roles
-
-Start planner and coder as new named native subagents when required by the
-state machine. Start reviewers through Claude Code's native Agent/Task tool as
-new tasks with no resumed session or inherited planner/coder conversation.
-Restrict reviewer tools to read-only inspection when the host supports tool
-allow/deny configuration.
-
-For a reviewer round:
-
-1. Run `review-manager.js --task-id <id> --kind plan|code --round N --prepare`.
-2. Pass the returned prompt unchanged to the matching reviewer role.
-3. Require the reviewer to run its context-isolation preflight before reading
-   repository files and return exactly one JSON object with no repository writes.
-4. Save the response to a temporary file outside the repository.
-5. Run `review-manager.js ... --finalize --input <file> --agent-id <id>`.
-
-Prepare binds input digests and the current Git tree. Finalize reconstructs the
-request and rejects input, snapshot, or worktree drift before writing the
-immutable reviewer-run and canonical review. The orchestrator normalizes
-`reviewerConfig` to the host-native contract with source
-`claude-native-subagent`; it does not trust reviewer self-reporting.
-Finalize also rejects output that lacks the exact passed
-`context-isolation-preflight` evidence. This self-check supplements, but does
-not replace, starting a new native task without a resumed session.
-
-## Failure
-
-If Claude Code cannot create fresh native subagents, stop the workflow and
-report that review-loop requires native planner, reviewer, and coder subagent
-support.
+只有宿主能为当前会话注册临时角色时，临时角色才有效。项目角色需要用户明确确认，并执行 `/agents` 重新加载或重启会话。
+
+## 启动角色
+
+首次需要时，以具名原生子 Agent 启动 planner 和 coder；后续方案轮次可以复用原 planner，后续代码轮次也可以复用原 coder。不得在 planner 与 coder 之间复用同一个实例。
+
+`plan-reviewer` 和 `code-reviewer` 的每一轮评审都必须通过 Claude Code 原生 Agent/Task 工具创建全新独立任务；不得恢复或复用任何历史 reviewer 任务，也不得继承父级会话、planner 或 coder 的任何上下文。任务消息必须再次明确这是当前轮次新建的独立实例。Finalize 会校验 `--agent-id` 未在历史 reviewer-run 中出现。如果宿主支持工具允许/拒绝配置，将 reviewer 的工具限制为只读检查。
+
+每轮 reviewer 执行以下步骤：
+
+1. 运行 `review-manager.js --task-id <id> --kind plan|code --round N --prepare`。
+2. 将返回的提示词原样传给对应 reviewer 角色。
+3. 确认 reviewer 以本轮全新且不继承上下文的原生任务拉起，Agent ID 未用于任何之前轮次，只返回一份符合固定格式的 Markdown 文档，且不得写入仓库。
+4. 将响应保存到仓库外的临时文件。
+5. 运行 `review-manager.js ... --finalize --input <file> --agent-id <id>`。
+
+Prepare 会绑定输入摘要和当前 Git 树，并把 `diffs/code-diff-N.patch` 作为代码 reviewer 与人工共同使用的评审交接产物。Finalize 会重建请求，并在写入不可变 reviewer-run 和规范评审前拒绝输入、工作树或评审 patch 漂移。宿主原生 reviewer 配置只记录在 reviewer-run 的执行证据中，不信任 reviewer 自报配置，也不写入评审 Markdown。
+上下文隔离由上述启动方式保证。
+
+所有需展示给用户或等待用户确认的自然语言产物必须使用中文；平台命令、路径、协议字段和枚举值可保留原文。
+
+## 失败处理
+
+如果 Claude Code 无法创建新的原生子 Agent，停止工作流，并用中文说明 review-loop 需要原生 planner、reviewer 和 coder 子 Agent 支持。