planning-with-files

<div align="center"> <img src="media/pwf-banner-v5.webp" alt="PWF: Every task. Every step. Three planning files on a brass-inlaid base beneath an engraved arch" width="100%"> </div> <h1 align="center"> Planning with Files&nbsp;&nbsp;&nbsp;<a href="https://trendshift.io/repositories/17191" title="Trendshift: #1 daily across all languages, January 6, 2026"><img src="https://trendshift.io/api/badge/trendshift/repositories/17191/daily" alt="Trendshift: #1 Repository of the Day across all languages" width="250" height="55" align="middle"></a> </h1> <p align="center"> <strong>The planning skill your agent cannot ignore.</strong><br> Not a prompt it might follow. A hook that fires every turn, a plan on disk that survives <code>/clear</code>, and 3 out of 3 blind A/B wins to show it works. </p> <p align="center"> <em>Your agent's context window dies. The plan does not.</em> </p> <p align="center"> Persistent file-based planning for AI coding agents and long-running agent tasks: the skill keeps <code>task_plan.md</code>, <code>findings.md</code>, and <code>progress.md</code> on disk. Activated lifecycle hooks inject selected project planning context, so the plan survives context loss, <code>/clear</code>, 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. </p> <p align="center"> <a href="https://github.com/OthmanAdi/planning-with-files/stargazers"><img src="https://img.shields.io/github/stars/OthmanAdi/planning-with-files?style=flat&color=yellow" alt="Stars"></a> <a href="https://github.com/OthmanAdi/planning-with-files/releases"><img src="https://img.shields.io/github/v/release/OthmanAdi/planning-with-files?style=flat&label=release" alt="Latest release"></a> <a href="https://skills.sh/othmanadi/planning-with-files"><img src="https://skills.sh/b/othmanadi/planning-with-files" alt="skills.sh installs"></a> <a href="https://skillsplayground.com/skills/othmanadi-planning-with-files-planning-with-files/"><img src="https://skillsplayground.com/badges/installs/othmanadi-planning-with-files-planning-with-files.svg" alt="Skills Playground installs"></a> <a href="https://skill-history.com/othmanadi/planning-with-files"><img src="https://skill-history.com/badge/othmanadi/planning-with-files.svg" alt="Downloads"></a> <a href="https://github.com/OthmanAdi/planning-with-files/issues?q=is%3Aissue+is%3Aclosed"><img src="https://img.shields.io/github/issues-closed/OthmanAdi/planning-with-files?color=success" alt="Closed issues"></a> <a href="https://github.com/OthmanAdi/planning-with-files/pulls?q=is%3Apr+is%3Aclosed"><img src="https://img.shields.io/github/issues-pr-closed/OthmanAdi/planning-with-files?color=success" alt="Closed PRs"></a> </p> <p align="center"> <a href="docs/evals.md"><img src="https://img.shields.io/badge/benchmark-96.7%25_pass_(29%2F30)-2da44e?style=flat" alt="Benchmark: 96.7 percent assertion pass rate with skill"></a> <a href="docs/evals.md"><img src="https://img.shields.io/badge/blind_A%2FB-3%2F3_wins-2da44e?style=flat" alt="Blind A/B: 3 of 3 wins"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/OthmanAdi/planning-with-files?style=flat" alt="MIT license"></a> </p> <p align="center"> <a href="#before-and-after-clear"><strong>See it survive /clear</strong></a> · <a href="#quick-install"><strong>Install</strong></a> · <a href="#built-for-long-running-agent-tasks">Long-running tasks</a> · <a href="#first-class-hosts-native-plugins">First-class hosts</a> · <a href="#multi-agent-runs-orchestrators-workers-and-subagents">Multi-agent</a> · <a href="#benchmark-results">The numbers</a> </p> <p align="center"> _{Proof, comparisons and the repository reference are <a href="#reference">further down</a> · <a href="docs/installation.md">Full install guide</a>} </p>

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.

<p align="center"> <a href="media/pwf-context-story-v1.mp4"><img src="media/pwf-context-story-v1.gif" alt="Illustrated workflow: planning files preserve the task state through a context reset" width="760"></a> </p>

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.

<div><a id="the-problem"></a><a id="the-solution-3-file-pattern"></a><a id="the-core-principle"></a><a id="why-this-skill"></a><a id="the-manus-principles"></a></div>

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

<a id="hermes-agent-first-class-support-cli-and-desktop"></a>

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.

<details> <summary><strong>🌐 Available in 5 other languages</strong></summary>

🇸🇦 العربية / Arabic

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

🇩🇪 Deutsch / German

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

🇪🇸 Español / Spanish

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

🇨🇳 中文版 / Chinese (Simplified)

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

🇹🇼 正體中文版 / Chinese (Traditional)

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

These are real translations, not an English body with a translated description: the SKILL.md prose, the templates, and the user-facing output of check-complete, init-session and session-catchup are all localized. The status tokens stay literal English (**Status:** complete) on purpose, because check-complete.sh matches them with grep -F, so translating them would disable the completion gate.

Since v3.10.0 the variants also ship the full script surface: attestation, the Stop gate, the ledger, phase status and plan-doctor used to be canonical-only, which quietly made every non-English install a subset install. Full details, including what changed on the plugin route in v3.11.0, are in docs/languages.md.

They live under skills/i18n/, one directory deeper than the canonical skill. The install commands above are unchanged, because npx skills add resolves --skill by skill name across the whole repository. The Claude Code plugin scan reads skills/*/SKILL.md without recursing, so the plugin route registers the canonical skill alone and no longer carries five extra descriptions in every session's system prompt. On that route the /plan-ar, /plan-de, /plan-es, /plan-zh and /plan-zht commands read the translated skill from disk instead of invoking it by name.

</details> <details id="enhanced-support-per-ide-setup-guides"> <summary><strong>Enhanced Support: per-IDE setup guides</strong></summary>

| IDE | Installation Guide | Integration | |-----|-------------------|-------------| | Claude Code | Installation | Plugin + SKILL.md + Hooks | | Cursor | Cursor Setup | Skills + hooks.json | | GitHub Copilot | Copilot Setup | Hooks (incl. errorOccurred) | | Mastra Code | Mastra Setup | Skills + Hooks | | Gemini CLI | Gemini Setup | Skills + Hooks | | Kiro | Kiro Setup | Agent Skills | | Codex | Codex Setup | Skills + Hooks | | Hermes Agent | Hermes Setup | Skill + native plugin (tools, /pwf, pre_llm_call, post_tool_call, pre_verify gate), CLI and Desktop | | CodeBuddy | CodeBuddy Setup | Skills + Hooks | | FactoryAI Droid | Factory Setup | Skills + Hooks | | OpenCode | OpenCode Setup | Native plugin opencode-planning-with-files (chat.message injection, write reminders, compaction flush, session.idle gate, pwf_* tools, /pwf commands) + skill | | DeepSeek Harness | DeepSeek Harness Setup | Native plugin dsh-planning-with-files (agent/pre-step injection, write reminders, post-compaction restore, agent/turn-stopping gate, pwf_* tools, /pwf commands) + skill |

</details> <details> <summary><strong>Standard Agent Skills: discovery paths</strong></summary>

| IDE | Installation Guide | Skill Discovery Path | |-----|-------------------|---------------------| | Continue | Continue Setup | .continue/skills/ + .prompt files | | Pi Agent | Pi Agent Setup | .pi/skills/ (npm package) | | OpenClaw | OpenClaw Setup | .openclaw/skills/ (docs) | | Autohand Code | Autohand Code Setup | ~/.autohand/skills/ or .autohand/skills/ | | Antigravity | Antigravity Setup | .agent/skills/ (docs) | | Kilocode | [Kiloc