Planning with Files: the plan that outlives your context window
When the context window resets, an agent forgets which step it was on. planning-with-files keeps working state in three project files: task_plan.md, findings.md and progress.md. Lifecycle hooks feed selected parts of the plan back in every turn, so after a /clear, a crash or compaction the agent picks up at the current phase.
Three files: task_plan.md with phases and checkboxes, findings.md for research notes and decisions, progress.md for the session log and test results.
Hooks on prompt submit, tool use, stop and pre-compaction re-inject the plan and remind the agent to record progress.
Parallel tasks get their own dated .planning/ directories, and .active_plan selects which one a host works on.
A two-action rule: after every two views, searches or browser steps the agent saves what it learned to a file.
In the project's own tests the plan cut re-orientation from 13.3 turns to 5.0 and won 3 of 3 blind A/B comparisons.
When to use it
A task runs to dozens of tool calls and keeps hitting /clear or automatic context compaction.
You come back to work the next day and need to see at a glance which phase is done.
Several agents or worktrees run in parallel and each task needs its own plan.
Ask your agent
Start the API v2 migration by writing a phased plan to task_plan.md
Read task_plan.md and progress.md, then continue from the current phase
Log what we found about the login error in findings.md
Questions
How do I install planning-with-files?
Run npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g for a global install. Claude Code also has a plugin route that brings the hooks.
How is planning-with-files different from an agent memory tool?
Memory tools recall facts from earlier sessions. This skill manages the task in progress: its phases, status, dependencies and completion check.
Does planning-with-files upload my plans anywhere?
No. The skill states it has no network upload path, and the planning files are plain Markdown kept in your project and gitignored by default.
