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. Install from npm, the Claude Code plugin marketplace, or npx sk
planning-with-files is a persistent file-based planning skill for AI coding agents that survives context resets, crashes, and `/clear` commands. It maintains three markdown files (task_plan.md, findings.md, progress.md) on disk that are re-injected into the agent's context at every turn via lifecycle hooks. The skill works across 60+ agents including Claude Code, Cursor, GitHub Copilot, Codex, Hermes Agent, and OpenCode, preventing goal drift and memory loss during long-running tasks. Based on Manus AI's proven context-engineering pattern, it reduces re-orientation time from 13.3 turns to 5.0 turns after context wipes.
Key Features
Use Cases
- 01Multi-step coding tasks spanning 50+ tool calls that need to survive context window resets
- 02Long-running agent sessions that must maintain state across crashes, compaction, or /clear commands
- 03Research and planning tasks where findings and decisions must be preserved outside volatile context
- 04Multi-agent orchestration where workers share progress via markdown files on disk
- 05Recovery scenarios where a fresh session must resume work without re-reading the entire repository
- 06Tasks requiring completion gates that prevent premature 'done' declarations from the agent
Related Skills
View moresuperpowers
An agentic skills framework & software development methodology that works.
skills
Skills for Real Engineers. Straight from my .agents directory.
skills
Public repository for Agent Skills
ponytail
Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.
planning-with-files — FAQ
What is planning-with-files?+
planning-with-files is an agent skill that stores planning state (phases, findings, progress) in three markdown files on disk instead of in the volatile context window, then re-injects them at every turn via lifecycle hooks. This allows AI coding agents to resume work after /clear, crashes, or context compaction without losing their plan.
How do I install planning-with-files?+
For Claude Code, run '/plugin marketplace add OthmanAdi/planning-with-files' then '/plugin install planning-with-files@planning-with-files'. For other agents via Agent Skills standard, run 'npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g'. For Hermes Agent, install both the skill and native plugin with hermes commands.
Which AI clients and agents does this work with?+
It works with Claude Code, Cursor, GitHub Copilot, Codex CLI, Hermes Agent (CLI and Desktop), OpenCode, Pi, Mastra Code, Gemini CLI, Kiro, Continue, CodeBuddy, Factory Droid, and 60+ other agents via the Agent Skills standard. Enhanced hook support is available for Claude Code, Cursor, Copilot, Codex, Hermes, OpenCode, and several others.
What are the prerequisites?+
No API keys required. You need an AI coding agent that supports the Agent Skills standard or has native plugin support. For best results (lifecycle hooks), use Claude Code, Cursor, Copilot, Codex, Hermes, or OpenCode. Bash or PowerShell is needed for hook execution; Python 3 is optional but improves hook performance on Windows.
Is planning-with-files free?+
Yes, it is open source under the MIT License. You can use, modify, and distribute it freely.
How does this prevent the agent from losing its plan after /clear?+
The plan lives in task_plan.md, findings.md, and progress.md on disk, not only in the context window. Lifecycle hooks (SessionStart, UserPromptSubmit) automatically re-read these files and inject the active plan context at the start of each turn, so the agent always sees the current phase and status even after a context reset.
How do I install planning-with-files?+
Open the source repository on GitHub and follow its README. planning-with-files is a skill — MCP Agents Market links you directly to the official repo.
Is planning-with-files free?+
planning-with-files is an open-source project hosted on GitHub. Check the repository for its license and any usage requirements.