othmanadi/planning-with-files

Contributors

Code, documentation, and issue contributors. Select a portrait to open a GitHub profile or archived credit. Full credits.

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

See it survive /clear · Install · Long-running tasks · First-class hosts

Open the Commands, Multi-agent runs, Benchmarks & more section below for the reference · 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] Native integrations load planning context, provide progress reminders and support a completion gate. Commands and model-callable tools depend on the host; Qoder CLI loads the skill and lifecycle hooks without the Claude-specific command prompts. The platform setup guides describe each integration and the standard Agent Skills routes.

Star History

ClawHub Downloads