AI column

Coding@donghyeok99Staff

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

The context window is wiped by /clear, Phase 3 comes back from task_plan.md and work goes on; finding its place drops from 13.3 turns to 5.0.
The context window is wiped by /clear, Phase 3 comes back from task_plan.md and work goes on; finding its place drops from 13.3 turns to 5.0.
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.

PWF: Every task. Every step. Three planning files on a brass-inlaid base beneath an engraved arch

How it runs inside

  1. 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. 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. 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. 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. 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. 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

A session cut off halfway, then "Continue the work in this directory."13.3 turns to find its place on average, 5.0 with the plan (the README's internal benchmark)
A plan approved in Claude Code's plan modePhases in task_plan.md that keep the run's state on disk
Several tasks at onceThree files per .planning/YYYY-MM-DD-slug/, pinned with PLAN_ID
A finished planSet aside in .planning/.archive/ with set-active-plan.sh --archive (v3.28.0)

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

Sign in to post, comment and like.Sign in

Report

Reason

Read the community rules