Developers can preserve coding agent context across sessions using a file-based planning system
Long coding tasks often result in agents losing context and restarting from the beginning. This tool stores agent plans and progress as markdown files in the project folder, allowing work to resume from the last checkpoint even after a session ends or memory resets. It automates the process of agents managing their own plans, recovering from failures, and verifying completion.
Three files stored on disk
The system manages agent work state through three markdown files. task_plan.md contains a step-by-step checklist that serves as the reference for the current work location, while findings.md records discoveries and decisions made during investigation. progress.md accumulates session logs and test results. These files are created in the project root directory, and when running multiple tasks in parallel, separate directories with dates and slugs are created inside the .planning/ folder for isolation. By default, all files are included in .gitignore so they are not committed to version control systems.
Plan injection and recovery mechanism per turn
At the start of each turn, a lifecycle hook triggers to re-inject key parts of the disk-stored plan into the context window. This prevents context rot, where initial instructions are pushed out as the context fills up. Even if a session is reset with the /clear command or a crash occurs, the agent can return to the current stage by reading only the disk files. This process references only project files rather than analyzing previous conversation history, offering advantages in privacy and performance. Additionally, a gate verifies whether the plan is complete, preventing the agent from ending tasks in an unfinished state.
Support for 60+ agents and installation
This skill is based on the Agent Skills standard and can be used with over 60 coding agents, including Claude Code, Codex CLI, Cursor, GitHub Copilot, and OpenCode. Installation involves executing the single command npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g. Some hosts, such as Claude Code, provide it as a native plugin for deeper integration. Translated versions in five languages—Arabic, German, Spanish, and Chinese (Simplified/Traditional)—are available, with scripts and templates fully localized for each. If using Qoder CLI, Bash and Python 3.10 or higher are required.
Measured performance improvements
According to project measurements, disk-based planning reduced the number of turns required for an agent to reorient after /clear from 13.3 to 5.0. In all three blind A/B tests, agents using this method produced better results. Hook trigger time was shortened to 289ms after v3.6.0 optimizations, operating much faster than the previous 2.0 to 2.4 seconds. This means agents can maintain stable plan context every turn while minimizing latency.
Why it suits long-running tasks
This tool is particularly suitable for autonomous coding tasks that take tens of minutes to several hours. Agents maintain consistent goals without losing context midway and can return to a recoverable state when errors occur. Conversely, it may be an excessive structure for simple question-answering or short code fixes. Before use, verify that the agent supports the Agent Skills standard and that creating markdown files in the project folder is permitted. Completed plan files are not automatically archived, so important content should be promoted to code or documentation for separate management.
