Planning With Files

它做什么

• 磁盘上的三个文件——task_plan.md、findings.md、progress.md——由 UserPromptSubmit hook 在每轮开始时重注入当前计划
• /clear、上下文压缩与崩溃都打不断：清空后 skill 从磁盘重读项目文件；恢复路径只读项目文件，不翻 agent 会话记录
• 经 Agent Skills 标准覆盖 60+ agent，并为 Claude Code、Codex CLI、Qoder、Pi、Hermes Agent、OpenCode、DeepSeek Harness 提供原生插件
• v3 长任务特性：按 agent 的运行台账、PLAN_ID 并行任务计划隔离、能识别停摆的完成门，以及并行写入防护

什么时候用

「agent 干到一半忘了计划」是主要失败模式的长任务：重构、迁移、跨天的构建。与 plan mode 是互补不是替代——先接受计划，再让它写进 task_plan.md，之后由 hooks 稳住注意力窗口。也照应编排者/工人的多 agent 场景：同一份计划可在不同宿主间交接（Claude Code、Codex、Pi、Hermes、OpenCode 读同一批文件）。

如何上手

Claude Code 插件路径（skill + hooks + 斜杠命令）：

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

其他 agent 一行搞定（覆盖 60+ agent）：

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

另有 npm install planning-with-files 用于锁定版本，但它不注册 hook。

注意事项

各安装路径给的东西不同：只有 Claude Code 插件（及 Pi/Hermes/OpenCode/DSH 原生插件）带 hooks；裸 npx skills add 只装模式本身，frontmatter hook 能否生效取决于宿主。计划文件默认进 gitignore、属工作记忆——下一个任务会覆盖根计划，值得留的结论要主动沉淀进代码或文档。自 v3.6.0 起每次 hook 触发开销 289ms（KV-cache 稳定）。另有中文版 skill（planning-with-files-zh）单独分发。