用指定 reviewer…

当需要「反复审查并修复某段代码直到 reviewer 无严重问题」时，用指定 reviewer 启动自动改进循环。

适用场景

解决思路

1. 收集三个必需输入，不要猜测：1) Target：待改进目录的绝对路径，相对路径按工作目录解析并验证目录存在；2) Reviewer：执行每次审查的已安装 skill 或 agent，必须由用户指定，没有默认值也没有内置 reviewer，判断其类型——带命名空间的 agent（如 plugin-dev:skill-reviewer）用 "kind": "agent"，已安装 skill（如 pr-review-toolkit:review-pr）用 "kind": "skill"，若两者皆可能则查会话的 skill 列表，仍不确定就问用户，若用户未指定 reviewer 就询问，不要自行挑选；3) Scope：循环可触碰的仓库相对 glob，若用户未给出，提议目标目录（<repo-relative-target>/**）并在启动前确认。
2. 定位循环脚本：循环是本插件的动态工作流 workflows/improve.js，按路径启动（scriptPath 接受解析后的绝对路径；Workflow 工具的 name 解析内置和项目工作流，marketplace 安装的可能不响应 code-improver:improve）。按顺序尝试，先命中者胜——home 目录排在 . 之前，使已安装副本优先于本 marketplace 的 checkout：1) Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"；2) Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js"（若设置的是该变量）；3) Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null。使用打印出的确切路径；其插件目录（去掉 /workflows/improve.js 的路径）即 pluginRoot。若三者皆空，尝试一次 {name: "code-improver:improve"}；若也不可用则停止并说明无法定位循环。不要手工拼路径，不要自行编造循环。
3. 用 Workflow 工具以 {scriptPath: "<步骤2的路径>", args: {...}} 调用，args 包含：target（绝对目标路径）、reviewer（{kind: "agent|skill", name: "<命名空间名>", notes: "<reviewer 应了解的关于目标的信息>"}）、scope（["<仓库相对 glob>/**"]）、pluginRoot（步骤2得到的插件目录）、maxRounds（仅当用户要求不同上限时，默认 5）。pluginRoot 让运行找到其指标收集器；仅当步骤2退化为用工作流名时才省略该键，此时工作流会自行搜索。finalize（{"version_bump": bool, "narration_strip": bool, "docs_pass": bool}）仅在覆盖默认值时提供：目标位于插件内时做版本号提升，narration strip 和 docs pass 始终执行。decision 仅在续跑时提供。
4. 工作流在后台运行、无需照看：它审查、修复、再审查，每轮修复后检查 scope，且只有在审查干净时才能完成。它从不提交，所有改动留在工作区。
5. 若 Workflow 工具不可用或被拒绝，停止并说明。不要用直接编辑就地模仿循环——ledger、scope guard 和 escalation 保证都在工作流里，内联模仿不具备这些。
6. 若结果为 halted: "reviewer-unavailable"，转达并停止：指定的 reviewer 未安装在本会话中，告知用户哪个插件提供它，安装后重跑。不要自己审查目标。
7. 循环运行期间不要结束回合：Workflow 工具立即返回 task id，结果稍后到达。交互式会话中完成通知会重新唤起你，等待它；非交互式运行（脚本、CI、eval）没有后续回合，停止会中途放弃循环，因此启动后用 TaskOutput 传返回的 task id 轮询任务（或 sleep 后重查）直到完成，再转达结果。回答「循环在跑，稍后汇报」的会话已经丢失了这次运行。
8. 如实转达结构化结果，区分很重要：converged: true 表示最后一次动作是零 critical/major 发现的审查，报告使用的轮数、剩余 minor 发现（open_minor_count）和产物路径（ledger_path、metrics）；capped: true 表示修复预算耗尽且最终审查仍发现阻塞问题，明确说「capped，未收敛」并列出 open_blocking，不要当作成功呈现；escalation 表示循环检测到未收敛（发现反复出现、数量不降、或修复使问题转移），把 escalation 消息和 finding id 转达给用户——这需要设计决策而非更多轮次；halted 表示某个 guard 触发（scope 违规、未登记的新文件、reviewer 死亡或不可用、或 finalize 阶段自身编辑未通过其后的检查），转达 violations/new_untracked_files 中的路径、finalize_regressions 中的位置和 notes；notes 始终随结果返回，要呈现出来，其中包含诸如「已初始化 git 仓库」之类的醒目警告。
9. escalation 后继续：循环按设计在 escalation 时停止。用户决定后，用相同的 target 和 reviewer 启动新运行，并加上 {"decision": "<用户的裁决，逐字>"}。新运行会重新加载磁盘上的 ledger，因此每个 finding、拒绝和裁决都会延续——轮次重启，但无需重新推导。
10. 要停止运行中的循环，停止工作流任务（TaskStop）；磁盘上的 ledger 截至最后一轮是最新的，重跑会从它继续。

适用边界 · 注意事项

• 目标是 Claude Code skill：改用 skill-improver 入口，它会接好正确的 reviewer
• 目标是分支/PR：改用 pr-improver 入口，它从 diff 推导 scope
• 只是一次性审查：直接派发 reviewer；循环的价值在于迭代
• 只是快速单点修复：直接编辑文件