Merges two contributor PRs from @carterusedulm2-maker filed on 2026-05-25 plus
v2.42 transparency documentation surfaced by a deep audit of the v2.38.0
turn-loop integration on the same date.
PR #169 (4443737, by @carterusedulm2-maker): replaces the bash-only
"while [[ $# -gt 0 ]]" loop condition in init-session.sh with the POSIX
"while [ $# -gt 0 ]" across the 8 mirrored copies. The script's shebang is
"#!/usr/bin/env bash", but tests/test_init_session_slug.py:27 invokes the
script via ["sh", str(INIT_SH), *args] which bypasses the shebang and runs
the body under dash on Ubuntu, where [[ ... ]] is a syntax error. Behavior
identical under bash; the change only restores compatibility under dash so
the slug-mode test suite runs portably.
PR #170 (c5afda4, by @carterusedulm2-maker): documents an optional Topic
Handoff Pattern in docs/quickstart.md and docs/workflow.md for splitting
unrelated topics across .planning/<slug>/ directories or a manual
handoffs/<topic>.md detail layer alongside progress.md. Documentation only;
no shipped script reads handoffs/.
Install-scope transparency (canonical SKILL.md, README, CHANGELOG): the
v2.38.0 turn-loop integration shipped /plan-goal and /plan-loop as
plugin-scoped slash commands under commands/. Skill-only installs via
"npx skills add" or ClawHub land at ~/.claude/skills/planning-with-files/
and never see the commands/ folder. Previous SKILL.md wording read as if
all install routes received the wrappers; they do not. v2.42.0 documents
the split in the Turn-Loop Integration section and adds a manual fallback
procedure that lets the agent reproduce /plan-goal and /plan-loop semantics
by issuing Claude Code's native /goal and /loop primitives directly. The
manual procedure also covers the disable-model-invocation refusal pattern
tracked in anthropics/claude-code issues #26251 and #41417 where some
sessions decline to fire the wrapper even when the user types it.
PreCompact hook, /loop and /goal primitive integration, and the
templates/loop.md planning-aware loop template ship to both install routes
as before; only the slash-command convenience wrappers are plugin-scoped.
Version bumped to 2.42.0 across 17 parity-locked files via
scripts/bump-version.py. .continue, .gemini, .pi, .kiro lag intentionally
per AGENTS.md release scope.
Tests: 130 pass, 2 skip (Windows exec-bit, pre-existing since v2.34.1),
0 fail. Security audit completed 2026-05-25 (.planning/2026-05-25-
security-audit/findings.md): semgrep 0 findings on 23 critical scripts,
no preinstall/postinstall in any package.json, no remote fetches in shipped
runtime code, SLUG_RE path-traversal defense parity confirmed across the
14 SKILL.md variants, attestation + delimiter framing intact.
Web research basis for the transparency block: Anthropic skill docs at
code.claude.com/docs/en/skills confirm that prompt-based slash commands
are the blessed Claude Code pattern (matches bundled skills like /loop,
/goal, /run, /verify, /debug). Quote: "Unlike most built-in commands,
which execute fixed logic directly, bundled skills are prompt-based: they
give Claude detailed instructions and let it orchestrate the work using
its tools." The commands/ and skills/ directories are now unified per
Anthropic: "Custom commands have been merged into skills." Plugin scope
still distinguishes installation surface from npx skills add.
ClawHub upload pending: clawhub-upload/SKILL.md synced to 2.42.0 by the
bumper; manual upload to clawhub.io is the maintainer's separate step.
PR #167 (merged by @gauravvojha): test_script_permissions.py now carries a class-level pytest.mark.skipif for sys.platform == 'win32'. The two pre-existing Windows exec-bit failures (present since v2.34.1) skip cleanly on NTFS while still running on Linux and macOS. Post-merge repair: the upstream patch landed with a duplicate standalone function and a nested method inside it; the class-level skipif was re-applied, imports re-sorted, and the orphaned function removed, so test logic stays identical. Closes#166.
PR #168 (merged by @CleanDev-Fix): adds docs/attestation-locking.md, a new page covering the attest-plan.sh write path, atomic temp-rename guarantee, optional flock advisory lock, macOS Windows Git Bash WSL fallback table, and the slug-mode parallel workflow. Linked from the canonical SKILL.md Security Boundary section. Closes#165.
Version bumped to 2.41.0 across the 17 parity-locked files via scripts/bump-version.py. Tests: 130 pass, 2 skip, 0 fail.
Ships v2.40.1 on top of @TomXPRIME's PR #158 (merged via rebase, full
authorship preserved on the prior commit).
Version bumped to 2.40.1 across 14 SKILL.md variants, plugin.json,
marketplace.json, and CITATION.cff via scripts/bump-version.py.
.continue, .gemini, .pi, .kiro lag intentionally per CLAUDE.md
release scope.
README catch-up: the Releases & Session Recovery table was at v2.38.1.
Added v2.40.1, v2.40.0, v2.39.0 rows and bumped Current Version header
+ Version badge to v2.40.1.
CONTRIBUTORS.md: @TomXPRIME entry extended with PR #158 work.
Tests: 130 pass / 2 pre-existing Windows exec-bit failures
(test_script_permissions, unchanged from v2.40.0 and unrelated to this
release). Parity test passes.
SKILL.md:
- Remove redundant manual catchup instruction (extension auto-runs it)
- Add Rule 7: Continue After Completion
- Expand Scripts section with detailed descriptions + parallel plan workflow
- Add Security Boundary section (delimiter framing, attestation, security rules)
- Add missing anti-pattern: web content must go to findings.md only
package.json:
- Rename to @tomxprime/planning-with-files for npm publish
- Keep version at 1.1.0
README.md:
- Update install command to pi install npm:@tomxprime/planning-with-files
- Fix manual install to use pi install with local path
Bug fixes (items 1-5 in proposal_v2_40.md):
1. Hook resolution order inverted across UserPromptSubmit, PreToolUse, PreCompact.
Slug-mode now wins over legacy root task_plan.md when both exist. Closes the
bug where an active .planning/<slug>/ plan was silently bypassed in favor of
the root file. Resolution chain: PLAN_ID env > .planning/.active_plan >
newest .planning/<slug>/ by mtime > root fallback.
2. .active_plan target dir is validated. Dead pointers fall through cleanly.
3. .active_plan content is regex-validated as ^[A-Za-z0-9_][A-Za-z0-9._-]*$.
Whitespace-only and path-traversal corruption fall through instead of
producing weird path lookups. Tests cover whitespace, ../escape, and
leading-dot cases.
4. check-complete.sh wires into resolve-plan-dir.sh when no path arg given.
Restores slug-mode parity for any caller that invokes the script without an
explicit plan path.
5. Pi extension dangerous-command detection uses word-boundary regex. Benign
git push origin <branch> no longer triggers the warning; only --force,
--mirror, +ref, plus rm -rf, sudo, chmod 777/a+rwx, git reset --hard, git
clean -fd, fork bombs, dd to /dev/[sh]d[a-z].
Performance (items 6, 7):
6. mtime-keyed SHA-256 cache under ${TMPDIR:-/tmp}/pwf-sha cuts redundant hash
work on warm cache. Caches the result keyed by absolute plan-file path,
stores mtime + hash, skips sha256sum when mtime unchanged.
7. KV-cache hygiene on injected progress.md tail. Sub-second timestamps and
timezone-suffix forms are normalized to a stable epoch-zero form so the
model's prefix cache stays warm across turns. Manus-aligned.
Portability + races (items 19, 20):
19. resolve-plan-dir.sh portable mtime fallback chain: GNU stat -> BSD stat ->
date -r -> python3 -> python -> perl -> 0. Multi-plan workflows stop
silently degrading on non-GNU systems.
20. attest-plan.sh uses atomic temp+rename with optional flock guard.
Concurrent legacy-mode attestations stop producing truncated files that
triggered false [PLAN TAMPERED] warnings.
Tests: 130 pass / 2 pre-existing Windows exec-bit failures unchanged. +20 new
tests vs v2.39.0. See CHANGELOG for full inventory.
Version bumped to 2.40.0 across 14 SKILL.md variants + plugin.json +
marketplace.json + CITATION.cff via scripts/bump-version.py. .continue,
.gemini, .pi, .kiro lag intentionally.
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.
Hook commands embedded `'---BEGIN PLAN DATA---'` and `'---END PLAN DATA---'`
as plan-injection delimiters (v2.36.1, reinforced in v2.37 attestation).
Frontmatter parsers that split on the literal `---` substring to locate the
closing fence read the first `---` inside the hook command as the fence,
truncating the YAML mid-string. Claude Code's skill-discovery loader behaves
this way, so the description shown in the in-product skill list was a
fragment of the hook command tail instead of the documented description.
Real YAML parsers always handled the frontmatter correctly, so hook
execution and tamper attestation were never affected; only the displayed
metadata was wrong.
Swap delimiter shape to `===BEGIN PLAN DATA===` / `===END PLAN DATA===`
across canonical SKILL.md, all five language variants, the .codebuddy/
.codex/.cursor adapter mirrors, and the clawhub-upload bundle. Same
delimiter shape, same model-side framing semantics; `===` does not
collide with YAML's document separator.
Version bumped to 2.38.1 across 14 SKILL.md variants, plugin.json,
marketplace.json, CITATION.cff via scripts/bump-version.py. .continue,
.gemini, .pi, .kiro lag intentionally.
Surfaced by @bmyury via Discussion #153.
PreCompact hook fires on /compact and autoCompact. When task_plan.md is
present, surfaces a reminder to flush in-context progress to progress.md
before compaction completes and prints the active Plan-SHA256 if attested.
Stays silent without a plan. Exit 0 always; never blocks compaction.
/plan-goal composes with Claude Code's /goal (v2.1.139, May 12 2026).
Derives a termination condition from the active plan so /goal stops the
agent when the plan-file is genuinely complete, not just when the
conversation looks done.
/plan-loop composes with /loop (v2.1.72+). Default 10-minute tick re-reads
planning files, runs check-complete, nudges a progress.md entry if the
last tick produced no change. templates/loop.md ships a planning-aware
default for ~/.claude/loop.md so bare /loop works grounded in the plan.
OpenCode session-catchup rewritten for the SQLite migration (sst/opencode
dev @ 2026-05-14). Reads ${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db
read-only via URI, scopes by session.directory, surfaces unsynced planning
edits. Verified against a real 162 MB OpenCode database (94 sessions, 56
unsynced parts correctly extracted from the lovable-at-home directory).
Codex gains a PermissionRequest adapter that surfaces a one-line plan
reminder when an active plan exists. Read-only; never blocks.
Tests: +19 covering PreCompact behavior, slash command file structure,
OpenCode SQLite catchup with a synthetic schema-matching DB, and Codex
PermissionRequest emit/silent behavior. 98 tests passing.
Deliberately not changed: paths glob (auto-invocation behavior risk),
wholesale !command swap (would freeze attestation hash and defeat v2.37
tamper gate), native Plan Mode panel integration (no plugin API
documented), language variant consolidation (separate breaking-change
track). PreCompact lives in the canonical SKILL.md + 5 language variants
+ clawhub-upload; other IDE mirrors keep their existing compaction
hooks until per-IDE PreCompact adapters land in a future release.
Closes#150 (hash attestation): adds an opt-in second layer of defense for
plan injection. After v2.36.1 wrapped task_plan.md content in BEGIN/END
delimiters, the model still parsed the bytes. v2.37.0 adds /plan-attest, a
slash command that locks the current task_plan.md content with a SHA-256
stored at .planning/<active-plan>/.attestation (parallel-plan mode) or
./.plan-attestation (legacy mode). UserPromptSubmit and PreToolUse hooks
recompute the hash on every fire and emit "[PLAN TAMPERED — injection
blocked]" instead of plan content on mismatch. When attestation is set, the
injected context also carries a Plan-SHA256: line for audit. New helper:
scripts/attest-plan.sh and .ps1 with --show / --clear modes, propagated to
all six IDE mirrors that ship scripts.
Closes#151 (parity-locked version bumper): names the regression class
behind v2.34.1, v2.36.0, v2.36.2, v2.36.3 (one of N parity-locked files
forgotten on bump). Fixes it surgically without overshooting into
"regenerate all SKILL.md from canonical" (per-IDE frontmatter and per-
language prose are intentionally divergent). New
scripts/bump-version.py atomically bumps the parity set in one shot. New
tests/test_skill_md_version_parity.py fails the build the moment any
parity-locked file diverges from the canonical version. .continue,
.gemini, .pi, .kiro stay on their separate schemes and are surfaced in
every bump-version run so the omission is explicit.
Other changes:
- tests/test_canonical_script_sync.py: removed leftover duplicate
CanonicalScriptSyncTests class block (lines 99 to 137); SHARED_SCRIPTS
extended to ten entries for attest-plan.{sh,ps1}.
- scripts/sync-ide-folders.py: SCRIPTS manifest extended to cover
attest-plan helpers; existing eight scripts unchanged.
- canonical SKILL.md Security Boundary section: documents the two layers
of defense and the /plan-attest workflow.
- 14 SKILL.md variants + plugin.json + marketplace.json + CITATION.cff
bumped to 2.37.0 via scripts/bump-version.py (.continue / .gemini /
.pi / .kiro left on their own schemes per release scope rule).
Tests: 78 pass, 2 pre-existing Windows exec-bit failures unchanged.
resolve-plan-dir.{sh,ps1} and set-active-plan.{sh,ps1} were added to
scripts/ in v2.36.0 but never reached skills/planning-with-files/scripts/
or the IDE mirror folders. Users installing via npx skills could not use
the parallel planning workflow because the required scripts were absent.
Adds all four scripts to the canonical skill location. Updates
sync-ide-folders.py SCRIPTS manifest to include them, and propagates to
all IDE mirrors via the sync tool (24 new files across 6 IDE folders).
Strengthens test_canonical_script_sync.py to cover all 8 user-facing
scripts (was 4), so this class of gap trips the regression test going
forward.
Documents resolve-plan-dir.sh and set-active-plan.sh in the canonical
SKILL.md Scripts section with usage descriptions and a parallel task
workflow example.
Closes the v2.36.0 regression where slug-mode init-session.sh shipped only in
scripts/ and never reached skills/planning-with-files/scripts/ or the nine IDE
mirror folders. Users installing via npx skills or any IDE folder silently
received the v2.0.0 legacy-only script.
Also synced:
- analytics template support in init-session.ps1 (missed since v2.29.0)
- /usr/bin/env bash shebang in IDE mirror check-complete.sh files (drift from v2.35.1)
Adds tests/test_canonical_script_sync.py: byte-comparison assertion between
scripts/ and skills/planning-with-files/scripts/ for init-session and
check-complete, plus sync-ide-folders.py --verify assertion to catch IDE mirror
drift in CI going forward.
Closes security audit findings from skills.sh platform audits.
Stop hook: replace broad Get-ChildItem -Recurse over ~/.claude/plugins/cache
with resolution through $CLAUDE_SKILL_DIR env var first, then two specific
known install paths. Removes arbitrary code execution risk from cache
directory poisoning.
PowerShell ExecutionPolicy: Bypass -> RemoteSigned across all 14 SKILL.md
variants. RemoteSigned allows local scripts while blocking unsigned downloaded
scripts. Bypass was flagged as privilege escalation by Gen Agent Trust Hub.
Prompt injection delimiters: UserPromptSubmit and PreToolUse hooks now wrap
injected plan content in ---BEGIN PLAN DATA--- / ---END PLAN DATA--- markers
with explicit model instruction to treat contents as structured data and ignore
embedded instructions. Addresses the lack of sanitization boundary flagged in
the PROMPT_INJECTION finding.
Security Boundary docs: updated to document delimiter contract and add
explicit instruction that findings.md content (third-party web/search results)
must be treated as raw data. Addresses Snyk W011 third-party content exposure.
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.
- CONTRIBUTORS.md: added Emin017 (Qiming Chu) for PR #145 env bash shebangs fix; bumped total to 37+, updated date to April 29 2026
- README.md: bumped version badge to v2.35.1; added missing v2.35.0 row (Hermes + NLPM audit) and v2.35.1 row (shebang portability) to releases table; updated Current Version heading
Use /usr/bin/env bash so scripts resolve bash through PATH instead of
assuming /bin/bash exists. This improves shebang compatibility on
systems such as NixOS.
- Add Hermes adapter (PR #136 by @bailob): full skill bundle, Python adapter, /plan + /plan-status commands, 20 unit tests. Platform 17.
- Fix Pi PowerShell session-catchup missing quote (PR #137 by @xiaolai, closes part of #140)
- Cap session-catchup output at 100 lines with labeled prefix (PR #138 by @xiaolai, closes part of #140)
- Prefer known system Python paths over PATH in hook scripts (PR #139 by @xiaolai, closes part of #140)
- Add Hermes badge to README, bump IDE count to 17+, add hermes keyword in plugin.json
- Bump 14 SKILL.md variants, plugin.json, marketplace.json, CITATION.cff to 2.35.0
- Update CONTRIBUTORS.md: @bailob, @xiaolai added; total 36+
* 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
Resolving the Python interpreter solely from user PATH allows a malicious
PATH entry to redirect execution. Prefer well-known system interpreter
paths (/usr/bin/python3, /usr/local/bin/python3, /opt/homebrew/bin/python3)
before falling back to PATH-based resolution. Applies to session-start.sh,
pre-tool-use.sh, and error-occurred.sh.
Co-authored-by: Claude Code <noreply@anthropic.com>
Unbounded injection of session-catchup output into model context is a
medium-severity security concern: prior session content (which may include
web/search results or user messages) was injected verbatim with no size
limit. Add a 100-line cap via head -100 and prefix the context with a
label so the model knows this content is from a previous session.
Co-authored-by: Claude Code <noreply@anthropic.com>
Missing opening quote makes the command syntactically invalid on Windows.
Windows users running session-catchup via Pi's PowerShell hook get a
parse error and the script silently fails.
Co-authored-by: Claude Code <noreply@anthropic.com>
Two separate bugs, both reported by @nazeshinjite with a really
thorough diagnosis (the Claude output they included nailed it).
First: `export SD=` was failing as a shell builtin in Windows Git
Bash when invoked from Command Prompt — bash treated it like an
external command and threw "No such file or directory". Removed
`export` across all IDE variants.
Second, the real problem for Claude Code users: the fallback path
`$HOME/.claude/plugins/planning-with-files` doesn't exist. The
actual install is under `~/.claude/plugins/cache/`. The Claude Code
variants now use PowerShell's own `Get-ChildItem -Recurse` with `~`
expansion to find the script without relying on any path variable,
and a glob-based sh fallback for Unix. No hardcoded path, no
CLAUDE_PLUGIN_ROOT dependency.
Fixed across all 13 SKILL.md variants.
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
Unquoted description values containing ": " (colon + space) caused the
yaml parser to throw "Nested mappings are not allowed in compact mappings".
This silently prevented ar, de, and es from being discovered by the skills CLI.
Chinese variants were unaffected because they use fullwidth colons (:).