planning-with-files

---

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	1084 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 3-file pattern

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.

For every complex task the skill keeps exactly this in your project, 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.

The pattern is the one Manus described before Meta acquired it for $2 billion on December 29, 2025, eight months and $100M+ of revenue after launch:

"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

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.

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

dsh plugin --profile web add dsh-planning-with-files

then restart dsh web; the same command works for the headless, sdk and acp profiles.

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
DeepSeek Harness dsh plugin add	yes, with the skill	yes, /pwf, /pwf-status	yes, plugin hooks incl. the gate