README

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

you: continue

agent: I don't have context from an earlier session. Can you describe the task and where you left off?

The agent re-reads the repo, asks you to restate the goal, and rediscovers work it already finished.

With planning-with-files

===BEGIN PLAN DATA===
# Task Plan: auth middleware refactor
### Phase 2: Patch token expiry check
- [x] Reproduce the bug
- [x] Fix expiry comparison
- **Status:** complete
### Phase 3: Regression tests
- [ ] Add expiry edge-case tests
- **Status:** in_progress
===END PLAN DATA===

agent: Resuming Phase 3: adding the expiry edge-case tests.

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

┌──────────────────────────────────────────────┐
│  PLAN FILES                               3  │
│  AGENTS COVERED                         60+  │
│  PASS RATE (with skill)               96.7%  │
│  TEST SUITE                       301 green  │
│  SURVIVES /clear                        yes  │
└──────────────────────────────────────────────┘

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.

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
findings.md
progress.md"]
    F -->|"hooks re-inject the plan
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
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/.

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

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.

🇸🇦 العربية / 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

Copy the skill to your local folder:

macOS/Linux:

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

Windows (PowerShell):

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.

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:@tomxprime/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

The model-invocable SKILLS are named planning-with-files:planning-with-files (and -ar, -de, -es, -zh, -zht); the doubled form is the skill id, not a command you type. 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:

Note: If your IDE uses the legacy Rules system instead of Skills, see the legacy-rules-support branch.

BoxLite is a sandbox runtime, not an IDE. Skills load via ClaudeBox, BoxLite's official Claude Code integration layer.

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

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.

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
│   └── ...-ar / -de / -es / -zh / -zht    # 5 translated variants
├── .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/                        # 217-test suite (pytest), green on Windows and Linux CI
├── CHANGELOG.md · MIGRATION.md · SECURITY.md · CONTRIBUTING.md · CONTRIBUTORS.md
├── CITATION.cff · llms.txt · LICENSE
└── README.md

Every release bumps 18 parity-locked copies via scripts/bump-version.py; a test fails if any variant lags.

FAQ

How do I stop my coding agent from losing its plan after /clear or a crash?

The plan lives on disk in task_plan.md, findings.md, and progress.md, not only in the context window. At the start of each turn the UserPromptSubmit hook re-injects the active plan, and after a /clear or a new session the skill re-reads the files from disk (session recovery), so the agent recovers its goals and progress automatically.

What is the difference between planning-with-files and an agent memory tool?

Agent memory tools (vector stores, knowledge graphs) help an agent recall facts from past sessions. planning-with-files manages active execution state: the phases, status, dependencies, and completion check for the task the agent is working on right now. The problem it solves is planning continuity, not retrieval, and the two are complementary.

How does this prevent context rot?

Context rot is the drift that sets in as the context window fills and earlier instructions get crowded out. Because the plan is re-injected at the start of each turn from disk, the goals and phase status stay in the model's attention window as the conversation grows. This is an implementation of what Anthropic calls structured note-taking: write durable state to files outside the window, then read it back in when needed.

Which coding agents does this work with?

Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, CodeBuddy, Factory, Mastra, and 70+ others via the SKILL.md open standard (the npx skills installer alone targets 71 agents). Since v3.7.0 the repo also ships the cross-tool .agents/skills/planning-with-files/ layout in-tree, so tools that read the Agent Skills standard path natively (Zed, Amp, Warp, Devin, Antigravity, Gemini CLI, Cursor) discover the current skill from a plain git clone with no per-tool setup. Installation is one command; see Quick Install above.

How does this work with Claude Code's plan mode?

They are complementary stages, not alternatives. Plan mode is where you design and approve the approach before execution. planning-with-files persists the live execution state (phase status, findings, errors, progress) on disk while the work runs and re-injects it every turn. The handoff is one step: after accepting a plan-mode plan, tell the agent to write it into task_plan.md as phases (or invoke /plan and let the skill create the files from it), then execute in normal mode. From that point the hooks keep the phases in the attention window, and the files survive /clear, compaction, and session death.

What happens to the plan files after a task is complete?

They are working memory, not a tracked deliverable. task_plan.md, findings.md, progress.md, and the .planning/ directory are gitignored by default and are not archived automatically: the next task overwrites the root plan, and a slug directory just stops being active. Anything worth keeping should be promoted into code, a commit, or a doc. See After Completion: What Happens to the Plan Files for the full lifecycle and how to retain a completed plan. This is a deliberate default, not a missing feature; a completion-triggered archive step is a welcome opt-in extension.

How fast are the hooks?

One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from 2.0 to 2.4 seconds before it, and the injected plan block is KV-cache stable by construction. The plan stays in the attention window every turn, and /clear stops being fatal.

View all releases · CHANGELOG

Parallel plan isolation (.planning/YYYY-MM-DD-slug/ directories) and Codex session isolation shipped in v2.36.0. The experimental/isolated-planning branch was the earlier prototype; master is now the canonical location.

Forks & Extensions

Used in the Wild

Skill Registries & Hubs

Built something? Open an issue to get listed!

Full list of everyone who made this project better: CONTRIBUTORS.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

<a href="https://repostars.dev/?repos=OthmanAdi%2Fplanning-with-files&theme=copper"></a>