v2.34.1 — Stop hook Windows Git Bash fix

What changed

The Stop hook was silently failing on Windows 11 with Git Bash, specifically when running inside Command Prompt. Two separate bugs:

Bug 1: export SD= was treated as an external command instead of a shell builtin in certain Windows Git Bash invocation contexts. The error bash: export: No such file or directory was cosmetic noise on top of the real failure, but it meant the variable was never set.

Bug 2 (the real one for Claude Code): The fallback path $HOME/.claude/plugins/planning-with-files doesn't exist. The plugin installs to ~/.claude/plugins/cache/planning-with-files/planning-with-files/VERSION/ — a completely different location. So $SD was either empty or wrong, and both powershell.exe -File and sh calls failed.

What's fixed

Claude Code skill variants now use PowerShell's Get-ChildItem -Recurse to find check-complete.ps1 under ~/.claude/plugins/cache, with PowerShell's own ~ home expansion — no bash variable needed, no hardcoded path. The sh fallback uses a glob against the correct cache path. All other IDE variants (Codex, Cursor, CodeBuddy, Factory, Mastra Code, OpenCode) have export SD= replaced with SD=.

13 SKILL.md variants updated total.

How to update

npx skills add planning-with-files

Or if you installed via plugin:

claude plugin update

---

Reported by @nazeshinjite with an exceptionally clear diagnosis. Thank you.

v2.34.0 — Codex hooks restored, Tessl CI, spring cleaning

What's new in v2.34.0

Codex hooks restored (closes #132)

.codex/hooks.json and .codex/hooks/ scripts are back. These were added in v2.31.0 by @Leon-Algo (PR #120) and accidentally wiped during the v2.32.0 release cycle when master was rewritten.

Codex users now have full lifecycle hook parity with Claude Code, Cursor, and Copilot:

Hook	What It Does
SessionStart	Runs session catchup + injects active plan context
UserPromptSubmit	Re-injects plan and progress on every message
PreToolUse	Re-reads task_plan.md (top 30 lines) before Bash
PostToolUse	Reminds agent to update progress.md
Stop	Blocks once on incomplete phases, then re-prompts

A new test suite (tests/test_codex_hooks.py, 5 tests) covers hooks.json structure, SessionStart injection, PreToolUse systemMessage, PostToolUse reminder, and Stop block/allow behavior.

Tessl skill-review CI (PR #131)

.github/workflows/skill-review.yml now runs on every PR that touches a SKILL.md, posting quality scores and AI-suggested improvements as a PR comment. Contributors can type /apply-optimize to commit the suggestions directly. Non-blocking by default.

Exec bit fix (PR #122)

check-complete.sh and init-session.sh were tracked as 100644 (not executable) in the canonical source. Fixed to 100755. A regression test (tests/test_script_permissions.py) prevents this from recurring.

Bug fixes

• Duplicate metadata.version key removed from .codebuddy, .cursor, .mastracode, .opencode, and .codex SKILL.md files
• docs/codex.md rewritten to cover hooks installation, hooks protocol, workspace vs personal install, and troubleshooting

Contributors

4 contributors who were missed in previous releases are now properly credited in CONTRIBUTORS.md:

• @Leon-Algo — PRs #119, #120, #122 (Codex scripts, hooks, exec bits)
• @YSAA1 — PR #109 (Codex session-catchup fallback fix)
• @kevinaimonster — PR #108 (Simplified Chinese localization)
• @wd041216-bit — PR #107 (Community Built showcase)

@lasmarois's entry updated to include PR #37 (session-agnostic catchup scanning).

Total contributors: 32+

---

Thanks to @Leon-Algo for three separate PRs and for being patient while your hooks work was accidentally wiped. Thanks to @popey for the Tessl CI integration.

v2.33.0 — Multi-Language Expansion (Arabic, German, Spanish + Enhanced Chinese)

What's New

Multi-language expansion — planning-with-files now ships in 6 languages, making context engineering accessible to developers worldwide.

New Language Variants

Language	Skill	Install
🇸🇦 Arabic	planning-with-files-ar	npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g
🇩🇪 German	planning-with-files-de	npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g
🇪🇸 Spanish	planning-with-files-es	npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g
🇨🇳 Chinese (Simplified)	planning-with-files-zh	npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g
🇹🇼 Chinese (Traditional)	planning-with-files-zht	npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g

Changes

• Arabic (-ar) — Full localization with RTL support, Arabic phase headers and state labels
• German (-de) — Complete German localization of all scripts, templates, and SKILL.md
• Spanish (-es) — Comprehensive Spanish localization with consistent state labels
• Chinese Simplified (-zh) — All scripts now display Chinese messages (previously mixed with English)
• Chinese Traditional (-zht) — Refined localization throughout
• New commands — plan-ar.md, plan-de.md, plan-es.md for autocomplete in each language
• README — Language installers now in a clean collapsible section
• Fix — Removed duplicate version YAML key in zh and zht SKILL.md frontmatter (invalid YAML, would resolve to v2.32.0 in strict parsers)

Install (English)

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

View all language variants in the README

---

Full Changelog: https://github.com/OthmanAdi/planning-with-files/blob/master/CHANGELOG.md

v2.32.0 — Codex Session Catchup + Security Badge + Stop Hook Fix

What's new

Two community PRs landed today, plus a long-overdue version sync.

Codex Session Catchup Rewrite

session-catchup.py now reads Codex rollout JSONL from ~/.codex/sessions, prefers CODEX_THREAD_ID when skipping the current thread, filters subagent and tiny sessions, and detects planning-file updates from structured Codex patch_apply_end events.

This is a major rewrite (+1,945/−486 lines) that brings full session recovery parity to Codex users — the same catchup workflow Claude Code users have had since v2.2.0.

Loaditout Security Badge

The project earned an A-grade from Loaditout (top 20.5% of 20,000+ MCP servers scanned). The badge is now in the README.

Stop Hook Git Bash Fix

On Windows, Git Bash (MSYS2) was treating bare SD="/c/Users/..." as a command to execute instead of a variable assignment. Changed to export SD="..." across all 9 SKILL.md variants. Non-breaking for all other shells.

Version Sync

All 12 SKILL.md files, plugin.json, marketplace.json, and CITATION.cff were scattered across versions 2.22.0–2.26.1. Everything is now unified to 2.32.0.

---

Changes

• Codex session catchup (PR #124 by @ebrevdo)
• Loaditout A-grade security badge (PR #126, closes #123)
• Stop hook Git Bash (MSYS2) fix (PR #126, closes #125)
• Version bumped to 2.32.0 across all 12 SKILL.md files, plugin.json, marketplace.json, CITATION.cff
• CHANGELOG, CONTRIBUTORS, and README updated

Contributors

• @ebrevdo (Eugene Brevdo) — Codex session catchup rewrite (PR #124)
• @OthmanAdi (Ahmad Othman Ammar Adi) — Loaditout badge + Stop hook fix (PR #126)

Inspiration & Thanks

• @ebrevdo for the thorough Codex session format analysis and the clean test suite that came with the rewrite
• @mizaibear for reporting the Stop hook issue on Windows in #127 (same root cause as #125, confirmed independently)
• @Leon-Algo for the Codex hooks integration in v2.31.0 that made this catchup work possible
• Loaditout for the security audit — A-grade certification

Full changelog: CHANGELOG.md

v2.31.0 - Codex hooks.json integration

What's new

Codex now gets the full hooks integration it was always supposed to have.

The README has listed Codex as Skills + Hooks since the IDE branch launched, but the install guide only told users to copy the skill files. Nobody got hooks.json or the hooks folder. This release fixes that.

What's included

• .codex/hooks.json with all five lifecycle hooks: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop
• .codex/hooks/ with shell scripts reused from the Cursor integration and thin Python adapters that translate output into Codex's JSON hook protocol
• Rewritten docs/codex.md with a complete install guide covering workspace and personal installation, hooks merging, codex_hooks = true config, verification steps, and troubleshooting
• Regression tests for all five hooks in tests/test_codex_hooks.py

No changes to master, core skill, or any other IDE

This release only touches the ide/codex branch. The core skill and all other IDE integrations are unchanged.

Thanks to @Leon-Algo for the contribution.

v2.30.1

Fixed missing executable bits on Codex planning scripts. The three shell scripts under .codex/skills/planning-with-files/scripts/ were tracked as 100644 (not executable), so running them directly failed with permission denied. This restores the execute bits and adds a regression test.

What changed:

• check-complete.sh, init-session.sh, session-catchup.py now have correct file modes on the ide/codex branch
• New test: test_codex_script_permissions.py catches future permission regressions (skips on Windows where mode bits are unreliable)

Note: The same permission issue exists on other IDE branches. This release fixes Codex only. A broader fix across all IDE branches is tracked separately.

Thanks to @Leon-Algo for the fix (PR #119).

Full changelog: CHANGELOG.md

v2.30.0

Two things changed.

Path variable fix. All three skill variants (main, zh, zht) now use ${CLAUDE_SKILL_DIR} instead of ${CLAUDE_PLUGIN_ROOT} for script and template paths. Anthropic added this variable in Claude Code v2.1.69 (March 5) specifically so skills can reference their own directory. The old variable had path resolution failures on Windows and Linux (related to #32). The Stop hook keeps a 3-level fallback for backward compatibility: CLAUDE_SKILL_DIR, then CLAUDE_PLUGIN_ROOT, then a hardcoded path.

IDE configs moved to branches. All IDE-specific configurations (Cursor, Copilot, Gemini, Kiro, Codex, Mastra, CodeBuddy, Factory, OpenCode, Continue, Pi Agent) now live on their own branches instead of cluttering master. Master is just the core skill, templates, scripts, and docs. Each IDE branch has its version bumped to 2.30.0 and can be maintained independently.

Branches: ide/cursor, ide/codex, ide/continue, ide/gemini, ide/opencode, ide/codebuddy, ide/factory, ide/pi-agent, ide/kiro, ide/mastra, ide/copilot.

Also fixed: plugin.json and marketplace.json bumped from 2.23.0 to 2.30.0 (fixes #117). Analytics templates now correctly included in the skill directory for npx skills add installs.

Install command is the same as before:

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

Full changelog: CHANGELOG.md

v2.29.0 — Analytics Workflow Template

What's New

Analytics workflow template (PR #115 by @mvanhorn, addresses #103)

New --template analytics flag on init-session.sh and init-session.ps1 for data exploration and analysis workflows.

Usage

./scripts/init-session.sh --template analytics my-project

What it includes

• analytics_task_plan.md with 4 analytics-specific phases: Data Discovery, Exploratory Analysis, Hypothesis Testing, Synthesis
• analytics_findings.md with Data Sources table, Hypothesis Log, Query Results, and Statistical Findings sections
• Analytics-specific progress.md with a Query Log table instead of Test Results
• Default behavior unchanged. Existing users are not affected.

Thanks

• @mvanhorn (Matt Van Horn) for the implementation
• @sedlukha for the original feature request in #103

Full Changelog: v2.28.0...v2.29.0

v2.28.0 — Traditional Chinese (zh-TW) Skill Variant

What's New

Added Traditional Chinese (zh-TW) skill variant for Taiwan, Hong Kong, and Macau users.

Install

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

Changes

• Full Traditional Chinese translation of SKILL.md with localized hooks and trigger phrases
• Translated templates (task_plan.md, findings.md, progress.md)
• Localized scripts (check-complete, init-session, session-catchup)
• Cross-platform support (bash + PowerShell)

Contributors

• @waynelee2048 (PR #113)

Full Changelog: v2.27.0...v2.28.0

v2.27.0 — Kiro Agent Skill Support

What's New

• Kiro Agent Skill layout — full .kiro/skills/planning-with-files/ support with bootstrap scripts, steering integration, and planning templates. Replaces the old .kiro/scripts/ approach with Kiro's native Agent Skill format. (PR #112)
• Updated docs/kiro.md and sync script to match new layout

Contributors

• @EListenX (Yi Chenxi) — Kiro Agent Skill implementation

Full Changelog

v2.26.2...v2.27.0