Adds the section on the first-turn TERMINAL_CWD rewrite: the mechanism,
what was reproduced with the 0.21.0 source, what the plugin says since
v3.20.2, the PWF_PLAN_ROOT pin for project-scoped CLI sessions, the
shell-hook route as the unaffected alternative, and the home-directory
inverse risk (#272).
The compaction listener keyed on agent/session-start with source compact,
which no dsh release dispatches: the published 0.1.5-rc.2 declares the
source in the SessionStartSource union but every publish site announces
startup or resume, and the 0.1.6 alpha line does the same after folding the
field into agent/created. A live /compact against dsh 0.1.5-rc.2 wrote
compaction/start, compaction/summary, the compact checkpoint message and
compaction/end to the session log and the listener never ran.
The plugin now listens on session/event for a successful compaction/end,
marks the session, and the next agent/pre-step for that agent appends the
compaction note and the framed plan as one message: the continuation step
for an automatic pressure compaction (which runs inside the loop's own
pre-step listener ahead of ours), the next prompt for a manual /compact.
The plan is read at that step instead of being queued into the inbox, so a
prompt that arrives later never carries a stale copy and never a second
one. The mark survives a rejected step, is dropped when the step already
carries a queued plan message, and is cleared on session/disposed.
@deepseek-ai/dsh-compaction 0.1.5-rc.2 joins the devDependencies for the
SessionEventMap augmentation only; nothing is imported at runtime.
docs/deepseek-harness.md documents the dsh route for a dsh user: the
four lifecycle points, the two commands and three tools, the skill
install through npx skills add -g, the plugin install through dsh
plugin --profile <name> add for the web, headless, sdk and acp
profiles, the --dump-config check, the row config, plan selection
(PLAN_ID, .active_plan, PWF_PLAN_ROOT, ambiguity, PLANNING_DISABLED),
the gate and its cap, what is not covered (no pre-tool recitation, no
session catchup adapter, hooks: frontmatter ignored, dsh's own /plan
untouched, the 0.1.6 alpha event rename), Windows notes and
troubleshooting. docs/installation.md gains the DeepSeek Harness row
in the route matrix and a platform note pointing at the guide.
The hook file tree lists every shipped file, including user-prompt-submit.sh,
hooks.windows.json and the scripts directory the PowerShell hooks now depend
on. The selection paragraph states the actual rules (binding PLAN_ID, pin,
single-plan pointer or newest fallback, two plans require PLAN_ID, stale
pointer falls through, unsafe pointer fails closed) and that the bash hooks
stay root-plan only. The PreToolUse note no longer claims stderr for both
twins.
PowerShell named-plan slug mode (#247), exact planning filename
boundary for session catchup across every shipped copy (#248), and
selector-routed active-pointer replacement with planning-root
containment in both initializers (#249), plus the maintainer follow-ups
from the release review.
CHANGELOG entry, contributor credits for @ShaunLinTW and
@kuei51307-hub, README releases row, CITATION date, and the
script-driven parity bump of the 19 tracked version files.
docs/opencode.md claimed that npx skills add -g installs the skill to
~/.config/opencode/skills/; it installs to ~/.agents/skills/, which
OpenCode reads natively alongside ~/.claude/skills/,
~/.config/opencode/skills/ and the project-local .agents/skills/,
.claude/skills/ and .opencode/skills/. The page is rewritten around the
real paths and the plugin route (opencode.json "plugin", commands, the
gate and its limits, session catchup, oh-my-opencode and superpowers
notes kept). The .opencode skill's restore-context snippets and file
location table probe every location, and an OpenCode Notes section
explains that the hooks: frontmatter is a Claude Code convention OpenCode
ignores.
README, MIGRATION.md, docs/installation.md and the English SKILL.md
host tier tables now say what each OpenCode install gets: the native
plugin is Tier 2 (follow-up inject), skill-only installs stay notify
only.
Reported by @luyanfeng in #235.
The native Hermes plugin now resolves .planning/<slug>/ plans with the
same rules as the shell route (PLAN_ID, .planning/.active_plan, newest
slug, legacy root; slug validation, containment, BOM-tolerant pointer,
the inject-plan.sh nested-root ambiguity rule with a once-per-turn
notice, PWF_PLAN_ROOT fail-closed, PLANNING_DISABLED), answers Hermes'
pre_verify hook with the completion gate in gated mode using the
check-complete.sh decision table and state files, registers /pwf,
/pwf-status and /plan-status through ctx.register_command (the Markdown
command files were never loaded by Hermes), registers the bundled skill
from the plugin's own directory, creates gated and autonomous plans with
attestation from planning_with_files_init(name, mode), evaluates
completion in Python when sh is absent, and ships a shell-hook bridge
for Hermes config-file hooks.
The .hermes SKILL.md fixes the native Windows home (%LOCALAPPDATA%\hermes)
and documents the plugin surface; docs/hermes.md is rewritten from the
Hermes 0.19.1 source and a live install (CLI, Desktop, Windows, gate
limits, shell-hook route, import-agent migration); AGENTS.md, llms.txt
and docs/installation.md carry the Hermes route.
Verified live through Hermes' own plugin manager and scanned SAFE by
Hermes' skills-guard. An adversarial second-model review found four
divergences from the shell route in the first build; all are fixed and
covered by tests/test_hermes_first_class.py, including a differential
test against inject-plan.sh.
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