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 and re-injects them every turn, so the plan survives context loss, /clear, crashes, and compaction. Manus-style working memory on disk, with an opt-in completion gate. Installs across 60+ agents via the Agent Skills standard.

See it survive /clear · The 3 files · Why it works · The numbers · Install

_{Everything technical is 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).

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

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. Session catchup 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. An animated summary lives at docs/benchmark/index.html (rendered view).

Full methodology and results · Technical write-up

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

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.

Reference

Everything below is the technical half: how the hooks fire, every command, every supported platform, and the release history.

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)?          → session catchup re-reads all three
6. Every phase complete?                  → only then does the Stop gate release (gated mode)

Hooks make steps 2 to 6 mechanical rather than optional: 5 lifecycle hooks on Claude Code, 7 on Codex, 8 on Pi 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 ==>|"session catchup re-reads the files"| R["fresh session resumes<br/>at the current phase"]

Session Recovery

When your context fills up and you run /clear, the skill recovers the previous session automatically:

1. Checks the active IDE's session store for previous session data (~/.claude/projects/ for Claude Code, ~/.codex/sessions/ for Codex)
2. Finds when the planning files were last updated
3. Extracts the conversation that happened after (potentially lost context)
4. Shows a catchup report so you can sync

Pro tip: disable auto-compact to maximize context before clearing:

{ "autoCompact": false }

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.

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.

Works across 18+ platforms

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

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: resumes work after /clear by re-reading the planning files from the active IDE's session store.
• 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, and Kiro; 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; .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

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
├── 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

Acknowledgments

• Manus AI, for pioneering the context-engineering pattern this skill implements
• Anthropic, for Claude Code, Agent Skills, and the Plugin system
• 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.

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