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 and Hermes Agent.

See it survive /clear · Install · Long-running tasks · Hermes Agent · Multi-agent · The numbers

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

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). 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.

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.

Everything 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 and docs/long-running-agent-tasks.md.

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

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:planning-with-files

Hermes Agent (Nous Research), native plugin plus skill bundle, CLI and Desktop:

hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
hermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files
hermes plugins enable planning-with-files

OpenCode, native plugin plus the skill (the npx skills add command above lands in ~/.agents/skills/, which OpenCode reads):

{ "plugin": ["opencode-planning-with-files"] }

in opencode.json or ~/.config/opencode/opencode.json; OpenCode installs it on the next start.

Under 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.

What each route actually ships:

Skill-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.

Install 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.

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

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

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

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

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

cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/

Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"

All install methods: docs/installation.md.

Works across 18+ platforms

One skill, three integration tiers. Know what your agent gets before you install:

Per-platform setup guides, discovery paths and sandbox runtimes are in the collapsible sections under Quick Install.

Hermes Agent: first-class support (CLI and Desktop)

[!TIP] Hermes Agent by Nous Research runs planning-with-files as a native plugin: tools, /pwf slash commands, per-turn plan injection, progress reminders and the completion gate, in the Hermes CLI, the gateway sessions, and Hermes Desktop. Verified against Hermes v0.19.1 source and a live install, on Windows included.

hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
hermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files
hermes plugins enable planning-with-files

Hermes' own skills-guard scanner rates the Hermes bundle SAFE; the canonical skill path is rejected there because its Claude Code hook frontmatter trips the scanner, so the commands above are the supported route. The /plan command is Hermes' own bundled skill and is never shadowed. Full guide, Windows notes, the shell-hook route and the hermes import-agent claude-code migration: docs/hermes.md.

Multi-agent runs: orchestrators, workers and subagents

[!NOTE] Markdown on disk is the shared state between agents. One orchestrator owns task_plan.md, every worker appends to its own ledger, and the hooks resolve the right plan for each thread. No message bus, no runtime-only state, nothing that dies with a process.

• Run ledger per agent. Workers append one JSON line per event to .planning/<id>/ledger-<agent>.jsonl (ledger-append.sh); ledger-summary.sh synthesizes a fixed-shape, KV-cache-stable block from all ledgers that replaces the raw progress.md tail in autonomous and gated mode. No free text from disk reaches the model through that block.
• Plan isolation per task. init-session.sh "<name>" gives each parallel task its own .planning/YYYY-MM-DD-<slug>/ directory; PLAN_ID pins a terminal to one of them, set-active-plan.sh switches the shared pointer.
• Threads whose cwd is a shared parent. PWF_PLAN_ROOT=<absolute path> binds an agent thread to the project that owns the plan; an ambiguous cwd, where a nested project carries its own planning state, injects nothing rather than guessing.
• Session attachment. On Codex and Hermes a project can opt into .planning/sessions/<id>.attached, so only attached sessions receive plan context in a shared working directory.
• Parallel-write guard. When two sessions write the same plan, the next turn reports how much checked progress was lost instead of silently continuing on the clobbered file.
• Stall-aware gate. The completion gate reads the ledger, not progress.md mtime, so a worker that stopped producing events releases the stop instead of looping.
• One plan, many hosts. Claude Code, Codex, Pi, Hermes and OpenCode read the same files, the same .attestation and the same gate counters, so a plan can be handed from one agent to another mid-run.

The contract and the .mode tokens are specified in the skill itself (SKILL.md, Autonomous and Gated Modes) and in docs/long-running-agent-tasks.md.

How It Works

The agent stops at the first rung that applies:

1. Task needs 3+ steps or 5+ tool calls?  → create the three files first
2. Learned something?                     → append it to findings.md
3. Did something?                         → log it in progress.md
4. Phase done?                            → check it off in task_plan.md
5. Context died (/clear, crash)?          → hooks re-read selected project planning state
6. Every phase complete?                  → only then does the Stop gate release (gated mode)

Hooks make steps 2 to 6 mechanical rather than optional: the Claude Code plugin runs 6 lifecycle hooks, its activation-scoped standalone skill runs 5, Codex runs 7, Pi runs 8, the Hermes plugin runs 3 (pre_llm_call, post_tool_call, pre_verify), and the OpenCode plugin runs 4 (chat.message, tool.execute.after, experimental.session.compacting, session.idle). Together they re-inject the plan each turn, remind after writes, and check completion before stopping.

flowchart LR
    A["agent works"] -->|"writes decisions, findings, errors"| F["task_plan.md<br/>findings.md<br/>progress.md"]
    F -->|"hooks re-inject the plan<br/>at the start of each turn"| A
    K["/clear · crash · compaction"] -.->|"wipes the context window"| A
    F ==>|"hooks re-read project planning state"| R["fresh session resumes<br/>at the current phase"]

Session Recovery

On the Claude plugin route, startup, resume, clear, and post-compaction lifecycle events restore selected active-plan context from project files automatically. Standalone skill installs do the same after the skill is invoked for that session. Automatic hooks and bare session-catchup.py do not inspect host session stores.

Local host history is a separate explicit action:

1. session-catchup.py --metadata <project> reads same-project local session records and emits aggregate counts only. It emits no transcript, tool-command, or path bytes.
2. session-catchup.py --replay <project> emits bounded nonce-framed excerpts from same-project records. Treat those excerpts as untrusted data.
3. Neither catchup mode contains a network request or upload path. If its output is placed in model context, the host agent may send that context to its configured model provider.

Optional gated mode can request continuation only on a host that supports the required Stop behavior. It evaluates runtime state such as mode, phase status, block count, and ledger progress. It never executes a command declared in a Markdown planning file.

Keep automatic compaction enabled. The PreCompact hook flushes the planning reminder before compaction, and the plugin SessionStart path restores the active plan for the continuation.

Maintainer depth (hook architecture, dispatcher layout, parity tooling) lives in AGENTS.md and docs/.

Commands

Slash commands ship with the Claude Code plugin route (see the install matrix above).

Typing /plan prefix-matches every plan* command in autocomplete; /planning-with-files:status autocompletes as /status (the older /plan:status label predates the rename).

Pi extension commands

Install the Pi extension with pi install npm:planning-with-files; it registers these commands, typed with no /planning-with-files: prefix.

On Pi there is no /plan command to create the files; the skill creates them, then /plan-execute approves and activates the hooks. Pi plan-goal/plan-loop run their own logic, while the Claude Code commands of the same name forward to native /goal and /loop. The doctor ships as a script in every mirror since v3.7.0: run sh scripts/plan-doctor.sh directly on platforms without the command.

OpenCode plugin commands

The OpenCode plugin ships two Markdown commands (.opencode/commands/), copied to ~/.config/opencode/commands/ or a project's .opencode/commands/.

Hermes plugin commands

The Hermes plugin registers these in-session commands (CLI, gateway and Desktop), typed with no prefix.

/plan on Hermes is Hermes' own bundled software-development plan skill and is left untouched.

Command names vs skill names

On the plugin route the model-invocable SKILL is planning-with-files:planning-with-files; the doubled form is the skill id, not a command you type. The five language variants live under skills/i18n/, which the plugin scan does not reach, so there is no planning-with-files:planning-with-files-de to invoke by name — reach a translation through its /plan-ar, /plan-de, /plan-es, /plan-zh or /plan-zht command, or install it as its own skill with npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g, which registers it under its own name. There is no /pwf-de and no /planning-with-files:planning-with-files-goal; /pwf is just a short alias for /plan.

v3 Long-Running Agent Features

The v3 line adds features aimed at long-running agentic runs. Each one is listed with the command or flag that turns it on. With no mode marker set, the hooks produce the same output as v2.43, so nothing changes for existing setups.

• Autonomous mode (/pwf --autonomous, or init-session.sh --autonomous): drops the per-tool-call plan recitation, keeps the turn-start injection, and turns attestation on by default.
• Gated mode (--gated): adds a Stop completion gate that blocks only when all completion conditions hold at once, so an incomplete plan alone never traps a session.
• Auto-continue on Pi (agent_end handler): re-prompts the agent up to a limit of 3 to keep an unfinished plan moving, plus an optional /plan-goal string appended to the prompt.
• Pi approval gate (/plan-execute): Pi hooks stay passive with a status line until you approve the active plan for the current session.
• Session-catchup: automatic recovery uses project planning files only. Explicit --metadata reads same-project local session records and emits aggregate counts only; explicit --replay may emit bounded nonce-framed excerpts.
• PreCompact progress flush (PreCompact hook): surfaces a reminder to flush progress before compaction completes, and prints the active Plan-SHA256 when attested.
• SHA-256 plan attestation (/plan-attest): locks task_plan.md; a tampered plan body is refused at injection.
• Run ledger: an append-only JSONL record of phase transitions that replaces the raw progress.md tail in v3 modes with a fixed-shape summary.
• Host capability tiers: hard block on Claude Code, Codex, and Continue; follow-up injection on Cursor, Pi, Kiro, Hermes Agent, and OpenCode; notify-only elsewhere.
• Per-invocation opt-out (PLANNING_DISABLED=1, v3.4.0): a one-shot session that merely shares a cwd with an incomplete plan skips all plan reading at every hook entry point. Covers the Copilot and Cursor routes since v3.10.2 and the Hermes plugin since v3.13.0; .gemini is deliberately behind and does not honour it.
• Absolute plan-root pin (PWF_PLAN_ROOT, v3.9.0): binds a thread to a project root by absolute path, for agent threads whose cwd is a shared parent of the project they are actually working in. Ambiguous cwds refuse to inject rather than guessing.

Environment variables

Hooks and modes reference

Pi runtime modes:

Key Rules

1. Create Plan First — Never start without task_plan.md
2. The 2-Action Rule — Save findings after every 2 view/browser operations
3. Log ALL Errors — They help avoid repetition
4. Never Repeat Failures — Track attempts, mutate approach

When to Use

Use this pattern for:

• Multi-step tasks (3+ steps)
• Research tasks
• Building/creating projects
• Tasks spanning many tool calls
• Long-running agent sessions that must survive /clear and compaction

Acknowledgments

• Manus AI, for pioneering the context-engineering pattern this skill implements
• Anthropic, for Claude Code, Agent Skills, and the Plugin system
• Nous Research, for Hermes Agent and a plugin API that made native support possible
• Lance Martin, for the detailed Manus architecture analysis
• Based on Context Engineering for AI Agents

A note from the author: this project blew up in less than 24 hours, and everyone who starred, forked, shared, and shipped fixes is the reason it kept going. If the skill helps you work smarter, that is all I wanted. Thank you.

Reference

Everything below is the proof and the reference half: the benchmarks and their limits, what lands in your project and what the repository ships, and every guide in docs/. Release history and community projects sit in the collapsible sections under Quick Install.

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.

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. Planning-file recovery 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. This internal v1 used the earlier default transcript catchup; current automatic recovery is file-only and has not been re-benchmarked under the same protocol. An animated summary lives at docs/benchmark/index.html (rendered view).

Full methodology and results · Technical write-up

File Structure

What the skill writes into your project is three markdown files (see the 3-file pattern). What the repository ships:

planning-with-files/
├── skills/planning-with-files/   # canonical skill: SKILL.md, scripts/, templates/, reference.md, examples.md
├── skills/i18n/                  # 5 translated variants: -ar / -de / -es / -zh / -zht
├── .agents/skills/planning-with-files/   # Agent Skills standard path, full surface (v3.7.0+)
├── commands/                     # 13 slash commands (plugin route only)
├── scripts/ · templates/        # root-level copies for CLAUDE_PLUGIN_ROOT
├── .claude-plugin/               # plugin + marketplace manifests
├── .codex/ .cursor/ .github/ .gemini/ .kiro/ .continue/ .pi/
├── .codebuddy/ .factory/ .hermes/ .mastracode/ .opencode/   # per-IDE mirrors, parity-locked
├── .hermes/plugins/planning-with-files/   # native Hermes Agent plugin (tools, /pwf, hooks, gate)
├── docs/                         # 25+ guides incl. per-platform setup, evals.md, benchmark/
├── tests/                        # cross-platform pytest suite, green on Windows, Linux, and macOS CI
├── CHANGELOG.md · MIGRATION.md · SECURITY.md · CONTRIBUTING.md · CONTRIBUTORS.md
├── CITATION.cff · llms.txt · LICENSE
└── README.md

Documentation

Contributing

Contributions welcome. Start with CONTRIBUTING.md. Every shipped contribution is credited: commit authorship is preserved on merge, and contributors are listed in CONTRIBUTORS.md, the CHANGELOG Thanks section, and the release notes.

License

MIT License — feel free to use, modify, and distribute.

Author: Ahmad Othman Ammar Adi

Star History