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.
Version bump across the 19 parity targets, CHANGELOG, CONTRIBUTORS, and the
README releases row for the skills/i18n move that closes#130.
Also adds docs/languages.md, the page the translations never had, and
collapses the README FAQ by default.
The documented Pi install pointed at npm packages the maintainer does not
control: README and .pi docs at @tomxprime/planning-with-files (published
once at 1.1.0 on 2026-05-22, 15 releases behind), docs/pi-agent.md at
pi-planning-with-files (published from a fork at 1.0.1 on 2026-02-04).
Neither can be refreshed from this repo, so the canonical Pi install
handed users a stale snapshot.
Changes:
- .pi/skills/planning-with-files/package.json renamed to the unscoped
planning-with-files, version 3.9.0, matching the repo release.
- package.json files list gains negation patterns so node_modules,
__pycache__ and the extension package-lock never enter the tarball
(a dry-run pack from this machine was 179 MB unpacked without them,
66 kB with).
- Bundled extension package renamed planning-with-files-pi-extension;
lock file name and version synced (was stale at 1.1.0 vs 1.2.3).
- All live install docs point at pi install npm:planning-with-files.
- bump-version.py and test_skill_md_version_parity.py add the npm
package.json to the parity set (19 entries) so the npm version can
never silently drift from a release again. Publishing stays a manual
per-release step, documented in AGENTS.md.
The skill text described per tool call re-injection as "the +68% token tax
measured in the v2.21 eval". That eval measured total tokens for a whole task
with the skill against the same task without it, and its own write-up
attributes the difference to writing three structured files instead of one or
two. It never isolated recitation. Raised while answering #210; the wording
now states the measured per call figure instead of borrowing an unrelated
number.
PWF_PLAN_ROOT existed only in code comments and a refusal message, so the
escape hatch a user is told to reach for was undocumented. The skill now
explains the shared parent case and the ambiguity refusal, and the README
gains an environment variable table covering all seven knobs, several of which
had never been written down anywhere, including PWF_SESSION_ID.
README test count refreshed.
The Stop scalar never dispatched on macOS or Linux (the PowerShell branch
was always selected because check-complete.ps1 ships on every platform)
and was a silent no-op anywhere CLAUDE_SKILL_DIR was unset (the :- install
path fallback can never substitute because the probed variable is always a
non-empty string). Both the legacy completion advisory and the v3
completion gate were dead in those environments. The scalar now selects
targets by file existence and dispatches by platform, PowerShell only
under MINGW/MSYS/CYGWIN, sh elsewhere. Windows output is unchanged.
Patched in all 14 SKILL.md variants that carry the scalar.
session-catchup probed a ~/.claude/projects name that Claude Code never
writes for POSIX paths (leading dash stripped) or paths containing an
underscore (replaced with a dash), so recovery after /clear silently
found nothing there. The mapper now probes the exact spelling first,
keeps both legacy spellings for stores created by older versions, and
settles ambiguity via the cwd recorded in the newest session file.
Propagated to every shipped copy including the older-generation root,
.hermes, and .mastracode scripts.
Also: the attestation SHA cache is keyed on the absolute plan path so two
projects can no longer share a slot and report a false PLAN TAMPERED;
resolve-plan-dir.ps1 reaches parity with the sh resolver (slug filter,
task_plan.md requirement in the newest-dir scan, fail-closed containment);
ledger-append.sh no longer truncates summaries mid-codepoint (UTF-8-safe
trim via iconv with a pure-sh fallback).
New long-run features, all opt-in or additive: structure-aware injection
(PWF_INJECT=smart or an inject-smart .mode token) keeps the active phase,
phase counts, and the last three decisions in the window late in long
plans; a Next Step section in both plan templates plus a sixth reboot
question; session-catchup annotates tool results (ok or FAILED with the
first error line) instead of only listing attempts.
Infrastructure: macos-latest joins the CI matrix, a BSD-userland
simulation harness runs the script fleet without realpath, readlink,
flock, or sha256sum on the Linux leg, and .gitattributes pins LF for
scripts. SEO surfaces: llms.txt rewritten as a Q&A page, three
problem-query docs pages, plugin.json and CITATION.cff keyword hygiene.
Suite grows from 217 to 301 passed, 11 skipped, on Windows and both
existing CI legs; default hook output stays byte-identical to v2.43
(legacy invariant proven by the existing invariant tests).
Ships .agents/skills/planning-with-files/ so tools reading the
cross-tool Agent Skills path natively (Zed, Amp, Warp, Devin,
Antigravity, Gemini CLI, Cursor) discover the current skill from a
plain git clone. Full canonical surface: SKILL.md, references, six
templates, complete script set including hook dispatchers, ledger
tooling, and plan-doctor.
Wired into both maintenance systems so it cannot silently rot:
sync-ide-folders.py gains a .agents manifest (and now ships
plan-doctor.sh to every synced IDE folder), the SKILL.md joins the
bump-version.py parity set and the version-parity test (18 locked
entries). AGENTS.md and the bump-version.py docstring describe the
actual parity set. docs/gemini.md routes new installs through the
standard path instead of the intentionally lagged .gemini variant.
18-file parity bump to 3.7.0, CHANGELOG entry, README release row and
version heading.
installation.md now states what each install route actually ships (the
plugin route carries commands/ and reliable hook registration; npx
skills and manual copies do not), documents the project-trust gate that
silently disables project-level skills, and offers a one-line CLAUDE.md
trigger snippet: the July 2026 benchmark measured unforced skill
engagement at 60-67% while always-loaded rules lines engaged 100%.
The last two variant copies still teaching Manus-2025 "one tool call
per turn" (.factory, .mastracode) get the 2026 parallel-host update the
canonical reference.md already carries. kilocode.md notes the Windsurf
to Devin Desktop transition.
Adds an "After Completion" section to docs/workflow.md stating that the planning
files are ephemeral working memory, gitignored by default, and not archived
automatically, with guidance on retaining a completed plan and a note that a
completion-triggered archive step is a welcome opt-in extension. Pointers added in
docs/quickstart.md and a README FAQ entry. This writes down the lifecycle that
issue #14 answered only informally (#202).
Expands the README, additively and in the visible body, to document the command
surface that shipped across v2.33 through v3.4 but was never listed. The Claude
Code command table gains pwf, plan-goal, plan-loop, plan-attest, and the language
commands. New sections cover the Pi extension commands, a v3 long-running-agent
feature list, a hooks and modes reference across Claude Code, Codex, and Pi, and a
note on command names versus skill names (there is no /pwf-de and no
/planning-with-files:planning-with-files-goal). The File Structure block now lists
all 12 command files.
Codex on Windows runs each hook command through the native command
interpreter, not a POSIX shell. The .codex/hooks.json commands were POSIX
only (sh, python3, 2>/dev/null, $HOME, trailing || true), so python3 hit
the Microsoft Store alias, the redirection was an invalid path, and the
|| true success guard failed because true is not a Windows command. Every
hook exited non-zero and Codex reported "hook exited with code 1".
Add a per-hook commandWindows override, the sanctioned Codex mechanism.
The POSIX command is untouched, so macOS and Linux are byte for byte
unchanged. On Windows all seven hooks route through a new launcher,
.codex/hooks/pwf-hook.cmd, which picks a real Python (py -3, falling back
to python, never the Store python3 alias) and always exits 0. The three
shell hooks route through a new front door, .codex/hooks/run_sh.py.
codex_hook_adapter.run_shell_script resolves the Git for Windows sh.exe by
anchoring on git.exe and the standard install roots, so the shell scripts
run even when Git's usr\bin is off PATH, and hands session-catchup.py a
real interpreter via PYTHON_BIN. docs/codex.md Windows section rewritten.
Version bump 3.4.0 to 3.4.1 across the 17-file parity set. New tests: a
cross-platform guard that every hook declares a commandWindows free of the
POSIX tokens that break on Windows, and a Windows-only run_sh.py end-to-end
test. Reported by @mahdiit.
Rewrites the Benchmark v1 page and evals.md Test 5 to lead with what pwf wins:
a context-death resume in 5.0 turns (2.7x faster than a raw agent, 40 percent
fewer than the next method), correctness parity at 77/77, and the guarantees
table where pwf is the only method with automatic recovery, re-surfacing,
tamper-detection, isolation, and compaction. Triggering is reframed around the
like-for-like result (pwf leads superpowers 5 to 0). The single-machine Windows
per-fire timing is qualified as a local implementation detail under profiling,
not a headline. All numbers are unchanged and remain reproducible from the raw
runs. Docs only: no skill, hook, script, manifest, or version change.
First head-to-head of planning-with-files v3.4.0 against six alternative
planning methods (native, filesystem-notes, naive-plan, superpowers,
spec-kit, memory-bank) in one harness on claude-opus-4-8, graded by
deterministic oracles only. 77 cells, all disk-verified.
Reported honestly, losses first-class: task outcomes saturate (77/77 pass,
no arm wins on pass rate at this task size); unforced trigger rate is 60 to
67 percent and is the top backlog item; overhead is real (+50 to 100 percent
cost on small tasks, ~2s per hook fire on Windows). Where pwf leads: a resume
after context death takes 5.0 turns versus 8.3 to 13.3 for rivals, when the
plan exists. Adds docs/evals.md Test 5, docs/benchmark/index.html, one README
badge. No version bump, no skill, hook, script, or manifest changes.
Add an explicit /plan-execute approval command for the Pi extension so task_plan.md can be drafted and reviewed without activating plan injection, pre-tool recitations, post-write reminders, or auto-continue.
Scope approval to the current session and plan path, reset it on session lifecycle events, and document the passive review flow with focused runtime and docs coverage.
Version bumped to 3.2.0 across the 17 parity-locked files via
scripts/bump-version.py. .continue, .gemini, .pi, and .kiro lag
intentionally, now documented directly in AGENTS.md.
CHANGELOG, CONTRIBUTORS, and README updated. docs/evals.md gets a new
Test 4 documenting the functional verification of v3's long-running-session
mechanism on Windows, the two bugs it found, and what was fixed.
Three sections pointed users at .codebuddy/skills/planning-with-files/references/
for the task_plan.md, findings.md, and progress.md starter templates. Those
three files live in the skill's templates/ directory; references/ holds
examples.md and reference.md instead. Same mislabel PR #187 fixes in
antigravity.md, on a file outside that PR's scope.
PR #174 documented the cache at ${TMPDIR:-/tmp}/pwf-sha, the v2.40 location.
v3.0.0 moved it to $XDG_CACHE_HOME/pwf-sha (or $HOME/.cache/pwf-sha), with
/tmp only as the HOME-unset fallback (scripts/inject-plan.sh:165). Corrected the
documented location, keying precision (first 16 hex of SHA-256 of the plan
path), the clear command, container behavior (HOME is usually set), and the
SKILL.md cross-link that repeated the stale /tmp path.
Adds a bundled TypeScript extension under .pi/skills/planning-with-files/extensions/planning-with-files/
that maps Pi lifecycle events onto the same behavior the skill provides on Claude Code (PR #157 by
@TomXPRIME). Event surface: session_start, before_agent_start, tool_call, tool_result, agent_end,
session_before_compact, session_shutdown, input. Four modes: auto (DeepSeek-aware), parity,
cache-safe, notify. Attestation gate shares the v2.37 .attestation file. Four slash commands
registered (/plan-status, /plan-attest, /plan-goal, /plan-loop). 12 new contract tests.
Fixes docs/codex.md to use the canonical [features] hooks = true key (Issue #154 by @DLI1996),
with a deprecated-alias note so users on older configs keep working.
Version bumped to 2.39.0 across 14 SKILL.md variants, plugin.json, marketplace.json, CITATION.cff
via scripts/bump-version.py. .pi npm scheme bumped 1.0.1 -> 1.1.0 for the extension surface.
.continue, .gemini, .kiro lag intentionally.
Tests: 110 pass, 2 pre-existing Windows exec-bit failures unrelated to this release.
Closes#146, #147, #148.
Parallel plan isolation (#148, @shawnli1874): init-session.sh slug mode
creates .planning/YYYY-MM-DD-<slug>/ for each task. set-active-plan.sh/.ps1
switch the active plan pointer. resolve-plan-dir.sh/.ps1 provide the
resolution chain ($PLAN_ID env, .active_plan file, newest plan dir, legacy
fallback). All four Codex hooks route through the resolver. resolve_latest_dir
now requires task_plan.md to be present, preventing system dirs like sessions/
from being selected as plan dirs. short_uuid() probes each Python candidate
before trusting command -v, fixing silent failure on Windows Store aliases.
Codex session isolation (#146, @githubYiheng): sessions attach to a plan by
creating .planning/sessions/<session_id>.attached. user-prompt-submit.sh,
pre_tool_use.py, stop.py, and post_tool_use.py all gate on session attachment
before injecting context or blocking. Legacy mode preserved when
.planning/sessions/ does not exist.
Hermes integration notes (#147, @09ashishkapoor): docs/hermes.md gains an
Integration Notes section covering current support level, what is not full
parity with hook-native platforms, recommended integration pattern, and a
tradeoffs table.
34 new tests across five files. Version bumped to 2.36.0 across 14 SKILL.md
variants, plugin.json, marketplace.json, and CITATION.cff.
* feat: add Hermes adapter for planning-with-files
- add a Hermes project plugin with planning tools, status parsing, and reminder hooks
- add Hermes-specific skill and command wrappers while keeping the workflow close to upstream
- document generic Hermes installation and cover the adapter with focused unit tests
* fix: bundle Hermes skill assets and paths
Restores .codex/hooks.json and .codex/hooks/ scripts that were wiped when
master was rewritten during v2.32.0 (closes#132, original work by @Leon-Algo
in PR #120). Codex users now have full lifecycle hook parity with Claude Code,
Cursor, and Copilot: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse,
and Stop hooks all active.
Also includes:
- Tessl skill-review CI from PR #131 (@popey)
- Exec bit fix from PR #122 (@Leon-Algo) + regression test
- Duplicate metadata.version key fixed in .codebuddy, .cursor, .mastracode,
.opencode, and .codex SKILL.md files
- docs/codex.md rewritten to cover hooks installation and protocol
- CONTRIBUTORS.md: added @Leon-Algo, @YSAA1, @kevinaimonster, @wd041216-bit;
updated @lasmarois entry to include PR #37; total now 32+
- Version bumped to 2.34.0 across all 17 SKILL.md variants, plugin.json,
marketplace.json, and CITATION.cff
Adds full Kiro Agent Skill support with proper .kiro/skills/ layout,
bootstrap scripts, steering integration, and planning templates.
Replaces the old .kiro/scripts/ and .kiro/steering/ approach.
Also updates docs/kiro.md and sync-ide-folders.py skip list.
Contributed by Yi Chenxi (@EListenX)
v2.24.0 — Full IDE support audit and cleanup:
New features:
- Gemini CLI: add hooks (settings.json + 5 scripts: SessionStart, BeforeTool,
AfterTool, BeforeModel, SessionEnd). BeforeModel is unique to Gemini — injects
plan awareness before every model call.
- FactoryAI Droid: add hooks to SKILL.md frontmatter (was skills-only, now has
all 4 lifecycle events) + add scripts.
- GitHub Copilot: add errorOccurred hook for automatic error logging to plan.
Bug fixes:
- Continue: fix .prompt file — was entirely in Chinese, now English
- Pi Agent: fix package.json repo URL (was ttttmr/, now OthmanAdi/)
- Mastra Code: sync drifted check-complete.sh and session-catchup.py to canonical
- CodeBuddy/Codex: remove duplicate assets/templates/ directories
Consolidation:
- Remove .adal/, .agent/ (Antigravity), .kilocode/, .openclaw/ directories.
These IDEs implement the standard Agent Skills spec with no hooks — install
via `npx skills add` which handles IDE-specific placement automatically.
- README: restructure IDE table into Enhanced (hooks) vs Standard (Agent Skills)
- sync-ide-folders.py: remove entries for consolidated IDEs
Net: -4,609 lines (removed duplication, added real value)
Fixes#106. Three root causes identified and fixed:
1. Session catchup not working after /clear: Added UserPromptSubmit hook
to all 7 IDE SKILL.md files. When task_plan.md exists, injects a
directive to read all planning files before proceeding. Fires on every
user message, ensuring context recovery after /clear or compaction.
2. Progress not updating consistently: PostToolUse hook message now leads
with "Update progress.md" instead of only mentioning task_plan.md.
Added plan existence guard to avoid noise when no plan is active.
3. Post-plan additions not tracked: check-complete scripts now output
re-entry guidance when all phases are complete. Copilot agent-stop
scripts now return continuation context instead of empty JSON.
Added Critical Rule #7 (Continue After Completion) to SKILL.md body.
Applied across: 7 IDE SKILL.md files, 16 synced check-complete scripts,
4 Copilot hook scripts, CHANGELOG, plugin.json, marketplace.json.
Mastra Code reads hooks from .mastracode/hooks.json, not SKILL.md
frontmatter. All three hooks (PreToolUse, PostToolUse, Stop) were
silently non-functional. Added hooks.json with proper Mastra format
including matchers and timeouts. Fixed MASTRACODE_SKILL_ROOT env var
(does not exist in Mastra Code). Corrected docs/mastra.md to accurately
describe the hooks.json system and fixed personal install instructions
to include the hooks file.
Adds documentation and examples for running planning-with-files
inside BoxLite micro-VM sandboxes via ClaudeBox.
- docs/boxlite.md: full integration guide covering ClaudeBox Skill
API, persistent sessions, hooks behavior inside the VM, snapshots,
session recovery, and troubleshooting
- examples/boxlite/quickstart.py: working Python example using
ClaudeBox's Skill object to inject planning-with-files into a VM
- examples/boxlite/README.md: example context and requirements
- README: new Sandbox Runtimes section (BoxLite is infrastructure,
not an IDE - kept separate from the 16-platform IDE table)
- README: BoxLite badge, Documentation table entry, version bump
to 2.18.0, file structure updated
- CHANGELOG: v2.18.0 entry with full details
- CONTRIBUTORS: @DorianZheng added for Issue #84
BoxLite loads via pip install claudebox - no .boxlite/ folder needed
since ClaudeBox uses a Python Skill object, not file-system discovery.
Closes#84
OpenCode uses different session storage (.json at ~/.local/share/opencode/) than Claude Code (.jsonl at ~/.claude/projects/). Session catchup now detects the IDE and provides a clear workaround message instead of silently failing.
- Added IDE detection (checks env vars and directory structure)
- OpenCode users get helpful message to manually read planning files
- Claude Code functionality unchanged
- Updated OpenCode docs with known limitations section
Fixes#74
Cursor now supports hooks natively via .cursor/hooks.json. Added:
- hooks.json config with preToolUse, postToolUse, and stop hooks
- Hook scripts in bash (.sh) and PowerShell (.ps1)
- hooks.windows.json for native PowerShell users
- Rewrote docs/cursor.md — removed "hooks don't work" limitation,
documented full hook support including auto-continuation via stop hook
- Updated README Cursor format from "Skills" to "Skills + Hooks"
The stop hook is the highlight: it checks task_plan.md completion and
uses Cursor's followup_message to auto-continue the agent if phases
are incomplete (capped at 3 retries via loop_limit).
Thanks to @sulsDotK for reporting that Cursor now supports hooks.
OthmanAdi