| name | task-control-doc |
| description | Use when the user wants a master control document for a large, complex, long-running, or multi-session task. Defines how to create a task control doc that captures background, mandatory reads, subtask breakdown, and self-contained work packages so each subtask can be executed in a fresh session with minimal context. |
任务总控文档
当用户要求"为某件事做总控文档"时，使用本 skill。
真值源：~/.claude/skills/control/references/总控规范.md。本 skill 只描述如何创建总控；生命周期、归档定义、目录结构都在那里。
方法论补充：references/方法论.md（为什么要做、何时做、常见风险）。
1. 适用场景
- 任务很大、很复杂
- 任务可能跨多个会话完成
- 用户希望每个子任务都开新会话执行（这是默认假设）
- 上下文可能过长、容易污染或遗忘
中小任务用计划模式或 lightweight-design + construction-blueprint 即可，不需要总控。
2. 核心原则：子任务即工作包
这是本 skill 最重要的一条设计原则。
每个子任务都应该是一个自包含的工作包：
- 新会话只读「子任务详情 + 它列出的强制阅读文件」就能执行
- 不需要读总控其他子任务、不需要读总控规范
- 用户在新会话开头自己选模型，不预定义执行模式
- 子任务详情末尾有「会话启动提示词」可直接复制
写总控时按这个原则切分子任务，强制阅读必须精准到 1-3 个文件。
3. 文件位置与结构
默认路径：<PROJECT_ROOT>/docs/00-任务总控/{YYYY-MM-DD}-{任务名}/
任务目录用日期前缀（创建日，YYYY-MM-DD），防多 worktree 编号撞车。同日创建多任务可加字母后缀 2026-05-10b-... 或时分 2026-05-10-1430-...。
支持两种模式（创建时选择）：
3.1 单文件模式（默认，适合中小总控）
{YYYY-MM-DD}-{任务名}/
├── README.md # 主总控（含全部子任务详情）
└── _shared/ # 可选：唯一过程资产目录（归属由文件名前缀区分，见 §3.3）
适用：3-7 个子任务、各子任务详情不超过 50 行。
3.2 拆分模式（适合大总控）
{YYYY-MM-DD}-{任务名}/
├── README.md # 主总控（任务背景 + 子任务总表 + 进展记录，不含子任务详情）
├── T1-{子任务名}.md # T1 自包含工作包
├── T2-{子任务名}.md # T2 自包含工作包
├── T6-{子任务名}.md
└── _shared/ # 可选：唯一过程资产目录（归属由文件名前缀区分，见 §3.3）
├── T3-{资产文件}.csv # 子任务专属资产
└── {资产文件}.md # 任务级共享资产（无前缀）
适用：8+ 个子任务、每个子任务详情很长（带大量强制阅读、设计明细）。
优点：执行 T3 时只读 T3-xxx.md 一个文件，最小上下文。
⚠️ 拆分模式文件命名为脚本硬依赖：子任务文件名前缀必须与子任务总表「编号」列的内容完全一致。例如表中编号写 T1，对应文件必须命名为 T1-{子任务名}.md（next_subtask.py 用 glob("T1-*.md") 定位文件）。T01-xxx.md 或 t1-xxx.md 均无法被识别。
3.3 过程资产目录（唯一 _shared/，文件名前缀标归属）
任务执行过程中产生的中间文档（设计稿、数据样本、批判稿、清单等），不进入项目正式文档体系的，全部放进唯一资产目录 _shared/，归属由文件名前缀区分：
| 资产归属 | 命名 | 示例 |
|---|
| 某子任务专属 / 产出 | T{n}-{资产名}.md | T2-模型能力调查.md |
| 二级子任务产出 | T{n}.{m}-{资产名}.md | T6.3-联调记录.md |
| 多文件资产 | T{n}-{资产名}/ 子目录 | T8-渲染样图/ |
| 任务级共享（无单一归属） | 无前缀自然中文名 | 需求真值.md |
| 进入项目正式文档体系 | 项目本地约定路径（不在总控目录） | 按项目自身规则 |
判定口诀：这个文件能填进某个 T{n} 的「输出物」字段吗？能 → 带 T{n}- 前缀；不能 → 无前缀。
高频资产标准名：T{n}-轻量设计方案.md / T{n}-施工蓝图.md / T{n}-蓝图评审报告.md / T{n}-对抗评审报告.md，不得自创变体。
硬约束：
- 资产目录只有
_shared/ 一个，必须以 _ 开头——脚本只在任务根目录一层 glob T{n}-*.md，不进 _shared/，资产带 T{n}- 前缀不会撞车
- 禁止在任务根目录平铺资产；禁止新建
_T{n}/ 目录（旧规则已废除；存量任务的 _T{n}/ 原地只读）
- 出现第一个资产时即建
_shared/，即使只有 1 个文件
- 所有资产路径必须列在对应子任务详情的「输出物」字段——「输出物」是真值源，不再单独维护「资产清单」
详见 ~/.claude/skills/control/references/总控规范.md §1.1.1。
模板见：
- 单文件：
assets/任务总控模板.md
- 拆分：
assets/拆分模板/README.md + assets/拆分模板/子任务包.md
4. 必须包含的章节（单文件模式）
每份单文件总控（README.md）至少包含：
- 任务背景
- 总目标
- 完成定义
- 范围
- 非范围
- 全局强制阅读（最多 1-2 个项目级文件）
- 全局约束与注意事项
- 子任务总表
- 子任务详情（每个独立小节）
- 风险与待确认
- 进展记录
- 更新规则
不再单独写「本目录相关资产」章节：所有资产（_shared/ 下的过程资产）一律登记在对应子任务详情的「输出物」字段，避免双重维护。
拆分模式结构详见 §3.2 提及的两份模板。
⚠️ 脚本硬依赖（以下约束不可违反）：
- 章节标题：
子任务总表 这个名称是脚本正则匹配的固定锚点，不可改为 任务清单、子任务列表 等任何别名
- 状态值：脚本精确匹配以下枚举，拼写不能变体：
待完成 / 进行中 / 已完成 / 阻塞 / 已取消
5. 各章节写法要点
5.1 任务背景
不要写已经过期的历史过程。
5.2 总目标
3-7 条结果表达（不是动作表达）。详见 references/方法论.md §6.1。
5.3 完成定义
可检查的标准。
5.4 范围 / 非范围
明确包含什么、不包含什么。非范围章节用于防止后续 agent 自动扩张任务范围。
5.5 全局强制阅读
最多 1-2 个项目级文件。具体执行所需的文件应放到子任务级强制阅读，不在这里堆。
5.6 全局约束与注意事项
放任务通用规则：真值优先级、不能动的目录、输出格式硬约束。
6. 子任务总表（§8）
| 编号 | 子任务 | 状态 | 依赖 | 预期输出 |
|------|------|------|------|---------|
| T1 | 需求明确与架构设计 | 待完成 | 无 | 架构方案、接口契约 |
| T2 | 数据管理模块开发 | 待完成 | T1 | 数据管理后台代码 |
状态枚举：待完成 / 进行中 / 已完成 / 阻塞 / 已取消
创建阶段不写二级：初始化总控时只列一级 T1/T2/T3...。需要拆分时由用户在执行过程中触发 /control <key> split Tn（详见下方 §6.1），不在创建阶段就预先拆好二级。这是因为大多数任务在动手前根本不知道哪一级会真的太大。
⚠️ 列名为脚本硬依赖，不可自定义：render_control_status.py 和 next_subtask.py 依赖固定列名匹配，不得重命名或替换以下四列：
编号（或 序号）子任务（或 任务名称 / 子任务文件）状态（或 当前状态）预期输出（或 输出物 / 做什么）
如需追加任务专属列（如 批判编号），在这四列之后追加，不要替换。
注意：本 skill 不在子任务总表里写「执行模式」列。模型选择由用户在新会话开头决定（用 /model）。
6.1 中途拆分（一级 → 二级）
任务执行过程中，发现某个一级父任务 Tn 工作量超出预期、单一会话做不完 → 用户触发 /control <key> split Tn 把它原地拆为 Tn.1 ~ Tn.N。
只允许两级：Tn.x 不可再拆。深层就该开新总控、或重新设计任务边界。
拆分后表格自动变成：
| T1 | 父任务名 | 派生 | 无 | 父预期输出 | ← 状态列固定占位「派生」，渲染时聚合
| T1.1 | 子任务一 | 待完成 | 无 | 子1输出 |
| T1.2 | 子任务二 | 待完成 | T1.1 | 子2输出 |
| T2 | ... | ... | T1 | ... | ← 依赖 T1 自动语义为「所有 T1.* 完成」
详细规则：
- 父任务状态列固定写
派生（脚本会自动从子任务聚合实际状态）
- 二级编号必须形如
T{父}.{m}，m 从 1 起递增
/control <key> split Tn 由用户显式触发；AI 不可自行决定拆分粒度- 详细规范见
~/.claude/skills/control/references/总控规范.md §1.2.1
- 执行流程见 control skill §5.5
7. 子任务详情（§9）—— 自包含工作包
每个子任务展开为独立小节，结构如下：
### Tn 子任务名称
- **当前状态**：待完成
#### 子任务背景
（这一个子任务的上下文，用一段话讲清楚为什么要做这件事）
#### 强制阅读（精准 1-3 个）
- `路径`：为什么必须读 + 读完获得什么结论
- `路径`：为什么必须读
#### 输入
（前置依赖的产出物，明确列出）
#### 要做的事情
- 第一步
- 第二步
- 第三步
#### 不做什么（可选，建议填）
- 不做 X（属于 T<n+1>）
- 不修改 Y（属于其他模块）
#### 预期效果
（执行完后系统/文档应该是什么状态）
#### 输出物（必填，可检查）
- `具体路径/文件名`：内容简述
- `具体路径/文件名`：内容简述
> **路径写法**：进入项目正式文档体系的写正式路径（如 `docs/03-技术设计/...md`）；不进的过程资产写 `_shared/T{n}-{资产名}`（子任务专属）或 `_shared/{资产名}`（任务级共享）。**所有资产都必须列在这里**，不再单独维护「资产清单」段。
#### 完成判定
- [ ] 输出物 1 已产出且通过自检
- [ ] 输出物 2 已产出且通过自检
- [ ] （其他可检查条件）
#### 依赖关系
- 依赖：T1 已完成
- 阻塞：T<n+1>
#### 风险与注意事项
- 风险点 1
- 风险点 2
#### 会话启动提示词（可直接复制到新会话）
```
我要执行 docs/00-任务总控/{YYYY-MM-DD}-{任务名}/README.md 的 Tn 子任务。
请按以下步骤：
1. 读取这份总控的「任务背景」和子任务总表（不读其他子任务详情）
2. 读取本子任务详情：Tn - {子任务名}
3. 读取「强制阅读」列出的文件
4. 严格在 Tn 范围内执行，做完「要做的事情」、产出「输出物」、通过「完成判定」
5. 完成后回填总控状态为已完成
6. **不要做其他子任务**，做完立刻停止并向我报告
```
8. 进展记录与更新规则
8.1 进展记录
只写"会影响后续接手者"的关键进展：
- YYYY-MM-DD：[Tn] 完成，[摘要]
8.2 更新规则
- 子任务开始时改
进行中，开始前必须重新读取该子任务的强制阅读文件
- 子任务完成后改
已完成，立刻停止，不顺手做下一个
- 阻塞时改
阻塞 并写明原因
- 产出文件后回填到对应「输出物」
- 整体完成 → 用
archive_control.py --apply 自动归档（详见总控规范 §2.3）
- 任务删除 → 见总控规范 §2.4，不进归档
9. 输出物的好坏写法
好（明确可交付）：
- 补齐
docs/01-需求/{某具体文件}.md
- 完成某模块的 README 导航结构
差（抽象）：
详见 references/方法论.md §6.2。
10. 使用模板
创建新总控文档时，必须基于模板填充。两个正交维度：载体（单文件 / 拆分）×是否套用研发流程预设。
载体（按子任务数 / 详情长度自动选）：
| 载体 | 模板 | 写到哪里 |
|---|
| 单文件（默认，≤7 子任务且各 <50 行） | assets/任务总控模板.md | <任务目录>/README.md |
| 拆分（8+ 子任务或单包很长） | assets/拆分模板/README.md + assets/拆分模板/子任务包.md | <任务目录>/README.md + <任务目录>/T{n}-{子任务名}.md |
研发流程预设（正交，可叠加在任一载体上）：研发型任务（新功能 / 跨模块重构 / 带前后端+测试+部署链路）套用「八阶段动作菜单」，由 AI 据一句总需求实例化子任务树。模板见 assets/研发流程模板/，详见 §12、§13 与 references/标准研发流程.md。不是第三种载体——研发流程决定"有哪些子任务 / 怎么连依赖"，载体仍按上表自动选。
如该任务需要独立 git worktree，按总控规范 §3.3 命令模板手动 git worktree add 即可，无需在文档里登记。
11. 创建检查表
新建总控前自检：
12. 标准研发总控流程（可选预设）
绝大多数研发型任务遵循同一条流水线：调查 → 探讨 → 轻量设计 → 施工蓝图 → 测试用例设计 → 文档回写 → 施工 → 交付/发布验证。把它固化成预设，用户给一句总需求，AI 实例化出子任务树。
- 真值源：
references/标准研发流程.md（八阶段菜单、拆分决策表、评审风险触发、DAG 连法、槽位发现协议）。
- 触发：用户说"按标准研发流程建总控" / "研发流程总控" / "标准研发流程"，或任务明显是研发流水线。
- 定位：正交预设（见 §10），不新增
/control 命令。
- 项目绑定：八阶段是抽象的；具体"每阶段读什么 / 产出落哪 / 怎么验证 / 哪是死亡线"由项目研发流程补丁填充（发现协议见
标准研发流程.md §6.1）。
13. 研发流程实例化交互流程
套用研发流程预设创建总控时按此走。前三步是对话（不落盘），第四步才写文件。
第一步（fail-stop）：加载项目补丁。 先按 标准研发流程.md §6.1 在项目 skills 目录定位「研发流程补丁」。找不到 → 停机询问用户（先建补丁 / 改用通用拆分模式手工编排），禁止用带 {{槽位}} 的纯抽象模板直接落盘。
第二步：第 0 步明确任务 → README 头部。 收集用户总目标 / 总内容，确认整体需求，写进 研发流程模板/README.md 头部（背景/总目标/完成定义/范围/非范围）。此步不占编号。
第三步：实例化子任务树草案（表格呈现，不落盘）。 按 标准研发流程.md §4 拆分决策表，针对本任务把八阶段菜单实例化成线性一级 T1..Tn 草案——含每阶段拆几个 / 塌缩 / 跳过、评审是否独立、DAG 依赖列。以表格呈现给用户勾选 / 增删。
第四步：定稿落盘。 用户定稿后：① 重排线性编号并同步重写依赖引用；② 从对应阶段片段（assets/研发流程模板/阶段片段库/）生成被选中阶段的 T{n}-*.md，用补丁槽位对照表替换全部 {{槽位}}；③ 回填 README 子任务总表 + DAG 依赖列；④ 顶层 docs/00-任务总控/README.md 活跃任务表追加一行。
落盘前自检（硬）：
- 无残留
{{}} 占位（补丁已填实）
- 依赖引用 ⊆ 编号集合（无孤儿依赖）、无环
- 子任务文件名
T{n}-*.md 前缀与总表编号列完全一致
