![\"planning-with-files:](\"media/v3-banner-1400.jpg\")
\n\n\n The planning skill your agent cannot ignore.
\n 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.\n
\n Your agent's context window dies. The plan does not.\n
\n\n\nPersistent 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 and Hermes Agent.\n
\n ![\"Stars\"](\"https://img.shields.io/github/stars/OthmanAdi/planning-with-files?style=flat&color=yellow\")
![\"Latest](\"https://img.shields.io/github/v/release/OthmanAdi/planning-with-files?style=flat&label=release\")
![\"Skills](\"https://skillsplayground.com/badges/installs/othmanadi-planning-with-files-planning-with-files.svg\")
\n ![\"Downloads\"](\"https://skill-history.com/badge/othmanadi/planning-with-files.svg\"){kind=icon}
\n
\n ![\"Benchmark:](\"https://img.shields.io/badge/benchmark-96.7%25_pass_(29%2F30)-2da44e?style=flat\"){kind=icon}
![\"Blind](\"https://img.shields.io/badge/blind_A%2FB-3%2F3_wins-2da44e?style=flat\"){kind=icon}
![\"MIT](\"https://img.shields.io/github/license/OthmanAdi/planning-with-files?style=flat\")
\n See it survive /clear ·\n Install ·\n Long-running tasks ·\n Hermes Agent ·\n Multi-agent ·\n The numbers\n
\n\n\n Proof, comparisons and the repository reference are further down · Full install guide\n
\n\n---\n\n## Before and after /clear\n\nEvery coding agent loses its working memory when the context window resets. The plan does not have to die with it.\n\n### Without planning files\n\n![\"Terminal](\"media/terminal-without-plan.svg\")
\n\nThe agent re-reads the repo, asks you to restate the goal, and rediscovers work it already finished.\n\n---\n\n### With planning-with-files\n\n![\"Terminal](\"media/terminal-with-plan.svg\")
\n\nThe 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](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.\n\n| At a glance | |\n|---|---:|\n| Plan files | **3** |\n| Agents covered | **60+** |\n| Pass rate (with skill) | **96.7%** |\n| Test suite | **706 tests** |\n| Survives `/clear` | **yes** |\n\n## Built for long-running agent tasks\n\n> [!IMPORTANT]\n> **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.**\n>\n> 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](#benchmark-results)). Every mechanism below is a file on disk plus a hook, so it works the same on hour ten as on turn one.\n\n| What breaks long agent runs | What the skill does about it |\n|---|---|\n| 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 |\n| 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 |\n| 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 |\n| 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]` |\n| Two sessions overwrite each other's phases | The parallel-write guard reports when checked items or completed phases go down between turns |\n| 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 |\n| Hooks that quietly stop firing | `/plan-doctor` self-checks resolution, injection, attestation, install surfaces and per-fire latency |\n\nEverything 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](#v3-long-running-agent-features) and [docs/long-running-agent-tasks.md](docs/long-running-agent-tasks.md).\n\n## The Problem\n\nClaude Code and most AI agents suffer from:\n\n- **Volatile memory**: the TodoWrite list disappears on context reset\n- **Goal drift**: after 50+ tool calls, the original goals get crowded out\n- **Hidden errors**: failures are not tracked, so the same mistakes repeat\n- **Context stuffing**: everything crammed into the window instead of stored\n\n## The Solution: 3-File Pattern\n\nFor every complex task, create THREE files:\n\n```\ntask_plan.md → Track phases and progress\nfindings.md → Store research and findings\nprogress.md → Session log and test results\n```\n\n### The Core Principle\n\n```\nContext Window = RAM (volatile, limited)\nFilesystem = Disk (persistent, unlimited)\n\n→ Anything important gets written to disk.\n```\n\nIn your project, exactly this lands on disk and nothing else:\n\n```\nyour-project/\n├── task_plan.md ← phases + checkboxes; the resume point after /clear\n├── findings.md ← research notes and decisions, appended as you go\n└── progress.md ← session log and test results\n```\n\nParallel 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.\n\n## Why This Skill?\n\nOn December 29, 2025, [Meta acquired Manus for $2 billion](https://techcrunch.com/2025/12/29/meta-just-bought-manus-an-ai-startup-everyone-has-been-talking-about/). In just 8 months, Manus went from launch to $100M+ revenue. Their secret? **Context engineering.**\n\n> \"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.\"\n> — Manus AI\n\nThis skill packages that exact pattern for your coding agent.\n\n### The Manus Principles\n\n| Principle | Implementation |\n|-----------|----------------|\n| Filesystem as memory | Store in files, not context |\n| Plan recitation | Re-read plan before decisions (hooks) |\n| Error persistence | Log failures in plan file |\n| Goal tracking | Checkboxes show progress |\n| Completion verification | Stop hook checks all phases |\n\n## Quick Install\n\n**Claude Code, plugin route** (ships everything: skill, hooks, slash commands):\n\n```\n/plugin marketplace add OthmanAdi/planning-with-files\n/plugin install planning-with-files@planning-with-files\n```\n\n**Every other agent**, one line, 60+ agents via the [Agent Skills](https://agentskills.io) standard:\n\n```bash\nnpx skills add OthmanAdi/planning-with-files --skill planning-with-files -g\n```\n\n**npm**, to pin an exact version into a project or vendor it:\n\n```bash\nnpm install planning-with-files\n```\n\nThe 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.\n\n**Pi Coding Agent**, same npm package, wired up for you (skill, extension, status bar):\n\n```bash\npi install npm:planning-with-files\n```\n\n**Hermes Agent** (Nous Research), native plugin plus skill bundle, CLI and Desktop:\n\n```bash\nhermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes\nhermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files\nhermes plugins enable planning-with-files\n```\n\n**OpenCode**, native plugin plus the skill (the `npx skills add` command above lands in `~/.agents/skills/`, which OpenCode reads):\n\n```json\n{ \"plugin\": [\"opencode-planning-with-files\"] }\n```\n\nin `opencode.json` or `~/.config/opencode/opencode.json`; OpenCode installs it on the next start.\n\nUnder 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.\n\nWhat each route actually ships:\n\n| Route | Skill + scripts + templates | Slash commands | Hooks |\n|---|---|---|---|\n| Claude Code plugin | yes | **yes** | **yes** |\n| `npx skills add` | yes | no | frontmatter hooks, see note |\n| `npm install` | yes, under `node_modules/` | no | no, copy the skill in yourself |\n| `pi install npm:` | yes | **yes**, Pi commands | **yes**, via the Pi extension |\n| `hermes plugins install` | yes, with the skill bundle | **yes**, `/pwf`, `/pwf-status` | **yes**, plugin hooks incl. the gate |\n| OpenCode `opencode.json` plugin | yes, with the skill | **yes**, `/pwf`, `/pwf-status` (two copied command files) | **yes**, plugin hooks incl. the gate |\n| ClawHub / manual copy | yes | no | frontmatter hooks, see note |\n\nSkill-route installs can end up silently hook-less (project trust not accepted, or frontmatter hooks not registering on project-level installs). The hooks are the differentiating mechanism, so if they matter to you, use the plugin route, then verify with `/plan-doctor`. Full matrix and the two silent killers: [docs/installation.md](docs/installation.md#what-each-install-route-actually-ships).\n\nInstall acting up? Open your agent and say: *\"Read docs/installation.md and docs/troubleshooting.md from OthmanAdi/planning-with-files and fix my install.\"* Then run `/plan-doctor`.\n\n/planning-with-files with no prefix?