release: v3.11.2

docs/installation.md:101 and docs/windows.md:38 copy skills/* into the user's
skills directory. Since the v3.11.0 move of the language variants to
skills/i18n/, that glob also copies i18n/, which is not a skill: the user ends
up with ~/.claude/skills/i18n/ holding no SKILL.md, and the five translations
at ~/.claude/skills/i18n/planning-with-files-<lang>/ rather than the
~/.claude/skills/planning-with-files-<lang>/ that commands/plan-<lang>.md
probes first.

Both now name skills/planning-with-files, matching section 4 of
installation.md, README.md:250 and every other copy command in docs/. A second
line copying skills/i18n/* would restore what the glob used to install, but
docs/languages.md:26 states that installing English installs no translation,
and six skills in ~/.claude/skills/ returns the five extra descriptions to
every session that PR #226 removed from the plugin route.

The guard lives in tests/test_plugin_skill_surface.py, which owns the skills/
depth invariant. It matches only lines starting with cp or Copy-Item, so the
prose describing the skills/*/SKILL.md plugin scan does not trip it.

.agents/skills/planning-with-files/SKILL.md

@@ -28,7 +28,7 @@ hooks:
         - type: command
           command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 ---
 
 # Planning with Files

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "planning-with-files",
       "source": "./",
       "description": "Persistent file-based planning for AI coding agents. Crash-proof markdown plans that survive context loss, /clear, and crashes, with an opt-in completion gate and multi-agent shared state on disk. Manus-style, installs across 60+ agents via the SKILL.md standard.",
-      "version": "3.10.2"
+      "version": "3.11.2"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "planning-with-files",
-  "version": "3.10.2",
+  "version": "3.11.2",
   "description": "Persistent file-based planning for AI coding agents. Crash-proof markdown plans (task_plan.md, findings.md, progress.md) that survive context loss and /clear, with an opt-in completion gate and multi-agent shared state. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard. Includes Arabic, German, Spanish, and Chinese (Simplified and Traditional).",
   "author": {
     "name": "OthmanAdi",

.codebuddy/skills/planning-with-files/SKILL.md

@@ -36,7 +36,7 @@ hooks:
         - type: command
           command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/inject-plan.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 
 ---
 

.codex/skills/planning-with-files/SKILL.md

@@ -36,7 +36,7 @@ hooks:
         - type: command
           command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 
 ---
 

.cursor/skills/planning-with-files/SKILL.md

@@ -36,7 +36,7 @@ hooks:
         - type: command
           command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 
 ---
 

.factory/skills/planning-with-files/SKILL.md

@@ -36,7 +36,7 @@ hooks:
         - type: command
           command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 ---
 
 # Planning with Files

.gemini/hooks/before-model.sh

@@ -19,7 +19,7 @@ CURRENT_PHASE=$(grep -m1 "^## Current Phase" "$PLAN_FILE" 2>/dev/null || grep -m
 if [ -n "$CURRENT_PHASE" ]; then
     PYTHON=$(command -v python3 || command -v python)
     ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "[planning-with-files] Current: $CURRENT_PHASE" 2>/dev/null || echo "\"\"")
-    echo "{\"additionalContext\":$ESCAPED}"
+    printf '%s\n' "{\"additionalContext\":$ESCAPED}"
 else
     echo '{}'
 fi

.gemini/hooks/before-tool.sh

@@ -23,7 +23,7 @@ PYTHON=$(command -v python3 || command -v python)
 if [ -n "$PYTHON" ]; then
     ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CONTEXT" 2>/dev/null)
     if [ -n "$ESCAPED" ] && [ "$ESCAPED" != "\"\"" ]; then
-        echo "{\"systemMessage\":$ESCAPED}"
+        printf '%s\n' "{\"systemMessage\":$ESCAPED}"
         exit 0
     fi
 fi

.gemini/hooks/session-end.sh

@@ -19,7 +19,7 @@ if [ -f "$SCRIPT_DIR/check-complete.sh" ]; then
     if [ -n "$RESULT" ]; then
         PYTHON=$(command -v python3 || command -v python)
         ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$RESULT" 2>/dev/null || echo "\"\"")
-        echo "{\"systemMessage\":$ESCAPED}"
+        printf '%s\n' "{\"systemMessage\":$ESCAPED}"
         exit 0
     fi
 fi

.gemini/hooks/session-start.sh

@@ -24,7 +24,7 @@ fi
 
 if [ -n "$CATCHUP" ]; then
     ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CATCHUP" 2>/dev/null || echo "\"[planning-with-files] Session recovery data available. Read task_plan.md, progress.md, and findings.md.\"")
-    echo "{\"hookSpecificOutput\":{\"additionalContext\":$ESCAPED}}"
+    printf '%s\n' "{\"hookSpecificOutput\":{\"additionalContext\":$ESCAPED}}"
 else
     echo '{"hookSpecificOutput":{"additionalContext":"[planning-with-files] Active plan detected. Read task_plan.md, progress.md, and findings.md before proceeding."}}'
 fi

.github/hooks/scripts/error-occurred.sh

@@ -21,7 +21,7 @@ for _p in /usr/bin/python3 /usr/local/bin/python3 /opt/homebrew/bin/python3; do
     [ -x "$_p" ] && { PYTHON="$_p"; break; }
 done
 [ -z "$PYTHON" ] && PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
-ERROR_MSG=$($PYTHON -c "
+ERROR_MSG=$(printf '%s\n' "$INPUT" | $PYTHON -c "
 import sys, json
 try:
     data = json.load(sys.stdin)
@@ -29,12 +29,12 @@ try:
     print(msg[:200])
 except:
     print('')
-" <<< "$INPUT" 2>/dev/null || echo "")
+" 2>/dev/null || echo "")
 
 if [ -n "$ERROR_MSG" ]; then
     CONTEXT="[planning-with-files] Error detected: ${ERROR_MSG}. Log this error in task_plan.md under Errors Encountered with the attempt number and resolution."
-    ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CONTEXT" 2>/dev/null || echo "\"\"")
-    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"ErrorOccurred\",\"additionalContext\":$ESCAPED}}"
+    ESCAPED=$(printf '%s\n' "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
+    printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"ErrorOccurred\",\"additionalContext\":$ESCAPED}}"
 else
     echo '{}'
 fi

.github/hooks/scripts/pre-tool-use.sh

@@ -33,5 +33,5 @@ done
 [ -z "$PYTHON" ] && PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
 ESCAPED=$(echo "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
 
-echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":$ESCAPED}}"
+printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":$ESCAPED}}"
 exit 0

.github/hooks/scripts/session-start.sh

@@ -45,5 +45,5 @@ fi
 # Escape context for JSON
 ESCAPED=$(echo "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
 
-echo "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":$ESCAPED}}"
+printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":$ESCAPED}}"
 exit 0

.hermes/skills/planning-with-files/SKILL.md

@@ -2,7 +2,7 @@
 name: planning-with-files
 description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Hermes adaptation with minimal notes."
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 ---
 
 > Hermes note: lifecycle automation for this skill is provided by the Hermes adapter plugin in `.hermes/plugins/planning-with-files/`.

.mastracode/skills/planning-with-files/SKILL.md

@@ -36,7 +36,7 @@ hooks:
         - type: command
           command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 
 ---
 

.opencode/skills/planning-with-files/SKILL.md

@@ -36,7 +36,7 @@ hooks:
         - type: command
           command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.config/opencode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.opencode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 
 ---
 

.pi/skills/planning-with-files/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planning-with-files",
-  "version": "3.10.2",
+  "version": "3.11.2",
   "description": "Persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md and progress.md on disk so the plan survives /clear, context loss and compaction. Manus-style. Ships the skill plus a Pi Coding Agent extension.",
   "keywords": [
     "pi-package",

AGENTS.md

@@ -38,11 +38,11 @@ The maintained release set has 19 entries: 18 tracked files plus the gitignored
 | File | Notes |
 |------|-------|
 | `skills/planning-with-files/SKILL.md` | Primary English |
-| `skills/planning-with-files-ar/SKILL.md` | Arabic |
-| `skills/planning-with-files-de/SKILL.md` | German |
-| `skills/planning-with-files-es/SKILL.md` | Spanish |
-| `skills/planning-with-files-zh/SKILL.md` | Simplified Chinese |
-| `skills/planning-with-files-zht/SKILL.md` | Traditional Chinese |
+| `skills/i18n/planning-with-files-ar/SKILL.md` | Arabic |
+| `skills/i18n/planning-with-files-de/SKILL.md` | German |
+| `skills/i18n/planning-with-files-es/SKILL.md` | Spanish |
+| `skills/i18n/planning-with-files-zh/SKILL.md` | Simplified Chinese |
+| `skills/i18n/planning-with-files-zht/SKILL.md` | Traditional Chinese |
 | `.codebuddy/skills/planning-with-files/SKILL.md` | CodeBuddy IDE |
 | `.codex/skills/planning-with-files/SKILL.md` | Codex IDE |
 | `.cursor/skills/planning-with-files/SKILL.md` | Cursor IDE |

CHANGELOG.md

@@ -2,6 +2,78 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.11.2] - 2026-08-22
+
+### Fixed
+- **The two manual skills-only install commands copied the whole `skills/` directory after the language variants moved under `skills/i18n/` (PR #229 by @dylanpulver).** The Unix and PowerShell instructions now copy only `skills/planning-with-files`, so an English install no longer creates an unusable `~/.claude/skills/i18n/` entry or places the five translations one directory below the paths their commands probe.
+- **A fresh manual install could flatten the canonical skill into `~/.claude/skills/`.** With one source directory and no existing destination, `cp` and `Copy-Item` can create the destination from the source contents, leaving `SKILL.md` directly under `skills/`. Both instructions now create `~/.claude/skills` before copying the canonical skill directory into it.
+
+### Changed
+- `tests/test_plugin_skill_surface.py` now scans tracked Markdown for `cp` or `Copy-Item` commands that copy `skills/*` wholesale. It also locks the destination-creation step before both manual copies and falls back to a filesystem scan when Git is unavailable.
+
+### Verification
+- Required baseline before integration: 434 passed, 10 skipped, and 497 subtests passed.
+- Exact contributor head before the maintainer hardening: 435 passed, 10 skipped, and 497 subtests passed.
+- Amended release candidate: 436 passed, 10 skipped, and 499 subtests passed. GitHub Actions passed on Ubuntu, macOS, and Windows, and the Pi extension Vitest job passed.
+- `sync-ide-folders.py --verify` reports every maintained mirror in sync. `bump-version.py 3.11.2 --dry-run` resolves all 19 present parity targets with zero errors.
+
+### Thanks
+- Dylan traced the regression to the v3.11.0 language-directory move, found the only two whole-directory copy commands in tracked documentation, and added the guard that keeps that install shape out of future docs (PR #229).
+
+## [3.11.1] - 2026-08-21
+
+### Fixed
+- **The Copilot error hook could not be parsed by a POSIX shell (PR #228 by @dylanpulver).** `error-occurred.sh` fed both of its Python helpers with `<<<`, a bash here-string that dash does not implement. `tests/test_planning_disabled_optout.py` invokes the shell hooks as `["sh", script]`, so the `#!/bin/bash` shebang never applied, and on ubuntu runners, where `/bin/sh` is dash, the file died at line 32 with `Syntax error: redirection unexpected`. Master CI had failed on the ubuntu leg for five consecutive runs. Both call sites now pipe with `printf '%s\n'`. The four sibling hooks pipe with `echo`, and that form was deliberately not copied: dash's builtin `echo` expands backslash escapes, so an escaped newline inside an error message would come back as a real control character and `json.load` would reject it, trading a loud parse failure for a silent one. No user was affected, because `.github/hooks/planning-with-files.json` invokes the hook under a `bash` key, which bypasses both the shebang and the exec bit. This is a CI and portability fix.
+- The v3.11.0 changelog entry warning that shell hooks must not emit JSON with `echo` contained two raw newlines of its own, inside the code spans for `\n` and `printf '%s\n'`. The escapes were expanded when the entry was written, which broke both spans across lines.
+
+### Verification
+- The failure was reproduced locally against real dash rather than taken from the report: the pre-fix hook exits 2 with `Syntax error: redirection unexpected` at line 32, matching the ubuntu log verbatim, and the post-fix hook exits 0 and emits valid JSON with the newline escaped as two characters.
+- All five scripts in `.github/hooks/scripts/` were parsed under a POSIX shell. Before the change `error-occurred.sh` was the only one that failed, and after it none do.
+- The reasoning for avoiding `echo` was checked directly. Under dash, `echo` on the raw payload produces a literal newline and `json.load` rejects it with `Invalid control character`, while `printf '%s\n'` round trips.
+- Full Python suite on Windows: 434 passed, 10 skipped, 497 subtests passed.
+
+### Known limitations
+- The four `.gemini/hooks/*.sh` still carry `<<<`. Nothing runs them through `sh`, and `.gemini/settings.json` invokes them by path so their shebang applies, so they are out of scope here. `.gemini` is on the intentionally lagging list and moving it needs its own scope decision.
+
+### Thanks
+- Dylan found this in CI rather than in a bug report, reproduced the ubuntu condition locally instead of guessing at it, and confirmed the suite actually exercises the path by reverting his own change. He also declined the obvious fix: copying the `echo` form used by the four sibling hooks would have made the syntax error disappear while introducing a silent JSON corruption, and he said so in the pull request instead of leaving it to review. The scope note on `.gemini` is accurate on every point (PR #228).
+
+## [3.11.0] - 2026-08-20
+
+### Changed
+- **The plugin registers one skill instead of six (closes #130, reported by @sean3808; implemented by @dylanpulver in PR #226).** The five language variants moved from `skills/planning-with-files-<lang>/` to `skills/i18n/planning-with-files-<lang>/`. Nothing was deleted, renamed or merged. All five skill names, all five `npx skills add --skill` commands, and all five install destinations are exactly what they were. One directory of depth is the whole mechanism: Claude Code discovers a plugin's skills by scanning `skills/*/SKILL.md` at a single level without recursing, so a variant one level down is not registered on the plugin route, while `npx skills add` resolves `--skill` by skill name across a recursive scan and does not care about depth.
+- **The five language commands read their translated skill from disk.** `/plan-ar`, `/plan-de`, `/plan-es`, `/plan-zh` and `/plan-zht` now read `$HOME/.claude/skills/planning-with-files-<lang>/SKILL.md` first, then `${CLAUDE_PLUGIN_ROOT}/skills/i18n/planning-with-files-<lang>/SKILL.md`, and fall back to the canonical skill with an explicit instruction to keep working in that language. Each one also states that the status tokens stay literal English, because `check-complete.sh` matches them with `grep -F` and a translated token silently disables the completion gate.
+
+### Fixed
+- The second candidate path in the five language commands pointed at the marketplace clone rather than the running plugin. That clone tracks the default branch while an installed plugin is version-pinned, and it does not exist at all under `CLAUDE_CONFIG_DIR` or the zip-cache route. `${CLAUDE_PLUGIN_ROOT}` is substituted by the loader and is what the repository already uses in command prose.
+- `README.md` still advertised the five variant skill ids as model-invocable, which stops being true once the plugin no longer registers them.
+- **Seven shell hooks could emit JSON with a raw control character on macOS (reported by @dylanpulver).** They build their payload by interpolating a `json.dumps` result and emitting it with `echo`. Under their own `#!/bin/bash` shebang that is correct, but run with `sh` on macOS, where `/bin/sh` is bash in POSIX mode with `xpg_echo` set, `echo` turns the escaped `\n` inside the string back into a real newline and every parser rejects the result. All seven now use `printf '%s\n'`, which never interprets backslashes. Found while rebasing #226, with the one-line repro supplied.
+
+### Added
+- **`docs/languages.md`.** The five translations had no documentation page of their own: `docs/` carried a setup guide for every supported IDE and nothing for languages, and `docs/installation.md` did not mention them at all. Six lines in the README were the entire discovery path, which mattered less while the plugin auto-registered the variants and is now the only way in. The new page covers the table of names and commands, the install command per language, the repository layout, how the language commands behave on the plugin route, and why the status tokens stay literal English. Linked from the README and from `docs/installation.md`.
+
+### Verification
+- Measured against the real Claude Code loader rather than inferred. Debug output on the merged tree: `Loaded 1 skills from plugin ... default directory`, down from 6. Component inventory 19 to 14, projected always-on cost roughly 2,254 to 1,042 tokens per session. All thirteen slash commands survive, including the five language ones.
+- The skills CLI still discovers all seven skills in the moved layout by name. `npx skills add . --skill planning-with-files-de` in an isolated home installs to the same destination as before, with the translated SKILL.md and the full 20-script surface, and pulls in nothing else.
+- The German template writes literal `**Status:** in_progress` and the German `check-complete.sh` matches that exact string, so the completion gate is intact for non-English users.
+- Full Python suite: 434 passed, 10 skipped, 497 subtests passed. `sync-ide-folders.py --verify` clean. `bump-version.py` resolves the parity set at the new paths.
+- All 120 moved files are pure renames. No translated content was altered.
+
+### Known limitations
+- An existing variant install records the old path in its skills lock file, so `npx skills update` cannot resolve it until the skill is reinstalled. The installed skill keeps working and a fresh install always works. No change to this PR can avoid it; it is inherent to moving a directory.
+
+### Thanks
+
+This one took four attempts across seven months of the issue tracker to answer, so credit goes to everyone who pushed on it.
+
+- Sean opened #130 in April with the analysis that framed the whole problem: the scripts and templates were identical, only the prose differed, and the six skills were costing every session five descriptions it did not need. Every later attempt is a variation on that report.
+- Dylan wrote the answer that shipped (#226). He found the one-level plugin scan, checked the install route rather than assuming it, and carried the literal English status-token warning into all five commands where a previous attempt had not. He also named the one cost he could not remove, which is what made the change reviewable.
+- Som audited the five variants against the canonical skill in #216 and proved the drift #130 predicted: twelve missing scripts, a missing Windows UTF-8 fix, and sync tooling that covered only three dispatch targets. That analysis shipped as v3.10.0 and had to land before this change was safe.
+- Abdullah asked in #151 for a single canonical source with a CI parity gate. The gate shipped in v2.37.0 and is the reason this move could be verified rather than hoped at.
+- The earliest two reports were about the same duplication from the other direction: #53 by @back1ply proposed collapsing the eight client folders into one source, and #47 by @tiptinker asked for the Anthropic skills layout. Both are why `sync-ide-folders.py` exists.
+
+**On why this took so long.** The obvious fix was to delete the five directories, and it was proposed more than once. It could not be taken. Skill listings on a public directory cannot be retracted once published, so deleting the folders would not have removed the entries; it would have left five permanent listings whose install command had started to fail, which is worse for the people using them than either keeping or removing them. The variants also have real users who chose them deliberately, and a breaking change to a working install is not a reasonable price for a packaging problem. What was needed was a route that changes nothing anyone depends on, and it took until #226 to find one. The delay was not indecision about whether the problem was real. It was refusing to fix it by breaking installs.
+
 ## [3.10.2] - 2026-08-19
 
 ### Fixed

CITATION.cff

@@ -7,8 +7,8 @@ authors:
   - family-names: Adi
     given-names: Ahmad Othman Ammar
     alias: OthmanAdi
-version: "3.10.2"
-date-released: "2026-08-14"
+version: "3.11.2"
+date-released: "2026-08-22"
 license: MIT
 url: "https://github.com/OthmanAdi/planning-with-files"
 repository-code: "https://github.com/OthmanAdi/planning-with-files"

CONTRIBUTING.md

@@ -45,9 +45,11 @@ skills/planning-with-files/
 Language variants live under directories that follow this pattern:
 
 ```text
-skills/planning-with-files-<lang>/
+skills/i18n/planning-with-files-<lang>/
 ```
 
+Keep them one directory below `skills/`. The Claude Code plugin scan reads `skills/*/SKILL.md` and does not recurse, so a variant placed directly under `skills/` is registered for every plugin user and its description is added to every session's system prompt. `tests/test_plugin_skill_surface.py` fails if that happens.
+
 IDE adapter variants live under these directories:
 
 ```text

CONTRIBUTORS.md

@@ -374,6 +374,9 @@ Thank you to everyone who reported issues, provided feedback, and helped test fi
 
 - [@Whxuan0701](https://github.com/Whxuan0701) (WeiHaoxuan) - [PR #223](https://github.com/OthmanAdi/planning-with-files/pull/223), [PR #222](https://github.com/OthmanAdi/planning-with-files/pull/222), [PR #224](https://github.com/OthmanAdi/planning-with-files/pull/224) (found that the `PLANNING_DISABLED=1` opt-out from #195 had never reached any of the ten GitHub Copilot hook entry points, that the #191 zero-phase guard was missing from the Copilot PowerShell stop hook, and that the Hermes determinism probe hardcoded `python` so it could not run where only `python3` exists; three single-commit PRs, each with a test that executes the real script. Auditing them surfaced three further defects fixed in the same release: the Cursor route had the same opt-out gap across all eight of its hooks, the disabled `PreToolUse` branch was widening Copilot's permissions rather than staying neutral, and `error-occurred.ps1` had never logged an error on Windows because it read stdin into PowerShell's automatic `$input` variable)
 
+- [@dylanpulver](https://github.com/dylanpulver) (Dylan Pulver) - [PR #226](https://github.com/OthmanAdi/planning-with-files/pull/226) (answered issue #130 after two earlier attempts could not be taken: moved the five language variants one directory deeper so the Claude Code plugin scan, which reads `skills/*/SKILL.md` without recursing, stops registering them, while every `npx skills add --skill` command keeps resolving because that resolver matches by skill name across a recursive scan. Cut the plugin's always-on cost by roughly half without deleting, renaming or breaking a single install. Verified the install route rather than assuming it, carried the literal English status-token warning into all five language commands where an earlier attempt had not, and named the one cost he could not remove), [PR #228](https://github.com/OthmanAdi/planning-with-files/pull/228) (fixed the Copilot error hook, which fed its Python helpers with bash here-strings that dash cannot parse, so master CI had failed on the ubuntu leg for five consecutive runs. Reproduced the ubuntu condition locally instead of working from the log, and confirmed the suite genuinely exercises the path by reverting his own change. Declined the fix that would have looked right: copying the four sibling hooks' `echo` form clears the syntax error but silently corrupts JSON under dash, and he wrote that into the pull request rather than leaving it for review), [PR #229](https://github.com/OthmanAdi/planning-with-files/pull/229) (found the two manual install commands still copying `skills/*` after the translations moved under `skills/i18n/`, corrected both to name the canonical skill, and added a tracked-Markdown guard against the old install shape)
+- [@sean3808](https://github.com/sean3808) (Sean) - [Issue #130](https://github.com/OthmanAdi/planning-with-files/issues/130) (opened the consolidation report in April 2026 with the analysis that framed the problem for every later attempt: identical scripts and templates, prose the only real difference, and five skill descriptions injected into every session that most users would never invoke; resolved in v3.11.0)
+
 And many others who have starred, forked, and shared this project!
 
 - **[@voidborne-d](https://github.com/voidborne-d)** - [PR #149](https://github.com/OthmanAdi/planning-with-files/pull/149)
@@ -400,6 +403,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
 
 ---
 
-**Total Contributors:** 52+ and growing!
+**Total Contributors:** 54+ and growing!
 
-*Last updated: August 19, 2026*
+*Last updated: August 22, 2026*

README.md

@@ -5,7 +5,12 @@
 <h1 align="center">Planning with Files</h1>
 
 <p align="center">
-  <strong>Your agent's context window dies. The plan does not.</strong>
+  <strong>The planning skill your agent cannot ignore.</strong><br>
+  Not a prompt it might follow. A hook that fires every turn, a plan on disk that survives <code>/clear</code>, and 3 out of 3 blind A/B wins to show it works.
+</p>
+
+<p align="center">
+  <em>Your agent's context window dies. The plan does not.</em>
 </p>
 
 <p align="center">
@@ -26,13 +31,15 @@ Persistent file-based planning for AI coding agents and long-running agent tasks
 </p>
 
 <p align="center">
-  <a href="#before-and-after-clear">Before/After</a> ·
-  <a href="#the-solution-3-file-pattern">The 3 Files</a> ·
-  <a href="#quick-install">Install</a> ·
-  <a href="#benchmark-results">Benchmarks</a> ·
-  <a href="#works-across-18-platforms">Platforms</a> ·
-  <a href="#faq">FAQ</a> ·
-  <a href="docs/installation.md">Full install guide</a>
+  <a href="#before-and-after-clear"><strong>See it survive /clear</strong></a> ·
+  <a href="#the-solution-3-file-pattern">The 3 files</a> ·
+  <a href="#why-this-skill">Why it works</a> ·
+  <a href="#benchmark-results">The numbers</a> ·
+  <a href="#quick-install"><strong>Install</strong></a>
+</p>
+
+<p align="center">
+  <sub>Everything technical is <a href="#reference">further down</a> · <a href="docs/installation.md">Full install guide</a></sub>
 </p>
 
 ---
@@ -102,45 +109,55 @@ your-project/
 
 Parallel tasks get isolated directories instead: `.planning/YYYY-MM-DD-slug/` with the same three files, selected via `.active_plan` (v2.36.0+). Plain markdown, gitignored by default, no runtime state anywhere else.
 
-## How It Works
+## Why This Skill?
 
-The agent stops at the first rung that applies:
+On 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.**
 
-```
-1. Task needs 3+ steps or 5+ tool calls?  → create the three files first
-2. Learned something?                     → append it to findings.md
-3. Did something?                         → log it in progress.md
-4. Phase done?                            → check it off in task_plan.md
-5. Context died (/clear, crash)?          → session catchup re-reads all three
-6. Every phase complete?                  → only then does the Stop gate release (gated mode)
-```
+> "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
 
-Hooks make steps 2 to 6 mechanical rather than optional: 5 lifecycle hooks on Claude Code, 7 on Codex, 8 on Pi re-inject the plan each turn, remind after writes, and check completion before stopping.
+This skill packages that exact pattern for your coding agent.
 
-```mermaid
-flowchart LR
-    A["agent works"] -->|"writes decisions, findings, errors"| F["task_plan.md<br/>findings.md<br/>progress.md"]
-    F -->|"hooks re-inject the plan<br/>at the start of each turn"| A
-    K["/clear · crash · compaction"] -.->|"wipes the context window"| A
-    F ==>|"session catchup re-reads the files"| R["fresh session resumes<br/>at the current phase"]
-```
+### The Manus Principles
 
-### Session Recovery
+| 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 |
 
-When your context fills up and you run `/clear`, the skill recovers the previous session automatically:
+## Benchmark Results
 
-1. Checks the active IDE's session store for previous session data (`~/.claude/projects/` for Claude Code, `~/.codex/sessions/` for Codex)
-2. Finds when the planning files were last updated
-3. Extracts the conversation that happened after (potentially lost context)
-4. Shows a catchup report so you can sync
+> **Methodology note:** the 96.7% figure comes from the v2.21.0 evaluation run on `claude-sonnet-4-6` (2026-03-06). It measures file-pattern fidelity (does the agent create and maintain the 3-file structure), not goal-drift over long autonomous runs. Newer models and the autonomous-mode work are not yet covered by this number. Full methodology, dataset, and assertion list: [docs/evals.md](docs/evals.md).
 
-**Pro tip:** disable auto-compact to maximize context before clearing:
+Evaluated with Anthropic's [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) framework: skill v2.21.0, model `claude-sonnet-4-6`, 2026-03-06. 10 parallel subagents, 5 task types, 30 objectively verifiable assertions, 3 blind A/B comparisons.
 
-```json
-{ "autoCompact": false }
-```
+<p align="center">
+  <img src="media/benchmark-skill-vs-baseline.svg" width="860" alt="Eval results, with skill vs without: assertions passed 29 of 30 vs 2 of 30, 3-file pattern followed 5 of 5 vs 0 of 5, blind A/B wins 3 of 3 vs 0 of 3, average rubric score 10.0 vs 6.8">
+</p>
 
-Maintainer depth (hook architecture, dispatcher layout, parity tooling) lives in [AGENTS.md](AGENTS.md) and [docs/](docs/).
+| 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 |
+
+### Recovery after a context wipe
+
+> **Internal benchmark, v1 (2026-07-06).** Author-run against v3.4.0, harness-authored tasks, deterministic grading, no LLM grades anything. Treat it as the project's own measurement, not an independent comparison. Full method, arms, disclosed limits, and grader validation: [docs/evals.md](docs/evals.md#test-5-competitive-benchmark-v1-seven-planning-methods-head-to-head-2026-07-06-internal).
+
+Protocol: the session is hard-stopped at roughly half done, and a fresh session is told only "Continue the work in this directory." Every graded run across every arm ended pytest-green (77/77), so the difference is re-orientation cost, not correctness.
+
+<p align="center">
+  <img src="media/recovery-turns.svg" width="860" alt="Turns to resume after a context wipe, internal benchmark v1: 5.0 with planning-with-files, 13.3 for a raw agent with no planning method">
+</p>
+
+**With the planning files on disk, a resume took 5.0 turns on average; a raw agent took 13.3.** Session catchup plus hook injection put phase state in front of the model before its first tool call, and the same run found no correctness penalty anywhere. An animated summary lives at [docs/benchmark/index.html](docs/benchmark/index.html) ([rendered view](https://htmlpreview.github.io/?https://github.com/OthmanAdi/planning-with-files/blob/master/docs/benchmark/index.html)).
+
+[Full methodology and results](docs/evals.md) · [Technical write-up](docs/article.md)
 
 ## Quick Install
 
@@ -217,7 +234,9 @@ 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. See [issue #130](https://github.com/OthmanAdi/planning-with-files/issues/130) for why they stay separate skills rather than collapsing into one.
+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](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>
 
@@ -240,6 +259,67 @@ Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-f
 
 All install methods: [docs/installation.md](docs/installation.md).
 
+
+---
+
+<a id="reference"></a>
+
+## Reference
+
+Everything below is the technical half: how the hooks fire, every command, every supported platform, and the release history.
+
+| | |
+|---|---|
+| [How It Works](#how-it-works) | The hook loop, injection, and session recovery |
+| [Commands](#commands) | All 13 slash commands |
+| [Works across 18+ platforms](#works-across-18-platforms) | Per-IDE setup and discovery paths |
+| [v3 Long-Running Agent Features](#v3-long-running-agent-features) | Modes, the completion gate, attestation, env vars |
+| [Key Rules](#key-rules) · [When to Use](#when-to-use) | The four rules, and when the pattern pays off |
+| [File Structure](#file-structure) | What lands in your project, and the repository layout |
+| [FAQ](#faq) | Context rot, plan mode, agent memory tools |
+| [Releases](#releases) · [Community](#community) | Version history and community forks |
+| [Documentation](#documentation) | Every guide in `docs/` |
+
+## How It Works
+
+The agent stops at the first rung that applies:
+
+```
+1. Task needs 3+ steps or 5+ tool calls?  → create the three files first
+2. Learned something?                     → append it to findings.md
+3. Did something?                         → log it in progress.md
+4. Phase done?                            → check it off in task_plan.md
+5. Context died (/clear, crash)?          → session catchup re-reads all three
+6. Every phase complete?                  → only then does the Stop gate release (gated mode)
+```
+
+Hooks make steps 2 to 6 mechanical rather than optional: 5 lifecycle hooks on Claude Code, 7 on Codex, 8 on Pi re-inject the plan each turn, remind after writes, and check completion before stopping.
+
+```mermaid
+flowchart LR
+    A["agent works"] -->|"writes decisions, findings, errors"| F["task_plan.md<br/>findings.md<br/>progress.md"]
+    F -->|"hooks re-inject the plan<br/>at the start of each turn"| A
+    K["/clear · crash · compaction"] -.->|"wipes the context window"| A
+    F ==>|"session catchup re-reads the files"| R["fresh session resumes<br/>at the current phase"]
+```
+
+### Session Recovery
+
+When your context fills up and you run `/clear`, the skill recovers the previous session automatically:
+
+1. Checks the active IDE's session store for previous session data (`~/.claude/projects/` for Claude Code, `~/.codex/sessions/` for Codex)
+2. Finds when the planning files were last updated
+3. Extracts the conversation that happened after (potentially lost context)
+4. Shows a catchup report so you can sync
+
+**Pro tip:** disable auto-compact to maximize context before clearing:
+
+```json
+{ "autoCompact": false }
+```
+
+Maintainer depth (hook architecture, dispatcher layout, parity tooling) lives in [AGENTS.md](AGENTS.md) and [docs/](docs/).
+
 ## Commands
 
 Slash commands ship with the Claude Code plugin route (see the install matrix above).
@@ -280,7 +360,7 @@ On Pi there is no `/plan` command to create the files; the skill creates them, t
 | Pi | bare form, no prefix | `/plan-status`, `/plan-execute`, `/plan-goal` |
 | Continue.dev | `/planning-with-files` | |
 
-The model-invocable SKILLS are named `planning-with-files:planning-with-files` (and `-ar`, `-de`, `-es`, `-zh`, `-zht`); the doubled form is the skill id, not a command you type. There is no `/pwf-de` and no `/planning-with-files:planning-with-files-goal`; `/pwf` is just a short alias for `/plan`.
+On the plugin route the model-invocable SKILL is `planning-with-files:planning-with-files`; the doubled form is the skill id, not a command you type. The five language variants live under `skills/i18n/`, which the plugin scan does not reach, so there is no `planning-with-files:planning-with-files-de` to invoke by name — reach a translation through its `/plan-ar`, `/plan-de`, `/plan-es`, `/plan-zh` or `/plan-zht` command, or install it as its own skill with `npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g`, which registers it under its own name. There is no `/pwf-de` and no `/planning-with-files:planning-with-files-goal`; `/pwf` is just a short alias for `/plan`.
 
 ## Works across 18+ platforms
 
@@ -339,56 +419,6 @@ One skill, three integration tiers. Know what your agent gets before you install
 
 </details>
 
-## Why This Skill?
-
-On 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.**
-
-> "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
-
-This skill packages that exact pattern for your coding agent.
-
-### The Manus Principles
-
-| 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 |
-
-## Benchmark Results
-
-> **Methodology note:** the 96.7% figure comes from the v2.21.0 evaluation run on `claude-sonnet-4-6` (2026-03-06). It measures file-pattern fidelity (does the agent create and maintain the 3-file structure), not goal-drift over long autonomous runs. Newer models and the autonomous-mode work are not yet covered by this number. Full methodology, dataset, and assertion list: [docs/evals.md](docs/evals.md).
-
-Evaluated with Anthropic's [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) framework: skill v2.21.0, model `claude-sonnet-4-6`, 2026-03-06. 10 parallel subagents, 5 task types, 30 objectively verifiable assertions, 3 blind A/B comparisons.
-
-<p align="center">
-  <img src="media/benchmark-skill-vs-baseline.svg" width="860" alt="Eval results, with skill vs without: assertions passed 29 of 30 vs 2 of 30, 3-file pattern followed 5 of 5 vs 0 of 5, blind A/B wins 3 of 3 vs 0 of 3, average rubric score 10.0 vs 6.8">
-</p>
-
-| 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 |
-
-### Recovery after a context wipe
-
-> **Internal benchmark, v1 (2026-07-06).** Author-run against v3.4.0, harness-authored tasks, deterministic grading, no LLM grades anything. Treat it as the project's own measurement, not an independent comparison. Full method, arms, disclosed limits, and grader validation: [docs/evals.md](docs/evals.md#test-5-competitive-benchmark-v1-seven-planning-methods-head-to-head-2026-07-06-internal).
-
-Protocol: the session is hard-stopped at roughly half done, and a fresh session is told only "Continue the work in this directory." Every graded run across every arm ended pytest-green (77/77), so the difference is re-orientation cost, not correctness.
-
-<p align="center">
-  <img src="media/recovery-turns.svg" width="860" alt="Turns to resume after a context wipe, internal benchmark v1: 5.0 with planning-with-files, 13.3 for a raw agent with no planning method">
-</p>
-
-**With the planning files on disk, a resume took 5.0 turns on average; a raw agent took 13.3.** Session catchup plus hook injection put phase state in front of the model before its first tool call, and the same run found no correctness penalty anywhere. An animated summary lives at [docs/benchmark/index.html](docs/benchmark/index.html) ([rendered view](https://htmlpreview.github.io/?https://github.com/OthmanAdi/planning-with-files/blob/master/docs/benchmark/index.html)).
-
-[Full methodology and results](docs/evals.md) · [Technical write-up](docs/article.md)
-
 ## v3 Long-Running Agent Features
 
 The v3 line adds features aimed at long-running agentic runs. Each one is listed with the command or flag that turns it on. With no mode marker set, the hooks produce the same output as v2.43, so nothing changes for existing setups.
@@ -461,7 +491,7 @@ What the skill writes into your project is three markdown files (see [the 3-file
 ```
 planning-with-files/
 ├── skills/planning-with-files/   # canonical skill: SKILL.md, scripts/, templates/, reference.md, examples.md
-│   └── ...-ar / -de / -es / -zh / -zht    # 5 translated variants
+├── skills/i18n/                  # 5 translated variants: -ar / -de / -es / -zh / -zht
 ├── .agents/skills/planning-with-files/   # Agent Skills standard path, full surface (v3.7.0+)
 ├── commands/                     # 13 slash commands (plugin route only)
 ├── scripts/ · templates/        # root-level copies for CLAUDE_PLUGIN_ROOT
@@ -479,7 +509,11 @@ Every release maintains 18 tracked parity targets plus the gitignored ClawHub up
 
 </details>
 
-## FAQ
+<a id="faq"></a>
+
+<details>
+<summary><strong>❓ FAQ</strong></summary>
+
 
 ### How do I stop my coding agent from losing its plan after /clear or a crash?
 
@@ -509,11 +543,18 @@ They are working memory, not a tracked deliverable. `task_plan.md`, `findings.md
 
 One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from 2.0 to 2.4 seconds before it, and the injected plan block is KV-cache stable by construction. The plan stays in the attention window every turn, and `/clear` stops being fatal.
 
+</details>
+
+<a id="releases"></a>
+
 <details>
 <summary><strong>📦 Releases</strong></summary>
 
 | Version | Highlights |
 |---------|------------|
+| **v3.11.2** | **Skills-only manual installs now copy one skill at the documented depth** (PR #229 by @dylanpulver). The Unix and PowerShell commands name `skills/planning-with-files` instead of copying `skills/*`, so the `skills/i18n/` subtree no longer lands below the loader path. Both instructions create `~/.claude/skills` first, which keeps a fresh install from placing `SKILL.md` directly under `skills/`. A tracked-Markdown test rejects the old whole-directory copy shape and locks the destination-creation step. |
+| **v3.11.1** | **The Copilot error hook could not be parsed by a POSIX shell** (PR #228 by @dylanpulver). `error-occurred.sh` fed its two Python helpers with `<<<`, a bash here-string that dash does not implement, and the suite invokes the shell hooks as `sh script`, so the `#!/bin/bash` shebang never applied. On ubuntu runners the file died at line 32 with `Syntax error: redirection unexpected`, and master CI had failed on that leg for five consecutive runs. Both call sites now pipe with `printf '%s\n'`. The sibling `echo` form was deliberately not copied: dash expands backslash escapes, which would have traded a loud syntax error for silent JSON corruption. No user was affected, because Copilot invokes the hook under a `bash` key that bypasses the shebang. |
+| **v3.11.0** | **The plugin registers one skill instead of six** (closes #130, reported by @sean3808; implemented by @dylanpulver in PR #226). The five language variants moved from `skills/planning-with-files-<lang>/` to `skills/i18n/planning-with-files-<lang>/`. Nothing deleted, nothing renamed, every `npx skills add --skill` command unchanged: Claude Code scans `skills/*/SKILL.md` one level without recursing, while the skills CLI resolves `--skill` by name across a recursive scan. Measured against the real loader, not inferred: 6 registered skills to 1, 19 components to 14, always-on cost roughly 2,254 to 1,042 tokens per session, with all thirteen slash commands intact. `/plan-de` and its four siblings read their translated skill from disk and state that the status tokens stay literal English, because `check-complete.sh` matches them with `grep -F`. Also fixes seven shell hooks that could emit JSON with a raw control character when run under a POSIX-mode shell on macOS. |
 | **v3.10.2** | **`PLANNING_DISABLED=1` had never reached the GitHub Copilot or Cursor hooks** (PRs #223, #222 and #224, by @Whxuan0701). Both routes read `task_plan.md` directly instead of dispatching to the script that carries the #195 guard, so eighteen hook entry points ignored the opt-out entirely: a one-shot task sharing a working directory with an unrelated plan had no way to detach from it. Auditing the merge found three more: the disabled `PreToolUse` branch answered `permissionDecision: allow`, so turning the skill off widened Copilot's permissions instead of staying neutral; `.cursor/hooks/stop.ps1` was the last copy the #191 zero-phase guard never reached, still auto-continuing on `0/0 phases done`; and `error-occurred.ps1` had never logged an error on Windows because it read stdin into `$input`, PowerShell's automatic pipeline variable, which does not hold the assignment under `-File`. The opt-out tests now run every hook with the variable unset as well as set, because the disabled-only versions stayed green against a fleet gutted to emit `{}`. Suite 424 to 430. |
 | **v3.10.1** | **Codex context hooks now emit valid event JSON on Linux and macOS** (fixes #220, reported by @mfehlhaber). `SessionStart`, `UserPromptSubmit`, and `PreCompact` use the same adapter as Windows, so planning output beginning with `[` is no longer misread as malformed JSON. This release also aligns the tracked npm payload with the published 20-script package, corrects the release reference, and makes the version bumper safe to run without the gitignored ClawHub stage in a fresh clone. |
 | **v3.10.0** | **Two sessions sharing one plan directory could silently destroy each other's work** (closes #217, reported by @dubes394). Both read `task_plan.md`, both write it back, and the later write discards the earlier one's phases while injection, `plan-doctor` and the Stop gate all read the result as an ordinary edit. Attestation could not cover it: it compares against a baseline a human approved once, not against what the hooks last observed, and it is a read side gate that cannot stop the stale write. The guard compares progress rather than hashes, because a hash comparison flags a single agent's own edit on its very next fire; checked items and completed phases only go up during normal work, so a decrease means work is gone. Verifying #130 alongside it exposed that every non-English install was a subset install, missing attestation, the Stop gate, the ledger, phase status and plan-doctor entirely, plus a Windows UTF-8 crash fix that never left the canonical skill. Closed additively, 60 files created and 0 overwritten, with the translator-owned scripts pinned so no future sync can English them. Also fixes a README top that showed five labels and no numbers on a phone. Suite 411 to 417. |
@@ -582,6 +623,8 @@ One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from
 
 </details>
 
+<a id="community"></a>
+
 <details>
 <summary><strong>🌍 What the community shipped</strong></summary>
 

commands/plan-ar.md

@@ -2,7 +2,12 @@
 description: "بدء تخطيط الملفات بنمط Manus. إنشاء task_plan.md و findings.md و progress.md للمهام المعقدة."
 ---
 
-استدعاء مهارة planning-with-files:planning-with-files-ar وتنفيذ التعليمات بدقة.
+اقرأ نص المهارة العربية من أول مسار موجود من هذين المسارين ونفّذ تعليماته بدقة:
+
+- `$HOME/.claude/skills/planning-with-files-ar/SKILL.md`
+- `${CLAUDE_PLUGIN_ROOT}/skills/i18n/planning-with-files-ar/SKILL.md`
+
+إذا لم يكن أي من المسارين موجودًا، استدعِ مهارة planning-with-files:planning-with-files وتابع العمل باللغة العربية.
 
 إذا لم تكن ملفات التخطيط الثلاثة موجودة في مجلد المشروع الحالي، قم بإنشائها:
 - task_plan.md — للمراحل والتقدم والقرارات
@@ -10,3 +15,5 @@ description: "بدء تخطيط الملفات بنمط Manus. إنشاء task_p
 - progress.md — لسجل الجلسة
 
 ثم ارشد المستخدم خلال سير عمل التخطيط. جميع ملفات التخطيط يجب أن تكون باللغة العربية.
+
+تبقى علامات الحالة بالإنجليزية حرفيًا (`**Status:** in_progress` و `**Status:** complete`) لأن `check-complete.sh` يبحث عنها باستخدام `grep -F`، وترجمتها تُعطّل بوابة الإكمال.

commands/plan-de.md

@@ -2,7 +2,12 @@
 description: "Starte Manus-artige Dateiplanung. Erstelle task_plan.md, findings.md, progress.md für komplexe Aufgaben."
 ---
 
-Rufe die planning-with-files:planning-with-files-de Skill auf und folge den Anweisungen genau.
+Lies den deutschen Skill-Text aus dem ersten dieser Pfade, der existiert, und folge ihm genau:
+
+- `$HOME/.claude/skills/planning-with-files-de/SKILL.md`
+- `${CLAUDE_PLUGIN_ROOT}/skills/i18n/planning-with-files-de/SKILL.md`
+
+Existiert keiner der beiden Pfade, rufe die planning-with-files:planning-with-files Skill auf und arbeite auf Deutsch weiter.
 
 Wenn die drei Planungsdateien nicht im aktuellen Projektverzeichnis existieren, erstelle sie:
 - task_plan.md — für Phasen, Fortschritt und Entscheidungen
@@ -10,3 +15,5 @@ Wenn die drei Planungsdateien nicht im aktuellen Projektverzeichnis existieren,
 - progress.md — für Sitzungsprotokolle
 
 Dann führe den Benutzer durch den Planungs-Workflow. Alle Planungsdateien müssen auf Deutsch sein.
+
+Die Statuskennzeichen bleiben wörtlich englisch (`**Status:** in_progress`, `**Status:** complete`), weil `check-complete.sh` sie mit `grep -F` sucht. Eine Übersetzung würde das Abschluss-Gate abschalten.

commands/plan-es.md

@@ -2,7 +2,12 @@
 description: "Iniciar planificación de archivos estilo Manus. Crear task_plan.md, findings.md, progress.md para tareas complejas."
 ---
 
-Invocar la habilidad planning-with-files:planning-with-files-es y ejecutar sus instrucciones estrictamente.
+Lee el texto de la habilidad en español desde la primera de estas rutas que exista y síguelo estrictamente:
+
+- `$HOME/.claude/skills/planning-with-files-es/SKILL.md`
+- `${CLAUDE_PLUGIN_ROOT}/skills/i18n/planning-with-files-es/SKILL.md`
+
+Si ninguna de las dos rutas existe, invoca la habilidad planning-with-files:planning-with-files y continúa trabajando en español.
 
 Si los tres archivos de planificación no existen en el directorio del proyecto actual, créalos:
 - task_plan.md — para fases, progreso y decisiones
@@ -10,3 +15,5 @@ Si los tres archivos de planificación no existen en el directorio del proyecto
 - progress.md — para registro de sesión
 
 Luego guía al usuario a través del flujo de trabajo de planificación. Todos los archivos de planificación deben estar en español.
+
+Los marcadores de estado se mantienen literalmente en inglés (`**Status:** in_progress`, `**Status:** complete`) porque `check-complete.sh` los busca con `grep -F`. Traducirlos desactivaría la verificación de finalización.

commands/plan-zh.md

@@ -2,11 +2,18 @@
 description: "启动 Manus 风格的文件规划。为复杂任务创建 task_plan.md、findings.md、progress.md。"
 ---
 
-调用 planning-with-files:planning-with-files-zh 技能，并严格按照其指示执行。
+从以下路径中第一个存在的文件读取中文技能正文，并严格按照其指示执行：
+
+- `$HOME/.claude/skills/planning-with-files-zh/SKILL.md`
+- `${CLAUDE_PLUGIN_ROOT}/skills/i18n/planning-with-files-zh/SKILL.md`
+
+如果两个路径都不存在，请调用 planning-with-files:planning-with-files 技能，并继续用中文工作。
 
 如果当前项目目录中不存在以下三个规划文件，请创建它们：
 - task_plan.md — 用于阶段、进度和决策
 - findings.md — 用于研究和发现
 - progress.md — 用于会话日志
 
-然后引导用户完成规划工作流。所有规划文件内容使用中文。
+然后引导用户完成规划工作流。所有规划文件内容使用中文。
+
+状态标记保持英文原样（`**Status:** in_progress`、`**Status:** complete`），因为 `check-complete.sh` 使用 `grep -F` 匹配它们，翻译这些标记会使完成检查失效。

commands/plan-zht.md

@@ -2,7 +2,12 @@
 description: "啟動 Manus 風格的檔案規劃。為複雜任務建立 task_plan.md、findings.md、progress.md。"
 ---
 
-調用 planning-with-files:planning-with-files-zht 技能，並嚴格按照其指示執行。
+從以下路徑中第一個存在的檔案讀取繁體中文技能正文，並嚴格按照其指示執行：
+
+- `$HOME/.claude/skills/planning-with-files-zht/SKILL.md`
+- `${CLAUDE_PLUGIN_ROOT}/skills/i18n/planning-with-files-zht/SKILL.md`
+
+如果兩個路徑都不存在，請調用 planning-with-files:planning-with-files 技能，並繼續以繁體中文工作。
 
 如果當前專案目錄中不存在以下三個規劃檔案，請建立它們：
 - task_plan.md — 用於階段、進度和決策
@@ -10,3 +15,5 @@ description: "啟動 Manus 風格的檔案規劃。為複雜任務建立 task_pl
 - progress.md — 用於工作階段日誌
 
 然後引導使用者完成規劃工作流程。所有規劃檔案內容使用繁體中文。
+
+狀態標記保持英文原樣（`**Status:** in_progress`、`**Status:** complete`），因為 `check-complete.sh` 使用 `grep -F` 比對，翻譯這些標記會使完成檢查失效。

docs/installation.md

@@ -98,7 +98,8 @@ If you only want the skill without the full plugin structure:
 
 ```bash
 git clone https://github.com/OthmanAdi/planning-with-files.git
-cp -r planning-with-files/skills/* ~/.claude/skills/
+mkdir -p ~/.claude/skills
+cp -r planning-with-files/skills/planning-with-files ~/.claude/skills/
 ```
 
 ---
@@ -115,6 +116,16 @@ Then move `planning-with-files/` to `~/.claude/skills/`.
 
 ---
 
+## Installing a language variant
+
+The workflow ships in Arabic, German, Spanish and both Chinese scripts alongside English. Each is its own skill, installed by name:
+
+```bash
+npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g
+```
+
+Installing a translation does not install the English skill, and installing English does not pull in any translation. See [languages.md](languages.md) for the full table, the repository layout, and how the language commands behave on the plugin route.
+
 ## Verifying Installation
 
 After installation, verify the skill is loaded:

docs/languages.md

@@ -0,0 +1,67 @@
+# Language variants
+
+`planning-with-files` ships the planning workflow in six languages. The English skill is the canonical one. Arabic, German, Spanish, Simplified Chinese and Traditional Chinese are full translations: the SKILL.md body, the three templates, and the user-facing output of `check-complete`, `init-session` and `session-catchup` are all translated, and each variant carries the same 20 scripts as the canonical skill.
+
+| Language | Skill name | Command |
+|---|---|---|
+| English | `planning-with-files` | `/plan` |
+| العربية | `planning-with-files-ar` | `/plan-ar` |
+| Deutsch | `planning-with-files-de` | `/plan-de` |
+| Español | `planning-with-files-es` | `/plan-es` |
+| 简体中文 | `planning-with-files-zh` | `/plan-zh` |
+| 繁體中文 | `planning-with-files-zht` | `/plan-zht` |
+
+## Installing one
+
+Pass the skill name with `--skill`. Add `-g` to install globally rather than into the current project.
+
+```bash
+npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g
+npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g
+npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g
+npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g
+npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g
+```
+
+Each lands in its own directory, for example `~/.claude/skills/planning-with-files-de/`, and registers under its own name. Installing a translation does not install the English skill, and installing the English skill does not install any translation.
+
+Running `npx skills add OthmanAdi/planning-with-files` with no `--skill` opens a picker listing all available skills with none preselected, so nothing is installed that you did not choose.
+
+## Where they live in the repository
+
+```
+skills/
+├── planning-with-files/          canonical English skill
+└── i18n/
+    ├── planning-with-files-ar/
+    ├── planning-with-files-de/
+    ├── planning-with-files-es/
+    ├── planning-with-files-zh/
+    └── planning-with-files-zht/
+```
+
+Since v3.11.0 the translations sit one directory deeper than the canonical skill. `npx skills add` resolves `--skill` by skill name across a recursive scan, so every install command above is unchanged by that layout and every skill remains individually installable.
+
+## On the Claude Code plugin route
+
+The plugin scan reads `skills/*/SKILL.md` at a single level and does not recurse, so the plugin registers the canonical skill alone. That is deliberate. Before v3.11.0 the plugin registered all six, and every session paid for five skill descriptions in its system prompt whether or not the user had any use for them.
+
+The five language commands still work on the plugin route. `/plan-de` and its siblings read the translated SKILL.md from disk, trying `$HOME/.claude/skills/planning-with-files-<lang>/SKILL.md` first and then `${CLAUDE_PLUGIN_ROOT}/skills/i18n/planning-with-files-<lang>/SKILL.md`. If neither exists, the command falls back to the canonical skill with an instruction to keep working in that language.
+
+Because the plugin no longer registers them, there is no `planning-with-files:planning-with-files-de` skill id to invoke by name on that route. Reach a translation through its command, or install it as its own skill with the command above.
+
+## Status tokens stay in English
+
+Every translated `task_plan.md` template keeps the status markers as literal English:
+
+```markdown
+- **Status:** pending
+- **Status:** in_progress
+- **Status:** complete
+```
+
+The completion gate matches those exact strings with `grep -F`. Translating them silently disables the gate, so the surrounding prose is translated and the tokens are not. The five language commands state this explicitly so the model does not translate them either.
+
+## Reporting a translation problem
+
+Open an issue naming the language and quoting the text. Translations are contributed and reviewed by speakers, not machine generated, so corrections from native speakers are welcome and land in the next release.

docs/windows.md

@@ -35,7 +35,8 @@ git clone https://github.com/OthmanAdi/planning-with-files.git $env:USERPROFILE\
 
 ```powershell
 git clone https://github.com/OthmanAdi/planning-with-files.git
-Copy-Item -Recurse planning-with-files\skills\* $env:USERPROFILE\.claude\skills\
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills" | Out-Null
+Copy-Item -Recurse planning-with-files\skills\planning-with-files $env:USERPROFILE\.claude\skills\
 ```
 
 ---

scripts/_v240_update_hook_bodies.py

@@ -32,11 +32,11 @@ REPO_ROOT = Path(__file__).resolve().parents[1]
 
 PARITY_SKILLS = [
     "skills/planning-with-files/SKILL.md",
-    "skills/planning-with-files-ar/SKILL.md",
-    "skills/planning-with-files-de/SKILL.md",
-    "skills/planning-with-files-es/SKILL.md",
-    "skills/planning-with-files-zh/SKILL.md",
-    "skills/planning-with-files-zht/SKILL.md",
+    "skills/i18n/planning-with-files-ar/SKILL.md",
+    "skills/i18n/planning-with-files-de/SKILL.md",
+    "skills/i18n/planning-with-files-es/SKILL.md",
+    "skills/i18n/planning-with-files-zh/SKILL.md",
+    "skills/i18n/planning-with-files-zht/SKILL.md",
     ".codebuddy/skills/planning-with-files/SKILL.md",
     ".codex/skills/planning-with-files/SKILL.md",
     ".cursor/skills/planning-with-files/SKILL.md",

scripts/bump-version.py

@@ -13,7 +13,7 @@ Run before tagging a release:
 
 Maintained targets (19 entries: 18 tracked files plus optional local staging):
     skills/planning-with-files/SKILL.md            (canonical)
-    skills/planning-with-files-{ar,de,es,zh,zht}/SKILL.md
+    skills/i18n/planning-with-files-{ar,de,es,zh,zht}/SKILL.md
     .{codebuddy,codex,cursor,factory,hermes,mastracode,opencode}/skills/planning-with-files/SKILL.md
     .agents/skills/planning-with-files/SKILL.md    (Agent Skills standard layout)
     clawhub-upload/SKILL.md                        (gitignored; bumped when present)
@@ -42,11 +42,11 @@ REPO_ROOT = Path(__file__).resolve().parents[1]
 # kind: "skill_md", "plugin_json", "marketplace_json", "citation_cff"
 PARITY_FILES = [
     ("skills/planning-with-files/SKILL.md", "skill_md"),
-    ("skills/planning-with-files-ar/SKILL.md", "skill_md"),
-    ("skills/planning-with-files-de/SKILL.md", "skill_md"),
-    ("skills/planning-with-files-es/SKILL.md", "skill_md"),
-    ("skills/planning-with-files-zh/SKILL.md", "skill_md"),
-    ("skills/planning-with-files-zht/SKILL.md", "skill_md"),
+    ("skills/i18n/planning-with-files-ar/SKILL.md", "skill_md"),
+    ("skills/i18n/planning-with-files-de/SKILL.md", "skill_md"),
+    ("skills/i18n/planning-with-files-es/SKILL.md", "skill_md"),
+    ("skills/i18n/planning-with-files-zh/SKILL.md", "skill_md"),
+    ("skills/i18n/planning-with-files-zht/SKILL.md", "skill_md"),
     (".codebuddy/skills/planning-with-files/SKILL.md", "skill_md"),
     (".codex/skills/planning-with-files/SKILL.md", "skill_md"),
     (".cursor/skills/planning-with-files/SKILL.md", "skill_md"),

scripts/sync-ide-folders.py

@@ -273,13 +273,13 @@ LANG_EXTRA_SCRIPTS = HOOK_DISPATCH_SCRIPTS + [
     "scripts/set-active-plan.ps1",
 ]
 
-# Language variants (skills/planning-with-files-<lang>/): SKILL.md, templates
+# Language variants (skills/i18n/planning-with-files-<lang>/): SKILL.md, templates
 # and references are real translations and must NEVER be overwritten with the
 # English canonical. Same for LANG_TRANSLATED_SCRIPTS above. The rest of the
 # canonical script surface is synced so non-English installs get the same
 # features, not a subset (issue #212 covered only the 3 dispatch targets).
 for _lang in ("ar", "de", "es", "zh", "zht"):
-    _base = f"skills/planning-with-files-{_lang}"
+    _base = f"skills/i18n/planning-with-files-{_lang}"
     IDE_MANIFESTS[_base] = _build_manifest(
         _base,
         ref_style="skip",

skills/i18n/planning-with-files-ar/SKILL.md

@@ -36,7 +36,7 @@ hooks:
         - type: command
           command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-ar/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 ---
 
 # نظام تخطيط الملفات

skills/i18n/planning-with-files-de/SKILL.md

@@ -36,7 +36,7 @@ hooks:
         - type: command
           command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-de/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 ---
 
 # Dateiplanungssystem

skills/i18n/planning-with-files-es/SKILL.md

@@ -36,7 +36,7 @@ hooks:
         - type: command
           command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-es/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
 metadata:
-  version: "3.10.2"
+  version: "3.11.2"
 ---
 
 # Sistema de Planificación con Archivos