Raw capture — raw/planning-with-files.md

url: https://github.com/OthmanAdi/planning-with-files date_fetched: 2026-07-05 backfilled: true

📣

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-filesis a persistent file-based planning skill forAI coding agents. It keepstask_plan.md,findings.md, andprogress.mdon disk so the agent survivescontext 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.

💬 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

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

Parallel plan isolation (

.planning/YYYY-MM-DD-slug/directories) and Codex session isolation shipped in v2.36.0. Theexperimental/isolated-planningbranch was the earlier prototype; master is now the canonical location.

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

How it works:

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

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

{ "autoCompact": false }🛠️ Supported IDEs (18+ Platforms)

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:

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 thelegacy-rules-supportbranch.

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

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g🌐 Available in 5 other languages

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

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

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

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

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

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.

Once installed, the AI agent will:

• Ask for your taskif no description is provided
• Createin your project directory- task_plan.md,- findings.md, and- progress.md
• Re-read planbefore 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)
• Remind youto update status after file writes (via PostToolUse hook)
• Store findingsin- findings.mdinstead of stuffing context
• Log errorsfor future reference
• Verify completionbefore stopping (via Stop hook)

Invoke with:

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

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

Methodology note:the 96.7% figure comes from the v2.21.0 evaluation run onclaude-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

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

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

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

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.

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.

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.

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.

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

• 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

Contributions welcome! Please:

• Fork the repository
• Create a feature branch
• Submit a pull request

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

Author: Ahmad Othman Ammar Adi