planning-with-files
为 AI 编程 agent 设计的持久化文件规划技能，通过 taskplan.md、findings.md、progress.md 三个文件让 agent 在 context 丢失、/clear 或崩溃后自动恢复任务状态。亮点是复现了被 Meta 20 亿美元收购的 Manus 核心模式，支持 Claude Code、Cursor、Codex 等 60+ agent 平台，提供可选的完成门控和并行规划隔离。基于 MIT 开源协议。
README
基于文件的规划 (Planning with Files)
📣 v3.0.0 新特性： 为长时间运行的 agent 运行提供可选的自主动模式和门控模式，并带有一个完成门（completion gate），该门会阻止 agent 直至计划实际完成。现有设置无需改动。
像 Manus 一样工作 — Meta 以 20亿美元 收购的 AI agent 公司。
planning-with-files 是为 AI 编码 agent 设计的持久化基于文件的规划技能。它将
task_plan.md、findings.md和progress.md保存在磁盘上，使 agent 能够抵抗 context loss（上下文丢失）、/clear和崩溃，并提供一个可选的完成门（completion gate），阻止 agent 直到计划实际完成。它通过 SKILL.md 标准安装到 60+ 种 agent 中。
-brightgreen)
致所有为这个技能点亮星星、fork 和分享的人——谢谢你们。这个项目在不到 24 小时内爆红，社区的支持令人难以置信。
如果这个技能能帮助你更聪明地工作，那就是我全部的心愿了。
🌍 社区贡献了什么Fork 与扩展
| Fork | 作者 | 构建内容 |
|---|---|---|
| devis | @st01cs | 以面试优先的工作流，/devis:intv 和 /devis:impl 命令，保证激活 |
| multi-manus-planning | @kmichels | 多项目支持，SessionStart git 同步 |
| plan-cascade | @Taoidle | 多级任务编排，并行执行，多 agent 协作 |
| agentfund-skill | @RioTheGreat-ai | 基于里程碑托管在 Base 上的 AI agent 众筹 |
| openclaw-github-repo-commander | @wd041216-bit | 针对 OpenClaw 的 7 阶段 GitHub 仓库审计、优化和清理工作流 |
实际使用中的项目
| 项目 | 说明 |
|---|---|
| lincolnwan/Planning-with-files-copilot-agent | 整个基于 planning-with-files 技能的 Copilot agent 仓库 |
| cooragent/ClarityFinance | AI 金融 agent 框架——直接致谢 Planning-with-Files 方法 |
| oeftimie/vv-claude-harness | 基于 Manus 风格持久化 markdown 规划的 Claude Code 工具集 (harness) |
| jessepwj/CCteam-creator | 使用基于文件的规划的多 agent 团队编排技能 |
技能注册表与中心
| 注册表 | 说明 |
|---|---|
| buzhangsan/skill-manager | 双语（英文/中文）技能中心，索引 31,000+ 个 Claude Code 技能——planning-with-files 可一键安装。 |
构建了一些东西？提交 issue 来被收录！
🤝 贡献者请参阅 CONTRIBUTORS.md 查看完整贡献者名单。
📦 发布与 Session 恢复当前版本：v3.2.0
| 版本 | 亮点 |
|---|---|
| v3.2.0 | 仓库健康审计：session-catchup.py 在 Windows 上不工作，以及“0/0 phases”虚假状态（关闭 #191，解决 #103，关闭 #188）。 session-catchup.py，即“在 /clear 后恢复”的机制，从未正确清理 Windows 风格的路径，并且在三次读取中没有显式编码，因此在 Windows 上静默地什么都不做，没有任何错误。inject-plan.sh 的包含守卫（containment guard）也静默地丢弃了在 8.3 短名称或 /tmp 别名路径下的计划注入和篡改检测。两者均已修复。另外，check-complete.sh/.ps1 以及三个 IDE 特定的 Stop 钩子对任何没有 ### Phase 标题的 task_plan.md 报告了虚假的“0/0 phases complete”（#191，由 @mixian939 报告）；在所有出现该模式的地方均已修复，包括规范脚本。--template analytics 标志（v2.29.0）在安装的每个技能包中都静默地回退到默认模板；现在 analytics 模板实际上会包含在 init-session.sh 读取它们的位置。合并了 PR #187（@Stephen-abc：Windows 测试编码修复，过时的安装路径文档）和 PR #192（@igorcosta：Autohand Code 设置文档）。新增了 SECURITY.md 并启用了私有漏洞报告（@AvitalAviv）。修正了 AGENTS.md 中的贡献者 PR 合并指导，该指导曾告诉 agent 以会重新分配作者身份的方式进行 squash-merge。测试套件 186 passed, 5 skipped, 0 failed。 |
| v3.1.3 | 修复：v3.1.2 中 SKILL.md 的 frontmatter 是无效的 YAML。 v3.1.2 的描述刷新添加了一个冒号，而英文 SKILL.md 的 description 未加引号，因此 YAML 拒绝了 frontmatter（“mapping values are not allowed here”），这可能会破坏技能加载和模型触发的描述。v3.1.3 在规范文件和七个英文 IDE 变体中为 description 加了引号（与已加引号的翻译变体匹配；解析后的值相同），并添加了 tests/test_skill_frontmatter_valid.py 来验证每个 SKILL.md frontmatter 是否为合法的 YAML。测试套件 184 passed。 |
| v3.1.2 | Session-catchup 命令在插件运行时之外工作，.hermes 对等性，刷新了技能描述（PR #186 由 @shunfeng8421 提交，关闭 #185，由 @xwang118 报告）。文档化的恢复上下文命令（Restore Context）使用了 ${CLAUDE_PLUGIN_ROOT}，而该变量仅在钩子执行期间由插件运行时设置，因此纯技能安装（npx skills add, Codex, Cursor）在 shell 中运行时会得到空变量和损坏的 /scripts/... 路径。现在规范文件、.codebuddy 和五个语言变体中使用 SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"；.hermes 变体为 $HERMES_HOME 添加了同样的回退。八个英文 SKILL.md 描述被刷新，以首先突出“面向 AI 编码 agent 的规划”和“上下文丢失生存能力”，Use when 触发器和翻译变体保持不变。仅文档更新；测试套件 180 passed。 |
| v3.1.1 | Codex 验证命令检查规范 hooks 特性标志（PR #184 由 @Fat-Jan 提交）。docs/codex.md 中的 verify 块运行了 codex features list | rg '^codex_hooks\s'，但 Codex 在 0.129.0 (openai/codex#20522) 中将其规范特性键从 codex_hooks 改为 hooks。别名在配置中仍能解析，但 codex features list 只打印 hooks，因此旧模式在当前 Codex 上未匹配到任何内容，并将正确配置的用户导向了升级路径。现在该命令 grep ^(hooks|codex_hooks)\s，故障排除句子涵盖了这两个名称，与自 v2.39.0 起文件中携带的 hooks = true 指导相匹配。仅文档更新；测试套件 180 passed。 |
| v3.1.0 | Codex Stop 钩子不再因计划未完成而阻塞，原生 Codex PreCompact 对等性，Pi 扩展测试套件，以及准确的 SHA 缓存文档（PR #180 由 @2023Anita 提交，关闭 #178；PR #181 由 @GongYuanCaiJi 提交；PR #175 和 PR #174 由 @mvanhorn 提交，关闭 #163 和 #164）。.codex Stop 适配器移除了 {"decision":"block"} 路径，该路径曾推动 Codex agent 自动继续未完成的阶段；现在只发出一个咨询性的进度同步提醒，与 v3 原则（未完成的计划本身从不阻止停止）相匹配。原生的 .codex/hooks.json 路径获得了相对于规范 SKILL.md 缺失的 PreCompact 钩子（pre-compact.sh），该钩子在从未触发该事件的运行时上处于休眠状态。Pi 扩展获得了涵盖所有八个生命周期处理器、四种运行时模式和认证门的 TypeScript 集成套件。docs/perf-notes.md 记录了认证 SHA 缓存，已更正为 v3 $XDG_CACHE_HOME/pwf-sha 位置。测试套件 180 passed。 |
| v3.0.0 | 用于长时间运行 agent 式运行的自主动和门控模式、结构化运行账本、可选的完成门（无重大变更：没有模式标记时，钩子产生与 v2.43 字节相同的输出）。init-session --autonomous 对强模型放弃每次工具调用的计划重新注入，保留轮次开始时的注入；--gated 添加了一个故意的 Stop 钩子完成门，仅在五个条件同时满足时才会阻塞：门控模式、存在 in_progress 阶段、stop_hook_active 为 false、阻塞计数低于上限、账本自上次阻塞以来已推进。因此，未完成的计划本身永远不会困住一个 session。新的仅追加 JSONL 运行账本（ledger-append, ledger-summary, phase-status，sh + ps1）在 v3 模式下用固定形状的摘要替换了原始的 progress.md 尾部。v3 模式下认证默认开启，未认证的计划主体在注入时被拒绝。每次 session 的 nonce 分隔符、SHA 缓存移至 $XDG_CACHE_HOME/pwf-sha、计划目录解析器中的 realpath 包含性检查。钩子数量已由轻量调度器（inject-plan.sh, gate-stop.sh）替换，这些调度器部署在两个 scripts/ 位置。新的 templates/task_plan_autonomous.md 包含 DependsOn/Owner/AcceptanceCheck 字段，v2 到 v3 迁移指南在 MIGRATION.md 中，主机能力层级已文档化（硬阻塞、后续跟随注入、仅通知）。测试套件 178 passed，加上位置对等性、门/账本/初始化模式/包含性测试。 |
| v2.43.0 | CONTRIBUTING.md + OpenCode 文档修复 + .continue/.gemini/.kiro 变体同步到对等（PR #171 由 @Skulli485，issue #172 由 @luyanfeng，issues #159/#160/#161）：仓库根目录下第一个 CONTRIBUTING.md，GitHub 会在 PR 创建流程中自动显示。docs/opencode.md 中的快速安装从 git clone 改为 npx skills add，因为手动安装块引用了重复路径（planning-with-files/planning-with-files/SKILL.md）。三个历史上滞后的 IDE SKILL.md 变体已升级到 v2.43.0 对等：.continue 从 v2.34.0（落后 9 个版本），.gemini 从 v2.34.0（落后 9 个版本），.kiro 从 v2.32.0-kiro（落后 11 个版本），保留了 IDE 特定的 frontmatter、钩子形状和 Kiro Agent Skill 布局。 |
| v2.42.0 | POSIX init-session.sh 可移植性 + 插件 vs 技能安装透明度 + 主题交接文档（PR #169 和 PR #170 由 @carterusedulm2-maker 提交）：init-session.sh 及其 7 个镜像将 [[ ]] bashism 替换为 POSIX [ ]，以便在测试通过 sh（而非 bash shebang）调用脚本时，在 dash (Ubuntu) 下干净地运行 tests/test_init_session_slug.py。规范 SKILL.md 增加了安装范围说明：/plugin install 会部署 commands/ 文件夹（包含 /plan-goal 和 /plan-loop），但 npx skills add（以及 ClawHub）不会。为这两个包装器记录了一个手动回退过程，以便仅技能 session 通过直接调用 Claude Code 的原生 /goal 和 /loop 原语产生相同效果。docs/quickstart.md 和 docs/workflow.md 为非常长时间运行的操作主题增加了可选的“主题交接模式”（handoffs/<topic>.md 与 progress.md 配合使用）。 |
| v2.41.0 | Windows exec-bit 测试跳过 + 认证锁定文档（PR #167 由 @gauravvojha，Issue #166；PR #168 由 @CleanDev-Fix，Issue #165）：test_script_permissions.py 现在在 Windows 上使用类级别的 pytest.mark.skipif(sys.platform == "win32") 跳过测试，因为 NTFS 不存储 POSIX 可执行位；两个自 v2.34.1 以来存在的 Windows exec-bit 失败已解决。新增专门的 docs/attestation-locking.md 页面，记录了 attest-plan.sh 的写入路径、原子 temp-rename 保证、可选的 flock 建议锁，以及针对并行 session 的推荐 slug 模式工作流。 |
| v2.40.1 | Pi 适配器 SKILL.md 同步差距 + npm 作用域修正（PR #158 由 @TomXPRIME 提交）：.pi SKILL.md 落后于 v2.39.0 之后的规范 Claude Code 副本；v2.40.1 向后移植了规则 7（完成后再继续）、安全边界部分、扩展的脚本部分（涵盖 set-active-plan.sh/resolve-plan-dir.sh/attest-plan.sh 以及并行任务工作流），以及“将 web 内容写入 task_plan.md”的反模式行。Pi npm 包从无作用域的 pi-planning-with-files 重命名为 @tomxprime/planning-with-files，匹配包作者的名字空间；安装文档相应更新。作者、仓库、许可证和 bug 的 URL 保持不变。 |
| v2.40.0 | Slug 模式解析修复 + 性能缓存 + KV-cache 卫生 + Pi 误报修复（来自 v2.40 研发实验的 9 项）：钩子解析顺序已颠倒，使 slug 模式优先于旧的根目录；.active_plan 目标目录 + 内容针对安全标识符正则表达式进行了验证；check-complete.sh 尊重 $PLAN_ID 和 .active_plan；Pi 扩展 isDangerousBashCommand 已替换为词边界正则表达式数组，因此良性的 git push origin <branch> 不再触发警告；mtime 键控的 SHA-256 缓存减少了 Windows Git Bash 上认证钩子的延迟；progress.md 尾部时间戳已标准化以保证 KV-cache 前缀稳定性；resolve-plan-dir.sh mtime 解析在 GNU/BSD/macOS/Alpine/Git Bash 之间可移植，并带有 python+perl 回退；attest-plan.sh 使用原子 temp-rename 和可选的 flock 解决了并发写入器竞争。130 pass / 2 个预先存在的 Windows exec-bit 失败，+20 个新测试。 |
| v2.39.0 | Pi 编码 Agent 完整钩子对等扩展 + Codex hooks 标志修复（PR #157 由 @TomXPRIME 提交，Issue #154 由 @DLI1996 提交）：.pi 适配器附带一个捆绑的 TypeScript 扩展，将 8 个 Pi 生命周期事件映射到该技能在 Claude Code 上提供的相同行为，具有四模式系统（auto/parity/cache-safe/notify），自动检测 DeepSeek 并保持 KV-cache 前缀稳定。Pi 运行时读取与规范 v2.37 attest-plan.sh 写入的相同 .attestation 文件，因此认证一次即可在两个运行时上锁定计划。四个斜杠命令（/plan-status、/plan-attest、/plan-goal、/plan-loop）镜像了其 Claude Code 对应项。另外，docs/codex.md 从 codex_hooks = true 换为 hooks = true 以匹配当前 OpenAI 规范键，并附带别名注释，以便使用旧配置的用户无需迁移。 |
| v2.38.1 | Claude Code 技能选择器中的描述字段乱码（通过 Discussion #153 由 @bmyury 发现）：钩子命令嵌入了 '---BEGIN PLAN DATA---' 计划注入分隔符；Claude Code 的技能发现加载器在第一个 --- 处分割了 frontmatter，并读取了截断的值作为描述。已更换为 ===BEGIN PLAN DATA=== / ===END PLAN DATA===，覆盖规范 SKILL.md、所有五个语言变体、.codebuddy/.codex/.cursor 适配器镜像以及 clawhub-upload。钩子执行和篡改认证从未受影响；仅影响显示元数据。 |
| v2.38.0 | Claude Code 轮次循环集成 + OpenCode SQLite 修复：新增 PreCompact 钩子，在 /compact 和 autoCompact 时触发，在压缩完成前提示刷新进度，并在已认证时打印活跃计划 SHA256。新增 /plan-goal 斜杠命令，与 Claude Code 的 /goal（v2.1.139, 2026年5月12日）配合使用：从活跃计划中推导出终止条件。新增 /plan-loop 与 /loop（v2.1.72+）配合使用：默认 10 分钟间隔，重新读取规划文件并运行 check-complete。新增 templates/loop.md 用于裸 /loop 的规划感知默认行为。Session-catchup 针对 OpenCode 的 SQLite 迁移进行了重写。Codex 获得了 PermissionRequest 适配器，在权限提示时显示计划上下文。 |
| v2.37.0 | 哈希认证 + 对等性增量更新（关闭 #150, #151）：/plan-attest 使用 SHA-256 锁定 task_plan.md；钩子阻止注入时的篡改。scripts/bump-version.py + 对等性测试消除了 v2.34.1、v2.36.0、v2.36.2 和 v2.36.3 背后的“遗漏一个变体”回归类别。（感谢 @oaabahussain！） |
| v2.36.3 | 并行规划脚本现在随技能一起发布：resolve-plan-dir.sh 和 set-active-plan.sh 在 v2.36.0 中缺失于已安装的技能中；现在已包含在规范 + 所有 IDE 镜像 + SKILL.md 文档更新中 |
| v2.36.2 | 规范脚本同步（PR #149）：skills/planning-with-files/scripts/init-session.sh 缺少 v2.36.0 中的 slug 模式；现已与 IDE 镜像同步 + 回归测试。（感谢 @voidborne-d！） |
| v2.36.1 | 安全加固：移除 Stop 钩子缓存搜索，ExecutionPolicy Bypass 改为 RemoteSigned，添加了提示注入分隔符。（已解决 Gen Agent Trust Hub FAIL） |
| v2.36.0 | 并行计划隔离 + Codex session 隔离（关闭 #146, #148）：init-session.sh slug 模式，set-active-plan.sh，resolve-plan-dir.sh，所有 Codex 钩子通过解析器路由，session 附加门控。Hermes 文档（关闭 #147）：集成说明已添加到 docs/hermes.md。34 个新测试。（感谢 @githubYiheng, @09ashishkapoor, @shawnli1874！） |
| v2.35.1 | Shebang 可移植性修复：将 /bin/bash 改为 /usr/bin/env bash，修复了在 NixOS 和 bash 不在 /bin/bash 的其他系统上的兼容性问题。（感谢 @Emin017！） |
| v2.35.0 | Hermes 适配器 + NLPM 审计加固：Hermes 平台 17 支持（感谢 @bailob！），NLPM 审计修复了 Python PATH 解析，session-catchup 注入上限，Pi PowerShell 语法（感谢 @xiaolai！） |
| v2.34.1 | Stop 钩子 Windows 可移植性修复（关闭 #133）：export SD= 在 Windows Git Bash 钩子上下文中失败；插件缓存结构的回退路径错误。已在所有 13 个 SKILL.md 变体中修复。（感谢 @nazeshinjite！） |
| v2.34.0 | Codex 钩子完全恢复（关闭 #132）：.codex/hooks.json + 生命周期脚本恢复——SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop。用于 SKILL.md 质量审查的 Tessl CI。可执行位修复。新增 4 位缺失的贡献者。（感谢 @Leon-Algo, @popey！） |
| v2.33.0 | 多语言扩展：新增阿拉伯语、德语和西班牙语技能变体（感谢社区贡献者！） |
| v2.32.0 | Codex session catchup 重写（感谢 @ebrevdo！），Loaditout A 级安全徽章，Stop 钩子 Git Bash 修复 |
| v2.31.0 | Codex hooks.json 集成，具有完整生命周期钩子（感谢 @Leon-Algo！） |
| v2.30.1 | 修复：Codex 脚本可执行位恢复（感谢 @Leon-Algo！） |
| v2.30.0 | CLAUDE_SKILL_DIR 变量，IDE 配置移至各 IDE 分支，plugin.json 从 v2.23.0 升级 |
| v2.29.0 | 分析工作流模板：用于数据探索 session 的 --template analytics 标志（感谢 @mvanhorn！） |
| v2.28.0 | 繁体中文 (zh-TW) 技能变体（感谢 @waynelee2048！） |
| v2.26.2 | 修复：钩子命令中的 --- 破坏了 YAML frontmatter 解析，钩子现在正确注册 |
| v2.26.1 | 修复：/clear 后的 session catchup，Windows 上的路径消毒 + 内容注入（感谢 @tony-stark-eth！） |
| v2.26.0 | IDE 审计：Factory 钩子，Copilot errorOccurred 钩子，Gemini 钩子，错误修复 |
| v2.18.2 | Mastra Code 钩子修复（hooks.json + 文档准确性） |
| v2.18.1 | Copilot 乱码完全修复 |
| v2.18.0 | BoxLite 沙箱运行时集成 |
| v2.17.0 | Mastra Code 支持 + 所有 IDE SKILL.md 规格修复 |
| v2.16.1 | Copilot 乱码修复：PS1 UTF-8 编码 + bash ensure_ascii（感谢 @Hexiaopi！） |
| v2.16.0 | GitHub Copilot 钩子支持（感谢 @lincolnwan！） |
| v2.27.0 | Kiro Agent Skill 布局（感谢 @EListenX！） |
| v2.15.1 | Session catchup 误报修复（感谢 @gydx6！） |
| v2.15.0 | /plan:status 命令，OpenCode 兼容性修复 |
| v2.14.0 | Pi Agent 支持，OpenClaw 文档更新，Codex 路径修复 |
| v2.11.0 | /plan 命令，便于自动完成 |
| v2.10.0 | Kiro steering 文件支持 |
| v2.7.0 | Gemini CLI 支持 |
| v2.2.0 | Session 恢复，Windows PowerShell，操作系统感知的钩子 |
并行计划隔离（
.planning/YYYY-MM-DD-slug/目录）和 Codex session 隔离已在 v2.36.0 中发布。experimental/isolated-planning分支是早期原型；master 现在是规范位置。
Session 恢复
当你的上下文填满并运行 /clear 时，该技能会自动恢复你之前的 session。
工作原理：
- 在活跃 IDE 的 session 存储中检查之前的 session 数据（Claude Code 为
~/.claude/projects/，Codex 为~/.codex/sessions/） - 查找规划文件上次更新时间
- 提取之后发生的对话（可能丢失的上下文）
- 显示追赶报告（catchup report），以便你同步
专业提示： 禁用自动压缩以最大化清除前的上下文：
{ "autoCompact": false }
增强支持（钩子 + 生命周期自动化）
这些 IDE 具有专用的钩子配置，可在工具使用前自动重新读取计划、提醒你更新进度，并在停止前验证完成情况：
| IDE | 安装指南 | 集成 |
|---|---|---|
| Claude Code | 安装 | Plugin + SKILL.md + Hooks |
| Cursor | Cursor 设置 | Skills + hooks.json |
| GitHub Copilot | Copilot 设置 | Hooks（包含 errorOccurred） |
| Mastra Code | Mastra 设置 | Skills + Hooks |
| Gemini CLI | Gemini 设置 | Skills + Hooks |
| Kiro | Kiro 设置 | Agent Skills |
| Codex | Codex 设置 | [Skills + Hooks](https://developers.openai |