Planning with Files: Disk-Based Plans for AI Agents That Survive /clear and Context Rot

The Problem: Context Windows Are Volatile Memory

Coding agents like Claude Code, Codex, and Cursor keep their working state in the context window. That window is RAM: it resets on /clear, on compaction, and on crash. The README lists the failure modes plainly: volatile memory, goal drift after 50+ tool calls, hidden errors that repeat, and context stuffing where everything is crammed into the window instead of stored. For a long-running task, this means the agent re-reads the repo, asks you to restate the goal, and rediscovers work it already finished. The project's answer is to treat the filesystem as disk: write anything important to a file, and read it back on every turn. This is aimed at engineers running autonomous or semi-autonomous agent sessions that outlast a single context window, where the cost of re-orientation is real time and tokens.

The 3-File Pattern and What Actually Lands on Disk

The core mechanism is a fixed set of three markdown files per task. task_plan.md tracks phases and checkboxes, findings.md stores research notes and decisions appended as you go, and progress.md holds the session log and test results. The README shows the exact layout in your project: task_plan.md, findings.md, progress.md at the root. For parallel tasks, the skill creates isolated directories under .planning/YYYY-MM-DD-slug/ with the same three files, and selects the active one via .active_plan, a feature added in v2.36.0. The files are plain markdown and gitignored by default, so no runtime state lives anywhere else. This is a deliberate constraint: the skill does not introduce a database or a binary format. If you can read markdown, you can inspect the agent's plan mid-task. The trade-off is that the plan is only as structured as the agent's markdown discipline, which the benchmark tries to measure.

How the Hooks Force Re-Injection Every Turn

The skill does not rely on the agent remembering to read the plan. It installs a UserPromptSubmit hook that fires before every user prompt and injects the plan data into the context. The README shows the real injection format as a ===BEGIN PLAN DATA=== block, written from task_plan.md on disk. There is also a Stop hook, mentioned in the release notes: v3.11.1 fixed the Copilot error hook to parse under a POSIX shell, which implies the hook set includes error handling. The completion gate is opt-in and uses a Stop hook to check whether all phases are checked. This hook-based design is what makes the skill different from a prompt that says 'keep a plan file'. The agent cannot ignore the plan because the hook inserts it before the model sees the next prompt. The cost is that every turn carries the plan text into the context, which is exactly the re-injection the README claims fights context rot. If the hook fails to fire, the whole mechanism collapses, so the release history's focus on hook parsing fixes is not cosmetic.

Installing It: One Skill, Many Agents

Installation follows the Agent Skills standard, which the README says covers 60+ agents including Claude Code, Codex, Cursor, Kiro, and OpenCode. The release notes show a notable change: v3.11.0 consolidated six skills into one, and v3.11.2 fixed skills-only installs to land at the documented path. That suggests you typically copy or symlink a skill directory into your agent's skills folder. The README points to docs/installation.md for the full guide, but the repository layout shows a standard skills structure. The explicit commands are not in the README excerpt, so you would need to read that file. The key practical point is that the skill is not a Python package you pip install; it is a set of hook definitions and markdown templates. The primary language listed is Python, but the skill itself is mostly shell and markdown. For a quick start, you clone the repo and copy the skill folder into your agent's skills path, then verify the hooks are recognized. The v3.11.2 fix implies that install path is a known friction point.

What the Benchmark Numbers Do and Do Not Prove

The README is unusually honest about its measurements. The headline pass rate of 96.7% comes from an evaluation run on claude-sonnet-4-6 on 2026-03-06, using Anthropic's skill-creator framework. The methodology note says it measures file-pattern fidelity, meaning whether the agent creates and maintains the 3-file structure, not goal drift over long autonomous runs. The A/B results are striking: with the skill, 29 of 30 assertions passed, versus 2 of 30 without. The 3-file pattern was followed in 5 of 5 evals with the skill and 0 of 5 without. The recovery benchmark is separate: a v1 internal run from 2026-07-06, author-run, where a session is hard-stopped at half done and a fresh session is told only 'Continue the work in this directory.' Every arm ended pytest-green, so the difference is re-orientation cost: 5.0 turns to resume with the files versus 13.3 without. The README explicitly labels this as the project's own measurement, not an independent comparison. The limits are real: newer models and autonomous mode are not covered by the 96.7% figure.

Limitations and Failure Modes You Should Know

The skill is not a silver bullet. The most obvious limitation is that it depends entirely on the agent correctly writing and updating the markdown files. If the agent fails to append to findings.md or forgets to check a box, the plan on disk becomes stale, and re-injecting a stale plan is worse than having no plan because the agent will trust it. The benchmark measures fidelity on short evals, not on hours-long autonomous runs. Another limitation is the hook dependency: if your agent does not support the Agent Skills standard or the specific hook events, the skill will not fire. The release notes show ongoing fixes to hook parsing, so this is not a settled area. The completion gate is opt-in, which means you must remember to enable it or the agent will not stop when done. Finally, the README's own methodology note admits the 96.7% figure does not cover autonomous mode, which is precisely the use case the skill claims to serve. For very short tasks, the overhead of creating three files and re-injecting them every turn is pure cost.

Alternatives: Memory Tools and Manual Prompting

The closest alternative is a manual approach: you write a plan in a markdown file yourself and instruct the agent to read it at the start of each turn. This costs nothing to install and works with any agent, but it relies on the agent's compliance. The README's own A/B results suggest that without a hook, agents follow the pattern poorly: 0 of 5 evals maintained the 3-file structure. Another alternative is agent-native memory features, such as Claude Code's TodoWrite or similar built-in task lists. Those live in the context window, which is exactly the volatility problem this skill solves. The difference in approach is structural: TodoWrite is RAM, files are disk. A third option is a custom script that snapshots the agent's context to disk on a schedule, but that requires you to build and maintain the hook logic yourself. Planning with Files packages that logic into a standard that spans 60+ agents, so you do not have to write a different hook for each agent. The trade-off is that you adopt someone else's file format and hook behavior.

Maintenance, License, and Upgrade Cost

The project is under the MIT license, so you can fork and modify it freely, which matters if you need to adapt the hooks to a custom agent. The repository is actively maintained: the last push was 2026-08-22, and the release history shows three patch releases in three days, all fixing install path and hook parsing issues. That velocity is a double-edged sword. It means bugs get fixed quickly, but it also means the skill's behavior can change between releases. The consolidation from six skills to one in v3.11.0 is a breaking change for anyone who installed the earlier version, and v3.11.2 fixed a path problem for skills-only installs, so upgrade cost is real. You should check the changelog before pulling a new version. The documentation is thorough, with docs/evals.md and docs/installation.md, which lowers the learning curve but does not remove the need to re-test your own agent workflow after each upgrade. The test suite is listed as 417 green, which suggests the project has automated checks, but that number is not a guarantee for your environment.

Editorial conclusion

Adopt this if you run long, multi-turn agent tasks and have hit context resets, /clear, or compaction wiping the agent's working memory. It is also a good fit if you want a deterministic completion gate that stops the agent when all phases are checked. Skip it if your tasks are short enough that context loss is rare, or if you cannot tolerate extra files in the repo and the overhead of a hook firing every turn. Before adopting, verify that your agent supports the Agent Skills standard and that the UserPromptSubmit and Stop hooks work in your environment, since the whole mechanism depends on those hooks. Also confirm the 96.7% pass rate still applies to your model: the README states that figure comes from a v2.21.0 run on claude-sonnet-4-6 from 2026-03-06 and does not cover newer models or autonomous mode.

Official sources

1. Official README
2. Project repository
3. Release notes