{"id":37227328,"url":"https://github.com/othmanadi/planning-with-files","last_synced_at":"2026-05-16T10:03:42.415Z","repository":{"id":331661023,"uuid":"1127110039","full_name":"OthmanAdi/planning-with-files","owner":"OthmanAdi","description":"Claude Code skill implementing Manus-style persistent markdown planning — the workflow pattern behind the $2B acquisition.","archived":false,"fork":false,"pushed_at":"2026-03-24T19:03:37.000Z","size":611,"stargazers_count":17863,"open_issues_count":5,"forks_count":1614,"subscribers_count":81,"default_branch":"master","last_synced_at":"2026-04-02T09:33:34.470Z","etag":null,"topics":["adal","agent","agent-skills","agents","antigravity","claude","claude-code","claude-skills","clawd","clawdbot","clawdbot-skill","clawdhub","codebuddy","cursor","factory-ai","kilocode","manus","manus-ai","moltbot","moltbot-skills"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OthmanAdi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-03T07:37:28.000Z","updated_at":"2026-04-02T09:31:51.000Z","dependencies_parsed_at":"2026-02-28T03:01:05.927Z","dependency_job_id":null,"html_url":"https://github.com/OthmanAdi/planning-with-files","commit_stats":null,"previous_names":["othmanadi/planning-with-files"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/OthmanAdi/planning-with-files","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OthmanAdi%2Fplanning-with-files","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OthmanAdi%2Fplanning-with-files/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OthmanAdi%2Fplanning-with-files/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OthmanAdi%2Fplanning-with-files/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OthmanAdi","download_url":"https://codeload.github.com/OthmanAdi/planning-with-files/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OthmanAdi%2Fplanning-with-files/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31575757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adal","agent","agent-skills","agents","antigravity","claude","claude-code","claude-skills","clawd","clawdbot","clawdbot-skill","clawdhub","codebuddy","cursor","factory-ai","kilocode","manus","manus-ai","moltbot","moltbot-skills"],"created_at":"2026-01-15T03:20:23.981Z","updated_at":"2026-05-16T10:03:42.408Z","avatar_url":"https://github.com/OthmanAdi.png","language":"Python","funding_links":[],"categories":["Skills Catalog"],"sub_categories":["Workflow (50)"],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"media/banner.png\" alt=\"planning-with-files\" width=\"100%\"\u003e\n\u003c/div\u003e\n\n# Planning with Files\n\n\u003e **Work like Manus** — the AI agent company Meta acquired for **$2 billion**.\n\n[![Benchmark](https://img.shields.io/badge/Benchmark-96.7%25_pass_rate-brightgreen)](docs/evals.md)\n[![A/B Verified](https://img.shields.io/badge/A%2FB_Blind-3%2F3_wins-brightgreen)](docs/evals.md)\n[![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com)\n[![Security Verified](https://img.shields.io/badge/Security-Audited_%26_Fixed_v2.21.0-blue)](docs/evals.md)\n\n[![Skills Playground](https://skillsplayground.com/badges/installs/othmanadi-planning-with-files-planning-with-files.svg)](https://skillsplayground.com/skills/othmanadi-planning-with-files-planning-with-files/)\n[![Downloads](https://skill-history.com/badge/othmanadi/planning-with-files.svg)](https://skill-history.com/othmanadi/planning-with-files)\n[![Version](https://img.shields.io/badge/version-2.38.1-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Closed Issues](https://img.shields.io/github/issues-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/issues?q=is%3Aissue+is%3Aclosed)\n[![Closed PRs](https://img.shields.io/github/issues-pr-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/pulls?q=is%3Apr+is%3Aclosed)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e💬 A Note from the Author\u003c/strong\u003e\u003c/summary\u003e\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/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🌍 What the community shipped\u003c/strong\u003e\u003c/summary\u003e\n\n### Forks \u0026 Extensions\n\n| Fork | Author | What They Built |\n|------|--------|-----------------|\n| [devis](https://github.com/st01cs/devis) | [@st01cs](https://github.com/st01cs) | Interview-first workflow, `/devis:intv` and `/devis:impl` commands, guaranteed activation |\n| [multi-manus-planning](https://github.com/kmichels/multi-manus-planning) | [@kmichels](https://github.com/kmichels) | Multi-project support, SessionStart git sync |\n| [plan-cascade](https://github.com/Taoidle/plan-cascade) | [@Taoidle](https://github.com/Taoidle) | Multi-level task orchestration, parallel execution, multi-agent collaboration |\n| [agentfund-skill](https://github.com/RioTheGreat-ai/agentfund-skill) | [@RioTheGreat-ai](https://github.com/RioTheGreat-ai) | Crowdfunding for AI agents with milestone-based escrow on Base |\n| [openclaw-github-repo-commander](https://github.com/wd041216-bit/openclaw-github-repo-commander) | [@wd041216-bit](https://github.com/wd041216-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/Planning-with-files-copilot-agent](https://github.com/lincolnwan/Planning-with-files-copilot-agent) | Entire Copilot agent repo built around the planning-with-files skill |\n| [cooragent/ClarityFinance](https://github.com/cooragent/ClarityFinance) | AI finance agent framework — Planning-with-Files approach directly credited |\n| [oeftimie/vv-claude-harness](https://github.com/oeftimie/vv-claude-harness) | Claude Code harness built on Manus-style persistent markdown planning |\n| [jessepwj/CCteam-creator](https://github.com/jessepwj/CCteam-creator) | Multi-agent team orchestration skill using file-based planning |\n\n### Skill Registries \u0026 Hubs\n\n| Registry | What It Is |\n|----------|-----------|\n| [buzhangsan/skill-manager](https://github.com/buzhangsan/skill-manager) | Bilingual (EN/中文) skill hub indexing 31,000+ Claude Code skills — planning-with-files installable one-click. |\n\n*Built something? [Open an issue](https://github.com/OthmanAdi/planning-with-files/issues) to get listed!*\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🤝 Contributors\u003c/strong\u003e\u003c/summary\u003e\n\nSee the full list of everyone who made this project better in [CONTRIBUTORS.md](./CONTRIBUTORS.md).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📦 Releases \u0026 Session Recovery\u003c/strong\u003e\u003c/summary\u003e\n\n### Current Version: v2.38.1\n\n| Version | Highlights |\n|---------|------------|\n| **v2.38.1** | **Description field garbled in Claude Code skill picker** (surfaced via Discussion #153 by @bmyury): hook commands embedded `'---BEGIN PLAN DATA---'` plan-injection delimiters; Claude Code's skill-discovery loader split frontmatter on the first `---` and read the truncated value as the description. Swapped to `===BEGIN PLAN DATA===` / `===END PLAN DATA===` across canonical SKILL.md, all five language variants, the `.codebuddy/.codex/.cursor` adapter mirrors, and `clawhub-upload`. Hook execution and tamper attestation never affected; only the displayed metadata. |\n| **v2.38.0** | **Claude Code turn-loop integration + OpenCode SQLite fix**: new PreCompact hook fires on `/compact` and autoCompact, surfaces a reminder to flush progress before compaction completes and prints the active Plan-SHA256 when attested. New `/plan-goal` slash command composes with Claude Code's `/goal` (v2.1.139, May 12 2026): derives a termination condition from the active plan. New `/plan-loop` composes with `/loop` (v2.1.72+): default 10-minute tick re-reads planning files and runs check-complete. New `templates/loop.md` for the bare `/loop` planning-aware default. Session-catchup rewritten for OpenCode's SQLite migration. Codex gets a `PermissionRequest` adapter that surfaces plan context at permission prompts. |\n| **v2.37.0** | **Hash attestation + parity bumper** (closes #150, #151): `/plan-attest` locks `task_plan.md` with a SHA-256; hooks block injection on tamper. `scripts/bump-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/planning-with-files/scripts/init-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/hermes.md`. 34 new tests. (thanks @githubYiheng, @09ashishkapoor, @shawnli1874!) |\n| **v2.35.1** | **Shebang portability fix**: changed `/bin/bash` to `/usr/bin/env bash` in hook scripts, fixing compatibility on NixOS and other systems where bash is not at `/bin/bash`. (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/hooks.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 `/clear`, 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** | `/plan:status` command, OpenCode compatibility fix |\n| **v2.14.0** | Pi Agent support, OpenClaw docs update, Codex path fix |\n| **v2.11.0** | `/plan` 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://github.com/OthmanAdi/planning-with-files/releases) · [CHANGELOG](CHANGELOG.md)\n\n\u003e 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.\n\n---\n\n### Session Recovery\n\nWhen your context fills up and you run `/clear`, 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 (`~/.claude/projects/` for Claude Code, `~/.codex/sessions/` 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/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🛠️ Supported IDEs (17+ Platforms)\u003c/strong\u003e\u003c/summary\u003e\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/installation.md) | Plugin + SKILL.md + Hooks |\n| Cursor | [Cursor Setup](docs/cursor.md) | Skills + [hooks.json](https://cursor.com/docs/hooks) |\n| GitHub Copilot | [Copilot Setup](docs/copilot.md) | [Hooks](https://docs.github.com/en/copilot/reference/hooks-configuration) (incl. errorOccurred) |\n| Mastra Code | [Mastra Setup](docs/mastra.md) | Skills + [Hooks](https://mastra.ai/docs/mastra-code/configuration) |\n| Gemini CLI | [Gemini Setup](docs/gemini.md) | Skills + [Hooks](https://geminicli.com/docs/hooks/) |\n| Kiro | [Kiro Setup](docs/kiro.md) | [Agent Skills](https://kiro.dev/docs/skills/) |\n| Codex | [Codex Setup](docs/codex.md) | [Skills + Hooks](https://developers.openai.com/codex/skills) |\n| Hermes Agent | [Hermes Setup](docs/hermes.md) | Skill + Project Plugin |\n| CodeBuddy | [CodeBuddy Setup](docs/codebuddy.md) | [Skills + Hooks](https://www.codebuddy.ai/docs/cli/skills) |\n| FactoryAI Droid | [Factory Setup](docs/factory.md) | [Skills + Hooks](https://docs.factory.ai/cli/configuration/skills) |\n| OpenCode | [OpenCode Setup](docs/opencode.md) | Skills + Custom session storage |\n\n#### Standard Agent Skills Support\n\nThese IDEs implement the [Agent Skills](https://agentskills.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/continue.md) | `.continue/skills/` + [.prompt files](https://docs.continue.dev/customize/deep-dives/prompts) |\n| Pi Agent | [Pi Agent Setup](docs/pi-agent.md) | `.pi/skills/` ([npm package](https://www.npmjs.com/package/@mariozechner/pi-coding-agent)) |\n| OpenClaw | [OpenClaw Setup](docs/openclaw.md) | `.openclaw/skills/` ([docs](https://docs.openclaw.ai/tools/skills)) |\n| Antigravity | [Antigravity Setup](docs/antigravity.md) | `.agent/skills/` ([docs](https://codelabs.developers.google.com/getting-started-with-antigravity-skills)) |\n| Kilocode | [Kilocode Setup](docs/kilocode.md) | `.kilocode/skills/` ([docs](https://kilo.ai/docs/agent-behavior/skills)) |\n| AdaL CLI (Sylph AI) | [AdaL Setup](docs/adal.md) | `.adal/skills/` ([docs](https://docs.sylph.ai/features/plugins-and-skills)) |\n\n\u003e **Note:** If your IDE uses the legacy Rules system instead of Skills, see the [`legacy-rules-support`](https://github.com/OthmanAdi/planning-with-files/tree/legacy-rules-support) branch.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🧱 Sandbox Runtimes (1 Platform)\u003c/strong\u003e\u003c/summary\u003e\n\n| Runtime | Status | Guide | Notes |\n|---------|--------|-------|-------|\n| BoxLite | ✅ Documented | [BoxLite Setup](docs/boxlite.md) | Run Claude Code + planning-with-files inside hardware-isolated micro-VMs |\n\n\u003e **Note:** BoxLite is a sandbox runtime, not an IDE. Skills load via [ClaudeBox](https://github.com/boxlite-ai/claudebox) — BoxLite’s official Claude Code integration layer.\n\n\u003c/details\u003e\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://img.shields.io/badge/Claude%20Code-Plugin-blue)](https://code.claude.com/docs/en/plugins)\n[![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-green)](https://code.claude.com/docs/en/skills)\n[![Cursor Skills](https://img.shields.io/badge/Cursor-Skills-purple)](https://docs.cursor.com/context/skills)\n[![Kilocode Skills](https://img.shields.io/badge/Kilocode-Skills-orange)](https://kilo.ai/docs/agent-behavior/skills)\n[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Skills-4285F4)](https://geminicli.com/docs/cli/skills/)\n[![OpenClaw](https://img.shields.io/badge/OpenClaw-Skills-FF6B6B)](https://openclaw.ai)\n[![Kiro](https://img.shields.io/badge/Kiro-Agent_Skill-00D4AA)](https://kiro.dev/docs/skills/)\n[![AdaL CLI](https://img.shields.io/badge/AdaL%20CLI-Skills-9B59B6)](https://docs.sylph.ai/features/plugins-and-skills)\n[![Pi Agent](https://img.shields.io/badge/Pi%20Agent-Skills-FF4081)](https://pi.dev)\n[![GitHub Copilot](https://img.shields.io/badge/GitHub%20Copilot-Hooks-000000)](https://docs.github.com/en/copilot/reference/hooks-configuration)\n[![Mastra Code](https://img.shields.io/badge/Mastra%20Code-Skills-00BCD4)](https://code.mastra.ai)\n[![Hermes](https://img.shields.io/badge/Hermes-Agent_Skill-5C7CFA)](docs/hermes.md)\n[![BoxLite](https://img.shields.io/badge/BoxLite-Sandbox-6C3483)](https://boxlite.ai)\n\n## Quick Install\n\n```bash\nnpx skills add OthmanAdi/planning-with-files --skill planning-with-files -g\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🌐 Available in 5 other languages\u003c/strong\u003e\u003c/summary\u003e\n\n**🇸🇦 العربية / Arabic**\n```bash\nnpx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g\n```\n\n**🇩🇪 Deutsch / German**\n```bash\nnpx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g\n```\n\n**🇪🇸 Español / Spanish**\n```bash\nnpx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g\n```\n\n**🇨🇳 中文版 / Chinese (Simplified)**\n```bash\nnpx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g\n```\n\n**🇹🇼 正體中文版 / Chinese (Traditional)**\n```bash\nnpx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g\n```\n\n\u003c/details\u003e\n\nWorks with Claude Code, Cursor, Codex, Gemini CLI, and 40+ agents supporting the [Agent Skills](https://agentskills.io) spec.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔧 Claude Code Plugin (Advanced Features)\u003c/strong\u003e\u003c/summary\u003e\n\nFor Claude Code-specific features like `/plan` autocomplete commands:\n\n```\n/plugin marketplace add OthmanAdi/planning-with-files\n/plugin install planning-with-files@planning-with-files\n```\n\n\u003c/details\u003e\n\nThat's it! Now use one of these commands in Claude Code:\n\n| Command | Autocomplete | Description |\n|---------|--------------|-------------|\n| `/planning-with-files:plan` | Type `/plan` | Start planning session (v2.11.0+) |\n| `/planning-with-files:status` | Type `/plan:status` | Show planning progress at a glance (v2.15.0+) |\n| `/planning-with-files:start` | Type `/planning` | Original start command |\n\n**Alternative:** If you want `/planning-with-files` (without prefix), copy skills to your local folder:\n\n**macOS/Linux:**\n```bash\ncp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/\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/installation.md](docs/installation.md) for all installation methods.\n\n## Why This Skill?\n\nOn December 29, 2025, [Meta acquired Manus for $2 billion](https://techcrunch.com/2025/12/29/meta-just-bought-manus-an-ai-startup-everyone-has-been-talking-about/). In just 8 months, Manus went from launch to $100M+ revenue. Their secret? **Context engineering**.\n\n\u003e \"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\u003e — 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- `/planning-with-files:plan` - Type `/plan` to find in autocomplete (v2.11.0+)\n- `/planning-with-files:start` - Type `/planning` to find in autocomplete\n- `/planning-with-files` - Only if you copied skills to `~/.claude/skills/`\n\nSee [docs/quickstart.md](docs/quickstart.md) for the full 5-step guide.\n\n## Benchmark Results\n\nFormally evaluated using Anthropic's [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) framework (v2.22.0). 10 parallel subagents, 5 task types, 30 objectively verifiable assertions, 3 blind A/B comparisons.\n\n| Test | with_skill | without_skill |\n|------|-----------|---------------|\n| Pass rate (30 assertions) | **96.7%** (29/30) | 6.7% (2/30) |\n| 3-file pattern followed | 5/5 evals | 0/5 evals |\n| Blind A/B wins | **3/3 (100%)** | 0/3 |\n| Avg rubric score | **10.0/10** | 6.8/10 |\n\n[Full methodology and results](docs/evals.md) · [Technical write-up](docs/article.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/browser 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/creating 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/\n├── commands/                # Plugin commands\n│   ├── plan.md              # /planning-with-files:plan command (v2.11.0+)\n│   ├── plan-ar.md           # Arabic /plan command (v2.33.0+)\n│   ├── plan-de.md           # German /plan command (v2.33.0+)\n│   ├── plan-es.md           # Spanish /plan command (v2.33.0+)\n│   └── start.md             # /planning-with-files:start command\n├── templates/               # Root-level templates (for CLAUDE_PLUGIN_ROOT)\n├── scripts/                 # Root-level scripts (for CLAUDE_PLUGIN_ROOT)\n├── docs/                    # 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/                # Integration examples\n│   └── boxlite/             # BoxLite quickstart\n│       ├── README.md\n│       └── quickstart.py\n├── planning-with-files/     # Plugin skill folder\n│   ├── SKILL.md\n│   ├── templates/\n│   └── scripts/\n├── skills/                  # Skill variants\n│   ├── planning-with-files/     # English (default)\n│   │   ├── SKILL.md\n│   │   ├── examples.md\n│   │   ├── reference.md\n│   │   ├── templates/\n│   │   └── scripts/\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/   # Arabic (v2.33.0+)\n│   │   ├── SKILL.md\n│   │   ├── templates/\n│   │   └── scripts/\n│   ├── planning-with-files-de/   # German (v2.33.0+)\n│   │   ├── SKILL.md\n│   │   ├── templates/\n│   │   └── scripts/\n│   ├── planning-with-files-es/   # Spanish (v2.33.0+)\n│   │   ├── SKILL.md\n│   │   ├── templates/\n│   │   └── scripts/\n│   ├── planning-with-files-zh/   # Chinese Simplified (v2.25.0+)\n│   └── planning-with-files-zht/  # Chinese Traditional (v2.28.0+)\n├── .gemini/                 # Gemini CLI skills + hooks\n│   ├── settings.json        # Hook configuration (v2.26.0)\n│   ├── hooks/               # Hook scripts (SessionStart, BeforeTool, AfterTool, BeforeModel, SessionEnd)\n│   └── skills/\n│       └── planning-with-files/\n├── .codex/                  # Codex CLI skills + hooks\n│   └── skills/\n├── .opencode/               # OpenCode skills (custom session storage)\n│   └── skills/\n├── .claude-plugin/          # Plugin manifest\n├── .cursor/                 # Cursor skills + hooks\n│   ├── hooks.json           # Hook configuration\n│   ├── hooks/               # Hook scripts (bash + PowerShell)\n│   └── skills/\n├── .codebuddy/              # CodeBuddy skills + hooks\n│   └── skills/\n├── .factory/                # FactoryAI Droid skills + hooks (v2.26.0)\n│   └── skills/\n├── .pi/                     # Pi Agent skills (npm package)\n│   └── skills/\n│       └── planning-with-files/\n├── .continue/               # Continue.dev skills + prompt files\n│   ├── prompts/             # .prompt file for slash commands\n│   └── skills/\n├── .github/                 # GitHub Copilot hooks (incl. errorOccurred)\n│   └── hooks/\n│       ├── planning-with-files.json  # Hook configuration\n│       └── scripts/         # Hook scripts (bash + PowerShell)\n├── .mastracode/             # Mastra Code skills + hooks\n│   └── skills/\n├── .kiro/                   # Kiro Agent Skills (v2.27.0+)\n│   └── skills/\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/](./docs/) 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://manus.im/blog/Context-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://github.com/OthmanAdi)\n\n## Star History\n\n\u003ca href=\"https://repostars.dev/?repos=OthmanAdi%2Fplanning-with-files\u0026theme=copper\"\u003e\u003cimg src=\"https://repostars.dev/api/embed?repo=OthmanAdi%2Fplanning-with-files\u0026theme=copper\" width=\"100%\" alt=\"Star History Chart\" /\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fothmanadi%2Fplanning-with-files","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fothmanadi%2Fplanning-with-files","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fothmanadi%2Fplanning-with-files/lists"}