Planning with Files
OthmanAdi/planning-with-files
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,592
- Skills in the pack
- 6
- Agents supported
- 17plus 60 other agents through the Agent Skills standard
- License
- MIT
- Last commit
- 3 days ago20 October 2026
- Instruction size
- 13k 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 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.
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.
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
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.
- Made by
- Ahmad Othman Ammar Adi
- Topic
- Coding workflow
- Works with
- Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Kiro, Mastra Code, Hermes Agent, CodeBuddy, Factory Droid, OpenCode, DeepSeek Harness, Continue, Pi, OpenClaw, Antigravity, Kilocode
How much context Planning with Files uses
| All 6 skills | 13,018 words across every SKILL.md file |
|---|---|
| Largest skill | planning-with-files, 5,689 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.
Is Planning with Files still maintained?
| Last commit | , 3 days ago |
|---|---|
| Latest release | v3.25.0, 20 October 2026 |
| Stars gained in 7 days | +123 |
| Stars gained in 30 days | Shown after 30 days of tracking |
| Open issues and pull requests | 10 |
| Forks | 2,294 |
Tools Planning with Files works with
Similar skill packs
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.
Sources
- OthmanAdi/planning-with-files on GitHub
- Planning with Files README
- Planning with Files SKILL.md
- Planning with Files license
Something wrong or out of date? Email [email protected] with a link to the source. Stats come from the public GitHub API and update every day.
For the maker
Add the badge to your README or site. The number updates every day.
Sharing on X? Open the share card with the pack's live numbers.
