用途
plannotator 是一个“路由优先”的可视化审批关卡（visual approval gate），用于 AI 智能体计划、Markdown 规格文档和代码差异（diff）的人工审查。它本身不是规划器，而是位于以下环节之间的人工审批门：
- 计划/规格创建（task-planning、ralph）
- 编排/运行时归属（jeo、task-planning、bmad）
- 更广泛的 PR/代码判断（code-review）
- 渲染 UI 缺陷标注（agentation）
- 干净的浏览器验证（browser-harness）
其核心定位是：当任务需要对一个审查包进行分类、打开最小且诚实的可视化审查路径，并把宽泛的规划、PR 策略、UI 批评等工作排除在门外时使用。
主要能力
- 将审查请求归一化为一个主审查包（primary packet）：plan-review、diff-review、markdown-review、platform-setup、troubleshooting。
- 对具体待审产物进行存在性校验（计划、diff、PR、Markdown 文件或生成响应）。
- 提供差异审查脚本路径，例如：
- bash scripts/review.sh
- bash scripts/review.sh HEAD~1
- bash scripts/review.sh main...HEAD
- 提供平台配置与状态检查脚本：
- bash scripts/install.sh
- bash scripts/check-status.sh
- bash scripts/configure-remote.sh
- 支持计划审查、差异审查、Markdown 审查、平台配置与故障排查五类流程。
- 明确区分“原生钩子（native-hook）”与“手动审查（manual-review）”两种触发模式。
使用方式
技能建议按以下步骤执行：
- 先分类审查包：将请求归一化为一个主审查包，默认取最小明显解释（已有实现计划→plan-review；已有代码变更/PR/提交范围→diff-review；已有规格或 Markdown 产物→markdown-review；安装/集成问题→platform-setup；远程/浏览器/状态不稳定问题→troubleshooting）。
- 验证具体产物存在：确认计划、diff、PR、Markdown 文件或生成响应已存在，且用户想要的是审查而非计划生成。若产物缺失，应路由出去而不是强行使用审查工具。
- 只选择一个审查包，其余列为后续事项。
- 运行所选审查包：
- 计划审查：确认运行时可将计划交给 plannotator，使用真实存在的原生/钩子路径，每个步骤标注一个问题，以批准、请求修改或归档/保存结束。
- 差异审查：使用具体目标并启动最小差异包（见上方脚本命令）。
- Markdown 审查：确认规格/PRD/架构文件存在，直接使用标注/审查模式，并在运行时仅支持标注而非更强批准路径时明确说明。
- 平台配置：先运行 install.sh 与 check-status.sh，再参考 references/platform-setup.md。
- 故障排查：先运行 check-status.sh 与 configure-remote.sh，再参考 references/notes-and-troubleshooting.md。
- 明确手动与钩子的现实差异：Claude 和 Gemini 是最清晰的原生/钩子驱动的计划审查适配平台；Codex 虽有公开钩子，但上游 plannotator 仍将实际路径记录为手动 diff/Markdown 审查或部分配置；OpenCode 用户明确要求在自动调用过于积极时提供更多手动控制。不应将其简化为“所有平台行为一致”。
- 积极路由相邻工作：规划/规格创建或细化→task-planning、ralph、survey；编排状态或多智能体路由→jeo、task-planning、bmad；宽泛 PR 策略、合并门禁或风险判断→code-review；渲染 UI 缺陷标注→agentation；干净的一次性浏览器验证→browser-harness；超出保存已审产物的笔记/仓库/wiki 管理→obsidian、llm-wiki。
- 使用简短输出契约，例如：
plannotator Review Packet
- Primary packet:
- Artifact:
- Platform + trigger mode:
- Next action:
- Outcome or limitation:
- Route-outs:
对于偏配置的请求，使用简短配置简报，包含：平台、原生钩子 vs 手动审查状态、安装命令、验证步骤、注意事项。
适用场景
- 编码智能体已产出实现计划，人工必须在编码开始前批准或请求修改。
- 存在具体 git diff、提交范围或 PR，审查者希望基于浏览器进行行级定位反馈。
- Markdown 产物（如规格、PRD、架构说明或生成的计划包）需要可视化审查与修订反馈。
- 用户需要将 plannotator 接入 Claude Code、Gemini CLI、Codex CLI 或 OpenCode，主要工作是配置审查循环。
- 审查流程已存在，但远程模式、稳定 URL/端口或平台特定行为不稳定，需要针对性故障排查。
限制
以下情况不应使用本技能：
- 主要工作是撰写或细化计划/规格本身 → task-planning、ralph 或 survey
- 主要工作是宽泛 PR 策略、合并标准、风险判断或代码所有者批准 → code-review
- 主要工作是驱动前端修复的精确渲染 UI 批评 → agentation
- 主要工作是干净的一次性浏览器自动化或确定性网站验证 → browser-harness
- 主要工作是任务编排、看板状态或多智能体路由 → jeo、task-planning、bmad
- 主要工作是笔记分类、wiki 策展或长期笔记系统管理 → obsidian、llm-wiki
其他限制：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