plannotator

plannotator

当任务是对一个评审材料包进行分类、开启最精简且忠实的可视化评审路径，并将广泛的规划、PR 政策和 UI 评审工作排除在入口之外时，使用此技能。

plannotator 不是规划工具。 它是位于以下环节之间的人工审批关卡：

• 计划／规范创建（task-planning、ralph）
• 编排／运行时管理（jeo、task-planning、bmad）
• 更广泛的 PR／代码评判（code-review）
• 渲染后 UI 的问题标注（agentation）
• 干净的浏览器验证（browser-harness）

请先阅读这些支持文档：

• references/intake-packets-and-route-outs.md
• references/platform-setup.md
• references/notes-and-troubleshooting.md

何时使用此技能

• 编码 Agent 已生成实施计划，需要人工在开始编码前批准或要求修改。
• 已有具体的 git 差异、提交范围或 PR，评审者希望通过浏览器针对特定行提供反馈。
• 需要对规范、PRD、架构说明或生成的计划包等 markdown 文件进行可视化评审并提供修改反馈。
• 用户需要将 plannotator 接入 Claude Code、Gemini CLI、Codex CLI 或 OpenCode，且主要任务是为评审流程进行设置。
• 评审流程已经存在，但远程模式、稳定 URL／端口或特定平台行为不稳定，需要针对性排查。

何时不使用此技能

• 主要任务是编写或完善计划／规范本身 → task-planning、ralph 或 survey
• 主要任务是广泛的 PR 政策、合并标准、风险评判或代码所有者审批 → code-review
• 主要任务是针对精确的渲染后 UI 提出评审意见，并据此推动前端修复 → agentation
• 主要任务是干净、可随时丢弃的浏览器自动化或确定性网站验证 → browser-harness
• 主要任务是任务编排、看板状态或多 Agent 路由 → jeo、task-planning、bmad
• 主要任务是笔记分类、Wiki 策展或长期笔记系统管理 → obsidian、llm-wiki

说明

第 1 步：先对评审材料包进行分类

在讨论命令之前，先将请求归一化为一个主要材料包。

plannotator_intake:
  primary_packet: plan-review | diff-review | markdown-review | platform-setup | troubleshooting
  artifact_ready: yes | no
  artifact_type: plan | git-diff | pr | markdown-spec | generated-response | unknown
  platform: claude | gemini | codex | opencode | mixed | unknown
  trigger_mode: native-hook | manual-review | unknown
  feedback_goal: approve | request-changes | annotate | archive | unknown
  repo_context: git-repo | markdown-only | remote-container | unknown
  confidence: high | medium | low

默认采用最精简、最明显的解释：

• 现有实施计划 → plan-review
• 现有代码更改／PR／提交范围 → diff-review
• 现有规范或 markdown 文件 → markdown-review
• 安装／集成问题 → platform-setup
• 远程／浏览器／状态不稳定问题 → troubleshooting

第 2 步：确认具体的评审材料是否存在

只有在有具体材料可供评审时，plannotator 才能发挥作用。

检查清单：

1. 计划、差异、PR、markdown 文件或生成的响应已经存在。
2. 用户需要的是评审，而不是生成计划。
3. 对于差异评审，git 仓库、PR URL 或明确的提交范围必须存在。
4. 对于 markdown／规范评审，必须能确定文件或生成的材料。
5. 对于笔记导出，必须已配置保存／集成；将其视为次要事项，而不是主要材料包。

如果材料不存在，应转交其他工具，而不是强行使用评审工具。

第 3 步：恰好选择一个评审材料包

使用 references/intake-packets-and-route-outs.md 中的路由器，选择一个主要材料包：

• plan-review
• diff-review
• markdown-review
• platform-setup
• troubleshooting

将其他事项列为后续任务，不要将其并列为共同负责人。

第 4 步：运行选定的数据包

• 计划审查 → 确认运行时可以将计划交给 plannotator，实际可用时采用原生/钩子路径，每个步骤标注一个问题，并以批准、请求修改或归档/保存结束。
• 差异审查 → 使用具体目标并启动最精简的差异数据包：

  bash scripts/review.sh
  bash scripts/review.sh HEAD~1
  bash scripts/review.sh main...HEAD
  

• Markdown 审查 → 确认规范/PRD/架构文件存在，直接使用标注/审查模式；如果运行时仅支持标注，而不支持更完善的审批流程，请明确说明。
• 平台设置 → 从以下内容开始：

  bash scripts/install.sh
  bash scripts/check-status.sh
  

  然后使用 references/platform-setup.md。
• 故障排除 → 从以下内容开始：

  bash scripts/check-status.sh
  bash scripts/configure-remote.sh
  

  然后使用 references/notes-and-troubleshooting.md。

第 5 步：明确说明手动与钩子支持的实际情况

• Claude 和 Gemini 是最明确适合原生/钩子驱动计划审查的平台。
• Codex 提供公开钩子，但上游 plannotator 仍将手动差异/Markdown 审查或部分设置记录为实际可用的路径。
• OpenCode 用户明确表示，当自动调用过于频繁时，他们希望有更多手动控制。

不要将其简化为“所有平台的工作方式都一样”。

第 6 步：积极引导相关工作

• 计划/规范的创建或完善 → task-planning、ralph、survey
• 编排状态或多 Agent 路由 → jeo、task-planning、bmad
• 广泛的 PR 策略、合并门控或风险判断 → code-review
• 渲染后的 UI 缺陷标注 → agentation
• 干净、一次性的浏览器验证 → browser-harness
• 除保存已审查产物之外的笔记/知识库/wiki 管理 → obsidian、llm-wiki

第 7 步：采用简短的输出约定

首选输出：

# plannotator Review Packet
- Primary packet:
- Artifact:
- Platform + trigger mode:
- Next action:
- Outcome or limitation:
- Route-outs:

对于设置内容较多的请求，请使用简短的设置说明，包含：

• 平台
• 原生钩子与手动审查的支持情况
• 安装命令
• 验证步骤
• 注意事项

示例

示例 1：批准具体计划

输入

Agent 已经提出了一个包含 6 个步骤的实施计划。我想通过可视化方式检查它，然后在开始编写代码之前选择批准计划或反馈修改意见。

良好输出方向

• 选择 plan-review
• 确认计划已经存在
• 使用运行时实际可用的审查界面
• 每个步骤标注一个问题
• 以批准或请求修改结束
• 如果计划仍不成熟，则将计划创建工作转交出去

示例 2：审查差异

输入

Agent 已经修改了三个文件。打开 main...HEAD 的可视化差异审查，让我留下有针对性的反馈。

良好输出方向

• 选择 diff-review
• 确认 Git 上下文/差异范围
• 使用 bash scripts/review.sh main...HEAD
• 将更广泛的 PR 策略审查转交给 code-review

示例 3：审查 PRD/规范产物

输入

我想标注这份架构说明，然后选择原样接受，或在继续之前反馈修改意见。

良好输出方向

• 选择 markdown-review
• 确认 Markdown 产物存在
• 说明当前平台支持原生审批还是仅支持手动标注
• 将笔记导出作为次要操作，并将 wiki/知识库管理工作转交出去

示例 4：核实 Codex 设置的实际情况

输入

为 Codex 设置 plannotator，这样我就能在代码运行前审查计划。

良好输出方向

• 选择 platform-setup
• 从安装和状态验证开始
• 如实说明目前 Codex 手动/部分支持的实际情况，不要承诺上游文档并未说明的功能对等
• 如有需要，将广泛的钩子/平台策略工作转交出去

最佳实践

1. 将 plannotator 视为可视化审批关卡，而非规划引擎。
2. 每次审查一份具体的产物。
3. 明确区分手动审查与原生钩子的差异。
4. 尽可能为每个问题添加一条批注。
5. 明确给出最终结果：批准、请求修改、仅添加批注或归档。
6. 将笔记导出作为审查材料包的辅助功能。
7. 将 PR 策略、编排和渲染 UI 评审交由相邻技能处理，不要让 plannotator 承担超出其范围的工作。

参考资料

• GitHub：backnotprop/plannotator
• 官方网站：plannotator.ai
• references/intake-packets-and-route-outs.md
• references/platform-setup.md
• references/notes-and-troubleshooting.md
• references/review-modes-and-boundaries.md