{"data":{"slug":"othmanadi-planning-with-files","name":"planning-with-files","tagline":"Persistent file-based planning for AI coding agents","github_url":"https://github.com/OthmanAdi/planning-with-files","owner":"OthmanAdi","repo":"planning-with-files","owner_avatar_url":"https://avatars.githubusercontent.com/u/78882424?v=4","primary_language":"Shell","stars":26250,"forks":2199,"topics":["agent-skills","autonomous-agents","claude","claude-code","claude-code-skills","claude-skills","codex","coding-agent","context-engineering","context-rot","cursor","github-copilot","hermes-plugin","hermes-skill","llm-agents","long-running-agents","manus","multi-agent-systems","planning","session-recovery"],"archived":false,"github_pushed_at":"2026-08-19T17:32:24+00:00","maintenance_label":"Very active","stars_delta_30d":691,"url":"https://www.graphcanon.com/tools/othmanadi-planning-with-files","markdown_url":"https://www.graphcanon.com/tools/othmanadi-planning-with-files.md","api_url":"https://www.graphcanon.com/api/graphcanon/tools/othmanadi-planning-with-files","graph_url":"https://www.graphcanon.com/api/graphcanon/graph?tool=othmanadi-planning-with-files","description":"Persistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60+ agents.","homepage_url":"https://www.skills.sh/othmanadi/planning-with-files/planning-with-files","license":"MIT","open_issues":9,"watchers":109,"ai_summary":"Provides crash-proof markdown plans that survive context loss in long-running agentic tasks. Supports multi-agent shared state on disk through a deterministic completion gate.","readme_excerpt":"## Quick Install\n\n**Claude Code, plugin route** (ships everything: skill, hooks, slash commands):\n\n```\n/plugin marketplace add OthmanAdi/planning-with-files\n/plugin install planning-with-files@planning-with-files\n```\n\n**Every other agent**, one line, 60+ agents via the [Agent Skills](https://agentskills.io) standard:\n\n```bash\nnpx skills add OthmanAdi/planning-with-files --skill planning-with-files -g\n```\n\n**npm**, to pin an exact version into a project or vendor it:\n\n```bash\nnpm install planning-with-files\n```\n\nThe package carries `SKILL.md`, `scripts/` and `templates/`, so this is the route for locking a version into a repo's dependencies or copying the skill in yourself. It does not register hooks on its own.\n\n**Pi Coding Agent**, same npm package, wired up for you (skill, extension, status bar):\n\n```bash\npi install npm:planning-with-files\n```\n\nUnder a minute. Safe to re-run. Trigger it by typing `/plan` (plugin) or asking the agent to \"plan this task\"; the skill also self-triggers on multi-step tasks.\n\nWhat each route actually ships:\n\n| Route | Skill + scripts + templates | Slash commands | Hooks |\n|---|---|---|---|\n| Claude Code plugin | yes | **yes** | **yes** |\n| `npx skills add` | yes | no | frontmatter hooks, see note |\n| `npm install` | yes, under `node_modules/` | no | no, copy the skill in yourself |\n| `pi install npm:` | yes | **yes**, Pi commands | **yes**, via the Pi extension |\n| ClawHub / manual copy | yes | no | frontmatter hooks, see note |\n\nSkill-route installs can end up silently hook-less (project trust not accepted, or frontmatter hooks not registering on project-level installs). The hooks are the differentiating mechanism, so if they matter to you, use the plugin route, then verify with `/plan-doctor`. Full matrix and the two silent killers: [docs/installation.md](docs/installation.md#what-each-install-route-actually-ships).\n\nInstall acting up? Open your agent and say: *\"Read docs/installation.md and docs/troubleshooting.md from OthmanAdi/planning-with-files and fix my install.\"* Then run `/plan-doctor`.\n\n<details>\n<summary><strong>🌐 Available in 5 other languages</strong></summary>\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\nThese are real translations, not an English body with a translated description: the SKILL.md prose, the templates, and the user-facing output of `check-complete`, `init-session` and `session-catchup` are all localized. The status tokens stay literal English (`**Status:** complete`) on purpose, because `check-complete.sh` matches them with `grep -F`, so translating them would disable the completion gate.\n\nSince v3.10.0 the variants also ship the full script surface: attestation, the Stop gate, the ledger, phase status and plan-doctor used to be canonical-only, which quietly made every non-English install a subset install. See [issue #130](https://github.com/OthmanAdi/planning-with-files/issues/130) for why they stay separate skills rather than collapsing into one.\n\n</details>\n\n<details>\n<summary><strong>Prefer <code>/planning-with-files</code> with no prefix?</strong></summary>\n\nCopy the skill 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-w","github_created_at":"2026-01-03T07:37:28+00:00","created_at":"2026-07-07T17:40:25.800564+00:00","updated_at":"2026-08-19T18:02:26.154419+00:00","categories":[{"slug":"ai-agents","name":"AI Agents","url":"https://www.graphcanon.com/categories/ai-agents","markdown_url":"https://www.graphcanon.com/categories/ai-agents.md","api_url":"https://www.graphcanon.com/api/graphcanon/categories/ai-agents"},{"slug":"developer-tools","name":"Developer Tools","url":"https://www.graphcanon.com/categories/developer-tools","markdown_url":"https://www.graphcanon.com/categories/developer-tools.md","api_url":"https://www.graphcanon.com/api/graphcanon/categories/developer-tools"}],"tags":[{"slug":"agent-skills","name":"agent-skills"},{"slug":"ai-agents","name":"ai-agents"},{"slug":"claude-code","name":"claude-code"},{"slug":"codex","name":"codex"},{"slug":"coding-agent","name":"coding-agent"},{"slug":"multi-agent-systems","name":"multi-agent-systems"},{"slug":"planning","name":"planning"}],"trust":{"provenance":{"is_fork":false,"github_id":1127110039,"owner_type":"User","methodology":"github_public_v1","parent_repo":null,"near_duplicate_slugs":[]},"computed_at":"2026-08-19T18:02:25.353Z","maintenance":{"label":"Very active","score":96,"methodology":"github_public_v1","releases_90d":26,"days_since_push":0,"last_release_at":"2026-08-19T17:32:59Z","stars_delta_30d":691,"open_issues_delta_30d":4},"security_summary":{"status":"no_lockfile","scanner":null,"low_count":0,"high_count":0,"last_scan_at":"2026-07-11T11:16:38.117Z","medium_count":0,"scan_profile":"none","critical_count":0}},"capability_facts":{"scan":{"source":"repo_scan","observed_at":"2026-08-19T18:02:25.843Z"},"languages":{"value":["shell"],"source":"github.language","observed_at":"2026-08-19T18:02:25.843Z"},"license_spdx":{"value":"MIT","source":"github.license","observed_at":"2026-08-19T18:02:25.843Z"}},"decision_facts":{"hosting":null,"pricing":{"model":"freemium","summary":"Freely available under MIT License; community-supported."},"requirements":{"min_ram_gb":null,"requires_docker":false},"constraints":{"min_ram_gb":null,"pricing_model":"freemium","requires_docker":false},"when_to_use":["- When your coding agent needs to retain plans across sessions without context loss.","- For supporting multi-agent shared state, ensuring all agents have the most updated plan on disk.","- Necessary when working with tasks that require continuity and resilience against crashes.","- If you are using Claude Code or other AI agents supporting the Skill.md standard."],"when_not_to_use":["- When you do not need persistent storage for plans, such as short tasks where context is unlikely to be lost.","- For projects that strictly prohibit the use of external file storage for tracking progress due to security concerns.","- If your workflow heavily relies on in-memory planning strategies that are more suitable than disk-based solutions."],"source":"enrich:decision_facts","observed_at":"2026-07-11T13:42:59.614Z"},"constraint_facets":{"min_ram_gb":null,"pricing_model":"freemium","requires_docker":false},"decision_summary":[{"label":"Pricing","value":"freemium - Freely available under MIT License; community-supported."},{"label":"Adopt for","value":"A tool designed for providing persistent file-based planning in long-running AI coding tasks."}]}}