docs/agent-forgets-plan-after-clear.md
/clear empties the context window. Everything the agent knew only from the conversation is gone: the goal, the current phase, the errors it already hit. The next thing you see is the agent asking you to restate the task, then re-reading the repo to rediscover work it already finished. The fix is not a bigger window. The fix is keeping the plan somewhere /clear cannot reach: the filesystem.
This page describes the pattern planning-with-files implements. Overview: README.
Because in-context state is volatile by design. In-context todo lists disappear on context reset, goals stated once get crowded out after 50+ tool calls, and failures that are not written down get repeated. /clear, crashes, and compaction all destroy the same thing: state that was never persisted.
The core principle, from the context-engineering pattern described in the Manus blog:
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
Applied concretely, exactly three files land in your project root:
your-project/
├── task_plan.md ← phases + checkboxes; the resume point after /clear
├── findings.md ← research notes and decisions, appended as you go
└── progress.md ← session log and test results
Plain markdown, gitignored by default, no runtime state anywhere else. Parallel tasks get isolated directories under .planning/YYYY-MM-DD-slug/ instead.
Files on disk only help if the model actually reads them, so that step is mechanical rather than left to model discipline. A UserPromptSubmit hook re-injects the active plan from disk at the start of every turn, wrapped in ===BEGIN PLAN DATA=== and ===END PLAN DATA=== markers. Companion hooks remind the agent to update progress.md after writes and check phase completion before stopping. On Claude Code that is 5 lifecycle hooks; Codex runs 7 and Pi runs 8.
The loop means the plan is in front of the model by construction, not by hoping the model remembers to re-read it.
~/.claude/projects/ for Claude Code, ~/.codex/sessions/ for Codex).git diff --stat, and resumes at the current phase.A resumed session can answer the reboot questions from the files alone: where am I (current phase in task_plan.md), what is the goal (goal statement in the plan), what have I learned (findings.md), what have I done (progress.md). In the project's internal recovery benchmark (v1, author-run), a fresh session with the files on disk resumed in 5.0 turns on average against 13.3 for a raw agent; method and limits in docs/evals.md.
Yes. The skill installs across 60+ agents via the Agent Skills standard; the npx skills installer alone targets 71. Lifecycle hooks run on Claude Code, Codex, Cursor, GitHub Copilot, Kiro, and other platforms listed in the README platform table, and since v3.7.0 the repo also ships the .agents/skills/ standard layout in-tree, so tools that read that path (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI, Cursor) discover the skill from a plain git clone.
For runs that go beyond a single session, see long-running agent tasks: autonomous mode, the completion gate, and the run ledger build on the same three files.
Claude Code, plugin route (ships the skill, hooks, and slash commands):
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
Every other agent, one line via the Agent Skills standard:
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
Full route matrix and verification: README and docs/installation.md.