Planning with Files: Persistent File-Based Planning for AI Agents
Keep agent plans on disk
Persists plans, findings and progress, reducing context loss in long-running tasks.
The core workflow has cross-platform tests, versioned scripts and recovery rules; fixed-revision scripts passed static compilation.
Includes path constraints, prompt-injection hardening and security guidance; automatic hooks execute local scripts and re-inject workspace plan content.
Public tests, changelog, security policy and self-authored comparative evaluations are available, without independent reproduction.
The three-file workflow is understandable, while hooks, modes and lengthy guidance raise setup cost.
Recent releases include documented security fixes, tests and release history.
- Automatic hooks run local scripts; enable them only in trusted workspaces after reviewing configuration.
- Plan files are repeatedly injected into context; do not place untrusted content in them.
- The author's evaluation reports added time and token cost, with clearer benefit on long tasks.
What it does & when to use it
Planning with Files is an Agent Skill for AI coding agents and long-running agentic tasks. It stores task_plan.md, findings.md, and progress.md on disk so work can survive context loss, /clear, and crashes. The repository also offers optional autonomous and gated modes, with integrations for Claude Code, Codex CLI, Cursor, Kiro, OpenCode, and more than 60 agents through the SKILL.md standard.
The skill gives complex tasks a durable Markdown-based execution state. Agents create a phased plan, record research findings and errors, update progress, and re-read the plan through supported lifecycle hooks. Version 3 adds opt-in autonomous and gated modes, a structured run ledger, completion checks, SHA-256 plan attestation, and parallel plan isolation features.
- Multi-step coding tasks involving three or more phases
- Research workflows that need durable notes and findings
- Long-running agent sessions that may encounter /clear, compaction, context loss, or crashes
- Multi-agent workflows that need shared state on disk
- Project work that should verify planned phases before the agent stops
Pros & cons
- Persists execution state on disk across context loss, /clear, and crashes
- Separates phases, research findings, and progress logs into clear files
- Offers integrations for Claude Code, Codex, Cursor, Kiro, OpenCode, and other agent environments
- Includes optional autonomous mode, completion gating, run ledgers, and SHA-256 plan attestation
- Provides multilingual variants, platform-specific setup guides, and documented Windows support
- Requires local filesystem access and shell or lifecycle-hook execution; a bare model API cannot run it directly
- Hook behavior, commands, and installation procedures vary across agent platforms
- The source states that SKILL.md is not cached here, so its complete frontmatter and body cannot be independently verified
- Recovery and completion automation depend on the host agent exposing the required lifecycle events or hooks
How to install
The documented general installation command is: npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g. The README also lists separate commands for Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese variants. For Claude Code plugin features, use /plugin marketplace add OthmanAdi/planning-with-files followed by /plugin install planning-with-files@planning-with-files.
How to use
After installation, start a planning session with /planning-with-files:plan or /planning-with-files:start; in Claude Code, /planning-with-files:status displays a progress overview. The default workflow creates task_plan.md for phases, findings.md for research, and progress.md for session logs and test results. The documented rules include creating the plan first, saving findings after every two view or browser operations, logging all errors, and avoiding repeated failed approaches.
Compared to similar skills
Planning with Files is different from an agent memory tool such as a vector store or knowledge graph. Its focus is active execution state—phases, dependencies, progress, and completion checks—rather than long-term fact retrieval. Compared with keeping a todo list only in the context window, it writes important state to task_plan.md, findings.md, and progress.md so the agent can reload it after a reset or new session.