| name | task-control |
| description | Codex 的持久化任务管理技能。任务跨多个文件、需要拆分、可能中断、需要恢复、需要显式注册和过程记录时使用。它通过 `.codex/plans/{branch}/TASKS.md` 与 `process.md` 管理任务生命周期，并提供断点恢复、研究发现、错误记录和状态同步规则。 |
任务控制
管理长任务生命周期：注册、拆分、暂停、恢复、取消、完成。
所有任务数据按分支隔离，默认使用：.codex/plans/{branch}/。
一、分支检测
每次操作前执行：
- 检测当前分支名
- 如果当前仓库不是 git 仓库，则使用稳定默认值，例如
main
- 检查
.codex/plans/{branch}/ 是否存在，不存在则创建
- 检查
.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. 错误记录
记录失败尝试和结果，避免重复踩坑。
五、恢复任务
- 读取
TASKS.md
- 找到状态为“进行中”或“暂停”的任务
- 打开对应
process.md
- 先读恢复胶囊
- 再读
[~] 步骤中的“下一步”
- 按记录恢复，不从头重规划
六、暂停任务
- 在
TASKS.md 中把任务标记为暂停
- 在
process.md 中把当前步骤标记为 [~]
- 写入明确下一步
- 更新恢复胶囊
- 如有新发现或新错误，同步写入对应章节
七、取消任务
- 先确认用户要取消
- 检查是否存在未提交代码或未处理文档变更
- 询问这些产物保留还是丢弃
- 再从
TASKS.md 中移除，并删除或归档任务目录
八、完成任务
- 确认所有步骤已完成
- 从
TASKS.md 中移除任务
- 删除或归档对应任务目录
- 汇报完成内容与验证结果
九、任务拆分原则
需要判断、确认或切换产出形态时拆分子任务，例如：
- 方案选择
- 跨域改动
- 从探索切到写文档或改代码
- 对外变更确认
- 验收节点
纯执行型连续步骤可以不拆。
十、子代理协作
当长任务被拆给子代理时，task-control 仍应由主代理维护主记录，不能因为子代理存在就跳过持久化。
建议额外记录：
- 当前子任务负责人
- 派发给子代理的边界
- 子代理回传的改动范围
- 尚未收口的后续步骤
如果任务已经注册，派发子代理前至少做到：
- 在
process.md 中写明当前进入哪个子任务阶段。
- 记录子代理需要读取的文件和回传要求。
- 子代理返回后，把有效结果合并回
process.md 的“研究发现”“步骤列表”或“下一步”。
- 若子代理执行中断，主代理仍负责写断点，不把恢复责任悬空给下一轮会话。
十一、异常处理
常见异常处理建议：
process.md 格式损坏：尽量按现有信息恢复，无法恢复时提示用户确认状态TASKS.md 与实际目录不一致：以文件系统为准修正- 仓库无 git 分支：使用默认分支名
- 断点文件路径失效：根据上下文推测新路径，必要时询问用户
