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 コマンドやクラッシュによる）と、重要なタスク計画や調査結果が失われるという「揮発性メモリ」の問題にしばしば直面します。これにより、目標の逸脱、繰り返される間違い、セッションリセット後にユーザーが手動で目標を再定義する必要性が生じます。

仕組み

このプロジェクトは、ファイルシステムをエージェントの作業メモリ用の永続ディスクとして扱う「3ファイルパターン」を実装しています。複雑なタスクごとに、エージェントは以下の3つの特定のMarkdownファイルを作成・維持します：

  • task_plan.md: 進捗のためのフェーズとチェックボックスを追跡します。
  • findings.md: 調査ノートと決定事項を保存します。
  • progress.md: セッションログとテスト結果を記録します。

これらのファイルが確実に使用されるよう、プロジェクトは様々なAIエージェント（Claude Code、Cursor、GitHub Copilotなど）向けのライフサイクルフックを提供します。これにより、毎ターンの開始時にプランをエージェントのコンテキストに再注入し、エージェントに更新を促し、エージェントが停止する前に完了を確認します。

対象者

LLMのコンテキストウィンドウの制限を超える、長期間かつ多段階のタスクに取り組んでいるAIコーディングエージェント（Claude Code、Cursor、Piなど）の利用者。

ハイライト

  • 永続メモリ: コンテキストの消去、クラッシュ、セッションのリセット後も保持されます。
  • 幅広い互換性: Agent Skills 標準を通じて、18以上のプラットフォームにわたる60以上のエージェントをサポートしています。
  • ライフサイクル自動化: フックを使用して、プランの注入と更新をオプションではなく機械的なプロセスにします。
  • セッションリカバリ: 前回のセッションデータを自動的に検出し、エージェントが現在のフェーズから作業を再開できるようにします。
  • アテステーション: プランの内容の改ざんを防ぐための SHA-256 ロッキングメカニズムが含まれています。