| name | task-planning |
| description | Decide when multi-step work needs a session todo list, decompose tasks, and track progress with the todo tool. LOAD when starting or continuing complex work — not when the user explicitly asks to "make a todo list". |
| category | agent |
Task planning (todo)
原则
- 用户说目标，Agent 决定是否拆 — 不必等「帮我拆任务」「列个 todo」。
todo tool = 记事本；拆什么、几条、顺序 — 你的判断。- 静默维护：建表、改 status 不要逐步播报；开始一句、结束给结果摘要。
- 与
clarify 不同：todo 是 Agent 自己的执行清单，不是问用户「还需要什么」。
何时 LOAD / 何时调用 todo
应该建表或更新（有分拆价值）
| 信号 | 示例 |
|---|
| 3+ 依赖步骤 | 先读代码 → 改 3 个文件 → 跑测试 → 更新文档 |
| 用户一次给多项 | 「修 CI、顺便更新 README、再开个 PR」 |
| 长链路 tool 调用 | 多轮 bash / 多文件 edit / 调研 + 实现 |
| 执行中发现新步骤 | merge=true 追加或改 status |
| 强信号 | 「分步做」「别漏」「先计划」—— 但不是必要条件 |
不要调用 todo（直接做）
| 情况 | 示例 |
|---|
| 一步完成 | 读一个文件、答一个概念、跑一条命令 |
| 纯对话 | 翻译、总结、闲聊 |
| 已有短 skill 且 ≤2 步 | 固定 one-shot 配方够用时 |
| 用户要直接结果 | 「别啰嗦，直接给答案」 |
灰色地带（自行判断）
- 名义 2 步但每步很重 → 可拆 2 条
- 开头以为简单，中途变大 → 做到一半
merge=false 新开一版计划 也可
配方
A. 开始复杂任务
判断：3+ 步 / 多子任务 / 长链路？
→ 否：直接执行，不调 todo
→ 是：
todo(todos='[
{"id":"1","content":"…","status":"in_progress"},
{"id":"2","content":"…","status":"pending"}
]', merge=false)
→ 立刻做第 1 项（不要只建表不动手）
拆法： 一般 3–7 条，按依赖排序；不要碎成 15 条 micro-task。
不要默认加「测试/验证」条，除非用户要求或项目惯例必须。
B. 推进中更新
完成一步 → todo(todos='[{"id":"1","status":"completed"},{"id":"2","status":"in_progress"}]', merge=true)
发现新步骤 → todo(todos='[{"id":"4","content":"…","status":"pending"}]', merge=true)
某步失败 → cancel 旧项 + 加修订项 merge=true
同时只有 1 个 in_progress（store 会纠正多个 in_progress，但仍应主动保持）。
C. 收尾
全部 relevant 项 → completed（或 cancelled 废弃项）
→ 给用户 **结果摘要**（完成了什么、如何验证）
→ 不要复读整张 todo 表，除非用户要看
D. 只读当前计划
todo() # 无参，返回完整列表 + summary
与 system prompt 的关系
Planning & Progress 段要求多步工作先 brief plan — 本 skill 规定用 todo tool 承载该 plan，使进度可追踪、可持久（workspace/.psi/todos/{session_id}.json）。
不要
- 不要把礼貌性收尾写进 todo（「询问用户是否满意」不是任务项）
- 不要每改一次 todo 就向用户汇报
- 不要用 todo 代替
clarify（缺信息、要选方案 → 用 clarify 或自然语言问用户）
- 简单任务不要为了「显得专业」强行建表
相关
- Task self-check：收尾前静默自检 —
skills/task-self-check/SKILL.md
- Subagent 委派：隔离子任务用 subagent，不是 todo —
skills/subagent-orchestration/SKILL.md
