# Planning with Files for Claude Code, Codex and OpenCode: a plan that survives /clear

> Planning with Files keeps task_plan.md, findings.md and progress.md on disk and re-injects them every turn, so an agent's working memory outlives its context window. Here is how it works, how to install it, and where the evidence stops.

**OthmanAdi/planning-with-files** — Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Claude Code, Codex, Cursor, Kiro, OpenCode and 60+ agents via the Agent Skills standard.

- Repository: https://github.com/OthmanAdi/planning-with-files
- Stars: 27,181 · Forks: 2,260
- Language: Python
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/othmanadi-planning-with-files

## The failure mode Planning with Files targets: a plan that lives only in the context window

Every coding agent treats its context window as working memory, and every context window is finite. The README lists four symptoms it attributes to that design: the TodoWrite list vanishes on reset, goals drift after 50+ tool calls, failures are not recorded so the same mistake repeats, and everything gets crammed into the window instead of stored. The project is aimed at anyone running agent sessions long enough to hit those, which in practice means Claude Code, Codex, Cursor, Kiro and OpenCode users working on multi-phase tasks rather than one-shot edits.

The framing the README borrows from Manus is blunt: context window is RAM, filesystem is disk, and anything important gets written to disk. That is the whole thesis. It is not a better planner inside the model. It is a relocation of the plan outside the model, plus machinery to put it back in front of the model before it acts.

## Three markdown files plus a hook: how the mechanism actually works

The pattern is three files in the project root: task_plan.md for phases and checkboxes, findings.md for research notes and decisions, and progress.md for the session log and test results. The README states that exactly these land on disk and nothing else, that they are plain markdown, and that they are gitignored by default, with no runtime state stored anywhere else.

The part that makes it more than a convention is the hook. The README says a UserPromptSubmit hook fires every turn and writes the plan into context inside a block delimited by ===BEGIN PLAN DATA===. That is per-turn re-injection, and it is the answer to context rot: the plan is not read once at the start of a session and then slowly crowded out, it is pushed back in before each turn. A second hook is described as a stop hook that checks all phases, which is the opt-in completion gate.

For parallel work the layout changes. The README describes isolated directories at .planning/YYYY-MM-DD-slug/ holding the same three files, selected through a .active_plan file, a mechanism it attributes to v2.36.0 and later. The repository's top-level layout matches the multi-agent claim: separate directories for .claude-plugin, .codex-plugin, .cursor, .kiro, .opencode, .gemini, .continue and others, alongside a single skills/ directory and a hooks/ directory. Release v3.11.0 is titled "one skill instead of six", so the earlier per-agent skill split was consolidated.

## Installing Planning with Files and running a first task

The README points at docs/installation.md for the full guide and describes a skills-only install path. Release v3.11.2 is titled "skills-only installs land at the documented path", which tells you two things: skills-only is a supported route, and the install location was a bug as recently as that release. Check that the skill directory exists where your agent looks for skills before you assume the install worked.

The repository ships a scripts/ directory and a commands/ directory, but the README excerpt does not spell out a single install command, so treat the plugin marketplaces for your specific agent as the source of truth. What the README does document is the shape of a first task. The three files it names are task_plan.md, findings.md and progress.md in the project root. Then give the agent a multi-phase task and confirm the plan file is being written.

The README's own before-and-after example shows the resume prompt as a single sentence:

```text
Continue the work in this directory.
```

If the hook is active, the next turn's context should contain a ===BEGIN PLAN DATA=== block populated from task_plan.md on disk. That block is your smoke test. If it is absent, the hook is not firing in your agent and nothing else about the skill matters yet.

One more thing to verify on first run: the README says the files are gitignored by default. If you want the plan committed as a record of the work, you are fighting the default, not using it.

## What the benchmark numbers do and do not measure

The README leads with 96.7% against 6.7% on 30 assertions, 5/5 versus 0/5 on following the three-file pattern, and 3/3 blind A/B wins. Read the methodology note directly beneath those figures, because it is unusually candid: the 96.7% comes from a v2.21.0 evaluation run on claude-sonnet-4-6 dated 2026-03-06, and it measures file-pattern fidelity, meaning whether the agent creates and maintains the structure, not goal drift over long autonomous runs. Newer models and the autonomous-mode work are explicitly not covered by that number.

The recovery benchmark is separate and the README labels it internal v1, dated 2026-07-06, run against v3.4.0 with harness-authored tasks and deterministic grading. In that protocol a session is hard-stopped at roughly half done and a fresh session is told only to continue. Resume took 5.0 turns on average with the planning files on disk against 13.3 for a raw agent, and every graded run in every arm ended pytest-green at 77/77, so the measured difference is re-orientation cost rather than correctness. That is a narrow claim, and the README presents it as the project's own measurement rather than an independent comparison.

Two things are worth noticing. First, the headline pass-rate number and the recovery number come from different runs, different versions and different dates; they should not be added together into a single story about the skill. Second, the 417-green test suite is a fact about the project's own tests, not about your agent.

## Where Planning with Files is the wrong tool

The skill's value is proportional to how much state your task accumulates. If a task fits in one context window and finishes before any reset, the three files are overhead: you pay a hook firing on every turn and you maintain markdown that never gets used for recovery. The README's own framing assumes long-running work.

The completion gate is opt-in, and that is a deliberate limit rather than a defect. A stop hook that checks all phases can block an agent from finishing, which is useful when you want the agent held to the plan and irritating when you want it to stop and ask. The README does not document rollback for the gate, so if you enable it, understand that the documented behaviour is a check, not a documented escape hatch.

The recovery benchmark also has a boundary the README states plainly: the difference it measures is re-orientation cost, not correctness, because every arm ended pytest-green. If your concern is that an agent will silently produce wrong code after a context wipe, this benchmark does not speak to that. And the per-turn re-injection has its own cost, since plan content is written into context on every turn; the README does not quantify the token overhead, so budget for it rather than assuming it is free.

## Planning with Files versus OpenSpec and versus a plain AGENTS.md

The comparison people search for is planning with files versus OpenSpec, and the difference is in what gets enforced. Planning with Files is three markdown files plus hooks that re-inject them and optionally gate completion; the artefacts are a plan, findings and a progress log, and the README describes them as gitignored by default. An OpenSpec-style workflow is built around a specification document that changes go through. If you need a spec that reviewers sign off on before code is written, the three-file pattern is the wrong artefact: it is a working memory, not a contract.

Against a hand-written AGENTS.md or CLAUDE.md, the difference is the hook. A static instructions file is read at session start and then competes with everything else in the window; the README's claim is that re-injection every turn is what defeats context rot. That is the specific mechanism to test in your own agent, because it is the one a static file cannot replicate.

## Licence, maintenance and upgrade cost

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the extent of what can be said here; the LICENSE file in the repository is the authority, and nothing in this article is legal advice.

The last push to master was on 2026-08-22, and the repository is not archived. The three most recent releases are tightly clustered: v3.11.0 on 2026-08-20, v3.11.1 on 2026-08-21, and v3.11.2 on 2026-08-22. Two of those three are bug fixes rather than features, one for a Copilot error hook parsing under a POSIX shell and one for the skills-only install path. That cadence is worth reading as a signal about surface area: the project spans 60+ agents through the Agent Skills standard, and each integration is a place where a path or a shell assumption can break.

Upgrade cost is therefore mostly integration cost. A MIGRATION.md file exists at the top level, which suggests the project has had breaking changes worth documenting. The v3.11.0 consolidation from six skills to one is exactly the kind of change that moves files on disk, so read MIGRATION.md before jumping versions rather than assuming the install path is stable across releases.

## Conclusion

Adopt Planning with Files if you run long agent sessions in Claude Code, Codex, Cursor, Kiro or OpenCode and you have been burned by a /clear or a compaction that erased the plan. Skip it if your tasks finish inside a single context window, or if you want an enforced spec workflow rather than three markdown files. Before trusting it, verify three things yourself: that the UserPromptSubmit hook actually fires in your agent, that the skill lands at the path your agent expects after install, and that task_plan.md in your repo is the file the resume prompt reads. The repository's own methodology note is the clearest boundary: the 96.7% figure measures file-pattern fidelity on claude-sonnet-4-6 from a 2026-03-06 run, not goal drift over long autonomous sessions.

## FAQ

### How do you use Planning with Files?

Create task_plan.md, findings.md and progress.md in your project root, then give the agent a multi-phase task. The UserPromptSubmit hook re-injects the plan into context each turn inside a ===BEGIN PLAN DATA=== block, and after a /clear you resume with a prompt such as "Continue the work in this directory."

### What is the Planning with Files skill?

It is an Agent Skills planning layer that keeps three markdown files on disk and re-injects them every turn, so the plan survives context loss, /clear, crashes and compaction. It also offers an opt-in completion gate that checks all phases. The README describes it as Manus-style working memory on disk.

### What is the difference between Planning with Files and OpenSpec?

Planning with Files produces a working memory: task_plan.md, findings.md and progress.md, gitignored by default, with hooks that re-inject the plan and optionally gate completion. An OpenSpec-style workflow centers on a specification document that changes go through. If you need a spec reviewers approve before code is written, the three-file pattern is a different artefact.

## Sources

- [Official README](https://github.com/OthmanAdi/planning-with-files#readme)
- [Project repository](https://github.com/OthmanAdi/planning-with-files)
- [Release notes](https://github.com/OthmanAdi/planning-with-files/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/othmanadi-planning-with-files