Planning with Files: an agent's plan that survives /clear
An agent that took 13.3 turns to find its place after /clear took 5.0 with its plan on disk
- Who
- An MIT-licensed planning skill by OthmanAdi, for people who hand coding agents work that takes hours.
- When
- Public since January 2026, #1 on Trendshift across all languages on 6 January; latest release v3.28.1 on 7 November.
- Where
- Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode and more, 60+ agents; the files stay in your project.
What was hard
Hand an agent a long task and it starts well, but after fifty or so tool calls the goal blurs. After /clear or a compaction you spend a while telling it where it was. And sometimes it stops and says it is done when it is not.
What it does about it
The plan lives in three markdown files in your project, not in the conversation: phases and their status in task_plan.md, what was learned in findings.md, what was done and the test results in progress.md. Hooks put the plan back in every turn, and after /clear or a compaction the new session reads the current phase from the files and carries on. Turn on gated mode and it cannot stop while a phase is still in progress.

How it runs inside
- 1
You → planning-with-files
/plan, or "plan this task"init-session makes the three planning files in your project from the templates.skills/planning-with-files/scripts/init-session.sh - 2
planning-with-files → task_plan.md and two more
goal, next step, Phase 1 to 5Each phase has checkboxes and a Status of pending, in_progress or complete.skills/planning-with-files/templates/task_plan.md - 3
Claude Code → task_plan.md and two more
check off, add findings, log progressWhat it learns goes to findings.md; what it did and the test results go to progress.md.skills/planning-with-files/SKILL.md - 4
claude-hook.sh → Claude Code
UserPromptSubmit: the plan, every turnEach turn the selected plan is put in front of the context, so the goal does not drift.hooks/hooks.json - 5
claude-hook.sh → Claude Code
Stop: hold while a phase is unfinishedGated mode only: an in_progress phase holds the stop, with a block cap and stall detection.skills/planning-with-files/scripts/gate-stop.sh - 6
claude-hook.sh → Resume at the current phase
SessionStart after /clear: inject-plan.shA new session reads the current phase from the plan on disk and starts again where it was.skills/planning-with-files/scripts/inject-plan.sh
What goes in, what comes out
Is it for you
Good for
- Refactors or migrations that run for hours
- Long sessions where /clear or auto-compaction keeps making you explain again
- Handing one plan from Claude Code to another agent such as Codex mid-run
- Several agents working on different tasks in one repository
Not for
- 13.3 to 5.0 turns is the project's internal benchmark v1; the README says today's file-only recovery has not been measured the same way.
- Installed with npx skills, the hooks can be silently missing; the README suggests the Claude Code plugin and /plan-doctor if hooks matter.
- The planning files are gitignored by default and not archived on their own; move what you want to keep into code, commits or docs.
- The parallel-write guard is a warning after the write, not a lock or a merge.
Reviewed by Devalley’s editor before publishing. How the column is made