Work like Manus — the AI agent company Meta acquired for $2 billion.
💬 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.
🌍 See What the Community Built
| Fork | Author | Features |
|---|---|---|
| devis | @st01cs | Interview-first workflow, /devis:intv and /devis:impl commands, guaranteed activation |
| multi-manus-planning | @kmichels | Multi-project support, SessionStart git sync |
| plan-cascade | @Taoidle | Multi-level task orchestration, parallel execution, multi-agent collaboration |
| agentfund-skill | @RioTheGreat-ai | Crowdfunding for AI agents with milestone-based escrow on Base |
| openclaw-github-repo-commander | @wd041216-bit | 7-stage GitHub repo audit, optimization, and cleanup workflow for OpenClaw |
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
| Version | Highlights |
|---|---|
| v2.30.0 | Migrate to ${CLAUDE_SKILL_DIR}, IDE configs moved to dedicated branches, cleaner master |
| v2.29.0 | Analytics workflow template: --template analytics flag for data exploration sessions (thanks @mvanhorn!) |
| v2.28.0 | Traditional Chinese (zh-TW) skill variant (thanks @waynelee2048!) |
| v2.26.2 | Fix: --- in hook commands broke YAML frontmatter parsing, hooks now register correctly |
| v2.26.1 | Fix: session catchup after /clear, path sanitization on Windows + content injection (thanks @tony-stark-eth!) |
| v2.26.0 | IDE audit: Factory hooks, Copilot errorOccurred hook, Gemini hooks, bug fixes |
| v2.18.2 | Mastra Code hooks fix (hooks.json + docs accuracy) |
| v2.18.1 | Copilot garbled characters complete fix |
| v2.18.0 | BoxLite sandbox runtime integration |
| v2.17.0 | Mastra Code support + all IDE SKILL.md spec fixes |
| v2.16.1 | Copilot garbled characters fix: PS1 UTF-8 encoding + bash ensure_ascii (thanks @Hexiaopi!) |
| v2.16.0 | GitHub Copilot hooks support (thanks @lincolnwan!) |
| v2.27.0 | Kiro Agent Skill layout (thanks @EListenX!) |
| v2.15.1 | Session catchup false-positive fix (thanks @gydx6!) |
| v2.15.0 | /plan:status command, OpenCode compatibility fix |
| v2.14.0 | Pi Agent support, OpenClaw docs update, Codex path fix |
| v2.11.0 | /plan command for easier autocomplete |
| v2.10.0 | Kiro steering files support |
| v2.7.0 | Gemini CLI support |
| v2.2.0 | Session recovery, Windows PowerShell, OS-aware hooks |
🧪 Experimental: Isolated parallel planning (
.planning/{uuid}/folders) is being tested onexperimental/isolated-planning. Try it and share feedback!
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
~/.claude/projects/ - 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 Platforms (16+)
The core skill works with any IDE supporting the Agent Skills open spec:
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -gThis covers Claude Code, Cursor, Codex, Gemini CLI, OpenClaw, Antigravity, Kilocode, AdaL CLI, and 40+ other agents.
For IDEs with lifecycle hooks (pre-tool, post-tool, stop verification), each IDE has its own branch with adapted SKILL.md and hook scripts:
| IDE | Branch | Guide | Integration |
|---|---|---|---|
| Claude Code | master (built-in) |
Installation | Plugin + SKILL.md + Hooks |
| Cursor | ide/cursor |
Setup | Skills + hooks.json |
| GitHub Copilot | ide/copilot |
Setup | Hooks |
| Gemini CLI | ide/gemini |
Setup | Skills + Hooks |
| Kiro | ide/kiro |
Setup | Agent Skills |
| Codex | ide/codex |
Setup | Skills + Hooks |
| Mastra Code | ide/mastra |
Setup | Skills + Hooks |
| CodeBuddy | ide/codebuddy |
Setup | Skills + Hooks |
| FactoryAI Droid | ide/factory |
Setup | Skills + Hooks |
| OpenCode | ide/opencode |
Setup | Skills + Custom session storage |
| Continue | ide/continue |
Setup | Skills + .prompt files |
| Pi Agent | ide/pi-agent |
Setup | Skills (npm) |
These IDEs work with npx skills add out of the box, no IDE-specific branch required:
OpenClaw | Antigravity | Kilocode | AdaL CLI
Note: If your IDE uses the legacy Rules system instead of Skills, see the
legacy-rules-supportbranch.
🧱 Sandbox Runtimes (1 Platform)
| Runtime | Status | Guide | Notes |
|---|---|---|---|
| BoxLite | Documented | BoxLite Setup | Run Claude Code + planning-with-files inside hardware-isolated micro-VMs |
Note: BoxLite is a sandbox runtime, not an IDE. Skills load via ClaudeBox -- BoxLite’s official Claude Code integration layer.
🌿 Branches
| Branch | Purpose |
|---|---|
master |
Core skill, templates, scripts, docs |
ide/cursor |
Cursor IDE hooks and SKILL.md |
ide/copilot |
GitHub Copilot hooks |
ide/gemini |
Gemini CLI hooks and SKILL.md |
ide/kiro |
Kiro Agent Skill layout |
ide/codex |
Codex CLI hooks and SKILL.md |
ide/mastra |
Mastra Code hooks and SKILL.md |
ide/codebuddy |
CodeBuddy hooks and SKILL.md |
ide/factory |
FactoryAI Droid hooks and SKILL.md |
ide/opencode |
OpenCode hooks and SKILL.md |
ide/continue |
Continue.dev skill and prompts |
ide/pi-agent |
Pi Agent skill |
feat/analytics-subagent |
Analytics subagent (closes #103) |
experimental/isolated-planning |
Parallel planning sessions |
legacy-rules-support |
IDE Rules system (pre-Skills) |
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中文版 / 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, 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:
| Command | Autocomplete | Description |
|---|---|---|
/planning-with-files:plan |
Type /plan |
Start planning session (v2.11.0+) |
/planning-with-files:status |
Type /plan:status |
Show planning progress at a glance (v2.15.0+) |
/planning-with-files:start |
Type /planning |
Original start command |
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.
| 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 |
Once installed, the AI agent will:
- Ask for your task if no description is provided
- Create
task_plan.md,findings.md, andprogress.mdin your project directory - 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)
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.
Formally evaluated using Anthropic's skill-creator framework (v2.22.0). 10 parallel subagents, 5 task types, 30 objectively verifiable assertions, 3 blind A/B comparisons.
| Test | with_skill | without_skill |
|---|---|---|
| Pass rate (30 assertions) | 96.7% (29/30) | 6.7% (2/30) |
| 3-file pattern followed | 5/5 evals | 0/5 evals |
| Blind A/B wins | 3/3 (100%) | 0/3 |
| Avg rubric score | 10.0/10 | 6.8/10 |
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/ (master branch)
├── skills/
│ ├── planning-with-files/ # Core skill
│ │ ├── SKILL.md
│ │ ├── examples.md
│ │ ├── reference.md
│ │ ├── templates/
│ │ └── scripts/
│ ├── planning-with-files-zh/ # Chinese (Simplified)
│ └── planning-with-files-zht/ # Chinese (Traditional)
├── commands/ # Plugin commands (/plan, /start)
├── templates/ # Root-level templates
├── scripts/ # Root-level scripts
├── docs/ # All platform setup guides
├── examples/ # Integration examples
├── tests/ # Test suite
├── .claude-plugin/ # Plugin manifest
├── CHANGELOG.md
├── CONTRIBUTORS.md
├── LICENSE
└── README.md
IDE-specific configs live on dedicated branches (ide/cursor, ide/copilot, etc.)
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
