Planning with Files   

The planning skill your agent cannot ignore.
Not a prompt it might follow. A hook that fires every turn, a plan on disk that survives /clear, and 3 out of 3 blind A/B wins to show it works.

Your agent's context window dies. The plan does not.

Persistent file-based planning for AI coding agents and long-running agent tasks: the skill keeps task_plan.md, findings.md, and progress.md on disk. Activated lifecycle hooks inject selected project planning context, so the plan survives context loss, /clear, crashes, and compaction. Automatic recovery reads project files only. Reading same-project local agent session records for aggregate counts or bounded replay requires an explicit catchup mode. Installs across 60+ agents via the Agent Skills standard, with native plugins for Claude Code, Codex CLI, Pi and Hermes Agent.

See it survive /clear · Install · Long-running tasks · Hermes Agent · Multi-agent · The numbers

_{Proof, comparisons and the repository reference are further down · Full install guide}

---

Before and after /clear

Every coding agent loses its working memory when the context window resets. The plan does not have to die with it.

Without planning files

The agent re-reads the repo, asks you to restate the goal, and rediscovers work it already finished.

---

With planning-with-files

The transcript is illustrative; the ===BEGIN PLAN DATA=== block is the skill's real injection format, written into context by the UserPromptSubmit hook from task_plan.md on disk. In the project's internal recovery benchmark, a fresh session with the files on disk resumed in 5.0 turns on average against 13.3 for a raw agent (internal v1, author-run; method and limits in docs/evals.md). That benchmark used the earlier default transcript-catchup behavior. Current automatic recovery uses project files only, so the figure is historical evidence rather than a fresh measurement of the current default.

| At a glance | | |---|---:| | Plan files | 3 | | Agents covered | 60+ | | Pass rate (with skill) | 96.7% | | Test suite | 706 tests | | Survives /clear | yes |

Built for long-running agent tasks

[!IMPORTANT]

Most harnesses ship a to-do list that lives inside the context window. planning-with-files ships a plan that lives on disk, is re-injected every turn, is hash-attested, and can hold the agent's stop until the plan reports complete.

> That is the difference between an agent that forgets after /clear, compaction or a crash and one that resumes at the current phase. In the project's own measurements the plan on disk turned a 13.3-turn re-orientation into 5.0 turns, and the skill won 3 of 3 blind A/B comparisons (numbers and limits). Every mechanism below is a file on disk plus a hook, so it works the same on hour ten as on turn one.

| What breaks long agent runs | What the skill does about it | |---|---| | The context window is wiped by /clear, compaction, or a crash | The plan is re-read from disk on the next turn; SessionStart, UserPromptSubmit and PreCompact hooks carry the current phase back in | | Goal drift after 50+ tool calls | The plan head is re-injected every turn; PWF_INJECT=smart keeps the goal, the next step and the active phase in the window late in a long plan | | The agent declares "done" early | Gated mode: the Stop gate holds the stop only while an in_progress phase remains, with a block cap and stall detection so an incomplete plan alone never traps a session | | The plan is silently rewritten by a tool result, a collaborator, or a bug | SHA-256 attestation: a plan body that no longer matches the approved hash is refused at injection with [PLAN TAMPERED] | | Two sessions overwrite each other's phases | The parallel-write guard reports when checked items or completed phases go down between turns | | Autonomous loops burn tokens on recitation | Autonomous mode drops the per-tool-call recitation and replaces the raw progress tail with a fixed-shape ledger summary; injection is KV-cache stable and one hook fire costs about 289 ms | | Hooks that quietly stop firing | /plan-doctor self-checks resolution, injection, attestation, install surfaces and per-fire latency |

Everything in that table is opt-in per plan and byte-identical to the previous behavior when no mode marker is set. Details: v3 Long-Running Agent Features and docs/long-running-agent-tasks.md.

The Problem

Claude Code and most AI agents suffer from:

• Volatile memory: the TodoWrite list disappears on context reset
• Goal drift: after 50+ tool calls, the original goals get crowded out
• Hidden errors: failures are not tracked, so the same mistakes repeat
• Context stuffing: everything crammed into the window instead of stored

The Solution: 3-File Pattern

For every complex task, create THREE files:

task_plan.md      → Track phases and progress
findings.md       → Store research and findings
progress.md       → Session log and test results

The Core Principle

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.

In your project, exactly this lands on disk and nothing else:

your-project/
├── task_plan.md   ← phases + checkboxes; the resume point after /clear
├── findings.md    ← research notes and decisions, appended as you go
└── progress.md    ← session log and test results

Parallel tasks get isolated directories instead: .planning/YYYY-MM-DD-slug/ with the same three files, selected via .active_plan (v2.36.0+). Plain markdown, gitignored by default, no runtime state anywhere else.

Why This Skill?

On December 29, 2025, Meta acquired Manus for $2 billion. In just 8 months, Manus went from launch to $100M+ revenue. Their secret? Context engineering.

"Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables."

— Manus AI

This skill packages that exact pattern for your coding agent.

The Manus Principles

| Principle | Implementation | |-----------|----------------| | Filesystem as memory | Store in files, not context | | Plan recitation | Re-read plan before decisions (hooks) | | Error persistence | Log failures in plan file | | Goal tracking | Checkboxes show progress | | Completion verification | Stop hook checks all phases |

Quick Install

Claude Code, plugin route (ships everything: skill, hooks, slash commands):

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

Every other agent, one line, 60+ agents via the Agent Skills standard:

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

npm, to pin an exact version into a project or vendor it:

npm install planning-with-files

The package carries SKILL.md, scripts/ and templates/, so this is the route for locking a version into a repo's dependencies or copying the skill in yourself. It does not register hooks on its own.

Pi Coding Agent, same npm package, wired up for you (skill, extension, status bar):

pi install npm:planning-with-files

Hermes Agent (Nous Research), native plugin plus skill bundle, CLI and Desktop:

hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
hermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files
hermes plugins enable planning-with-files

OpenCode, native plugin plus the skill (the npx skills add command above lands in ~/.agents/skills/, which OpenCode reads):

{ "plugin": ["opencode-planning-with-files"] }

in opencode.json or ~/.config/opencode/opencode.json; OpenCode installs it on the next start.

Under a minute. Safe to re-run. Trigger it by typing /plan (plugin) or asking the agent to "plan this task"; the skill also self-triggers on multi-step tasks.

What each route actually ships:

| Route | Skill + scripts + templates | Slash commands | Hooks | |---|---|---|---| | Claude Code plugin | yes | yes | yes | | npx skills add | yes | no | frontmatter hooks, see note | | npm install | yes, under node_modules/ | no | no, copy the skill in yourself | | pi install npm: | yes | yes, Pi commands | yes, via the Pi extension | | hermes plugins install | yes, with the skill bundle | yes, /pwf, /pwf-status | yes, plugin hooks incl. the gate | | OpenCode opencode.json plugin | yes, with the skill | yes, /pwf, /pwf-status (two copied command files) | yes, plugin hooks incl. the gate | | ClawHub / manual copy | yes | no | frontmatter hooks, see note |

Skill-route installs can end up silently hook-less (project trust not accepted, or frontmatter hooks not registering on project-level installs). The hooks are the differentiating mechanism, so if they matter to you, use the plugin route, then verify with /plan-doctor. Full matrix and the two silent killers: docs/installation.md.

Install acting up? Open your agent and say: "Read docs/installation.md and docs/troubleshooting.md from OthmanAdi/planning-with-files and fix my install." Then run /plan-doctor.

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g

cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/

Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"