This reverts commit 0b9e4aee89.
Planning with Files
Work like Manus — the AI agent company Meta acquired for $2 billion.
Thank You
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.
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
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
See docs/installation.md for all installation methods.
Documentation
| Document | Description |
|---|---|
| Installation Guide | All installation methods (plugin, manual, Cursor, Windows) |
| Quick Start | 5-step guide to using the pattern |
| Workflow Diagram | Visual diagram of how files and hooks interact |
| Troubleshooting | Common issues and solutions |
| Cursor Setup | Cursor IDE-specific instructions |
| Windows Setup | Windows-specific notes |
Versions
| Version | Features | Install |
|---|---|---|
| v2.1.0 (current) | Claude Code v2.1 compatible, SessionStart hook, PostToolUse hook, user-invocable | /plugin install planning-with-files@planning-with-files |
| v2.0.x | Hooks, templates, scripts | See releases |
| v1.0.0 (legacy) | Core 3-file pattern | git clone -b legacy |
See CHANGELOG.md for details.
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.
Usage
Once installed, Claude will automatically:
- Create
task_plan.mdbefore starting complex tasks - Re-read plan before major decisions (via PreToolUse hook)
- Remind you to update status after file writes (via PostToolUse hook)
- Store findings in
findings.mdinstead of stuffing context - Log errors for future reference
- Verify completion before stopping (via Stop hook)
Or invoke manually with /planning-with-files.
See docs/quickstart.md for the full 5-step guide.
Key Rules
- 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
File Structure
planning-with-files/
├── docs/ # Documentation
│ ├── installation.md
│ ├── quickstart.md
│ ├── workflow.md
│ ├── troubleshooting.md
│ ├── cursor.md
│ └── windows.md
├── skills/
│ └── planning-with-files/
│ ├── SKILL.md # Main skill definition
│ ├── templates/ # File templates
│ └── scripts/ # Helper scripts
├── .claude-plugin/ # Plugin manifest
├── .cursor/ # Cursor rules
├── CHANGELOG.md
├── MIGRATION.md
├── LICENSE
└── README.md
The Manus Principles
| Principle | Implementation |
|---|---|
| Filesystem as memory | Store in files, not context |
| Attention manipulation | Re-read plan before decisions (hooks) |
| Error persistence | Log failures in plan file |
| Goal tracking | Checkboxes show progress |
| Completion verification | Stop hook checks all phases |
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
Community Forks
| Fork | Author | Features |
|---|---|---|
| multi-manus-planning | @kmichels | Multi-project support, SessionStart git sync |
Built something? Open an issue to get listed!
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:
- Fork the repository
- Create a feature branch
- Submit a pull request
License
MIT License — feel free to use, modify, and distribute.
Author: Ahmad Othman Ammar Adi