Task Pack 与任务系统

当 plan 较大、需要并行或分批执行时，task pack 是 plan 与 work 之间的可验证交接层。它派生自计划，不替代计划。

核心模型

text

docs/plans/<plan>.md           ← 单一真源
   │
   │ standalone spec-write-tasks skill
   ▼
docs/tasks/<task-pack>.md      ← 派生执行切片
   │
   │ /spec:work / $spec-work
   ▼
代码 / 测试 / 验证证据

关键约束：plan 是 source-of-truth，task pack 只是派生。task pack 不应增加 plan 之外的 scope 或验收标准。

何时需要 task pack

plan 规模	推荐做法
1–2 个文件、无依赖	直接 `/spec:work`，跳过 task pack
多模块、有依赖、可并行	用 standalone `write-tasks` 编译 task pack
长链条但每步明确	用 task pack 让交接更清晰
需求未稳定	不要写 task pack；先回到 brainstorm 或 plan

task pack 的字段

每个 task pack 文件含一个 JSON 契约段，关键字段：

字段	含义
`spec_id`	与 source plan 的同链 id，必须匹配
`source_plan`	关联 plan 的 repo-relative 路径
`source_plan_hash`	计划文件 SHA256，用于 freshness 检测
`tasks[]`	任务卡片数组：每张卡片含 task_id、files、test_focus、done_signal、stop_if
`dependencies`	任务图依赖关系
`waves`	可并行的执行批次

CLI 校验

spec-first 提供两个确定性校验子命令：

bash

# 计算 plan 文件 hash（在 plan 还没派生 task 时也可调用）
spec-first tasks hash docs/plans/<plan>.md

# 校验 task pack 与 plan 的同链一致性
spec-first tasks validate docs/tasks/<task-pack>.md --repo .

tasks validate 检查：

task pack 的 source_plan_hash 与当前 plan 文件的实际 hash 是否匹配
spec_id 是否同链
files[] 是否都是 POSIX repo-relative 路径
parallelizable / wave / 字段类型是否符合 schema

校验失败时输出结构化错误，不修改文件系统。

边界

spec-write-tasks 不是 /spec:* 或 $spec-* workflow——它是 standalone handoff skill，没有命令入口
spec-first tasks 是 CLI 子命令，只做结构与 hash 校验，不做语义判断（实现取舍仍由 work workflow 中的 LLM 完成）
task pack 不是新需求源——它派生于 plan；plan 变化后应重新编译或验证 freshness
task pack 的 freshness：plan 修改后 source_plan_hash 与实际 hash 不匹配时，需要重新派生

与 docs/tasks 的提交策略

团队场景	推荐
个人 / 小项目	可不提交 task pack，直接 plan → work
多人协作、明确交接	提交 task pack，让 reviewer 看到执行边界
跨会话长链任务	必须提交，避免重新派生时 hash 漂移

更详细的 spec-write-tasks 契约见 spec-write-tasks 详情。

Task Pack 与任务系统 ​

核心模型 ​

何时需要 task pack ​

task pack 的字段 ​

CLI 校验 ​

推荐流程 ​

边界 ​

与 docs/tasks 的提交策略 ​