Quick Install

Claude Code, plugin route (ships everything: skill, hooks, slash commands):

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

Every other agent, one line, 60+ agents via the Agent Skills standard:

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

npm, to pin an exact version into a project or vendor it:

npm install planning-with-files

The 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.

Pi Coding Agent, same npm package, wired up for you (skill, extension, status bar):

pi install npm:planning-with-files

Hermes Agent (Nous Research), native plugin plus skill bundle, CLI and Desktop:

hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
hermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files
hermes plugins enable planning-with-files

OpenCode, native plugin plus the skill (the npx skills add command above lands in ~/.agents/skills/, which OpenCode reads):

{ "plugin": ["opencode-planning-with-files"] }

in opencode.json or ~/.config/opencode/opencode.json; OpenCode installs it on the next start.

Under 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.

What each route actually ships:

Skill-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.

Install 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.

<details> <summary><strong>🌐 Available in 5 other languages</strong></summary>

🇸🇦 العربية / Arabic

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g

🇩🇪 Deutsch / German

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g

🇪🇸 Español / Spanish

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -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 -g

These 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.

Since 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. Full details, including what changed on the plugin route in v3.11.0, are in docs/languages.md.

They live under skills/i18n/, one directory deeper than the canonical skill. The install commands above are unchanged, because npx skills add resolves --skill by skill name across the whole repository. The Claude Code plugin scan reads skills/*/SKILL.md without recursing, so the plugin route registers the canonical skill alone and no longer carries five extra descriptions in every session's system prompt. On that route the /plan-ar, /plan-de, /plan-es, /plan-zh and /plan-zht commands read the translated skill from disk instead of invoking it by name.

</details>

<details> <summary><strong>Prefer <code>/planning-with-files</code> with no prefix?</strong></summary>

Copy the skill 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\"

</details>

<details> <summary><strong>Enhanced Support: per-IDE setup guides</strong></summary>

</details>

<details> <summary><strong>Standard Agent Skills: discovery paths</strong></summary>

Note: If your IDE uses the legacy Rules system instead of Skills, see the legacy-rules-support branch.

</details>

<details> <summary><strong>Sandbox runtimes</strong></summary>

BoxLite is a sandbox runtime, not an IDE. Skills load via ClaudeBox, BoxLite's official Claude Code integration layer.

</details>

<a id="faq"></a>

<details> <summary><strong>❓ FAQ</strong></summary>

Hermes Agent: first-class support (CLI and Desktop)

[!TIP] Hermes Agent by Nous Research runs planning-with-files as a native plugin: tools, /pwf slash commands, per-turn plan injection, progress reminders and the completion gate, in the Hermes CLI, the gateway sessions, and Hermes Desktop. Verified against Hermes v0.19.1 source and a live install, on Windows included.

hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
hermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files
hermes plugins enable planning-with-files

Hermes' own skills-guard scanner rates the Hermes bundle SAFE; the canonical skill path is rejected there because its Claude Code hook frontmatter trips the scanner, so the commands above are the supported route. The /plan command is Hermes' own bundled skill and is never shadowed. Full guide, Windows notes, the shell-hook route and the hermes import-agent claude-code migration: docs/hermes.md.

Forks & Extensions