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. Claude Code, Codex, Cursor, Kiro, OpenCode and 60+ agents via the Agent Skills standard.

解决的问题

AI 编程代理经常面临易失性内存的问题，当上下文窗口重置时（例如通过 /clear 命令或崩溃），关键的任务计划和研究结果会丢失。这会导致目标偏移、重复错误，以及用户在会话重置后需要手动重新说明目标。

工作原理

该项目实现了一种“三文件模式”，将文件系统视为代理工作内存的持久化磁盘。对于每个复杂的任务，代理会创建并维护三个特定的 Markdown 文件：

  • task_plan.md：跟踪阶段和进度复选框。
  • findings.md：存储研究笔记和决策。
  • progress.md：会话日志和测试结果。

为了确保这些文件得到使用，该项目为各种 AI 代理（如 Claude Code、Cursor 和 GitHub Copilot）提供了生命周期钩子，在每一轮开始时将计划重新注入代理的上下文，提醒代理编写更新，并在允许代理停止之前验证完成情况。

适用对象

使用 AI 编程代理（如 Claude Code、Cursor 或 Pi）的开发者，他们正在处理超出 LLM 上下文窗口限制的长期、多步骤任务。

亮点

  • 持久化内存：在上下文清除、崩溃和会话重置后依然存在。
  • 广泛的兼容性：通过 Agent Skills 标准支持 18 多个平台上的 60 多个代理。
  • 生命周期自动化：使用钩子使计划注入和更新成为机械化的过程，而非可选操作。
  • 会话恢复：自动检测之前的会话数据，帮助代理从当前阶段恢复工作。
  • 验证：包含 SHA-256 锁定机制，以防止计划内容被篡改。