It turns an agent's scratchpad into durable project state
Planning with Files addresses a mundane failure that becomes expensive on long coding jobs: the agent forgets. Instead of leaving the goal, research, and completed work inside a context window, it writes them to 3 files: task_plan.md, findings.md, and progress.md. A hook then re-injects the plan on each turn, including after /clear or compaction. The idea is deliberately plain. Markdown is easy to inspect, edit, diff, and recover, so users do not need a database or proprietary dashboard to understand what the agent believes it is doing.
The README draws a useful boundary around that promise. It describes 3 root-level files for a normal task, while parallel work can live under dated .planning directories selected through .active_plan, a mechanism available since v2.36.0. The files are gitignored by default, which avoids accidental noise in ordinary commits, but also means teams must decide whether any planning record belongs in version control. This is working memory for an agent, not a replacement for tickets, architecture decisions, or human review.
Our run was clean and reasonably quick
We cloned commit 9e94390 into an unprivileged Debian sandbox with 3 CPUs and 8 GB of RAM. Installation succeeded in 17 seconds, pulling in 35 packages and consuming 37 MB on disk. The build then succeeded in 5 seconds. Those results matter because they show that the polished README is backed by a repository that can actually be installed and built in a fresh environment without secrets or privileged access.
Pytest finished in 39 seconds with 403 passed, 0 failed, and 43 skipped of 403. The dependency audit reported 0 known vulnerabilities. We also found 3 CI workflow files and a dedicated tests directory, although there is no Dockerfile. The checkout contained 610 files, roughly 65,092 lines of source, and occupied 14.2 MB, so this is no longer merely a tiny prompt packaged in a folder. Its implementation and compatibility surface deserve the same review discipline as any other developer tool.
The three-file contract is the strongest feature
The best part is the clear division across 3 files. task_plan.md holds phases and checkboxes, findings.md preserves research and decisions, and progress.md records session activity and test results. That separation makes recovery legible: an agent can find the current phase without treating every observation as a task, while a developer can audit why a decision was made. The completion gate is opt-in, which is sensible because rigid stopping rules can be counterproductive for exploratory work.
The evidence is useful, but it is still the author's evidence
The headline evaluation reports a 96.7% assertion pass rate, or 29 of 30, compared with 2 of 30 without the skill. It also reports 3 wins in 3 blind A/B comparisons. Those numbers sound decisive until you read the methodology note: the v2.21.0 evaluation used claude-sonnet-4-6 and measured fidelity to the three-file pattern, not long-horizon goal drift. In other words, it strongly suggests that the skill gets agents to maintain its prescribed files, but it does not independently establish that every real project finishes faster or better.
The recovery result needs the same calibration. The README says a fresh session resumed in 5.0 turns on average versus 13.3 for a raw agent, but labels this an internal v1, author-run benchmark with harness-authored tasks. That disclosure is good documentation practice. It lets buyers treat the result as a useful engineering signal without mistaking it for neutral validation. We would like to see independent replications, more models, and longer tasks that measure delivery correctness rather than file-format compliance.
The main costs are ceremony, context, and repository hygiene
Three Markdown files are simple, but they are not free. Agents must keep them current, hooks spend context tokens re-injecting content, and stale findings can become confidently repeated mistakes. On a 10-minute edit, the planning overhead may exceed the recovery benefit. Parallel directories and .active_plan solve naming collisions, yet they also introduce state that developers need to understand when several tasks or agents touch the same checkout. A completion gate can improve follow-through, but only if the plan itself remains accurate.
The project's deepest proof remains internal, and there are 0 community testimonials in the supplied data. The absence of a Dockerfile is not a defect for a shell-oriented agent skill, but container-first operators will need their own wrapper. Security-conscious teams should inspect which local files a hook sends into agent context before enabling it around sensitive notes.
Active maintenance and low issue volume support adoption
Project health looks strong as of August 26, 2026. The repository has 26,376 stars, only 7 open issues, a last push on August 22, and release v3.11.2 published the same day. A recent push and release together are better evidence of active maintenance than star count alone. We do not have issue response times or contributor distribution, so the community score should stop short of perfect despite the impressive adoption signal.
It belongs beside your agent, not above your delivery system
In a real stack, Planning with Files fits at the workspace layer beside 3 established systems. Let it preserve the agent's immediate plan and discoveries, while Git remains the source of code history, CI verifies changes, and an issue tracker owns commitments visible to the team. That division keeps ephemeral reasoning useful without turning local files into an unofficial project-management database. For sensitive work, review hook scope and keep secrets out of planning notes.
Adopt it when a task routinely spans more than 1 context window, survives handoffs, or gets interrupted by /clear. Skip it for isolated edits and workflows that already restore durable state through an orchestrator. The project earns its recommendation because the implementation ran cleanly on our box and because its central mechanism is understandable. Its real value is a disciplined habit: write down the plan, preserve findings, and record what actually happened.