[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-2451":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":46,"readmeContent":47,"aiSummary":48,"trendingCount":16,"starSnapshotCount":16,"syncStatus":49,"lastSyncTime":50,"discoverSource":51},2451,"planning-with-files","OthmanAdi\u002Fplanning-with-files","OthmanAdi","Persistent file-based planning for long-running agentic tasks. Crash-proof markdown plans, deterministic completion gate, multi-agent shared state on disk. Works with Claude Code, Codex CLI, Cursor, Hermes agent, Pi, Kiro, OpenCode and 60+ agents via the SKILL.md standard.","",null,"Python",23044,2032,104,11,0,42,353,2111,230,44.92,"MIT License",false,"master",true,[27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45],"adal","agent-skills","antigravity","claude","claude-code","claude-skills","copilot","copilot-skills","hermes","hermes-agent","hermes-skill","kilocode","manus","mastra","openclaw","openclaw-skills","pi","pi-agent","planning","2026-06-12 02:00:41","\u003Cdiv align=\"center\">\n\u003Cimg src=\"media\u002Fbanner.png\" alt=\"planning-with-files\" width=\"100%\">\n\u003C\u002Fdiv>\n\n# Planning with Files\n\n> **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.\n\n[![Benchmark](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBenchmark-96.7%25_pass_rate-brightgreen)](docs\u002Fevals.md)\n[![A\u002FB Verified](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FA%2FB_Blind-3%2F3_wins-brightgreen)](docs\u002Fevals.md)\n[![SkillCheck Validated](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSkillCheck-Validated-4c1)](https:\u002F\u002Fgetskillcheck.com)\n[![Security Verified](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSecurity-Audited_%26_Fixed_v2.21.0-blue)](docs\u002Fevals.md)\n\n[![Skills Playground](https:\u002F\u002Fskillsplayground.com\u002Fbadges\u002Finstalls\u002Fothmanadi-planning-with-files-planning-with-files.svg)](https:\u002F\u002Fskillsplayground.com\u002Fskills\u002Fothmanadi-planning-with-files-planning-with-files\u002F)\n[![Downloads](https:\u002F\u002Fskill-history.com\u002Fbadge\u002Fothmanadi\u002Fplanning-with-files.svg)](https:\u002F\u002Fskill-history.com\u002Fothmanadi\u002Fplanning-with-files)\n[![Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fversion-2.37.0-brightgreen)](https:\u002F\u002Fgithub.com\u002FOthmanAdi\u002Fplanning-with-files\u002Freleases)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![Closed Issues](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fissues-closed\u002FOthmanAdi\u002Fplanning-with-files?color=success)](https:\u002F\u002Fgithub.com\u002FOthmanAdi\u002Fplanning-with-files\u002Fissues?q=is%3Aissue+is%3Aclosed)\n[![Closed PRs](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fissues-pr-closed\u002FOthmanAdi\u002Fplanning-with-files?color=success)](https:\u002F\u002Fgithub.com\u002FOthmanAdi\u002Fplanning-with-files\u002Fpulls?q=is%3Apr+is%3Aclosed)\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>💬 A Note from the Author\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nTo 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.\n\nIf this skill helps you work smarter, that's all I wanted.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🌍 What the community shipped\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n### Forks & Extensions\n\n| Fork | Author | What They Built |\n|------|--------|-----------------|\n| [devis](https:\u002F\u002Fgithub.com\u002Fst01cs\u002Fdevis) | [@st01cs](https:\u002F\u002Fgithub.com\u002Fst01cs) | Interview-first workflow, `\u002Fdevis:intv` and `\u002Fdevis:impl` commands, guaranteed activation |\n| [multi-manus-planning](https:\u002F\u002Fgithub.com\u002Fkmichels\u002Fmulti-manus-planning) | [@kmichels](https:\u002F\u002Fgithub.com\u002Fkmichels) | Multi-project support, SessionStart git sync |\n| [plan-cascade](https:\u002F\u002Fgithub.com\u002FTaoidle\u002Fplan-cascade) | [@Taoidle](https:\u002F\u002Fgithub.com\u002FTaoidle) | Multi-level task orchestration, parallel execution, multi-agent collaboration |\n| [agentfund-skill](https:\u002F\u002Fgithub.com\u002FRioTheGreat-ai\u002Fagentfund-skill) | [@RioTheGreat-ai](https:\u002F\u002Fgithub.com\u002FRioTheGreat-ai) | Crowdfunding for AI agents with milestone-based escrow on Base |\n| [openclaw-github-repo-commander](https:\u002F\u002Fgithub.com\u002Fwd041216-bit\u002Fopenclaw-github-repo-commander) | [@wd041216-bit](https:\u002F\u002Fgithub.com\u002Fwd041216-bit) | 7-stage GitHub repo audit, optimization, and cleanup workflow for OpenClaw |\n\n### Used in the Wild\n\n| Project | What It Is |\n|---------|-----------|\n| [lincolnwan\u002FPlanning-with-files-copilot-agent](https:\u002F\u002Fgithub.com\u002Flincolnwan\u002FPlanning-with-files-copilot-agent) | Entire Copilot agent repo built around the planning-with-files skill |\n| [cooragent\u002FClarityFinance](https:\u002F\u002Fgithub.com\u002Fcooragent\u002FClarityFinance) | AI finance agent framework — Planning-with-Files approach directly credited |\n| [oeftimie\u002Fvv-claude-harness](https:\u002F\u002Fgithub.com\u002Foeftimie\u002Fvv-claude-harness) | Claude Code harness built on Manus-style persistent markdown planning |\n| [jessepwj\u002FCCteam-creator](https:\u002F\u002Fgithub.com\u002Fjessepwj\u002FCCteam-creator) | Multi-agent team orchestration skill using file-based planning |\n\n*Built something? [Open an issue](https:\u002F\u002Fgithub.com\u002FOthmanAdi\u002Fplanning-with-files\u002Fissues) to get listed!*\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🤝 Contributors\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nSee the full list of everyone who made this project better in [CONTRIBUTORS.md](.\u002FCONTRIBUTORS.md).\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📦 Releases & Session Recovery\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n### Current Version: v2.37.0\n\n| Version | Highlights |\n|---------|------------|\n| **v2.37.0** | **Hash attestation + parity bumper** (closes #150, #151): `\u002Fplan-attest` locks `task_plan.md` with a SHA-256; hooks block injection on tamper. `scripts\u002Fbump-version.py` + parity test kill the \"missed one variant\" regression class behind v2.34.1, v2.36.0, v2.36.2, and v2.36.3. (thanks @oaabahussain!) |\n| **v2.36.3** | **Parallel planning scripts now ship in the skill**: `resolve-plan-dir.sh` and `set-active-plan.sh` were missing from the installed skill in v2.36.0; now in canonical + all IDE mirrors + SKILL.md docs updated |\n| **v2.36.2** | **Canonical script sync** (PR #149): `skills\u002Fplanning-with-files\u002Fscripts\u002Finit-session.sh` was missing slug mode from v2.36.0; now synced with IDE mirrors + regression test. (thanks @voidborne-d!) |\n| **v2.36.1** | **Security hardening**: Stop hook cache search removed, ExecutionPolicy Bypass changed to RemoteSigned, prompt injection delimiters added. (Gen Agent Trust Hub FAIL resolved) |\n| **v2.36.0** | **Parallel plan isolation + Codex session isolation** (closes #146, #148): `init-session.sh` slug mode, `set-active-plan.sh`, `resolve-plan-dir.sh`, all Codex hooks route through resolver, session attachment gating. **Hermes docs** (closes #147): integration notes added to `docs\u002Fhermes.md`. 34 new tests. (thanks @githubYiheng, @09ashishkapoor, @shawnli1874!) |\n| **v2.35.1** | **Shebang portability fix**: changed `\u002Fbin\u002Fbash` to `\u002Fusr\u002Fbin\u002Fenv bash` in hook scripts, fixing compatibility on NixOS and other systems where bash is not at `\u002Fbin\u002Fbash`. (thanks @Emin017!) |\n| **v2.35.0** | **Hermes adapter + NLPM audit hardening**: Hermes platform 17 support (thanks @bailob!), NLPM audit fixed Python PATH resolution, session-catchup injection cap, Pi PowerShell syntax (thanks @xiaolai!) |\n| **v2.34.1** | **Stop hook Windows portability fix** (closes #133): `export SD=` failed in Windows Git Bash hook context; fallback path was wrong for plugin cache structure. Fixed across all 13 SKILL.md variants. (thanks @nazeshinjite!) |\n| **v2.34.0** | **Codex hooks fully restored** (closes #132): `.codex\u002Fhooks.json` + lifecycle scripts back — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop. Tessl CI for SKILL.md quality reviews. Exec bit fix. 4 missing contributors added. (thanks @Leon-Algo, @popey!) |\n| **v2.33.0** | **Multi-language expansion**: Arabic, German, and Spanish skill variants added (thanks to community contributors!) |\n| **v2.32.0** | Codex session catchup rewrite (thanks @ebrevdo!), Loaditout A-grade security badge, Stop hook Git Bash fix |\n| **v2.31.0** | Codex hooks.json integration with full lifecycle hooks (thanks @Leon-Algo!) |\n| **v2.30.1** | Fix: Codex script executable bits restored (thanks @Leon-Algo!) |\n| **v2.30.0** | `CLAUDE_SKILL_DIR` variable, IDE configs moved to per-IDE branches, plugin.json bumped from 2.23.0 |\n| **v2.29.0** | Analytics workflow template: `--template analytics` flag for data exploration sessions (thanks @mvanhorn!) |\n| **v2.28.0** | Traditional Chinese (zh-TW) skill variant (thanks @waynelee2048!) |\n| **v2.26.2** | Fix: `---` in hook commands broke YAML frontmatter parsing, hooks now register correctly |\n| **v2.26.1** | Fix: session catchup after `\u002Fclear`, path sanitization on Windows + content injection (thanks @tony-stark-eth!) |\n| **v2.26.0** | IDE audit: Factory hooks, Copilot errorOccurred hook, Gemini hooks, bug fixes |\n| **v2.18.2** | Mastra Code hooks fix (hooks.json + docs accuracy) |\n| **v2.18.1** | Copilot garbled characters complete fix |\n| **v2.18.0** | BoxLite sandbox runtime integration |\n| **v2.17.0** | Mastra Code support + all IDE SKILL.md spec fixes |\n| **v2.16.1** | Copilot garbled characters fix: PS1 UTF-8 encoding + bash ensure_ascii (thanks @Hexiaopi!) |\n| **v2.16.0** | GitHub Copilot hooks support (thanks @lincolnwan!) |\n| **v2.27.0** | Kiro Agent Skill layout (thanks @EListenX!) |\n| **v2.15.1** | Session catchup false-positive fix (thanks @gydx6!) |\n| **v2.15.0** | `\u002Fplan:status` command, OpenCode compatibility fix |\n| **v2.14.0** | Pi Agent support, OpenClaw docs update, Codex path fix |\n| **v2.11.0** | `\u002Fplan` command for easier autocomplete |\n| **v2.10.0** | Kiro steering files support |\n| **v2.7.0** | Gemini CLI support |\n| **v2.2.0** | Session recovery, Windows PowerShell, OS-aware hooks |\n\n[View all releases](https:\u002F\u002Fgithub.com\u002FOthmanAdi\u002Fplanning-with-files\u002Freleases) · [CHANGELOG](CHANGELOG.md)\n\n> Parallel plan isolation (`.planning\u002FYYYY-MM-DD-slug\u002F` directories) and Codex session isolation shipped in v2.36.0. The `experimental\u002Fisolated-planning` branch was the earlier prototype; master is now the canonical location.\n\n---\n\n### Session Recovery\n\nWhen your context fills up and you run `\u002Fclear`, this skill **automatically recovers** your previous session.\n\n**How it works:**\n1. Checks for previous session data in the active IDE's session store (`~\u002F.claude\u002Fprojects\u002F` for Claude Code, `~\u002F.codex\u002Fsessions\u002F` for Codex)\n2. Finds when planning files were last updated\n3. Extracts conversation that happened after (potentially lost context)\n4. Shows a catchup report so you can sync\n\n**Pro tip:** Disable auto-compact to maximize context before clearing:\n```json\n{ \"autoCompact\": false }\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🛠️ Supported IDEs (17+ Platforms)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n#### Enhanced Support (hooks + lifecycle automation)\n\nThese IDEs have dedicated hook configurations that automatically re-read your plan before tool use, remind you to update progress, and verify completion before stopping:\n\n| IDE | Installation Guide | Integration |\n|-----|-------------------|-------------|\n| Claude Code | [Installation](docs\u002Finstallation.md) | Plugin + SKILL.md + Hooks |\n| Cursor | [Cursor Setup](docs\u002Fcursor.md) | Skills + [hooks.json](https:\u002F\u002Fcursor.com\u002Fdocs\u002Fhooks) |\n| GitHub Copilot | [Copilot Setup](docs\u002Fcopilot.md) | [Hooks](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Freference\u002Fhooks-configuration) (incl. errorOccurred) |\n| Mastra Code | [Mastra Setup](docs\u002Fmastra.md) | Skills + [Hooks](https:\u002F\u002Fmastra.ai\u002Fdocs\u002Fmastra-code\u002Fconfiguration) |\n| Gemini CLI | [Gemini Setup](docs\u002Fgemini.md) | Skills + [Hooks](https:\u002F\u002Fgeminicli.com\u002Fdocs\u002Fhooks\u002F) |\n| Kiro | [Kiro Setup](docs\u002Fkiro.md) | [Agent Skills](https:\u002F\u002Fkiro.dev\u002Fdocs\u002Fskills\u002F) |\n| Codex | [Codex Setup](docs\u002Fcodex.md) | [Skills + Hooks](https:\u002F\u002Fdevelopers.openai.com\u002Fcodex\u002Fskills) |\n| Hermes Agent | [Hermes Setup](docs\u002Fhermes.md) | Skill + Project Plugin |\n| CodeBuddy | [CodeBuddy Setup](docs\u002Fcodebuddy.md) | [Skills + Hooks](https:\u002F\u002Fwww.codebuddy.ai\u002Fdocs\u002Fcli\u002Fskills) |\n| FactoryAI Droid | [Factory Setup](docs\u002Ffactory.md) | [Skills + Hooks](https:\u002F\u002Fdocs.factory.ai\u002Fcli\u002Fconfiguration\u002Fskills) |\n| OpenCode | [OpenCode Setup](docs\u002Fopencode.md) | Skills + Custom session storage |\n\n#### Standard Agent Skills Support\n\nThese IDEs implement the [Agent Skills](https:\u002F\u002Fagentskills.io) open specification. Install with `npx skills add` — the installer places the skill in each IDE's discovery path automatically:\n\n| IDE | Installation Guide | Skill Discovery Path |\n|-----|-------------------|---------------------|\n| Continue | [Continue Setup](docs\u002Fcontinue.md) | `.continue\u002Fskills\u002F` + [.prompt files](https:\u002F\u002Fdocs.continue.dev\u002Fcustomize\u002Fdeep-dives\u002Fprompts) |\n| Pi Agent | [Pi Agent Setup](docs\u002Fpi-agent.md) | `.pi\u002Fskills\u002F` ([npm package](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@mariozechner\u002Fpi-coding-agent)) |\n| OpenClaw | [OpenClaw Setup](docs\u002Fopenclaw.md) | `.openclaw\u002Fskills\u002F` ([docs](https:\u002F\u002Fdocs.openclaw.ai\u002Ftools\u002Fskills)) |\n| Antigravity | [Antigravity Setup](docs\u002Fantigravity.md) | `.agent\u002Fskills\u002F` ([docs](https:\u002F\u002Fcodelabs.developers.google.com\u002Fgetting-started-with-antigravity-skills)) |\n| Kilocode | [Kilocode Setup](docs\u002Fkilocode.md) | `.kilocode\u002Fskills\u002F` ([docs](https:\u002F\u002Fkilo.ai\u002Fdocs\u002Fagent-behavior\u002Fskills)) |\n| AdaL CLI (Sylph AI) | [AdaL Setup](docs\u002Fadal.md) | `.adal\u002Fskills\u002F` ([docs](https:\u002F\u002Fdocs.sylph.ai\u002Ffeatures\u002Fplugins-and-skills)) |\n\n> **Note:** If your IDE uses the legacy Rules system instead of Skills, see the [`legacy-rules-support`](https:\u002F\u002Fgithub.com\u002FOthmanAdi\u002Fplanning-with-files\u002Ftree\u002Flegacy-rules-support) branch.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🧱 Sandbox Runtimes (1 Platform)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n| Runtime | Status | Guide | Notes |\n|---------|--------|-------|-------|\n| BoxLite | ✅ Documented | [BoxLite Setup](docs\u002Fboxlite.md) | Run Claude Code + planning-with-files inside hardware-isolated micro-VMs |\n\n> **Note:** BoxLite is a sandbox runtime, not an IDE. Skills load via [ClaudeBox](https:\u002F\u002Fgithub.com\u002Fboxlite-ai\u002Fclaudebox) — BoxLite’s official Claude Code integration layer.\n\n\u003C\u002Fdetails>\n\n---\n\nA 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.\n\n[![Claude Code Plugin](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude%20Code-Plugin-blue)](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fplugins)\n[![Claude Code Skill](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude%20Code-Skill-green)](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fskills)\n[![Cursor Skills](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCursor-Skills-purple)](https:\u002F\u002Fdocs.cursor.com\u002Fcontext\u002Fskills)\n[![Kilocode Skills](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FKilocode-Skills-orange)](https:\u002F\u002Fkilo.ai\u002Fdocs\u002Fagent-behavior\u002Fskills)\n[![Gemini CLI](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGemini%20CLI-Skills-4285F4)](https:\u002F\u002Fgeminicli.com\u002Fdocs\u002Fcli\u002Fskills\u002F)\n[![OpenClaw](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FOpenClaw-Skills-FF6B6B)](https:\u002F\u002Fopenclaw.ai)\n[![Kiro](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FKiro-Agent_Skill-00D4AA)](https:\u002F\u002Fkiro.dev\u002Fdocs\u002Fskills\u002F)\n[![AdaL CLI](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FAdaL%20CLI-Skills-9B59B6)](https:\u002F\u002Fdocs.sylph.ai\u002Ffeatures\u002Fplugins-and-skills)\n[![Pi Agent](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPi%20Agent-Skills-FF4081)](https:\u002F\u002Fpi.dev)\n[![GitHub Copilot](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub%20Copilot-Hooks-000000)](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Freference\u002Fhooks-configuration)\n[![Mastra Code](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMastra%20Code-Skills-00BCD4)](https:\u002F\u002Fcode.mastra.ai)\n[![Hermes](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FHermes-Agent_Skill-5C7CFA)](docs\u002Fhermes.md)\n[![BoxLite](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBoxLite-Sandbox-6C3483)](https:\u002F\u002Fboxlite.ai)\n\n## Quick Install\n\n```bash\nnpx skills add OthmanAdi\u002Fplanning-with-files --skill planning-with-files -g\n```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🌐 Available in 5 other languages\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**🇸🇦 العربية \u002F Arabic**\n```bash\nnpx skills add OthmanAdi\u002Fplanning-with-files --skill planning-with-files-ar -g\n```\n\n**🇩🇪 Deutsch \u002F German**\n```bash\nnpx skills add OthmanAdi\u002Fplanning-with-files --skill planning-with-files-de -g\n```\n\n**🇪🇸 Español \u002F Spanish**\n```bash\nnpx skills add OthmanAdi\u002Fplanning-with-files --skill planning-with-files-es -g\n```\n\n**🇨🇳 中文版 \u002F Chinese (Simplified)**\n```bash\nnpx skills add OthmanAdi\u002Fplanning-with-files --skill planning-with-files-zh -g\n```\n\n**🇹🇼 正體中文版 \u002F Chinese (Traditional)**\n```bash\nnpx skills add OthmanAdi\u002Fplanning-with-files --skill planning-with-files-zht -g\n```\n\n\u003C\u002Fdetails>\n\nWorks with Claude Code, Cursor, Codex, Gemini CLI, and 40+ agents supporting the [Agent Skills](https:\u002F\u002Fagentskills.io) spec.\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🔧 Claude Code Plugin (Advanced Features)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nFor Claude Code-specific features like `\u002Fplan` autocomplete commands:\n\n```\n\u002Fplugin marketplace add OthmanAdi\u002Fplanning-with-files\n\u002Fplugin install planning-with-files@planning-with-files\n```\n\n\u003C\u002Fdetails>\n\nThat's it! Now use one of these commands in Claude Code:\n\n| Command | Autocomplete | Description |\n|---------|--------------|-------------|\n| `\u002Fplanning-with-files:plan` | Type `\u002Fplan` | Start planning session (v2.11.0+) |\n| `\u002Fplanning-with-files:status` | Type `\u002Fplan:status` | Show planning progress at a glance (v2.15.0+) |\n| `\u002Fplanning-with-files:start` | Type `\u002Fplanning` | Original start command |\n\n**Alternative:** If you want `\u002Fplanning-with-files` (without prefix), copy skills to your local folder:\n\n**macOS\u002FLinux:**\n```bash\ncp -r ~\u002F.claude\u002Fplugins\u002Fcache\u002Fplanning-with-files\u002Fplanning-with-files\u002F*\u002Fskills\u002Fplanning-with-files ~\u002F.claude\u002Fskills\u002F\n```\n\n**Windows (PowerShell):**\n```powershell\nCopy-Item -Recurse -Path \"$env:USERPROFILE\\.claude\\plugins\\cache\\planning-with-files\\planning-with-files\\*\\skills\\planning-with-files\" -Destination \"$env:USERPROFILE\\.claude\\skills\\\"\n```\n\nSee [docs\u002Finstallation.md](docs\u002Finstallation.md) for all installation methods.\n\n## Why This Skill?\n\nOn December 29, 2025, [Meta acquired Manus for $2 billion](https:\u002F\u002Ftechcrunch.com\u002F2025\u002F12\u002F29\u002Fmeta-just-bought-manus-an-ai-startup-everyone-has-been-talking-about\u002F). In just 8 months, Manus went from launch to $100M+ revenue. Their secret? **Context engineering**.\n\n> \"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.\"\n> — Manus AI\n\n## The Problem\n\nClaude Code (and most AI agents) suffer from:\n\n- **Volatile memory** — TodoWrite tool disappears on context reset\n- **Goal drift** — After 50+ tool calls, original goals get forgotten\n- **Hidden errors** — Failures aren't tracked, so the same mistakes repeat\n- **Context stuffing** — Everything crammed into context instead of stored\n\n## The Solution: 3-File Pattern\n\nFor every complex task, create THREE files:\n\n```\ntask_plan.md      → Track phases and progress\nfindings.md       → Store research and findings\nprogress.md       → Session log and test results\n```\n\n### The Core Principle\n\n```\nContext Window = RAM (volatile, limited)\nFilesystem = Disk (persistent, unlimited)\n\n→ Anything important gets written to disk.\n```\n\n## The Manus Principles\n\n| Principle | Implementation |\n|-----------|----------------|\n| Filesystem as memory | Store in files, not context |\n| Attention manipulation | Re-read plan before decisions (hooks) |\n| Error persistence | Log failures in plan file |\n| Goal tracking | Checkboxes show progress |\n| Completion verification | Stop hook checks all phases |\n\n## Usage\n\nOnce installed, the AI agent will:\n\n1. **Ask for your task** if no description is provided\n2. **Create `task_plan.md`, `findings.md`, and `progress.md`** in your project directory\n3. **Re-read plan** before major decisions (via PreToolUse hook)\n4. **Remind you** to update status after file writes (via PostToolUse hook)\n5. **Store findings** in `findings.md` instead of stuffing context\n6. **Log errors** for future reference\n7. **Verify completion** before stopping (via Stop hook)\n\nInvoke with:\n- `\u002Fplanning-with-files:plan` - Type `\u002Fplan` to find in autocomplete (v2.11.0+)\n- `\u002Fplanning-with-files:start` - Type `\u002Fplanning` to find in autocomplete\n- `\u002Fplanning-with-files` - Only if you copied skills to `~\u002F.claude\u002Fskills\u002F`\n\nSee [docs\u002Fquickstart.md](docs\u002Fquickstart.md) for the full 5-step guide.\n\n## Benchmark Results\n\nFormally evaluated using Anthropic's [skill-creator](https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fskills\u002Ftree\u002Fmain\u002Fskills\u002Fskill-creator) framework (v2.22.0). 10 parallel subagents, 5 task types, 30 objectively verifiable assertions, 3 blind A\u002FB comparisons.\n\n| Test | with_skill | without_skill |\n|------|-----------|---------------|\n| Pass rate (30 assertions) | **96.7%** (29\u002F30) | 6.7% (2\u002F30) |\n| 3-file pattern followed | 5\u002F5 evals | 0\u002F5 evals |\n| Blind A\u002FB wins | **3\u002F3 (100%)** | 0\u002F3 |\n| Avg rubric score | **10.0\u002F10** | 6.8\u002F10 |\n\n[Full methodology and results](docs\u002Fevals.md) · [Technical write-up](docs\u002Farticle.md)\n\n## Key Rules\n\n1. **Create Plan First** — Never start without `task_plan.md`\n2. **The 2-Action Rule** — Save findings after every 2 view\u002Fbrowser operations\n3. **Log ALL Errors** — They help avoid repetition\n4. **Never Repeat Failures** — Track attempts, mutate approach\n\n## When to Use\n\n**Use this pattern for:**\n- Multi-step tasks (3+ steps)\n- Research tasks\n- Building\u002Fcreating projects\n- Tasks spanning many tool calls\n\n**Skip for:**\n- Simple questions\n- Single-file edits\n- Quick lookups\n\n## File Structure\n\n```\nplanning-with-files\u002F\n├── commands\u002F                # Plugin commands\n│   ├── plan.md              # \u002Fplanning-with-files:plan command (v2.11.0+)\n│   ├── plan-ar.md           # Arabic \u002Fplan command (v2.33.0+)\n│   ├── plan-de.md           # German \u002Fplan command (v2.33.0+)\n│   ├── plan-es.md           # Spanish \u002Fplan command (v2.33.0+)\n│   └── start.md             # \u002Fplanning-with-files:start command\n├── templates\u002F               # Root-level templates (for CLAUDE_PLUGIN_ROOT)\n├── scripts\u002F                 # Root-level scripts (for CLAUDE_PLUGIN_ROOT)\n├── docs\u002F                    # Documentation\n│   ├── installation.md\n│   ├── quickstart.md\n│   ├── workflow.md\n│   ├── troubleshooting.md\n│   ├── gemini.md            # Gemini CLI setup\n│   ├── cursor.md\n│   ├── windows.md\n│   ├── kilocode.md\n│   ├── codex.md\n│   ├── opencode.md\n│   ├── mastra.md             # Mastra Code setup\n│   └── boxlite.md            # BoxLite sandbox setup\n├── examples\u002F                # Integration examples\n│   └── boxlite\u002F             # BoxLite quickstart\n│       ├── README.md\n│       └── quickstart.py\n├── planning-with-files\u002F     # Plugin skill folder\n│   ├── SKILL.md\n│   ├── templates\u002F\n│   └── scripts\u002F\n├── skills\u002F                  # Skill variants\n│   ├── planning-with-files\u002F     # English (default)\n│   │   ├── SKILL.md\n│   │   ├── examples.md\n│   │   ├── reference.md\n│   │   ├── templates\u002F\n│   │   └── scripts\u002F\n│   │       ├── init-session.sh\n│   │       ├── check-complete.sh\n│   │       ├── init-session.ps1   # Windows PowerShell\n│   │       └── check-complete.ps1 # Windows PowerShell\n│   ├── planning-with-files-ar\u002F   # Arabic (v2.33.0+)\n│   │   ├── SKILL.md\n│   │   ├── templates\u002F\n│   │   └── scripts\u002F\n│   ├── planning-with-files-de\u002F   # German (v2.33.0+)\n│   │   ├── SKILL.md\n│   │   ├── templates\u002F\n│   │   └── scripts\u002F\n│   ├── planning-with-files-es\u002F   # Spanish (v2.33.0+)\n│   │   ├── SKILL.md\n│   │   ├── templates\u002F\n│   │   └── scripts\u002F\n│   ├── planning-with-files-zh\u002F   # Chinese Simplified (v2.25.0+)\n│   └── planning-with-files-zht\u002F  # Chinese Traditional (v2.28.0+)\n├── .gemini\u002F                 # Gemini CLI skills + hooks\n│   ├── settings.json        # Hook configuration (v2.26.0)\n│   ├── hooks\u002F               # Hook scripts (SessionStart, BeforeTool, AfterTool, BeforeModel, SessionEnd)\n│   └── skills\u002F\n│       └── planning-with-files\u002F\n├── .codex\u002F                  # Codex CLI skills + hooks\n│   └── skills\u002F\n├── .opencode\u002F               # OpenCode skills (custom session storage)\n│   └── skills\u002F\n├── .claude-plugin\u002F          # Plugin manifest\n├── .cursor\u002F                 # Cursor skills + hooks\n│   ├── hooks.json           # Hook configuration\n│   ├── hooks\u002F               # Hook scripts (bash + PowerShell)\n│   └── skills\u002F\n├── .codebuddy\u002F              # CodeBuddy skills + hooks\n│   └── skills\u002F\n├── .factory\u002F                # FactoryAI Droid skills + hooks (v2.26.0)\n│   └── skills\u002F\n├── .pi\u002F                     # Pi Agent skills (npm package)\n│   └── skills\u002F\n│       └── planning-with-files\u002F\n├── .continue\u002F               # Continue.dev skills + prompt files\n│   ├── prompts\u002F             # .prompt file for slash commands\n│   └── skills\u002F\n├── .github\u002F                 # GitHub Copilot hooks (incl. errorOccurred)\n│   └── hooks\u002F\n│       ├── planning-with-files.json  # Hook configuration\n│       └── scripts\u002F         # Hook scripts (bash + PowerShell)\n├── .mastracode\u002F             # Mastra Code skills + hooks\n│   └── skills\u002F\n├── .kiro\u002F                   # Kiro Agent Skills (v2.27.0+)\n│   └── skills\u002F\n├── CHANGELOG.md\n├── CITATION.cff\n├── LICENSE\n└── README.md\n```\n\n## Documentation\n\nAll platform setup guides and documentation are in the [docs\u002F](.\u002Fdocs\u002F) folder.\n\n\n## Acknowledgments\n\n- **Manus AI** — For pioneering context engineering patterns\n- **Anthropic** — For Claude Code, Agent Skills, and the Plugin system\n- **Lance Martin** — For the detailed Manus architecture analysis\n- Based on [Context Engineering for AI Agents](https:\u002F\u002Fmanus.im\u002Fblog\u002FContext-Engineering-for-AI-Agents-Lessons-from-Building-Manus)\n\n## Contributing\n\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Submit a pull request\n\n## License\n\nMIT License — feel free to use, modify, and distribute.\n\n---\n\n**Author:** [Ahmad Othman Ammar Adi](https:\u002F\u002Fgithub.com\u002FOthmanAdi)\n\n## Star History\n\n\u003Ca href=\"https:\u002F\u002Frepostars.dev\u002F?repos=OthmanAdi%2Fplanning-with-files&theme=copper\">\u003Cimg src=\"https:\u002F\u002Frepostars.dev\u002Fapi\u002Fembed?repo=OthmanAdi%2Fplanning-with-files&theme=copper\" width=\"100%\" alt=\"Star History Chart\" \u002F>\u003C\u002Fa>\n","该项目实现了一种基于Markdown文件的持久化计划工作流，类似于被Meta以20亿美元收购的Manus公司所使用的工作模式。其核心功能包括通过Python编写的Claude Code技能来支持任务规划和管理，并且具有高安全性和稳定性（经过审计和修复）。技术特点上，它采用了先进的AI代理技术，能够自动化处理复杂的项目管理和文档编辑任务。适用于需要高效组织和追踪多个项目或任务的场景，特别适合开发者、项目经理以及任何希望提高工作效率的人士。",2,"2026-06-11 02:49:55","top_language"]