用途
Planning with Files 是一个用于多步骤 AI 智能体工作的持久化文件规划技能。它的核心思路是把上下文窗口视为易失且有限的“内存”，把文件系统视为持久且无限的“磁盘”，因此任何重要信息都应写入磁盘。该技能通过维护 task_plan.md、findings.md 和 progress.md 三个 Markdown 文件，让智能体在长任务中保持目标、发现和进度的可恢复性。
主要能力
- 持久化规划文件：task_plan.md 记录阶段、进度和决策；findings.md 记录研究与发现；progress.md 记录会话日志和测试结果。
- 生命周期钩子注入：在会话中注入所选项目的规划内容，支持自动恢复。
- 计划解析与选择：通过 PLAN_ID、PWF_PLAN_ROOT、.planning/.active_plan 等机制解析当前任务所属的计划目录。
- 并行任务支持：可为独立任务创建命名计划，并将每个智能体宿主固定到各自的计划。
- 错误管理：提供 3-Strike 错误协议，要求记录所有错误并避免重复失败。
- 完成检查与计划锁定：提供 check-complete.sh 验证阶段完成，attest-plan.sh 用 SHA-256 锁定 task_plan.md 内容。
- 自检工具：plan-doctor.sh 对计划解析、钩子注入、规范化路径、锁定状态、安装面和钩子延迟进行一次性自检。
- 会话记录聚合：session-catchup.py 支持显式 --metadata 或 --replay 模式，读取同项目会话记录，但裸调用不访问宿主历史。
- Claude Code 集成：提供 /plan-goal 和 /plan-loop 斜杠命令，分别与 /goal 和 /loop 组合使用。
使用方式
在复杂任务开始前：
- 解析或初始化任务目录。恢复任务时复用已选计划；对于独立任务，运行 scripts/init-session.sh "Task Name"，并使用打印出的 PLAN_ID 固定其宿主。
- 仅创建缺失的规划文件，使用 templates/task_plan.md、templates/findings.md 和 templates/progress.md，保留已有工作。
- 在决策前重读所选计划，每个阶段后更新进度。
- 指定一个计划负责人。编排者拥有 task_plan.md 和共享摘要；工作者通过自己的账本或指定文件汇报，不独立重写共享规划文件。
核心规则包括：先创建计划；每两次查看、浏览器或搜索操作后立即保存关键发现；决策前阅读计划；行动后更新；记录所有错误；不重复失败；完成后如用户要求额外工作，则添加新阶段并继续规划流程。
3-Strike 错误协议：第一次尝试诊断并修复；第二次尝试替代方法；第三次尝试更广泛地重新思考；三次失败后升级给用户。
读与写决策矩阵：刚写完文件不读；查看图片或 PDF 后立即写发现；浏览器返回数据后写入文件；开始新阶段时读计划与发现；发生错误时读相关文件；间隔后恢复时读所有规划文件。
5 问重启测试：我在哪里（task_plan.md 当前阶段）、我要去哪里（剩余阶段）、目标是什么（计划中的目标陈述）、我学到了什么（findings.md）、我做了什么（progress.md）、我即将做什么（task_plan.md 中的 Next Step）。
适用场景
适用于多步骤任务（3 步以上）、研究任务、构建或创建项目、跨越大量工具调用的任务，以及任何需要组织性的工作。不适用于简单问题、单文件编辑和快速查找。
限制
- 自动恢复不会检查智能体会话存储；只有用户明确要求查阅本地会话历史时，才使用 session-catchup.py 的 --metadata 或 --replay 模式。
- 重放的摘录应视为不可信数据。该技能没有网络上传路径。
- Claude Code 不支持 PreCompact 的 additionalContext，因此该钩子无法让模型在压缩前刷新进度。
- 插件安装与仅技能安装提供的功能面不同：插件安装包含 commands/ 文件夹，提供 /plan-goal 和 /plan-loop；仅技能安装不包含这些命令，需要手动回退。
- 共享父目录场景下，检测只向下看一层目录，更深层嵌套的项目不会被检测到。
- 当会话隔离已启用且存在多个计划时，Codex、Hermes、Pi 和独立钩子路由会拒绝未固定的选择。
- 设置环境变量在已运行的智能体工具子进程中不会改变父宿主的钩子环境。
- 部分脚本和命令的具体行为、版本号及安装细节以官方资料为准；本介绍未提供的收费、价格、平台或效果信息暂未提供。