用途
planning-with-files 是一套面向 AI 编码智能体的持久化文件规划技能，灵感来自 Manus 的工作方式：把重要信息写进磁盘上的 Markdown 文件，作为“磁盘工作记忆”。核心模型是：上下文窗口相当于易失且有限的 RAM，文件系统相当于持久且几乎无限的磁盘，因此凡是重要的内容都应落到文件里。
主要能力
技能在项目目录（而非技能安装目录）中维护三个文件：
- task_plan.md：阶段、进度、决策，每个阶段完成后更新；
- findings.md：调研与发现，任何新发现后立即写入；
- progress.md：会话日志、测试结果，贯穿整个会话更新。
核心规则包括：复杂任务必须先建 plan；每完成 2 次查看、浏览或搜索操作后立即把关键发现写入文件，防止多模态信息丢失；重大决策前重读计划；每阶段结束后标记状态并记录错误；所有错误都记入计划文件以避免重复失败；所有阶段完成后若用户追加需求，则在计划中新增阶段并继续。技能还给出“三振错误协议”：首次诊断并定向修复，第二次换方法，第三次重新审视假设，三次失败后升级给用户。
使用方式
复杂任务开始前，以 templates/ 中的模板为参考创建三个规划文件，之后反复“读计划—执行—更新文件”。技能附带若干脚本：init-session.sh 初始化规划文件（带名称参数时在 .planning/YYYY-MM-DD-<slug>/ 下创建隔离计划，不带参数则在项目根目录写 task_plan.md）；set-active-plan.sh 切换活动计划指针；resolve-plan-dir.sh 解析当前活动计划目录；check-complete.sh 检查所有阶段是否完成；session-catchup.py 在 /clear 后恢复上一会话的上下文；attest-plan.sh（及 .ps1）用 SHA-256 锁定当前 task_plan.md 内容，可用 --show 查看、--clear 清除。
并行任务工作流：在同一仓库中同时处理多个任务时，每次 init-session 生成独立计划目录，通过切换活动计划或设置 PLAN_ID 环境变量让每个终端读取各自的计划。
与 Claude Code 的集成：技能注册 PreCompact 钩子，在手动或自动压缩前提醒智能体把上下文内进度写入 progress.md，并在设置了 attestation 时打印计划哈希；无计划时保持静默，始终以退出码 0 结束，不阻塞压缩。插件安装方式还会提供 /plan-goal 与 /plan-loop 斜杠命令，分别与 Claude Code 的 /goal、/loop 原语组合，用于设定终止条件和按周期复读计划文件；仅技能安装不含 commands/ 目录，可用文档给出的手动替代步骤达到相同效果。
v3 新增可选的 autonomous 与 gated 两种模式，通过在计划目录写入 .mode 标记文件启用，无标记时行为与旧版一致。autonomous 模式保留每回合开始的计划注入，但取消每次工具调用时的计划重注入，并以账本摘要替代原始进度尾部；gated 模式在此之上增加完成门禁，仅在满足多种条件（处于 gated 模式、存在 in_progress 阶段、未处于强制继续中、阻断次数未达上限、账本有进展）时才阻断停止，且阻断原因只含固定模板与阶段名称。门禁按宿主能力分级：Claude Code、Codex CLI 等可硬阻断，Cursor、Pi、Kiro 为后续消息注入，OpenCode、Gemini CLI 等仅通知。
适用场景与限制
适合多步骤任务（3 步以上）、调研任务、项目构建、跨大量工具调用的长任务，以及任何需要组织性的工作；简单问题、单文件编辑和快速查询可跳过。文档说明门禁仅在 Tier 1 宿主上是真正的强制，其余宿主会降级为通知；斜杠命令在部分会话中可能因 disable-model-invocation 而不触发，此时需使用手动替代流程。具体平台支持、收费与价格信息暂未提供。