planning-with-files: Crash-Proof Agent Plans That Survive /clear and /compact

The Problem It Solves

You've been there: 40 minutes into a refactor, the context fills up, you hit /compact, and your agent comes back not entirely sure what it was doing. Or you /clear to reset a bad state and lose the whole task outline. Context windows are volatile. Plans shouldn't be.

planning-with-files is an agent skill that sidesteps this by writing your plan to three markdown files — task_plan.md, findings.md, and progress.md — and re-reading them at the start of each agent turn. The plan lives on disk, not in the window.

The approach comes straight from how Manus AI manages long-running tasks internally. The README puts it plainly: markdown files are working memory on disk. Simple idea, real leverage.

When It Pays Off

For multi-step work (the README calls out 3+ steps as the minimum threshold), this earns its keep fast. Version migrations, multi-file refactors, research-then-build workflows — anything where you'd otherwise be re-explaining context at the top of each session.

It also enables multi-agent shared state: two agents in the same repo can read each other's progress notes off disk with zero coordination overhead.

The v3.0.0 update added a PreCompact hook that fires on /compact and autoCompact, flushing state to disk right before Claude summarizes the context away. The /plan-goal slash command composes with Claude Code's native /goal to derive a termination condition directly from whatever's in your active task_plan.md.

The Honest Caveats

Don't use this on simple tasks. The skill says so itself — maintaining three plan files is overhead you don't need for a one-shot script or a 20-line bug fix. If you can hold the whole task in one prompt, skip it.

Install method matters more than it should. The /plan-goal and /plan-loop slash commands only ship via the plugin install path (/plugin marketplace add). The faster npx skills add route doesn't include those wrappers — you'd fall back to Claude Code's native /goal and /loop primitives directly.

Hook integration also varies across platforms: 17+ are listed as supported, but Claude Code gets the full treatment while others may get partial coverage. Check the compatibility table in the README before assuming identical behavior in Cursor or Kiro.

Get It

From OthmanAdi/planning-with-files — compatible with Claude Code, Codex CLI, Cursor, Kiro, OpenCode, and 60+ other agents via the SKILL.md standard:

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

For the full command set including /plan-goal and /plan-loop, use /plugin marketplace add OthmanAdi/planning-with-files inside Claude Code instead. Credit: OthmanAdi.