plan-to-task-list-with-dag

此技能用于创建可排期的计划产物，而不是松散的规划文字。

不可妥协的规则：

1. 使用 AskUserQuestion 发起范围质疑并选择模式。
2. 拆解任务前先探索现有代码。绝不臆造文件路径。
3. 构建一个规范计划对象，然后从中生成 Markdown 和 JSON。
4. 每个任务都必须明确负责人、验证方式、依赖处理方式，并包含 Agent 字段。
5. 技能正文应聚焦工作流。计划架构、Agent 映射和示例应从参考资料加载。
6. 每个任务都需要 2-3 条可测试的验收标准，且至少有一条涵盖故障或边界情况。
7. 绝不创建涉及超过 3 个文件的任务，绝不创建循环依赖，也绝不假定代码库结构。
8. 如果任务声称包含副作用（持久化、WAL、网络 I/O、注册），必须说明此能力的来源。
9. 对于新文件，必须明确指定由哪个任务负责导出、注册和接线。
10. 如果任务可以通过占位内容或无效接线“完成”，应将语义强化拆分为明确的后续任务。
11. 将 JSON 视为真实来源。从同一个规范计划对象生成 Markdown。
12. 不要使用含糊的契约措辞（“内部更新”“最终会跳过”“优雅降级”），除非明确说明负责人、行为和恢复方式。
13. 区分本地复用和外部引用。不要将外部文档或克隆项目说成本地代码。

将计划转换为带 DAG 的任务列表

输入

• $request：可选的功能或规划请求文本

目标

生成具体且可安全执行的任务 DAG：

• 已质疑范围
• 以真实代码库结构为依据
• 足够原子化，便于并行工作
• 保存到 .ulpi/plans/<plan-name>.md 和 .ulpi/plans/<plan-name>.json

步骤 0：规划前先质疑范围

在拆解任务之前，快速检查是否存在重叠：

• 如果有 codemap 技能，优先使用它进行语义搜索
• 否则使用 Glob、Grep 和 Read

确定：

• 已有内容
• 可复用内容
• 真正新增的内容
• 可能的前置条件
• 可能的非目标
• 请求是否足够小，可以直接执行，而无需规划

然后使用 AskUserQuestion 确认：

• 规划模式：EXPANSION、HOLD 或 REDUCTION
• 默认的任务后审查：claude、codex、kiro、all 或 none
• 范围调整项或明确的非目标

范围框定得到确认前，不要继续。

成功标准：用户已确认范围、选择规划模式并选定默认审查方式。

步骤 1：探索真实代码范围

编写任何任务前，先探索代码库：

• 可能涉及的模块和目录
• 部分满足请求的现有代码
• 共享集成面：
  • 包根目录
  • 导出汇总文件
  • 注册表
  • 路由器
  • 清单
  • 启动钩子
• 公共接口：
  • API 路由
  • CLI 命令
  • 配置文件
  • 架构
  • 持久化格式

规则：

• 如果有 codemap 技能，优先通过它进行语义搜索
• 使用 Grep 进行精确字符串验证
• 在任务中提及实际文件前，先使用 Read 查看这些文件
• 绝不臆造路径、模块或现有辅助程序

成功标准：计划中提及的每个路径都来自已观察到的代码库现状。

步骤 2：记录规划契约

创建任务前，记录使计划有效的条件：

• 前置条件
• 非目标
• 跨边界契约
• 副作用的能力提供方
• 共享集成点
• 执行中途停止时的发布范围

明确说明：

• 持久化能力的来源
• 谁负责修改导出和注册
• 哪些公共接口必须保持稳定
• 必须保留哪些故障路径或隔离不变量

成功标准：计划说明必须已满足的条件，以及明确排除在范围之外的内容。

步骤 3：拆分为原子任务

创建的任务应具备以下特点：

• 原子性
• 范围限定于文件
• 考虑依赖关系
• 易于审核

任务规则：

• 每个任务优先涉及 1 到 3 个文件
• writeScope 中的每个文件都必须有明确的作用
• 每个任务都需要包含：
  • TASK-NNN ID
  • 标题
  • 描述
  • Type
  • Priority
  • Effort
  • Agent（参见 references/output-format.md 中的 Agent Selection Reference）
  • 验收标准
  • writeScope
  • validateCommand
• 每个任务包含 2-3 条可测试的验收标准；至少一条必须涵盖失败或边缘情况
• 对于公共接口，明确列出准确的签名／示例，并添加错误形状或错误路由检查
• 对于重写或组合任务，添加至少一条标准，证明现有语义没有被悄然丢弃
• 如果新文件需要导出或注册，应将其明确分配给某个任务
• 如果任务只创建结构，而语义强化仍有待完成，应明确拆分后续任务
• validateCommand 必须限定于切片范围——仅凭此任务的 writeScope 和已集成的依赖即可通过，并且可独立运行，不受无关工作影响：
  • 将验证范围限定到任务自身的文件，绝不可覆盖整个包。对于 vitest，使用 pnpm --filter <pkg> exec vitest run <path/to/file.test.ts>。不要使用 pnpm --filter <pkg> test -- <file>——-- 会导致 vitest 忽略位置参数并运行整个包，因此无关或已有失败会泄漏到该任务的门禁中，可能错误地阻止正确的切片通过。
  • 命令运行的每个测试文件都必须属于此任务的 writeScope，或由已集成的依赖保证通过。绝不可让任务的 validate 命令指向另一个任务拥有、且此任务无法修复的测试文件。
  • 避免使用只有在最终状态下才能通过的全套测试／端到端命令；如果两个部分无法各自独立验证，就应将其合并到同一个任务中。

成功标准：每个任务都无需隐含上下文即可执行，且规模足够小，便于独立审核。

步骤 4：映射依赖关系并最大化并行度

仅在存在真实依赖时添加依赖：

• 文件重叠
• 数据流
• API 契约
• 共享集成接口
• 能力提供方
• 生命周期或引导依赖

避免过度约束：

• 独立任务应保持并行
• 明确列出对共享文件的编辑，不要隐而不宣
• 不允许循环依赖

使用 P0 到 P3 优先级：

• P0：为其他任务提供支持的基础工作
• P1：核心功能工作
• P2：辅助工作和边缘情况
• P3：可选的润色、文档或清理工作

成功标准：依赖图无环、精简，并清晰呈现真实的并行层级。

步骤 5：从一个规范计划对象生成 Markdown 和 JSON

编写输出之前，加载 references/output-format.md。

同时编写两个文件：

• .ulpi/plans/<plan-name>.md
• .ulpi/plans/<plan-name>.json

要求：

• Markdown 和 JSON 必须描述相同的任务
• 两个文件中的任务 ID 必须完全一致
• 依赖关系的 JSON 是事实来源
• 磁盘上的 Markdown 不得包含 [PLAN] 标记

成功标准：两个产物均已生成，且描述相同的 DAG。

步骤 6：完成前进行验证

执行最终结构检查：

• 所有任务 ID 都存在于 Markdown 和 JSON 中
• 每个依赖目标都存在
• 没有循环
• 没有虚构的文件路径
• 没有任务的写入范围过大
• 验收标准在需要时涵盖边缘或失败行为
• 已设置默认审核方式

仅在需要展示格式示例时，才加载 references/examples.md。

成功标准：计划可供排程，内容前后一致，并已准备好执行。

Guardrails

• 不要跳过基于 AskUserQuestion 的范围挑战。
• 不要将其变成直接实施。
• 不要臆造现有文件、辅助函数或包边界。
• 不要将大型示例或输出模板直接内嵌在 SKILL.md 中。
• 不要添加 paths:。这是一个通用工作流技能。
• 不要添加 context: fork。此工作流依赖过程中与用户交互。
• 不要引入仅供 Agent 使用的标头。
• 不要创建涉及超过 3 个文件的任务。
• 不要过度约束依赖关系——彼此独立的任务必须保持并行。
• 不要将必需的共享文件编辑隐藏在狭窄的写入范围后面。
• 不要让任务声称具有其未定义能力所需的副作用。
• 不要将外部文档、克隆项目或网络调研说成本地代码，除非对应路径存在于仓库中。
• 不要使用 P1-P4 优先级。此技能使用 P0-P3。
• 不要分别在 JSON 和 Markdown 中手动维护计数、分层摘要或依赖引用——应从规范计划对象派生。

加载参考资料的时机

• references/personality.md 在会话开始时加载，以了解角色、专业知识、特质和沟通风格。
• references/knowledge.md 用于了解 DAG 语义、解析器假设和计划对象知识。
• references/output-format.md 在生成最终 Markdown 和 JSON 工件之前加载。
• references/examples.md 仅在需要查看类似请求的示例格式时加载。

输出约定

报告：

1. 所选模式和默认审查设置
2. 计划文件路径
3. 任务数量和关键路径摘要
4. 主要前置条件和非目标
5. 值得注意的风险或范围取舍