OthmanAdi/planning-with-files

Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.

它解决了什么问题

AI 编码代理经常面临「易失性内存」问题，即当上下文窗口被重置（例如通过 /clear 命令）、进行压缩或发生崩溃时，其任务计划和进度会丢失。这会导致目标漂移、重复错误，并迫使用户手动重新陈述目标。

它如何工作

该项目不将待办事项列表存储在易失性上下文窗口中，而是采用「文件系统作为内存」的方法。它在磁盘上维护三个持久化的 Markdown 文件：

task_plan.md：跟踪阶段、复选框和当前恢复点。
findings.md：存储研究笔记和决策记录。
progress.md：记录会话活动和测试结果。

生命周期钩子（如 UserPromptSubmit 或 SessionStart）会在每个回合开始时，自动将这些文件中的相关计划上下文重新注入代理的窗口，确保计划在上下文丢失时仍能保留，并持续处于模型的注意力窗口中。

适用人群

使用 AI 编码代理（如 Claude Code、Cursor、GitHub Copilot 或 Hermes Agent）执行长时间、复杂任务，且需要在会话或上下文重置之间保持持久性的开发者。

特色亮点

持久性：计划在 /clear 命令、崩溃和上下文压缩后依然存活。
代理无关性：通过 Agent Skills 标准兼容 60 多种代理，并为多个主流工具提供原生插件支持。
目标稳定性：每回合重新注入计划头部，防止目标漂移。
完整性检查：使用 SHA-256 证明机制检测计划是否被静默篡改。
完成门控：可阻止代理在磁盘上的计划中所有阶段未完成前声明任务「已完成」。