planning-with-files

AI coding agents have a structural weakness: their memory lives in a context window that gets truncated, summarized, or wiped entirely the moment you run a command like /clear. On a long task with many tool calls, an agent slowly forgets why it started, what it already tried, and which steps remain. A crash or a context reset can erase the entire mental model of a job that was half done. planning-with-files, an MIT-licensed skill from solo developer OthmanAdi, attacks this problem by moving planning state out of volatile context and onto disk. It installs a SKILL.md-based harness that maintains three persistent markdown files, so the agent can rebuild its full understanding of a task simply by re-reading them after any interruption.

The mechanism is deliberately low-tech, and that is the point. Three files carry the state: task_plan.md holds phases, dependencies, and completion status, findings.md stores research and technical notes, and progress.md logs sessions, test results, and errors. The harness re-injects these into context through SKILL.md lifecycle hooks tied to events like UserPromptSubmit, PreToolUse, and Stop. It runs in three modes. Legacy mode re-reads the plan before every tool call, autonomous mode injects only at session start and phase transitions to cut overhead for capable models, and gated mode adds a Stop-hook completion gate that blocks the agent from exiting while a phase is still incomplete. There is no database, no server, and nothing to host. The files are plain text you can read and edit yourself.

The natural audience is anyone running long, multi-step coding or research work inside agents like Claude Code, Cursor, or Codex, where context limits and session recovery are real daily friction. Concrete cases include multi-phase feature builds, drawn-out debugging sessions where earlier findings must not be lost, and research tasks that span several sittings. Because state is just files on disk, multiple agents can in principle read a shared plan, which makes it appealing for loosely coordinated multi-agent work. The project reports support for 60 plus agents, with deeper hook integration for tools like Claude Code, Cursor, GitHub Copilot, Gemini CLI, and Codex, and a lighter Agent Skills path for others. Installation is a single npx command, which lowers the barrier to trying it on a real project.

The honest caveats are worth taking seriously. This is a single-developer project that has accumulated a high star count over a short lifespan, so the usual scrutiny about star authenticity applies before you treat popularity as a signal of quality. The benchmark claims, including a self-reported 96.7 percent pass rate and high rubric scores, are documented by the author in docs/evals.md but are self-administered rather than independently verified, so read them as the project's own claims. File-based state is also fragile under concurrent multi-agent use: there is no locking, so two agents writing the same plan can clobber each other. Practical rough edges exist too, such as limited exec-bit handling on Windows because NTFS does not store POSIX permissions, and session recovery that depends on finding IDE-specific session metadata.

The grounding data lists no direct commercial alternative, and that fits reality: the real competition is the built-in task and to-do tracking that agent vendors increasingly ship natively. planning-with-files is a portable, vendor-neutral layer that works the same across many agents, which is its main argument over any single proprietary system. Adopt it when your tasks are genuinely long and multi-step, when you regularly hit context limits or need to resume after a crash, and when you value owning your plan as editable text rather than locking it inside one tool. Treat it as too early for short, single-session questions, for teams already standardized on an agent-integrated task system, or for heavy parallel multi-agent setups where the lack of file locking would bite. For the right workflow, it is a low-risk, low-cost addition.