# Planning with Files

> Keeps your agent's plan, findings and progress in markdown files on disk, so long tasks survive /clear, crashes and compaction.

Planning with Files is a skill and Claude Code plugin by Ahmad Othman Ammar Adi (OthmanAdi) that gives your agent a working memory on disk. It follows the file-based planning pattern Manus described: before a multi-step task, the agent writes task_plan.md, findings.md and progress.md in your project and keeps them up to date as it works. Lifecycle hooks put the current plan back in front of the agent every turn, so after /clear, a crash or compaction it picks up at the current phase.

What it teaches the agent
- Create the plan first: phases with checkboxes in task_plan.md before any work starts
- Save research notes and decisions to findings.md after every two view or browser operations
- Log progress, test results and every error in progress.md, and never repeat a failed attempt
- Re-read the plan before big decisions, and check off each phase when it's done
- Recover after a context reset by reading the planning files back from disk

What the Claude Code plugin adds
- Lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact and Stop) that re-inject the active plan
- Slash commands: /plan to start, a status report on the current phase, /plan-doctor to check the hooks really fire, /plan-attest to lock the plan with a SHA-256 hash, and /plan-goal and /plan-loop to keep going until the plan is complete
- Autonomous and gated modes for long runs; gated mode holds the agent's stop while a phase is still in progress, with a cap so it never traps a session
- Separate plans for parallel tasks under .planning/, each pinned with PLAN_ID, and per-agent run ledgers for multi-agent work
- Translations in Arabic, German, Spanish, Simplified Chinese and Traditional Chinese (/plan-ar, /plan-de, /plan-es, /plan-zh, /plan-zht)

How to install it
In Claude Code, add the maker's marketplace with /plugin marketplace add OthmanAdi/planning-with-files, then run /plugin install planning-with-files@planning-with-files. That route ships the skill, its hooks and its slash commands. For other agents, npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g installs the skill, and the README has steps for Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Hermes Agent and more.

Good to know
- No sign-in: it runs inside your agent and writes plain markdown files to your project, gitignored by default.
- It has no network upload path. Its catch-up modes read your agent's local session records for the same project only when you ask.
- Skill-only installs can end up without hooks; the plugin route ships them, and /plan-doctor checks they fire.
- It's MIT licensed.

- Type: Plugin
- Made by: OthmanAdi
- Category: AI & agents
- Formats: Claude plugins
- Version: 3.25.2
- Website: https://github.com/OthmanAdi/planning-with-files
- Source: https://github.com/OthmanAdi/planning-with-files
- Page: https://pluginboard.ai/plugins/planning-with-files

## Works with

- Claude
- GitHub Copilot
- Claude Code
- OpenClaw

## Install

### Claude

In Claude (web or desktop): Customize → Plugins → Add → Add marketplace, enter OthmanAdi/planning-with-files, then add planning-with-files

### Claude Code

In Claude Code:

```text
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
```

---
From Pluginboard (https://pluginboard.ai).