OthmanAdi/planning-with-files

Persistent file-based planning for AI coding agents and long-running agentic tasks. Crash-proof markdown plans that survive context loss and /clear, plus a deterministic completion gate and multi-agent shared state on disk. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard.

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.

raw.githubusercontent.com/OthmanAdi/planning-with-files/master/docs/evals.md raw.githubusercontent.com/OthmanAdi/planning-with-files/master/docs/evals.md getskillcheck.com raw.githubusercontent.com/OthmanAdi/planning-with-files/master/docs/evals.mdskillsplayground.com/skills/othmanadi-planning-with-files-planning-with-files skill-history.com/othmanadi/planning-with-files github.com/OthmanAdi/planning-with-files/releases opensource.org/licenses/MIT github.com/OthmanAdi/planning-with-files/issues github.com/OthmanAdi/planning-with-files/pulls

💬 A Note from the Author

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.

🌍 What the community shipped

Forks & Extensions

Used in the Wild

Skill Registries & Hubs

Built something? Open an issue to get listed!

🤝 Contributors

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

📦 Releases & Session Recovery

Current Version: v3.2.0

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:

🛠️ Supported IDEs (18+ Platforms)

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.

🧱 Sandbox Runtimes (1 Platform)

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.

code.claude.com/docs/en/plugins code.claude.com/docs/en/skills docs.cursor.com/context/skills kilo.ai/docs/agent-behavior/skills geminicli.com/docs/cli/skills openclaw.ai kiro.dev/docs/skills docs.sylph.ai/features/plugins-and-skills pi.dev docs.github.com/en/copilot/reference/hooks-configuration code.mastra.ai raw.githubusercontent.com/OthmanAdi/planning-with-files/master/docs/hermes.md boxlite.ai

Quick Install

🌐 Available in 5 other languages

🇸🇦 العربية / Arabic

🇩🇪 Deutsch / German

🇪🇸 Español / Spanish

🇨🇳 中文版 / Chinese (Simplified)

🇹🇼 正體中文版 / Chinese (Traditional)

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

🔧 Claude Code Plugin (Advanced Features)

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

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:

Windows (PowerShell):

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:

The Core Principle

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

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

repostars.dev