Planning with Files

📣 New in v3.0.0: opt-in autonomous and gated modes for long-running agent runs, with a completion gate that holds the agent until the plan is actually done. Existing setups change nothing.

Work like Manus — the AI agent company Meta acquired for $2 billion.

planning-with-files is a persistent file-based planning skill for AI coding agents. It keeps task_plan.md, findings.md, and progress.md on disk so the agent survives context loss, /clear, and crashes, with an opt-in completion gate that holds the agent until the plan is actually done. It installs across 60+ agents via the SKILL.md standard.

To everyone who starred, forked, and shared this skill — thank you. This project blew up in less than 24 hours, and the support from the community has been incredible.

If this skill helps you work smarter, that's all I wanted.

Forks & Extensions

Used in the Wild

Skill Registries & Hubs

Built something? Open an issue to get listed!

See the full list of everyone who made this project better in CONTRIBUTORS.md.

Current Version: v3.1.1

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.

Session Recovery

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

How it works:

1. Checks for previous session data in the active IDE's session store (~/.claude/projects/ for Claude Code, ~/.codex/sessions/ for Codex)
2. Finds when planning files were last updated
3. Extracts 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 }

Enhanced Support (hooks + lifecycle automation)

These IDEs have dedicated hook configurations that automatically re-read your plan before tool use, remind you to update progress, and verify completion before stopping:

Standard Agent Skills Support

These IDEs implement the Agent Skills open specification. Install with npx skills add — the installer places the skill in each IDE's discovery path automatically:

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

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

A Claude Code plugin that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage — the exact pattern that made Manus worth billions.

Quick Install

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

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

Works with Claude Code, Cursor, Codex, Gemini CLI, and 40+ agents supporting the Agent Skills spec.

For Claude Code-specific features like /plan autocomplete commands:

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

That's it! Now use one of these commands in Claude Code:

Alternative: If you want /planning-with-files (without prefix), copy skills 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\"

See docs/installation.md for all installation methods.

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

The Problem

Claude Code (and most AI agents) suffer from:

• Volatile memory — TodoWrite tool disappears on context reset
• Goal drift — After 50+ tool calls, original goals get forgotten
• Hidden errors — Failures aren't tracked, so the same mistakes repeat
• Context stuffing — Everything crammed into context 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.

The Manus Principles

Usage

Once installed, the AI agent will:

1. Ask for your task if no description is provided
2. Create task_plan.md, findings.md, and progress.md in your project directory
3. Re-read plan before major decisions (via PreToolUse hook in legacy mode; autonomous mode injects at session start and phase transitions instead, dropping the per-tool-call tax on strong models)
4. Remind you to update status after file writes (via PostToolUse hook)
5. Store findings in findings.md instead of stuffing context
6. Log errors for future reference
7. Verify completion before stopping (via Stop hook)

Invoke with:

• /planning-with-files:plan - Type /plan to find in autocomplete (v2.11.0+)
• /planning-with-files:start - Type /planning to find in autocomplete
• /planning-with-files - Only if you copied skills to ~/.claude/skills/

See docs/quickstart.md for the full 5-step guide.

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.

Formally evaluated using Anthropic's skill-creator framework (v2.22.0), model claude-sonnet-4-6, 2026-03-06. 10 parallel subagents, 5 task types, 30 objectively verifiable assertions, 3 blind A/B comparisons.

Full methodology and results · Technical write-up

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

Skip for:

• Simple questions
• Single-file edits
• Quick lookups

File Structure

planning-with-files/
├── commands/                # Plugin commands
│   ├── plan.md              # /planning-with-files:plan command (v2.11.0+)
│   ├── plan-ar.md           # Arabic /plan command (v2.33.0+)
│   ├── plan-de.md           # German /plan command (v2.33.0+)
│   ├── plan-es.md           # Spanish /plan command (v2.33.0+)
│   └── start.md             # /planning-with-files:start command
├── templates/               # Root-level templates (for CLAUDE_PLUGIN_ROOT)
├── scripts/                 # Root-level scripts (for CLAUDE_PLUGIN_ROOT)
├── docs/                    # Documentation
│   ├── installation.md
│   ├── quickstart.md
│   ├── workflow.md
│   ├── troubleshooting.md
│   ├── gemini.md            # Gemini CLI setup
│   ├── cursor.md
│   ├── windows.md
│   ├── kilocode.md
│   ├── codex.md
│   ├── opencode.md
│   ├── mastra.md             # Mastra Code setup
│   └── boxlite.md            # BoxLite sandbox setup
├── examples/                # Integration examples
│   └── boxlite/             # BoxLite quickstart
│       ├── README.md
│       └── quickstart.py
├── planning-with-files/     # Plugin skill folder
│   ├── SKILL.md
│   ├── templates/
│   └── scripts/
├── skills/                  # Skill variants
│   ├── planning-with-files/     # English (default)
│   │   ├── SKILL.md
│   │   ├── examples.md
│   │   ├── reference.md
│   │   ├── templates/
│   │   └── scripts/
│   │       ├── init-session.sh
│   │       ├── check-complete.sh
│   │       ├── init-session.ps1   # Windows PowerShell
│   │       └── check-complete.ps1 # Windows PowerShell
│   ├── planning-with-files-ar/   # Arabic (v2.33.0+)
│   │   ├── SKILL.md
│   │   ├── templates/
│   │   └── scripts/
│   ├── planning-with-files-de/   # German (v2.33.0+)
│   │   ├── SKILL.md
│   │   ├── templates/
│   │   └── scripts/
│   ├── planning-with-files-es/   # Spanish (v2.33.0+)
│   │   ├── SKILL.md
│   │   ├── templates/
│   │   └── scripts/
│   ├── planning-with-files-zh/   # Chinese Simplified (v2.25.0+)
│   └── planning-with-files-zht/  # Chinese Traditional (v2.28.0+)
├── .gemini/                 # Gemini CLI skills + hooks
│   ├── settings.json        # Hook configuration (v2.26.0)
│   ├── hooks/               # Hook scripts (SessionStart, BeforeTool, AfterTool, BeforeModel, SessionEnd)
│   └── skills/
│       └── planning-with-files/
├── .codex/                  # Codex CLI skills + hooks
│   └── skills/
├── .opencode/               # OpenCode skills (custom session storage)
│   └── skills/
├── .claude-plugin/          # Plugin manifest
├── .cursor/                 # Cursor skills + hooks
│   ├── hooks.json           # Hook configuration
│   ├── hooks/               # Hook scripts (bash + PowerShell)
│   └── skills/
├── .codebuddy/              # CodeBuddy skills + hooks
│   └── skills/
├── .factory/                # FactoryAI Droid skills + hooks (v2.26.0)
│   └── skills/
├── .pi/                     # Pi Agent skills (npm package)
│   └── skills/
│       └── planning-with-files/
├── .continue/               # Continue.dev skills + prompt files
│   ├── prompts/             # .prompt file for slash commands
│   └── skills/
├── .github/                 # GitHub Copilot hooks (incl. errorOccurred)
│   └── hooks/
│       ├── planning-with-files.json  # Hook configuration
│       └── scripts/         # Hook scripts (bash + PowerShell)
├── .mastracode/             # Mastra Code skills + hooks
│   └── skills/
├── .kiro/                   # Kiro Agent Skills (v2.27.0+)
│   └── skills/
├── CHANGELOG.md
├── CITATION.cff
├── LICENSE
└── README.md

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 60+ others via the SKILL.md open standard. Installation is one command; see Quick Install above.

Documentation

All platform setup guides and documentation are in the docs/ folder.

Acknowledgments

• Manus AI — For pioneering context engineering patterns
• 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

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

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>