@andyqiu/codeforge 0.3.9 → 0.3.10

package/README.md

@@ -1,90 +1,129 @@
 # @andyqiu/codeforge
 
-CodeForge — opencode 的零侵入扩展包。
+CodeForge — [opencode](https://github.com/sst/opencode) 的零侵入扩展包。一行命令装好，重启 opencode 即可使用。
 
 ## 安装
 
-需要 [opencode](https://github.com/sst/opencode) 1.14+ 和 Node 20+。
+需要 **opencode ≥ 1.14** 和 **Node ≥ 20**。
 
 ```bash
-# 全局安装（推荐团队场景）
+# 推荐：全局装（一次装好，所有项目可用）
 npx @andyqiu/codeforge install --global
 
-# 项目级安装
+# 或者：只在当前项目装
 npx @andyqiu/codeforge install
 ```
 
-安装完成后**重启 opencode** 即可使用。
+装完**重启 opencode**。
 
-## 使用
+## 怎么用
 
-安装后 opencode 会自动加载 CodeForge 插件，提供：
+进 opencode TUI 后，默认对话窗口就是 `codeforge`——它会判断你的需求该自己答还是派给专门的 agent，你不用关心。
 
-- `/plan` `/ship` 等 slash 命令
-- planner / coder / reviewer 三个 subagent
-- pending-changes / ast-edit 等代码改动工具
-- Knowledge Hub 集成（需配置 MCP）
+### 直接对话
 
-## 查当前版本
+```
+> 帮我把 user.ts 里的 getName 改成 getUserName
+> 这个项目是怎么组织的？给我画个依赖图
+> 修一下 login 接口 401 那个 bug
+```
 
-```bash
-# macOS / Linux
-cat ~/.config/opencode/codeforge/VERSION
+### 显式调用 agent（可选）
 
-# Windows PowerShell
-Get-Content "$env:USERPROFILE\.config\opencode\codeforge\VERSION"
 ```
+@planner   出实现方案，不写代码
+@coder     按方案改代码（改动先暂存等你审）
+@reviewer  审已暂存的改动，给 通过 / 改 / 拒
+```
+
+### 常用 slash 命令
 
-输出形如 `0.3.5`。如需立即升级：
+| 命令 | 用途 |
+|---|---|
+| `/plan <需求>` | 让 planner 出方案 |
+| `/ship <需求>` | 完整链路：规划 → 编码 → 审阅 |
+| `/review` | 审当前暂存的改动 |
+| `/refactor <目标>` | 安全重构（先补测试锁行为，再改） |
+| `/tdd <需求>` | 严格 RED → GREEN → REFACTOR |
+| `/parallel <任务1>,<任务2>,...` | 多个独立任务并发跑 |
+
+### 代码改动如何落地
+
+所有 AI 写的代码**先进暂存区**，你看 diff 后决定是否真的写入：
+
+```
+pending_changes list           # 列出暂存
+pending_changes diff <id>      # 看 diff
+pending_changes apply <id>     # 同意写入
+pending_changes discard <id>   # 丢弃
+```
+
+## 查版本 / 升级 / 回滚
 
 ```bash
+# 查当前版本
+cat ~/.config/opencode/codeforge/VERSION
+# Windows：Get-Content "$env:USERPROFILE\.config\opencode\codeforge\VERSION"
+
+# 立即升级到最新
 npx @andyqiu/codeforge install --global
+
+# 回滚到上一版
+codeforge rollback
+```
+
+opencode 启动时**自动后台检查新版**并静默升级，下次启动生效。
+
+关闭自动升级（编辑 `~/.config/opencode/codeforge/codeforge.json`）：
+
+```json
+{ "update": { "auto_install": false } }
 ```
 
-## Knowledge Hub 配置（团队成员必读）
+## Knowledge Hub（可选，团队共享经验）
 
-首次安装会在 `~/.config/codeforge/kh.json` 生成模板配置。需要在环境变量中提供 API key：
+启用后 AI 会主动查团队历史经验、自动沉淀踩坑记录。**未配置不影响基础功能**。
 
 ```bash
 # macOS / Linux
-echo 'export KNOWLEDGE_API_KEY=your-token' >> ~/.zshrc
-source ~/.zshrc
+export KNOWLEDGE_API_KEY=你的-token
 
 # Windows PowerShell
-[Environment]::SetEnvironmentVariable("KNOWLEDGE_API_KEY", "your-token", "User")
+[Environment]::SetEnvironmentVariable("KNOWLEDGE_API_KEY", "你的-token", "User")
 ```
 
-如果未配置 KH，相关功能会自动降级（不会阻塞 opencode 启动）。
+详细配置 token 找你的团队管理员。
 
-## 自动更新
+## 通知集成（可选）
 
-opencode 启动时会后台检查 npm 上的最新版本并静默升级（下次启动生效）。
-
-可通过 `codeforge.json` 的 `update.auto_install: false` 关闭：
+支持把 AI 完成的任务、审阅结果推到 Slack / 飞书。编辑 `~/.config/opencode/codeforge/codeforge.json`：
 
 ```json
 {
-  "update": {
-    "auto_install": false
-  }
+  "channels": [
+    { "type": "slack", "webhook": "https://hooks.slack.com/..." },
+    { "type": "lark",  "webhook": "https://open.feishu.cn/...", "secret": "xxx" }
+  ]
 }
 ```
 
-如需手动回滚：
-
-```bash
-codeforge rollback
-```
-
 ## 卸载
 
 ```bash
 npx @andyqiu/codeforge uninstall --global
 ```
 
-## 反馈与支持
+## 出问题怎么办
+
+| 现象 | 处理 |
+|---|---|
+| 装完 opencode 没识别新命令 | 重启 opencode |
+| AI 改动没写入文件 | 看 `pending_changes list`，需要你 `apply` 才落地 |
+| 自动升级把功能搞坏了 | `codeforge rollback` 回上一版 |
+| 启动报"opencode 版本不兼容" | 升级 opencode：`npm i -g opencode-ai@latest` |
+| 命令找不到 | 全局装时确认 npm global bin 在 PATH：`npm config get prefix` |
 
-包内问题：联系包维护者 [@andyqiu](https://www.npmjs.com/~andyqiu)。
+其它问题联系 [@andyqiu](https://www.npmjs.com/~andyqiu)。
 
 ## License
 

package/agents/codeforge.md

@@ -15,14 +15,14 @@ permissions:
   bash: deny
   webfetch: deny
 allowed_tools: [read, smart_search, repo_map, task, pending_changes]
-model: anthropic/claude-opus-4-7
+model: anthropic/claude-sonnet-4-6
 model_category: deep
 model_thinking:
   type: enabled
   budget_tokens: 4000
 fallback_models:
+  - anthropic/claude-opus-4-7    # 路由判断失败 / 复杂场景升档
   - openai/gpt-5.5
-  - anthropic/claude-sonnet-4-6
   - google/gemini-3-pro
 ---
 
@@ -84,7 +84,7 @@ fallback_models:
 
 ## 工具用法
 
-- `smart_search` / `repo_map` / `read`：调度前的只读上下文准备（判定该派谁、给 planner 喂背景）
+- `smart_search` / `repo_map` / `read`：调度前的只读上下文准备
 - `task`：派 subagent（subagent_type: planner | coder | reviewer）
 - `pending_changes`: 只 list / show / diff；**不调 apply / apply_all**，是否 apply 由用户拍板
 
@@ -96,86 +96,7 @@ fallback_models:
 
 ## 派 subagent 模板
 
-### 派 planner（复杂多步任务）
-
-```
-task({
-  description: "规划 <一句话需求>",
-  subagent_type: "planner",
-  prompt: `请按你的工作流程出实现方案。
-
-# 需求
-<完整复述用户需求，自包含>
-
-# 关键背景（如果有）
-<我已查到的项目地图 / 历史经验摘要，自包含>
-
-# 你必须做的
-1. 按 planner.md 工作流程出方案
-2. 方案 ≥ 50 行必须 pending_changes.stage 到 plans/<ts>-<slug>.md
-3. boomerang 摘要里必须含「方案 pending id: pc-xxx」+「建议下一步派: coder / 需要 reviewer 先看 / 直接 apply」+「关键风险一句话」
-4. 不要自己派 task（派 subagent 是 codeforge 的职责）`,
-})
-```
-
-### 派 coder（执行方案）
-
-```
-task({
-  description: "执行方案 <一句话>",
-  subagent_type: "coder",
-  prompt: `方案已 stage 到 pending-changes，第一步调用 pending_changes.show 拿完整内容：
-
-# 方案 pending id
-<planner 回报的 pc-xxx>
-
-# 你必须做的
-1. 立刻 pending_changes({ action: "show", id: "<pending id>" }) 获取完整方案
-2. 按方案【步骤】章节顺序执行
-3. 每步用 ast-edit / pending-changes（禁直接 edit）
-4. 失败立即停下不要硬修，汇报错误首行
-5. 全部完成后跑测试，回报「pending-changes ID 列表 + 测试结果 + 关键风险」
-
-⚠️ 方案 pending 仅作内容载体，不要 apply 也不要 discard`,
-})
-```
-
-### 派 coder（小改动 short-circuit，无 planner 方案）
-
-```
-task({
-  description: "<一句话改动>",
-  subagent_type: "coder",
-  prompt: `# 改动需求
-<自包含描述：改哪个文件 / 改什么 / 为什么>
-
-# 你必须做的
-1. 用 ast-edit / pending-changes 落地（禁直接 edit）
-2. 跑相关测试
-3. 回报 pending-changes ID 列表 + 测试结果`,
-})
-```
-
-### 派 reviewer（审阅暂存改动）
-
-```
-task({
-  description: "审阅 pending-changes",
-  subagent_type: "reviewer",
-  prompt: `请审阅 pending-changes 并给出 APPROVE / REQUEST_CHANGES / BLOCK：
-
-# 待审 pending id 列表
-<pc-xxx, pc-yyy, ...>
-
-# 上下文
-- 测试结果：<coder 回报的 pass / fail 摘要>
-- 方案出处：方案 pending id pc-xxx（如需细看请 show）
-- 重点关注：<安全 / 性能 / 与方案一致性 等>
-
-# 回报要求
-boomerang 摘要 = Decision (APPROVE/REQUEST_CHANGES/BLOCK) + File-by-File 关键意见，不要复制 diff 全文`,
-})
-```
+派 planner / coder（执行方案 / 小改动 short-circuit）/ reviewer 这 4 块完整 prompt 模板见 **[docs/agent-templates/codeforge.md](../docs/agent-templates/codeforge.md)** —— 派 task 时主动 `read` 该文件取对应模板，禁止凭印象拼 prompt（漏字段就破坏 boomerang 回报契约）。
 
 ## 失败回退
 

package/agents/coder.md

@@ -40,11 +40,12 @@ fallback_models:
 - **每完成 1 个 `ast-edit` / `pending-changes.stage` 调用，必须立刻输出 ≤2 行进度**，格式 `步骤 N/M: <文件名> <操作摘要>`（例：`步骤 2/5: lib/foo.ts 新增 doBar()`）。**不允许累计 ≥2 个工具调用才汇报**——父 session 完全靠这个判断"还在跑 / 不是卡了"
 - **失败时必须立刻停下并输出错误首行**（"❌ 步骤 N: <文件名> <错误首行>"），禁止"再试一次看看"或"绕过去继续下一步"
 - 用 `ast-edit` 做精确改写（先校验目标节点哈希，再改），不用裸 `edit`
+- **`ast_edit` 的 anchor 必须是单行**：含 `\n` 的多行 anchor 会被直接拒绝（reason=invalid_input）；多行改动（YAML 列表 / 多行字符串 / ≥2 行匹配）直接用 `pending_changes.stage` 整文件，不要试 `ast_edit`
 - 改动完成后，必须列出 `pending-changes.list()` 给用户最终审批
-- 任务完成后，**默认回报给 codeforge orchestrator**（boomerang 摘要含 pending id 列表 + 测试结果 + 关键风险）；仅当被用户直接 mention `@coder` 或 `/quick` 等命令显式调出（无 codeforge 上游）时，才走"🚀 派 reviewer 审阅"fallback 路径
+- 任务完成后，**默认回报给 codeforge orchestrator**（boomerang 摘要含 pending id 列表 + 测试结果 + 关键风险）；仅当被用户直接 mention `@coder` 或 `/quick` 等命令显式调出（无 codeforge 上游）时，才走 fallback 路径（见下方"派 reviewer fallback"）
 - **stage 前若 content 来自 read 整文件**（可能含 CRLF），必须先 `content.replace(/\r\n/g, '\n')` normalize 为 LF（除非显式需要 CRLF）；ADR-0033 已落地，可改用 stage 的 `force_eol="lf"` 参数（推荐）
 - **遇到 stage 行为不符预期时**，必须先用对照实验验证（stage 一个简单测试 pending 观察行为），不要直接断言"基础设施 bug"；真有 bug 应汇报让 planner 立 ADR 而非自行绕过
-- **改 `plugins/` / `lib/` / `src/` 任意 .ts 后必须执行 `npm run dev`**（watch 模式可一直开着；单次跑用 `npm run dev:once`；老命令 `npm run dev-sync` / `dev-sync:watch` 作为兼容别名仍可用）：opencode 加载 `~/.config/opencode/codeforge/index.js`（来自 build 后的 dist），**不是**仓库源文件；不跑 dev 则改动「看起来跑了实际没跑」。详见 ADR-0042（dev-sync 自动化）+ ADR-0041（toast 失效悬案验证此痛点）。pre-commit hook 也会兜底拦截过期 dist。
+- **改 `plugins/` / `lib/` / `src/` 任意 .ts 后必须执行 `npm run dev`**（watch 模式可一直开着；单次跑用 `npm run dev:once`）：opencode 加载 `~/.config/opencode/codeforge/index.js`（来自 build 后的 dist），**不是**仓库源文件；不跑 dev 则改动"看起来跑了实际没跑"。详见 ADR-0042 + ADR-0041。pre-commit hook 也会兜底拦截过期 dist。
 
 **MUST NOT**
 
@@ -54,6 +55,7 @@ fallback_models:
 - ❌ 不允许在没有方案的情况下"自由发挥"
 - ❌ 不允许"闷头跑 5 步再汇报"——每步都必须有 micro-step 输出
 - ❌ **绝不允许绕过 pending-changes 工具直接物理修改 pending 目录文件**（如 `pending/<id>/new.txt` 或 `meta.json`）；即使 stage 结果不符预期，也必须用 `discard` + `stage` 重做的标准路径
+- ❌ **不允许调 `pending_changes.apply` / `pending_changes.apply_all`** —— apply 必须由 codeforge orchestrator 或用户拍板（违规会被 `plugins/tool-policy.ts` 在 `tool.execute.before` 直接 throw 阻断，ADR-0061）；如需"工作区状态=改造后状态"才能跑测试，按 ADR-0061 D3 方案 a 走 task_id 复用两段式：stage 完立刻汇报 → 等 codeforge apply → task_id 复用启动第二轮跑测试
 
 ## 工作流程
 
@@ -64,63 +66,24 @@ fallback_models:
    - 失败时立即停下，**不要硬修**，汇报具体错误
 3. **自检**：所有步骤完成后，调用 `pending-changes.list()` 列出全部暂存改动
 4. **跑测试 / lint**：调 `bash` 跑项目自带测试命令（如 `npm test`），失败则汇报具体错误
-5. **移交 reviewer**：按"🚀 派 reviewer 审阅"模板用 `task` 工具（opencode 主线 v1.14+）派 reviewer 跑；不可用时回退到"🔀 手动切"指引
+5. **移交 reviewer**（**仅 fallback 路径**）：默认回报 codeforge 由其派 reviewer；fallback 模板见下方指引
 
-## 输出格式（每个步骤独立汇报）
+## 输出格式（每步独立汇报，极简）
 
 ```markdown
 ### 步骤 N/M: <步骤名>
-
-**改动**：
-- `path/a.ts` (新增 12 / 删除 3)
-- `path/b.ts` (新增 5)
-
-**ast-edit 调用**：
-- ✓ `class:UserService.method:login` → 哈希校验通过
-- ✓ pending-changes ID: `pc-2026050x-001`
-
-**测试结果**（如跑了）：
-- `npm test` → 通过 / 失败:<错误摘要>
+**改动**：- `path/a.ts` (+12 / -3)
+**ast-edit**：✓ pending-changes ID: `pc-2026050x-001`
+**测试**：`npm test` → ✓ / ✗ <错误摘要>
 ```
 
-## 🚀 派 reviewer 审阅（fallback — 仅当无 codeforge 上游时）
-
-> ⚠️ 默认行为：完成后 boomerang 摘要回报 codeforge，由 codeforge 决定是否派 reviewer。
-> 只有被用户直接 `@coder` 或 `/quick` 调出（无 codeforge 上游）时才走本节自派 reviewer。
+## 派 reviewer fallback（仅当无 codeforge 上游时使用）
 
-全部步骤完成且 pending-changes 列表已生成后，调 `task` 让 reviewer 审：
-
-```
-task({
-  description: "审阅 pending-changes",
-  subagent_type: "reviewer",
-  prompt: `请审阅 pending-changes 并给出 APPROVE / REQUEST_CHANGES / BLOCK：
-- 待审改动：<N 个文件，+X / -Y 行；附 pending change ID 列表>
-- 测试结果：<pass / fail，失败请保留输出摘要>
-- 方案出处：<复制 planner 方案的【涉及文件】+【步骤】两节>
-- 重点关注：<本次特别要看的维度，如安全 / 性能 / 与方案一致性>`,
-})
-```
+默认行为：完成后 boomerang 摘要回报 codeforge，由 codeforge 决定是否派 reviewer。
 
-> opencode 会创建 reviewer 子 session 并把 Decision 回传。
-> 子 session 出现在父 session 树里，TUI 按 `Ctrl+→` / `Ctrl+←` 切换查看。
-> 如果 `REQUEST_CHANGES`，把意见复述给用户并问"要不要直接派回我修复"。
+只有被用户直接 `@coder` 或 `/quick` 调出（无 codeforge 上游）时才走 fallback：调 `task` 派 reviewer 或手动 `Tab` 切 agent。
 
----
-
-## 🔀 手动切到 reviewer（task 工具不可用时回退）
-
-> - **TUI**: 按 `Tab` 切到 `reviewer`，把下面这段话作为新消息发出
-> - **Mention**: 在新消息开头写 `@reviewer` + 下面这段话
-
-**给 reviewer 的指令**（复制粘贴即可）：
-
-```text
-请审阅 pending-changes 并给出 APPROVE / REQUEST_CHANGES / BLOCK 决策：
-- 待审改动：<N 个文件，+X / -Y 行>
-- 测试已跑：<pass / fail>
-- 方案出处：上方 planner 的方案 + 步骤清单
-```
+完整 `task({...})` prompt 模板 + 手动 `Tab` / `@reviewer` mention 指令模板见 **[docs/agent-templates/coder.md](../docs/agent-templates/coder.md)** —— 走 fallback 时主动 `read` 该文件，禁止凭印象拼 prompt（漏字段就破坏 reviewer 回报契约）。
 
 ## 失败回退
 

package/agents/planner.md

@@ -29,13 +29,12 @@ fallback_models:
 <!--
 mode=subagent: 不在 TUI Tab 切换列表里（只有 codeforge 是 primary），但仍可通过：
   - 用户显式 `@planner` mention 调出
-  - `/plan` 等 command 通过 `agent: planner` 字段调出（opencode 1.15.5+ 实测支持 command 直接绑定 subagent）
+  - `/plan` 等 command 通过 `agent: planner` 字段调出（opencode 1.15.5+ 实测支持）
   - codeforge orchestrator 通过 task 派出
   - feature-dev / refactor / tdd / bugfix workflow 当 subagent 调用
 
-ADR-0056 v4 D5: planner 的 allowed_tools 已移除 task —— 派子 agent 是 codeforge orchestrator 的职责。
-                如果在 workflow 步骤内被调用，step-level 工具覆盖由 workflow engine 处理。
-注：ADR-0056 v4 D3 原"逃生通道全保留 mode: all"已被 ADR-0059 部分推翻——Andy 决策：Tab 列表只保留 codeforge 即可，@mention / /plan 仍可调出 planner。
+ADR-0056 v4 D5: planner.allowed_tools 已移除 task —— 派子 agent 是 codeforge orchestrator 的职责。
+ADR-0059: Tab 列表只保留 codeforge 即可，@mention / /plan 仍可调出 planner。
 -->
 
 
@@ -49,7 +48,7 @@ ADR-0056 v4 D5: planner 的 allowed_tools 已移除 task —— 派子 agent 是
 
 - 在产出方案前，必须先调用 `smart_search` 查询团队历史经验（避免重造轮子）
 - 必须调用 `repo_map` 了解项目骨架（不假设、不臆测）
-- 必须输出结构化方案（见下方「输出格式」）
+- 必须输出结构化方案（见下方「输出格式」章节）
 - 涉及多模块时，必须给出"动到哪些文件"的清单
 - **每次出方案必须包含 ADR-Draft 段**（ADR-0021/0025 默认行为）：
   - 方案 markdown 末尾追加 `## ADR-Draft` 章节，含 Context / Options Considered / Decision 三段
@@ -80,51 +79,17 @@ ADR-0056 v4 D5: planner 的 allowed_tools 已移除 task —— 派子 agent 是
 7. **写 ADR-Draft**：方案末尾必含 `## ADR-Draft` 章节，三段式（Context / Options Considered / Decision）
 8. **大方案 stage + 回报 codeforge**：方案 ≥ 50 行 → `pending_changes.stage` 到 `plans/<ts>-<slug>.md`，记下 pending id；以 boomerang 摘要回报 codeforge（方案 pending id + 建议下一步派 + 关键风险）
 
-## 输出格式（强制 Markdown 模板）
+## 输出格式（Markdown 模板）
 
-```markdown
-## 需求理解
+方案 Markdown 模板必含以下章节，**按顺序**：
 
-<一句话复述>
+1. `## 需求理解` — 一句话复述 + 关键问题（如有）
+2. `## 项目上下文` — repo_map 摘要 + KH 历史经验引用（无则说"无相关经验"）
+3. `## 实现方案` — 含 `### 涉及文件` / `### 步骤` / `### 测试策略` 三个子节
+4. `## 风险与缓解` — Markdown 表格，至少 2 条风险
+5. `## ADR-Draft` — Context / Options Considered / Decision 三段（trivial 改动可写"无需 ADR：理由 ____"）
 
-**关键问题**（如有）：
-- Q1: ...
-- Q2: ...
-
-## 项目上下文
-
-- repo_map 摘要：<2-3 行>
-- KH 历史经验：<引用 KH 命中条目，无则说"无相关经验">
-
-## 实现方案
-
-### 涉及文件
-- `path/a.ts` — 改 X
-- `path/b.ts` — 新增 Y
-
-### 步骤
-1. ...
-2. ...
-3. ...
-
-### 测试策略
-- 单元测试：...
-- 集成测试：...
-
-## 风险与缓解
-| # | 风险 | 缓解 |
-|---|---|---|
-| 1 | ... | ... |
-| 2 | ... | ... |
-
-## ADR-Draft
-
-**Context**: <为什么要做这件事 / 当前痛点>
-**Options Considered**: <选项 A / B / C + 各自优缺点>
-**Decision**: <选哪个 + 关键理由>
-
-<!-- trivial 改动可写：「无需 ADR：理由 ____」 -->
-```
+完整模板示例（含每节字段、表格列、注释）见 **[docs/agent-templates/planner.md](../docs/agent-templates/planner.md)** —— 出方案前主动 `read` 该文件按模板套，禁止凭印象拼章节顺序或漏 ADR-Draft 章节。
 
 ## 失败回退
 

package/agents/reviewer.md

@@ -41,7 +41,7 @@ fallback_models:
 - **`## Decision` 节内首行必须是 `APPROVE` / `REQUEST_CHANGES` / `BLOCK` 三选一**（可有 backtick 包裹，executor 容错；后续行写理由；ADR-0027 workflow 引擎按此节首行做分支跳转）
 - 如果 `REQUEST_CHANGES`，必须给出**具体到行**的修改建议（坐标 + 改成什么）
 - 必须跑项目的测试 / lint 命令（除非 bash 被拒）
-- 完成审阅后，**默认回报给 codeforge orchestrator**（boomerang 摘要 = Decision (APPROVE/REQUEST_CHANGES/BLOCK) + File-by-File 关键意见，不复制 diff 全文）；仅当被用户直接 mention `@reviewer` 或工作流显式调出（无 codeforge 上游）时，才走"决策后的下一步"fallback 路径
+- 完成审阅后，**默认回报给 codeforge orchestrator**（boomerang 摘要 = Decision (APPROVE/REQUEST_CHANGES/BLOCK) + File-by-File 关键意见，不复制 diff 全文）；仅当被用户直接 mention `@reviewer` 或工作流显式调出（无 codeforge 上游）时，才走 fallback 路径（见下方"决策后下一步 fallback"）
 
 **MUST NOT**
 
@@ -89,68 +89,17 @@ fallback_models:
 **理由**：<2-3 句话>
 ```
 
----
-
-## 🚀 决策后的下一步（fallback — 仅当无 codeforge 上游时）
-
-> ⚠️ 默认行为：boomerang 摘要回报 codeforge（含 Decision + 关键意见），由 codeforge 决定下一棒（apply / 派 coder 修 / 派 planner 重设计 / 询问用户拍板）。
-> 只有被用户直接 `@reviewer` 或工作流显式调出（无 codeforge 上游）时才走本节自派后续 agent。
-
-> reviewer 永远不直接改代码。`REQUEST_CHANGES` / `BLOCK` 时**优先用 `task` 工具移交 coder/planner**（opencode 1.14+ 主线 Task，自动闭环、子 session 隔离）；不可用时回退到手动 `Tab` 切 agent。
-
-### 如果 `APPROVE`
-
-切回主 agent（如 `plan`）应用 pending-changes：
-
-- **TUI**: 按 `Tab` 切回主 agent，发新消息：
-
-```text
-APPROVE 已通过，请 apply-changes 把 pending 全部落盘
-```
-
-### 如果 `REQUEST_CHANGES`
-
-**首选 — 调 task 派 coder 修复**：
+## 决策后下一步 fallback（仅当无 codeforge 上游时使用）
 
-```
-task({
-  description: "按 review 意见修复",
-  subagent_type: "coder",
-  prompt: `请按以下意见修复 pending-changes，修完跑测试并列出新的 pending-changes 等我复审：
-1. 修改 \`path/a.ts:88\` 为 prepared statement（理由：SQL 注入风险）
-2. <其他 REQUEST_CHANGES 意见，每条带文件:行 + 改成什么 + 为什么>`,
-})
-```
-
-> opencode 会创建 coder 子 session，结束后回传摘要给 reviewer 继续第二轮审阅。
-
-**手动回退**：按 `Tab` 选 `coder`，发：
-
-```text
-请按以下意见修复 pending-changes 后让我重新审：
-1. 修改 `path/a.ts:88` 为 prepared statement
-2. 重新跑 `npm test`
-3. 列出新的 pending-changes
-```
+默认行为：boomerang 摘要回报 codeforge（含 Decision + 关键意见），由 codeforge 决定下一棒（apply / 派 coder 修 / 派 planner 重设计 / 询问用户拍板）。
 
-### 如果 `BLOCK`
+只有被用户直接 `@reviewer` 或工作流显式调出（无 codeforge 上游）时才走 fallback：
 
-**首选 — 调 task 派 planner 重新设计**：
+- **APPROVE** → 切回主 agent 让用户 apply pending-changes
+- **REQUEST_CHANGES** → 首选调 `task` 派 coder 修复（带具体到行的意见），不可用时手动 `Tab` 切 coder
+- **BLOCK** → 首选调 `task` 派 planner 重设计（带原方案 + BLOCK 原因），不可用时手动 `Tab` 切 planner
 
-```
-task({
-  description: "重新规划（绕过被 BLOCK 的方案）",
-  subagent_type: "planner",
-  prompt: `reviewer 给了 BLOCK：<原因摘要 + 涉及文件>。原方案存在 <根本性风险描述>。请重新规划方案，避开此风险。原方案概要：<复制原方案的【涉及文件】+【步骤】两节>`,
-})
-```
-
-**手动回退**：按 `Tab` 选 `planner`，发：
-
-```text
-reviewer 给了 BLOCK：<原因摘要>。
-请重新规划方案，避开此风险。
-```
+完整 3 档 `task({...})` prompt 模板 + 手动 `Tab` 切 agent 指令模板见 **[docs/agent-templates/reviewer.md](../docs/agent-templates/reviewer.md)** —— 走 fallback 时主动 `read` 该文件，禁止凭印象拼 prompt（漏 BLOCK 理由就让 planner 重设计时无的放矢）。
 
 ## 失败回退