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).
At a glance
Plan files 3
Agents covered 60+
Pass rate (with skill) 96.7%
Test suite 417 green
Survives /clear
yes
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
Attention manipulation 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
Benchmark Results
Methodology note: the 96.7% figure comes from the v2.21.0 evaluation run on claude-sonnet-4-6 (2026-03-06). It measures file-pattern fidelity (does the agent create and maintain the 3-file structure), not goal-drift over long autonomous runs. Newer models and the autonomous-mode work are not yet covered by this number. Full methodology, dataset, and assertion list: docs/evals.md.
Evaluated with Anthropic's skill-creator framework: skill v2.21.0, model claude-sonnet-4-6, 2026-03-06. 10 parallel subagents, 5 task types, 30 objectively verifiable assertions, 3 blind A/B comparisons.
Test with_skill without_skill
Pass rate (30 assertions) 96.7% (29/30) 6.7% (2/30)
3-file pattern followed 5/5 evals 0/5 evals
Blind A/B wins 3/3 (100%) 0/3
Avg rubric score 10.0/10 6.8/10
Recovery after a context wipe
Internal benchmark, v1 (2026-07-06). Author-run against v3.4.0, harness-authored tasks, deterministic grading, no LLM grades anything. Treat it as the project's own measurement, not an independent comparison. Full method, arms, disclosed limits, and grader validation: docs/evals.md.
Protocol: the session is hard-stopped at roughly half done, and a fresh session is told only "Continue the work in this directory." Every graded run across every arm ended pytest-green (77/77), so the difference is re-orientation cost, not correctness.
With the planning files on disk, a resume took 5.0 turns on average; a raw agent took 13.3. Session catchup plus hook injection put phase state in front of the model before its first tool call, and the same run found no correctness penalty anywhere. An animated summary lives at docs/benchmark/index.html (rendered view).
Full methodology and results · Technical write-up
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:pl