SuperAPI AI 工具集

batch-plan-validate

写作与研究

查看项目

更新于 10-22 16:17

技能介绍

用途

batch-plan-validate 面向这样的场景:用户需要连续产出并审阅多份相关的计划或规格文档,例如路线图中剩余的各步骤、一组相互独立的工单。它把“起草”和“逐份校验”解耦,避免在起草过程中被反复打断提问。

不适用于单个计划/规格(应直接使用 writing-plans 或 brainstorming),也不适用于任务之间存在必须先解决的跨任务依赖的情况——这类依赖需在开始排队前与用户协商确定。

主要能力

  • 队列来源:可从路线图文件解析顶层未勾选的 - [ ] 清单项作为队列条目(任务 id 取标签或编号,如 B4、C),也可由用户在请求中直接列出任务。
  • 每个任务先起草步骤级 PRD(writing-prd),若步骤目录中已存在则不再重写。
  • 三种逐任务起草模式,可逐任务覆盖:
    • writing-plans(直接写计划):已有批准设计或无需架构决策时的默认模式。
    • brainstorming → writing-plans(先设计,批准后自动接续写计划):架构尚未确定且需要现在出计划时的默认模式。
    • brainstorming, design-only(只出设计,后续再写计划):用于后续按步骤即时写实现的场景。
  • 队列状态文件记录每个任务所选起草技能、PRD 路径、草稿路径与状态。
  • 状态流转:queued → drafted(含假设,待第一阶段 1.5)→ ready-for-validation → validated;无法起草的任务记为 blocked。

队列状态文件与续跑

状态文件默认路径为 tmp/reports/batch-plan-queue.md;若项目没有 tmp 产物约定,则回退到会话暂存目录。一个状态文件跟踪一个活动队列。

每次调用先检查该文件是否存在:

  • 不存在:按输入方式新建队列,全部标记为 queued,进入第一阶段。
  • 存在且来源与当前请求一致:视为续跑,不重建队列,也不对已 ready-for-validation 或 validated 的任务重跑第一阶段/1.5。若路线图源中出现了状态文件里没有的未勾选项,须用 AskUserQuestion 询问是追加到队尾还是本次忽略,不得静默增删。上次中断时仍为 queued/drafted/blocked 的任务先补完。
  • 存在但来源不一致:若其中所有任务已 validated,视为过期/已完成,告知用户并可提议删除后新建;否则须询问是继续这个未完成的旧队列,还是归档/丢弃后新建,不得静默覆盖。

每次阶段状态变化都要即时写回状态文件,续跑能力依赖该文件始终反映真实状态。

全部行均为 validated 后清理:删除状态文件与决策日志(若无未解决条目)。单个草稿/计划文件不在此清理,按各自技能生命周期处理。

使用方式(三个阶段)

第一阶段 — 全部起草(不使用原生 Plan Mode)

按顺序处理仍为 queued 或 drafted 的任务:步骤目录无 PRD 时先内联运行 writing-prd,保存到 docs/<feature-slug>/steps/<step-slug>/YYYY-MM-DD-<step-slug>-prd.md;随后内联运行所选起草技能(不作为子代理运行,以便拦截其阻塞提问),用普通 Write 保存草稿到同一步骤目录。此阶段不进入 Plan Mode,以便一趟走完整个队列。design-only 模式在设计文档完成后即停止,不执行自动接续的写计划环节。

起草过程中遇到本应阻塞提问的环节时:不提问,把问题、上下文和所采用的默认假设追加到决策日志;在草稿中标注 [ПРЕДПОЛОЖЕНИЕ, требует подтверждения] / [ASSUMPTION, needs confirmation];继续完成本任务再进入下一个。若某任务缺答案就完全无法起草(硬阻塞),在日志中记为 BLOCKING 并跳到下一任务,留待第一阶段 1.5 优先提出。

决策日志路径:项目有 tmp 产物约定时用 tmp/reports/batch-plan-decisions.md,否则用会话暂存目录;每个任务一节,含 question、context、assumption used。

若路线图存在 docs/<feature-slug>/roadmap-state.json,起草每个产物后同步更新其中该任务条目(PRD 写入 → prd-drafted 并设 prdPath;设计或计划写入 → spec-drafted+specPath 或 plan-drafted+planPath),并补全 stepFolder。这与队列状态文件并行维护,两者跟踪的对象不同。

每个任务起草完成后更新队列状态行:填写步骤目录、PRD 路径、草稿路径,状态设为 ready-for-validation(无未决问题)或 drafted(尚有假设待 1.5 处理);硬阻塞任务设为 blocked 并在 notes 写一行原因。第一阶段的起草数量不设上限。

第一阶段 1.5 — 解决已记录问题

全部任务都有草稿后,按队列顺序逐任务用 AskUserQuestion 处理决策日志:根据答复更新草稿(移除假设标记、应用决定),标记日志条目已解决,并把该任务状态置为 ready-for-validation、清空 notes。无日志条目的任务静默跳过。

第二阶段 — 校验下一批(Plan Mode 循环)

取队列顺序中最多 3 个 ready-for-validation 任务组成批次,从第一个开始,当前任务批准后才进入下一个:

  1. EnterPlanMode,记下 Plan Mode 系统消息给出的计划文件路径(在本任务循环内,这是无需权限提示即可编辑的唯一文件)。
  2. 把该任务 1.5 之后的最终草稿用 Write 复制到该计划文件。
  3. 在聊天消息中贴出完整计划文本(有意与 Plannotator 浏览器展示内容重复,而非摘要)。
  4. ExitPlanMode,触发 Plannotator 审阅。
  5. 批注/修改请求返回后,只改计划文件,不改草稿真实目标路径(否则每轮修订都会触发权限提示),回到第 3 步继续同一任务。
  6. 干净批准后,才把计划文件最终内容写入草稿真实目标路径;立即在状态文件把该任务置为 validated;若有 roadmap-state.json,同步更新(校验的是设计则 spec-validated,是计划则 plan-drafted)。然后进入批次内下一任务,回到第 1 步。

一批(≤3 个)全部 validated 后,本次运行停止,不自动开始下一批。向用户报告:整个队列中已 validated 的数量与仍为 ready-for-validation/blocked 的数量;说明对同一来源再次调用本技能会从下一批自动续跑校验(已起草任务跳过第一阶段/1.5)。若批次清空了队列(无 ready-for-validation 且无 blocked),改执行清理步骤。

适用场景

  • 按路线图逐步骤推进,先集中写完所有步骤的 PRD/设计,再分批审阅。
  • 一批相互独立的工单需要连续起草与确认。
  • 希望在起草阶段不被提问打断、把问题集中到 1.5 阶段一次性解决,并支持中途停下实施后再续跑的工作流。

限制与注意事项

  • 依赖 writing-prd、superpowers:writing-plans、superpowers:brainstorming 等底层技能;本技能只增加队列/阶段编排。存储与命名遵循 roadmap-conventions,起草前需先阅读;项目若存在 .claude/rules/skills/writing-plans.md、.claude/rules/skills/brainstorming.md 覆盖规则,需一并读取。
  • 第一阶段进入 Plan Mode 是错误的(会迫使每轮 ExitPlanMode/AskUserQuestion),会破坏“不停顿起草全部”的目标。
  • 第一阶段中途提阻塞问题、把第一阶段起草委派给子代理,都会失去拦截提问的能力,应避免。
  • ExitPlanMode 前必须在聊天中完整贴出计划文本,不能省略。
  • 第二阶段批次内严格按顺序,不得乱序或提前开始下一任务。
  • 单次调用校验不得超过 3 个任务;该上限只约束校验批次,不约束起草数量。
  • 批次批准后不自动串联下一批。
  • 修订轮只改 Plan Mode 计划文件,最终批准时才写目标路径,否则每轮都触发权限提示。
  • 状态变化后必须及时更新状态文件,否则续跑失效。
  • 每个任务的 steps/<step-slug>/ 目录必须有 PRD,不能跳过 PRD 直接写计划/设计;三类文档(PRD、设计、计划)均存放于 docs/<feature-slug>/steps/<step-slug>/,不可散落在仓库根目录。
  • 关于收费、价格、平台支持等信息,资料暂未提供。