Planning with Files skill for Claude Code

A long Claude Code task loses its thread in predictable places: after /clear, after the context is compacted, after a crash or a new session. planning-with-files moves the plan out of the context window and into files in your project, then uses hooks to put the current plan back in front of Claude at the start of each turn. The license is MIT. The README credits the pattern to Manus, whose agent described markdown files as its "working memory" on disk. For the basics of skills, read how Claude Skills work.

The three files

Several tasks in one project each get their own folder, .planning/YYYY-MM-DD-slug/, with the same three files. All of them are gitignored by default. They are working memory, so anything worth keeping should go into code, a commit or a document before the next task overwrites the plan.

What the hooks do

On the plugin install, hooks fire at session start, on each prompt, before and after tool calls, before compaction and when Claude tries to stop. Together they:

• re-inject the active phase and goals from task_plan.md on every prompt, so the plan stays in view as the conversation grows;
• remind Claude to update the files after it writes code or runs commands;
• restore the plan quietly when a session starts in a project that has one;
• hold the stop until the plan reports every phase complete.

The README puts one hook fire at 289 ms. In the author's own tests the files cut re-orientation after a reset from 13.3 turns to 5.0, and the skill won three of three blind A/B comparisons. These are the project's measurements, not independent ones.

When to use it

• Tasks that need more than one sitting: a migration, a refactor across many files, a research job.
• Work where you clear the context on purpose to save tokens and want Claude to pick up at the right phase.
• Pairing with plan mode. Approve a plan in plan mode, then ask Claude to write it into task_plan.md as phases. The skill keeps it alive while the work runs.

For a ten-minute fix the files are overhead. If you want a full method with tests and reviews built in, Superpowers covers planning too. To pin down the plan before any of this, start with grill-me.

How to install it

Claude Code, as a plugin. This is the route the author recommends, because only the plugin registers the hooks at startup and adds the slash commands:

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

Any agent that reads skills, through the skills installer. On this route the hooks start only after the skill is invoked in a session, and the slash commands are not copied:

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

The README also gives native plugin setups for Codex, OpenCode, Hermes Agent and others, and translated versions in Arabic, German, Spanish and Chinese.

How to use it

Ask for a task with several steps and Claude creates the files. The skill triggers from its description, and the author measured that at 60 to 67% of the time without a nudge. To make it fire every time, add this line to your CLAUDE.md, as the installation guide suggests:

When a task needs 3+ steps or 5+ tool calls, invoke the planning-with-files skill first and keep task_plan.md current.

The plugin adds its commands under its own name: type /planning-with-files: to list them. plan starts a plan, status shows the current phase and plan-doctor checks that the hooks resolve and inject. Run /plugin update planning-with-files@planning-with-files to update.

Limits

• Hooks run shell scripts on every turn. Read them before installing, as with any community plugin.
• Two sessions working on one plan folder at once used to overwrite each other. Newer versions guard against it, but one plan per session is still the safe setup.
• A project-level install inside .claude/skills/ loads only after you accept the project's trust dialog. Scripted sessions that never accept it load nothing and show no error.