task-control

name	task-control
description	Codex 的持久化任务管理技能。任务跨多个文件、需要拆分、可能中断、需要恢复、需要显式注册和过程记录时使用。它通过 `.codex/plans/{branch}/TASKS.md` 与 `process.md` 管理任务生命周期，并提供断点恢复、研究发现、错误记录和状态同步规则。

任务控制

管理长任务生命周期：注册、拆分、暂停、恢复、取消、完成。

所有任务数据按分支隔离，默认使用：.codex/plans/{branch}/。

一、分支检测

每次操作前执行：

1. 检测当前分支名
2. 如果当前仓库不是 git 仓库，则使用稳定默认值，例如 main
3. 检查 .codex/plans/{branch}/ 是否存在，不存在则创建
4. 检查 .codex/plans/{branch}/TASKS.md 是否存在，不存在则初始化

建议初始化内容：

# 任务清单

<!-- 暂无任务 -->

二、何时必须注册

满足任一条件即注册：

• 需要跨文件探索后再整合输出
• 涉及 3 个及以上编辑步骤
• 预计需要多轮交互或可能中断
• 涉及需求分析、设计、实现计划等阶段性产物
• 涉及对外变更，需要设置检查点

以下情况可以跳过：

• 单文件小改动
• 纯查询回答
• 无需恢复的短任务

三、TASKS.md 格式

每个任务建议记录：

• 任务名
• 状态：进行中 / 暂停 / 待确认
• 摘要
• 过程文件路径
• 恢复提示

推荐格式：

# 任务清单

## [任务名称]
- 状态：进行中
- 摘要：[任务简述]
- 过程文件：.codex/plans/{branch}/{task}/process.md
- 恢复提示：读取 process.md，然后从 [~] 步骤继续。

四、process.md 模板

每个任务一个 process.md。

最少包含以下部分：

1. 恢复胶囊

必须放在文件顶部，且每次写断点时同步更新。建议字段：

• 任务需求
• 关键决策
• 当前阶段
• 已完成产物
• 剩余工作
• 重要发现

2. 步骤列表

使用统一状态标记：

• [ ] 未开始
• [~] 进行中 / 断点
• [v] 已完成
• [x] 已取消

断点步骤必须包含：

• 当前产物
• 下一步
• 涉及文件

3. 研究发现

记录执行过程中发现的重要信息，避免恢复后重复探索。

4. 错误记录

记录失败尝试和结果，避免重复踩坑。

五、恢复任务

1. 读取 TASKS.md
2. 找到状态为“进行中”或“暂停”的任务
3. 打开对应 process.md
4. 先读恢复胶囊
5. 再读 [~] 步骤中的“下一步”
6. 按记录恢复，不从头重规划

六、暂停任务

1. 在 TASKS.md 中把任务标记为暂停
2. 在 process.md 中把当前步骤标记为 [~]
3. 写入明确下一步
4. 更新恢复胶囊
5. 如有新发现或新错误，同步写入对应章节

七、取消任务

1. 先确认用户要取消
2. 检查是否存在未提交代码或未处理文档变更
3. 询问这些产物保留还是丢弃
4. 再从 TASKS.md 中移除，并删除或归档任务目录

八、完成任务

1. 确认所有步骤已完成
2. 从 TASKS.md 中移除任务
3. 删除或归档对应任务目录
4. 汇报完成内容与验证结果

九、任务拆分原则

需要判断、确认或切换产出形态时拆分子任务，例如：

• 方案选择
• 跨域改动
• 从探索切到写文档或改代码
• 对外变更确认
• 验收节点

纯执行型连续步骤可以不拆。

十、子代理协作

当长任务被拆给子代理时，task-control 仍应由主代理维护主记录，不能因为子代理存在就跳过持久化。

建议额外记录：

• 当前子任务负责人
• 派发给子代理的边界
• 子代理回传的改动范围
• 尚未收口的后续步骤

如果任务已经注册，派发子代理前至少做到：

1. 在 process.md 中写明当前进入哪个子任务阶段。
2. 记录子代理需要读取的文件和回传要求。
3. 子代理返回后，把有效结果合并回 process.md 的“研究发现”“步骤列表”或“下一步”。
4. 若子代理执行中断，主代理仍负责写断点，不把恢复责任悬空给下一轮会话。

十一、异常处理

常见异常处理建议：

• process.md 格式损坏：尽量按现有信息恢复，无法恢复时提示用户确认状态
• TASKS.md 与实际目录不一致：以文件系统为准修正
• 仓库无 git 分支：使用默认分支名
• 断点文件路径失效：根据上下文推测新路径，必要时询问用户