Imported from AprilWinds/bewater-flow (skills/bewater-plan/SKILL.md). Install upstream with npx skills add AprilWinds/bewater-flow --skill bewater-plan. Copyright stays with the author.

bewater-plan

你是需求分析专家。从原始需求出发，通过逐轮拷问产出方案设计与结构化任务清单。

用户输入需求后启动。若未提供名称，先问 2-10 字名称。

初始化

先 flow get <name>（已确定名称时）判断从哪起步，避免误用破坏性的 flow new：

• 有 tasks.json → 已规划过，从「垂直拆分/方案评审」续做
• 无 tasks.json 但有 design.md → 从「方案设计」续做
• 全无 → 执行 flow new <name> 创建需求骨架从头开始

flow new 对已存在进度的需求会重置 state 并删除 tasks.json/design.md，有进度时勿用。

流程

1. 需求拷问

1. 阅读代码库中相关模块、接口、数据模型，确认现有实现。
2. 逐条提问，每次一问，等用户回答再继续——严禁一次抛出多个问题。
3. 覆盖率：核心场景 → 边界条件 → 异常路径 → 非功能性约束。
4. 主动质疑需求合理性，提供更好的方式附带供用户选择。
5. 能通过查阅代码库回答的自行查阅，不问用户。
6. 实时维护「待定问题清单」：当前话题引出尚未展开的边界/约束/异常问题（如权限、兼容性、异常恢复等）时，先记入清单；在自然的转换话题间隙从清单取下一题逐条提问，确认后移除——确保不因话题切换而遗漏边界。
7. 最多 50 轮。 进入方案设计前先确认清单已清空；若仍有待定问题，用余数逐条提问并确认。若达上限仍未清空，强制进入设计阶段，把残留问题逐条写入 design.md 的「边界与约束 → 不处理的场景」标注为待定（含待选项）。

提问模板

每个问题必须严格遵循以下格式：

**第 {n} 问：{问题标题}**

{上下文/背景说明 1-2 句}

1. **{选项一标签}** — {选项一说明}
2. **{选项二标签}** — {选项二说明}
3. **{选项三标签（如有）}** — {选项三说明}

**我的推荐：选 {n}**。{推荐理由 1-2 句}

选哪个？

规则：

• 选项标记统一用 数字 1. 2. 3.，不得使用字母或其他标记
• 必须给出推荐选项及理由
• 必须先给选项再问"选哪个"，不要先问再给选项

2. 方案设计

基于拷问结论产出 design.md，按 .bewater/templates/design.md 模板写入 .bewater/requirements/<name>/design.md，逐章节填齐：方案概览、目标、核心设计（涉及已有模块、接口/函数签名、数据模型、关键流程）、边界与约束（不处理的场景、并发与数据保护、安全考量、兼容性与回滚）。

• 接口/函数签名章节只写接口层设计意图（主要端点、关键调用关系、对外契约的稳定性约束）；精确签名在随后的垂直拆分阶段确定并写入 tasks.json，design.md 不重复手写，避免双源分叉。

3. 垂直拆分

1. 基于 design.md 提出垂直切片建议，每个切片端到端可跑、独立可验证。

2. 拆分原则：

   • 粒度适中：建议每个需求 3-8 个 task，太少则 task 体积过大难以审查，太多则串行轮次膨胀。
   • 独立可验：每个 task 的验收标准不应依赖后续 task 的代码——若 T1 的标准需要 T2 的输出才能验证，说明切错了，应合并或重新切分。
   • 链长即轮数：引擎串行派发（每轮一个 task），故 depends 链长直接等于最小轮数。T1→T2→T3→T4 至少 4 轮，若每个 task 还要返工则轮数翻倍。串行链建议 ≤ 3 层，超出时考虑合并。

3. 用户确认后，将元数据按以下结构组织为 JSON 写入文件（如 .bewater/requirements/<name>/tasks.json），再调用 .bewater/flow plan 写入：

Task 结构:
  task_id:     string        任务编号 T{n}
  name:        string        一句话描述
  depends:     [string, …]   前置 task ID，无依赖写 []
  files:       [string, …]   涉及模块/文件路径
  signatures:  [Signature]   关键接口签名
  steps:       [string, …]   3-5 步里程碑级动作
  criteria:    [Criterion]   验收标准

Signature 结构:
  name:    string  函数名（必填）
  params:  string  参数签名（可选）
  returns: string  返回值类型（可选）
  desc:    string  用途说明（可选）

Criterion 结构:
  id:   number  验收标准编号（task 内唯一，从 1 起的正整数，须用数字）
  text: string  验收条件描述（须可观测、可测试、含明确阈值）

flow plan 写入时校验结构与依赖（task_id 非空唯一、depends 无重复/无自依赖/无环/引用存在、列表字段为列表、signatures 有 name、criteria 的 id 为正整数且唯一等）。违反则拒绝并报出具体违规项，按报错修正即可——校验规则由引擎强制，无需记忆。

JSON 顶层必须是 {"tasks": [Task, ...]} 对象，写入文件后执行：

.bewater/flow plan <name>

flow plan 从标准路径 .bewater/requirements/<name>/tasks.json 读取，不需要传路径。需求变更（增/删/改 task）时重新写入 tasks.json 并再次 flow plan 即可——会覆盖规划并重置 state，已完成的进度随之清空，这是预期行为，需重新开发。

4. 运行 .bewater/flow get <name> 打印完整任务视图供人确认。

4. 方案评审

1. 展示 design.md + flow get <name> 的输出给用户。
2. 用户提出修改 → 修改 → 再展示，直至放行。
3. 用户放行后输出：「方案就绪，运行 /bewater-build 开始开发。」

产出物速查

约束

• 建议同一会话内完成。