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 によるもの）、コンパクション中、またはクラッシュ後に、タスクプランと進捗が失われる「揮発性メモリ」の問題に悩まされることがよくあります。これにより、目標のドリフト（逸脱）、繰り返されるミス、そしてユーザーが手動で目標を再提示する必要性が生じます。

仕組み

揮発性のコンテキストウィンドウ内にToDoリストを保持する代わりに、このプロジェクトは「ファイルシステムをメモリとして利用する」アプローチを採用しています。ディスク上に以下の3つの永続的なMarkdownファイルを保持します：

task_plan.md: フェーズ、チェックボックス、および現在の再開ポイントを追跡します。
findings.md: 調査ノートと決定事項を保存します。
progress.md: セッションのアクティビティとテスト結果をログに記録します。

ライフサイクルフック（UserPromptSubmit や SessionStart など）により、各ターンの開始時にこれらのファイルから関連するプランコンテキストがエージェントのウィンドウに自動的に再注入され、プランがコンテキストの喪失を生き延び、モデルのアテンションウィンドウ内に留まることを保証します。

対象者

AIコーディングエージェント（Claude Code、Cursor、GitHub Copilot、または Hermes Agent など）を使用して、セッション間やコンテキストのリセットをまたぐ永続性が必要な、長期間かつ複雑なタスクを実行する開発者。

ハイライト

永続性: /clear コマンド、クラッシュ、およびコンテキストのコンパクションを生き延びます。
エージェントに依存しない: Agent Skills 標準およびいくつかの主要なツール向けのネイティブプラグインを介して、60以上のエージェントと互換性があります。
目標の安定性: 毎ターン、プランのヘッドを再注入することで、目標のドリフトを防ぎます。
整合性チェック: SHA-256 認証を使用して、プランが密かに改ざんされていないかを検出します。
完了の制御: ディスクベースのプラン内のすべてのフェーズが完了としてマークされるまで、エージェントがタスクを「完了」と宣言するのを防ぐことができます。