Planning with Files
OthmanAdi/planning-with-files
A planning skill that keeps task_plan.md, findings.md and progress.md on disk so an agent resumes after /clear.
Planning with Files is a free, MIT-licensed planning skill by Ahmad Othman Ammar Adi. It keeps a task plan, research findings and a progress log as three Markdown files in your project, and uses lifecycle hooks to feed the plan back to the agent each turn. The plan survives /clear, compaction and crashes. The README describes it as an implementation of the Manus working-memory pattern.
Facts checked on against the sources listed at the end of this page.
- GitHub stars
- 27,263
- Skills in the pack
- 6
- Agents supported
- 17plus 60 other agents through the Agent Skills standard
- Instruction size
- 12.8k wordsacross all SKILL.md files
How to install Planning with Files
| Agent | Command | Copy |
|---|---|---|
| Any agent the skills CLI supports | Per the README, hooks may not register on this route. The plugin route below is the one that ships hooks and slash commands for Claude Code. | |
| Claude Code | Ships the skill, hooks and slash commands. Run /plan-doctor afterward to check the hooks. | |
| Codex | The README lists Codex as an enhanced host with 7 lifecycle hooks and points to docs/codex.md in the repo for setup. | |
| Cursor | The README lists Cursor as an enhanced host that uses a hooks.json file and points to docs/cursor.md in the repo for setup. | |
| Gemini CLI | The README lists Gemini CLI as an enhanced host with hooks and points to docs/gemini.md in the repo for setup. |
Commands for 4 more agents
| GitHub Copilot | The README lists GitHub Copilot as an enhanced host with hooks and points to docs/copilot.md in the repo for setup. | |
|---|---|---|
| Hermes Agent | | |
| Pi | | |
| DeepSeek Harness | |
Commands as given in the README on 2 October 2026.
What is inside Planning with Files
| Skill | What it makes the agent do |
|---|---|
| planning-with-files | Creates and maintains task_plan.md, findings.md and progress.md, and resumes from them at the start of each turn and after a context reset. |
There are also five translated variants of the same skill: Arabic, German, Spanish, Simplified Chinese and Traditional Chinese. The Claude Code plugin has 13 slash commands, including /plan, /pwf, /plan-attest, /plan-goal, /plan-loop and /plan-doctor.
What Planning with Files runs on your machine
| Hooks | Yes. The Claude Code plugin registers 6 lifecycle hooks: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact and Stop. The README gives hook counts of 7 for Codex, 8 for Pi and 3 to 4 for Hermes, OpenCode and DeepSeek Harness. An optional gated mode lets the Stop hook hold the session until the plan is complete. |
|---|---|
| Bundled scripts | Yes. The skill ships shell, PowerShell and Python scripts, including inject-plan.py, check-complete.sh, attest-plan.sh and session-catchup.py. Session recovery reads project planning files only. Reading local agent session records needs an explicit --metadata or --replay run. |
| Network calls | None. The skill's description says it has no network upload path, and the README says neither session-catchup mode makes a network request. If catchup output is placed in the model's context, your agent may send it to its model provider. |
| API keys needed | None named in the README. |
| Tool permissions | The skill allows Read, Write, Edit, Bash, Glob and Grep. |
These are facts read from the repo, not a security rating. Read the files before you install any skill.
How much context Planning with Files uses
| All 6 skills | 12,779 words across every SKILL.md file |
|---|---|
| Largest skill | planning-with-files, 5,450 words |
| Loaded at start | Only each skill's name and description. The full text loads when a task needs that skill. |
Word counts are measured from the repo every day. Reference files a skill loads on demand are not counted.
How Planning with Files works
The skill treats the context window as memory that gets wiped and the disk as memory that does not. The agent writes phases to task_plan.md, notes to findings.md and a session log to progress.md. Hooks re-inject selected plan content at the start of each turn, remind the agent after writes, flush a reminder before compaction and check completion before a stop. The plan files are gitignored by default and are working notes, not deliverables.
For long runs there are optional modes. Autonomous mode drops per-tool-call recitation. Gated mode adds a Stop gate that blocks only while a phase is in progress, with a cap on blocks. /plan-attest locks the plan with a SHA-256 hash so a tampered plan is refused at injection. Parallel tasks get their own .planning/<date>-<slug>/ directories, selected with PLAN_ID. The author's own benchmark reports a resume taking 5.0 turns with the files against 13.3 for a raw agent, and says the figure is an internal measurement.
A good fit for
- Long or multi-step tasks that outlast one context window and need to resume after /clear or compaction
- People who run several agents or hosts on one plan, since Claude Code, Codex, Pi, Hermes and OpenCode read the same files
- Teams that want a plan the agent cannot silently rewrite, using attestation and the completion gate
- Users of Cursor, Copilot, Gemini CLI or Codex who want the same planning pattern through each host's hooks
Skip it if
- Short tasks, where three planning files add steps the work does not need
- Installs through npx skills when you want hooks, because the README says that route can end up without hooks and the plugin route is the one that ships them
- Anyone who wants a recall tool for facts across sessions, since the README says it manages the active task, not long-term memory
Is Planning with Files still maintained?
| Last commit | , 1 day ago |
|---|---|
| Latest release | v3.22.0, 1 October 2026 |
| Stars gained in 7 days | Shown after 7 days of tracking |
| Stars gained in 30 days | Shown after 30 days of tracking |
| Open issues and pull requests | 8 |
| Forks | 2,268 |
Tools Planning with Files works with
Questions about Planning with Files
Does it work in Cursor and Codex?
Yes. The README lists Cursor and Codex among 12 enhanced hosts, with hooks, and lists many more through the Agent Skills standard. Each has a setup guide in the repo's docs folder.
Is it free?
Yes. It is MIT licensed.
Does it send my plan anywhere?
The skill has no network upload path, per the README and the skill's description. Your agent still sends whatever is in its context to its own model provider.
What happens to the plan files when a task ends?
They are working notes, gitignored by default and not archived. The next task overwrites the root plan. The README says to promote anything worth keeping into code, a commit or a doc.
How do I check that the hooks work?
Run /plan-doctor on the Claude Code plugin route. It reports PASS, WARN or FAIL for plan resolution, injection, attestation, install surfaces and hook latency.