Planning With Files

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, Hermes Agent, OpenCode and DeepSeek Harness.

See it survive /clear · Install · Long-running tasks · First-class hosts · Multi-agent · The numbers

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

Quick Install

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

All install methods: docs/installation.md.

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.

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.

The 3-file pattern

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

→ Anything important gets written to disk.

The skill keeps your plan, findings, and progress in your project:

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

First-class hosts: native plugins

> [!TIP] > On these hosts planning-with-files runs as a native plugin: per-turn plan injection, progress reminders, the completion gate, /pwf commands and model-callable tools, with no shell hooks to register. Every other platform gets the skill through the Agent Skills standard and, where the host supports it, the frontmatter or config-file hooks listed in the platform setup guides.