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.
What it solves
AI coding agents often suffer from volatile memory, where critical task plans and research findings are lost when the context window resets (e.g., via /clear commands or crashes). This leads to goal drift, repeated mistakes, and the need for the user to manually restate goals after a session reset.
How it works
The project implements a "3-file pattern" that treats the filesystem as a persistent disk for the agent's working memory. For every complex task, the agent creates and maintains three specific Markdown files:
task_plan.md: Tracks phases and checkboxes for progress.findings.md: Stores research notes and decisions.progress.md: A session log and test results.
To ensure these files are used, the project provides lifecycle hooks for various AI agents (such as Claude Code, Cursor, and GitHub Copilot) that re-inject the plan into the agent's context at the start of every turn, remind the agent to write updates, and verify completion before allowing the agent to stop.
Who it’s for
Developers using AI coding agents (like Claude Code, Cursor, or Pi) who are working on long-running, multi-step tasks that exceed the context window limits of the LLM.
Highlights
- Persistent Memory: Survives context wipes, crashes, and session resets.
- Broad Compatibility: Supports 60+ agents across 18+ platforms via the Agent Skills standard.
- Lifecycle Automation: Uses hooks to make plan injection and updates mechanical rather than optional.
- Session Recovery: Automatically detects previous session data to help the agent resume work from the current phase.
- Attestation: Includes a SHA-256 locking mechanism to prevent tampered plan bodies.