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 證明機制，偵測計畫是否遭靜默竄改。
完成門檻：可阻止代理在磁碟上的計畫所有階段未完成前宣告任務「已完成」。