用途
planning-with-files 是一个基于 Markdown 文件的规划技能，用于 AI 编程智能体和长时间运行的智能体任务。它解决的核心问题是：智能体的上下文窗口会在 /clear、压缩或崩溃后丢失工作记忆，而磁盘上的计划不会。该技能将任务计划、发现和进度保存在项目内的 Markdown 文件中，并通过钩子在每一轮对话开始时重新注入选定的规划上下文，从而让计划在上下文丢失后仍能恢复。
主要能力
- 三文件模式：在项目中维护 task_plan.md、findings.md 和 progress.md。并行任务使用隔离目录 .planning/YYYY-MM-DD-slug/，包含同样的三个文件，通过 .active_plan 选择（v2.36.0+）。纯 Markdown，默认被 gitignore，不在其他地方保存运行时状态。
- 每轮重新注入：UserPromptSubmit 钩子在每轮开始时重新注入选定的活动计划上下文，对抗上下文腐化（context rot）。
- 崩溃与 /clear 恢复：在 /clear 或新会话后，技能从磁盘重新读取项目文件。自动恢复路径只读取项目文件；读取同项目本地智能体会话记录以进行聚合计数或有界重放需要显式启用 catchup 模式。
- 确定性完成门：完成门读取账本而非 progress.md 的修改时间，可阻止智能体在计划报告完成前停止。
- 哈希证明：计划经过哈希证明（hash-attested）。
- 多智能体运行：磁盘上的 Markdown 是智能体之间的共享状态。一个编排者拥有 task_plan.md 和共享摘要；每个工作者向自己的账本或分配的文件追加。每个智能体有运行账本（.planning/<id>/ledger-<agent>.jsonl），ledger-summary.sh 从所有账本合成固定形状、KV 缓存稳定的块。
- 计划隔离：init-session.sh "<name>" 为每个并行任务提供自己的 .planning/YYYY-MM-DD-<slug>/ 目录；PLAN_ID 将终端固定到其中一个；set-active-plan.sh --list 显示可用计划及阶段计数，set-active-plan.sh <id> 切换共享指针。
- 并行写入保护：如果勾选项目或已完成阶段减少，下一轮会发出警告。这是写入后的建议性检查，不是锁或合并机制。
- 停滞感知门：完成门读取账本，因此停止产生事件的工作者会释放停止而不是循环。
- 多主机共享：Claude Code、Codex、Pi、Hermes 和 OpenCode 读取相同的文件、相同的 .attestation 和相同的门计数器，因此计划可以在运行中途从一个智能体交给另一个。
使用方式
安装路由：
- Claude Code 插件路由（包含技能、钩子、斜杠命令）：
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
- 其他智能体，一行命令，通过 Agent Skills 标准支持 60+ 智能体：
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
- npm，将精确版本固定到项目或 vendor 化：
npm install planning-with-files
该包包含 SKILL.md、scripts/ 和 templates/，适合将版本锁定到仓库依赖中或自行复制技能。它本身不注册钩子。
- Pi Coding Agent，同一 npm 包，已为你接好（技能、扩展、状态栏）：
pi install npm:planning-with-files
- Hermes Agent（Nous Research），原生插件加技能包，CLI 和 Desktop：
hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
- OpenCode，原生插件加技能（npx skills add 命令会落到 ~/.agents/skills/，OpenCode 会读取）：
"plugin": ["planning-with-files"]
在 opencode.json 或 ~/.config/opencode/opencode.json 中；OpenCode 下次启动时安装。
- DeepSeek Harness（DSH），原生插件加技能（npx skills add 命令会落到 ~/.agents/skills/，DSH 会读取）：
dsh plugin install planning-with-files
然后重启 dsh web；同一命令适用于 headless、sdk 和 acp 配置文件。
触发方式：输入 /plan（插件）或让智能体“plan this task”；技能也会在多步任务上自触发。
适用场景
- 长时间运行的智能体任务：大多数工具链提供的待办列表存在于上下文窗口内，而 planning-with-files 的计划存在于磁盘上，每轮重新注入，经过哈希证明，并可阻止智能体停止直到计划报告完成。
- 需要跨 /clear、压缩或崩溃恢复的编程任务。
- 多智能体运行：编排者、工作者和子智能体之间通过磁盘上的 Markdown 共享状态。
- 与 Claude Code 的 plan mode 互补：plan mode 是执行前设计和批准方法，planning-with-files 在工作运行时将实时执行状态持久化到磁盘并每轮重新注入。
限制
- 计划文件是工作记忆，不是受跟踪的交付物。task_plan.md、findings.md、progress.md 和 .planning/ 目录默认被 gitignore，不会自动归档：下一个任务会覆盖根计划，slug 目录只是不再活跃。任何值得保留的内容应提升到代码、提交或文档中。
- 技能路由安装可能静默地没有钩子（项目信任未接受，或项目级安装时 frontmatter 钩子未注册）。钩子是差异化机制，如果钩子对你重要，请使用插件路由，然后用 /plan-doctor 验证。
- 并行写入保护是建议性检查，不是锁或合并机制，不能检测每一个被覆盖的计划、progress.md 或 findings.md。
- 自动恢复路径不检查智能体转录存储；读取同项目本地智能体会话记录需要显式 catchup 模式。
- 钩子性能：自 v3.6.0 优化后，一次钩子触发实测 289ms 墙钟时间，此前为 2.0 到 2.4 秒。
- 状态令牌保持字面英文（Status: complete），因为 check-complete.sh 用 grep -F 匹配它们，翻译它们会禁用完成门。
- 如果 IDE 使用旧版 Rules 系统而非 Skills，请参见 legacy-rules-support 分支。
- BoxLite 是沙箱运行时，不是 IDE；技能通过 ClaudeBox（BoxLite 的官方 Claude Code 集成层）加载。
支持平台
Claude Code、OpenAI Codex CLI、Cursor、GitHub Copilot、Kiro、OpenCode、Continue、Pi、Hermes Agent、CodeBuddy、Factory、Mastra 等 70+ 通过 SKILL.md 开放标准。自 v3.7.0 起，仓库还在树内提供跨工具 .agents/skills/planning-with-files/ 布局，因此原生读取 Agent Skills 标准路径的工具（Zed、Amp、Warp、Devin、Antigravity、Gemini CLI、Cursor）可以从纯 git clone 发现当前技能，无需按工具设置。
语言
提供阿拉伯语、德语、西班牙语、简体中文、繁体中文翻译。这些是真实翻译，不是英文正文加翻译描述：SKILL.md 正文、模板以及 check-complete、init-session 和 session-catchup 的用户可见输出都已本地化。它们位于 skills/i18n/ 下，比规范技能深一个目录。自 v3.10.0 起，变体也提供完整脚本表面。
