planning-with-files: agent plans that survive /clear

Your agent forgets everything the moment the context window fills and /clear runs. planning-with-files fixes that by writing the plan to disk from the start: three markdown files (task_plan.md, findings.md, progress.md) that survive the wipe and get re-injected automatically at the top of each turn via a lifecycle hook. Think of it as a sticky note taped to the wall instead of written on a whiteboard someone will definitely erase.

When it earns its keep

It pays off on longer tasks — anything multi-phase, multi-session, or likely to hit context limits. The benchmark numbers are genuinely striking: 96.7% assertion pass rate with the skill versus 6.7% without; recovery after /clear in 5 turns instead of 13.3. Those figures come from blind A/B tests across 30 benchmark runs. The skill works across 60+ agents out of the box: Claude Code, Cursor, Codex, Copilot, Hermes, OpenCode, and more — same install, same files.

The honest caveat

For short single-session tasks, the three-file setup is overkill — you are doing planning admin that does not pay off in a 30-minute fix. More importantly: the skill enforces a write discipline, but if the agent does not correctly update progress.md as it works, re-injection just re-injects stale state. It is not magic; the agent has to follow through. And the multi-agent slug mode for parallel tasks is genuinely useful but adds coordination complexity that needs some setup — factor in the onboarding time.

Install

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

Or from inside Claude Code: /plugin marketplace add OthmanAdi/planning-with-files. After install, invoke it with /planning-with-files and it scaffolds the three files into your project root.

Built and maintained by Ahmad Othman Ammar Adi. Full repo and benchmark details at github.com/OthmanAdi/planning-with-files. MIT-licensed.