v3.1.3: hotfix invalid YAML frontmatter from v3.1.2 (quote SKILL.md description)

Hotfix for a frontmatter regression in v3.1.2.

The description refresh shipped in v3.1.2 added a colon ("...AI coding agents: keeps..."), and the English SKILL.md carry the description field unquoted. That made the YAML frontmatter invalid (mapping values are not allowed here), which can break skill loading and the model-triggering description on Claude Code and the English IDE variants.

Fixed: the description is now wrapped in double quotes across the canonical file and the seven English IDE variants (.codebuddy, .codex, .cursor, .factory, .hermes, .mastracode, .opencode). The parsed value is identical, so triggering is unchanged. The translated variants were already quoted and were not affected.

Added: tests/test_skill_frontmatter_valid.py loads every SKILL.md frontmatter as YAML and guards against an unquoted description containing a colon-space. The version-parity check is a regex and could not catch this.

Version bumped to 3.1.3 across the 17 parity files. Suite: 184 passed, 4 skipped.

If you installed v3.1.2, updating to v3.1.3 restores valid frontmatter.

v3.1.2: session-catchup works outside the plugin runtime (+ .hermes parity, description refresh)

Documentation patch.

The session-catchup command documented in the skill body used ${CLAUDE_PLUGIN_ROOT}, which the Claude Code plugin runtime sets only when it executes a hook, not in an interactive shell. A skill-only install (npx skills add, Codex, Cursor) that copy-pasted the command got an empty variable and a broken /scripts/... path.

Fixed (PR #186 by @shunfeng8421, closes #185): SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}". Plugin users keep the variable as priority, skill-only users fall back to the default install path. Applied to the canonical file, .codebuddy, and the five language variants. Windows PowerShell and plugin behavior unchanged.

Also in this release:

• The .hermes variant carried the same unset-variable bug ($HERMES_HOME with no fallback). Fixed in both bash and PowerShell, keeping the runtime variable as priority.
• The eight English SKILL.md descriptions were refreshed to lead with persistent planning for AI coding agents and context-loss survival. The Use when trigger clause is unchanged, so model invocation is identical; the five translated variants keep their localized descriptions.
• Version bumped to 3.1.2 across the 17 parity-locked files.

Documentation only. Suite: 180 passed, 4 skipped.

Thanks to @shunfeng8421 for the fix, and to @xwang118 for surfacing the underlying problem in PR #183 that became #185.

v3.1.1: Codex verification command checks the canonical hooks flag

Documentation-only patch.

The Codex verification command in docs/codex.md greped for ^codex_hooks\s, a feature-flag name that current Codex no longer prints. Codex moved its canonical feature key from codex_hooks to hooks in 0.129.0 (openai/codex#20522). The old key still resolves as a deprecated alias in config.toml, but codex features list prints only the canonical hooks, so the bare pattern matched nothing on any current Codex and routed correctly configured users to the "upgrade Codex" path.

Fixed (PR #184 by @Fat-Jan): the command now greps ^(hooks|codex_hooks)\s and the troubleshooting sentence covers both names, matching the hooks = true guidance already carried in the file since v2.39.0.

Version bumped to 3.1.1 across the 17 parity-locked files. No code, hook, script, or test changed. Suite: 180 passed, 4 skipped.

Thanks to @Fat-Jan for catching it.

v3.1.0 - Codex stop non-blocking, Codex PreCompact parity, Pi extension tests

Adopts four community contributions from the v3.0.0 cycle, each preserving the contributor as commit author. With no v3 mode marker on disk the canonical hooks stay byte-identical to v2.43.0.

Fixed

• Codex Stop hook no longer blocks a normal stop on an incomplete plan (PR #180 by @2023Anita, closes #178). The .codex Stop adapter no longer emits {"decision": "block"} while phases are pending; it sends an advisory progress-sync reminder only, matching the v3 principle that an incomplete plan alone never blocks a stop.
• SHA-cache documentation corrected to the v3 location (PR #174 by @mvanhorn, closes #164). New docs/perf-notes.md documents the attestation SHA cache, corrected to the v3 $XDG_CACHE_HOME/pwf-sha path (then $HOME/.cache/pwf-sha, with /tmp only when HOME is unset).

Added

• Native Codex PreCompact hook (PR #181 by @GongYuanCaiJi). Closes the .codex/hooks.json parity gap against the canonical PreCompact hook. Stays dormant on runtimes that never fire the event.
• Pi extension integration test suite (PR #175 by @mvanhorn, closes #163). TypeScript vitest suite covering all eight Pi lifecycle handlers, the four runtime modes, and the attestation gate.

Verification

Python suite: 180 passed, 4 skipped, 0 failed. The Pi vitest suite was added and reviewed against runtime.ts source but not executed in this release environment; run npm install && npm test inside the extension directory to run it.

Full notes in CHANGELOG.md. Thanks to @2023Anita, @GongYuanCaiJi, and @mvanhorn.

v3.0.0 - Autonomous and gated modes for long running agentic work

v3 targets long running agentic runs on strong models (Opus 4.8, Fable 5, GPT 5.5 class). Everything new is opt-in. With no mode marker on disk the hooks produce byte identical v2.43.0 output, verified by diffing the old inline hook commands against the new dispatcher on the same fixtures. Existing workflows need no changes.

Autonomous mode

init-session.sh --autonomous keeps the turn start plan injection and drops the per tool call re-injection that the v2.21 eval measured as a 68 percent token tax. The plan file on disk stays the source of truth. Recitation is reduced, not removed: published evidence on goal drift in long runs still supports one injection per turn.

Gated mode

init-session.sh --gated adds a deliberate completion gate on the Stop hook. The gate blocks a stop only when all five conditions hold: the plan opted into gated mode, a phase is in_progress, stop_hook_active is false, the block count is under the cap (default 20, PWF_GATE_CAP to override, reset at init), and the run ledger advanced since the previous block. Any single failure lets the stop through. An incomplete plan alone never blocks a session, which is the design lesson from issue #178.

Run ledger

Workers append one JSON line per event to a per agent ledger file. The injected context becomes a fixed shape synthesized summary instead of a raw progress.md tail: no free text from disk, no timestamps, stable for the host prompt cache. New scripts: ledger-append, ledger-summary, phase-status (sh and ps1), shipped in both scripts/ locations.

Security

v3 modes refuse to inject an unattested plan body, and attestation is on by default at init. Per session nonce delimiters replace the static markers. The SHA cache moved from the shared /tmp to the user private XDG cache path. Realpath containment in the plan dir resolver rejects symlinked plan directories that escape the project root.

Migration

MIGRATION.md gains a v2 to v3 section with host capability tiers (hard block: Claude Code, Codex CLI, Continue.dev; follow-up inject: Cursor, Pi, Kiro; notify only: OpenCode, Gemini CLI). New template templates/task_plan_autonomous.md with DependsOn, Owner, and AcceptanceCheck fields. Suite at 178 passed.

Full details in the CHANGELOG.

v2.43.0 - CONTRIBUTING.md + OpenCode docs fix + .continue/.gemini/.kiro variant sync

What changed:

• CONTRIBUTING.md at repo root (PR #171 by @Skulli485, closes #162). Covers local setup, project layout, PR submission, authorship and credit policy, language variant rules, and where to ask questions. A pre-merge follow-up removed a duplicated intro and a broken four-backtick code fence that the original diff carried. GitHub auto-surfaces the file in the PR creation flow now.
• OpenCode docs broken path fix (issue #172, reported by @luyanfeng). docs/opencode.md referenced a doubled folder segment (planning-with-files/planning-with-files/SKILL.md) in the manual-install block, the cat usage block, and both ls verification commands. Quick Install switched from git clone to npx skills add; manual-install and verification paths corrected; session-catchup note updated to the SQLite store location the v2.38.0 rewrite introduced.
• .continue variant SKILL.md synced from v2.34.0 to v2.43.0 (issue #159, 9 versions behind). Rule 7, Security Boundary (delimiter framing + hash attestation), expanded Scripts section with parallel task workflow, 5-Question Reboot Test, and "Write web content to task_plan.md" anti-pattern ported. Continue-specific script paths preserved.
• .gemini variant SKILL.md synced from v2.34.0 to v2.43.0 (issue #160, 9 versions behind). Claude turn-loop integration omitted (Gemini CLI has no /plan-goal, /plan-loop, or PreCompact primitive). Gemini hooks metadata key preserved.
• .kiro variant SKILL.md synced from v2.32.0-kiro to v2.43.0-kiro (issue #161, 11 versions behind). STEP 0/1/2/3 structure, bootstrap scripts, steering, and Agent Skill layout preserved. Kiro suffix convention retained in the version field.
• Version bumped to 2.43.0 across 17 parity-locked files via scripts/bump-version.py.

Tests: 130 pass, 2 skip (Windows exec-bit, pre-existing since v2.34.1), 0 fail.

Thanks: @Skulli485 for PR #171, first contribution. @luyanfeng for reporting issue #172, first issue filed.

v2.42.0: POSIX init-session portability + plugin-vs-skill install transparency + Topic Handoff docs

v2.42.0: POSIX init-session.sh portability + plugin-vs-skill install transparency + Topic Handoff docs

Merges two contributor PRs from @carterusedulm2-maker (2026-05-25) and adds v2.42 transparency documentation that surfaced from a deep audit of the v2.38.0 turn-loop integration on the same day.

What shipped

Fixed

• POSIX init-session.sh portability across the 8 mirrors (PR #169). The script's shebang is #!/usr/bin/env bash, but tests/test_init_session_slug.py:27 invokes it via sh, bypassing the shebang. On Ubuntu where /bin/sh is dash, the while [[ $# -gt 0 ]] bashism was a syntax error. v2.42 swaps to POSIX while [ $# -gt 0 ] so the slug-mode test suite runs portably under both bash and dash.

Added

• Install-scope transparency block in canonical SKILL.md (Turn-Loop Integration section). Documents that /plugin install ships the commands/ folder with /plan-goal and /plan-loop, but npx skills add (and ClawHub) install only skills/planning-with-files/ and do not register the wrapper slash commands. The PreCompact hook is in the SKILL.md frontmatter and works for both routes.
• Manual fallback procedure for /plan-goal and /plan-loop inline in the canonical SKILL.md. Lets the agent reproduce wrapper semantics by issuing Claude Code's native /goal and /loop primitives directly. Also covers the disable-model-invocation refusal pattern from anthropics/claude-code #26251 and #41417 where some sessions decline to fire the wrapper even when the user types it.

Docs

• Topic Handoff Pattern documentation in docs/quickstart.md and docs/workflow.md (PR #170). Optional convention 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/.

Verification

• 130 pass, 2 skip (Windows exec-bit, pre-existing baseline), 0 fail.
• Security audit completed 2026-05-25: 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: Anthropic skill docs at code.claude.com/docs/en/skills confirm prompt-based slash commands are the blessed pattern (matches bundled /loop, /goal, /run, /verify, /debug).

Parity bump

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.

Thanks

@carterusedulm2-maker for PR #169 and PR #170, both filed on 2026-05-25, first contributions to the repo.

v2.41.0 - Windows exec-bit skip + attestation-locking docs

What changed:

• Windows POSIX exec-bit tests now skip on NTFS (PR #167 closes #166): test_script_permissions.py carries a class-level pytest.mark.skipif for sys.platform == 'win32'. The two tests that always failed on Windows with mode 0o100666 now skip cleanly there while still running on POSIX file systems. The upstream PR landed with a malformed patch; the skipif was re-applied at class granularity during post-merge repair with no change to test logic.
• New docs/attestation-locking.md page (PR #168 closes #165): documents the attest-plan.sh write path, atomic temp-rename guarantee, optional flock advisory lock, macOS and Windows Git Bash fallback behavior, and the recommended slug-mode parallel workflow. Linked from the SKILL.md Security Boundary section.
• Version bumped to 2.41.0 across the 17 parity-locked files via scripts/bump-version.py.
• Test count: 130 pass, 2 skip, 0 fail.

Thanks: @gauravvojha for reporting issue #166 and supplying the first-pass fix in PR #167. @CleanDev-Fix (CleanFix-Dev) for the attestation-locking documentation in PR #168.

v2.40.1 - Pi adapter SKILL.md sync + npm scope correction

Merges PR #158 by @TomXPRIME. Pi-only release; canonical Claude Code surface, hook bodies, and Pi extension TypeScript runtime are unchanged.

Tom's commit (0d74ded) is on master with full authorship preserved. The release commit (755276c) layers the version bump + CHANGELOG + CONTRIBUTORS + README updates on top.

Fixed

Pi adapter SKILL.md sync gap. The .pi/skills/planning-with-files/SKILL.md variant lagged the canonical Claude Code copy after v2.39.0. Four pieces of surface were missing on Pi: Rule 7 (Continue After Completion) covering multi-cycle plan extension when the user requests additional work, the Security Boundary section documenting BEGIN/END delimiter framing plus the v2.37 hash attestation defense layers, the expanded Scripts section covering set-active-plan.sh + resolve-plan-dir.sh + attest-plan.sh plus the parallel task workflow, and the "Write web content to task_plan.md" anti-pattern row. v2.40.1 backports all four items. The redundant manual session-catchup instruction is removed because the Pi extension shipped in v2.39.0 handles that lifecycle event automatically.

Pi npm package scope correction. .pi/skills/planning-with-files/package.json name field was set to the unscoped pi-planning-with-files. Tom owns the npm publishing chain for the Pi package; the unscoped form had ownership ambiguity. v2.40.1 renames to @tomxprime/planning-with-files, matching the package author's npm namespace. Author "Ahmad Othman Ammar Adi", repository URL, license, and bugs URL preserved. No new dependencies, no preinstall or postinstall scripts, no new bin entries, no new files; only the name field changed.

Pi install docs updated. .pi/skills/planning-with-files/README.md install command updated to pi install npm:@tomxprime/planning-with-files. Manual install section rewritten to use pi install ./.pi/skills/planning-with-files (local path) or a .pi/settings.json packages entry, replacing the previous "copy the folder into your skills dir then /reload" prose. SKILL.md cross-references updated to match.

Changed

Version bumped to 2.40.1 across the 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.

Verification

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. PR #158 changes the Pi adapter doc surface and the package.json name field only; the Pi extension TypeScript runtime, hook bodies, and canonical Claude Code surface are not touched. Safety audit on the PR confirmed no supply-chain attack vectors: no new dependencies, no install hooks, no bin shims, no new files, author and repository metadata preserved.

Thanks

@TomXPRIME: second contribution after the Pi full hook parity extension in v2.39.0. The Pi adapter is now actively maintained by its author, with the npm publishing chain pointing at his scoped namespace and the SKILL.md surface kept in sync with the canonical Claude Code copy. Credited in CONTRIBUTORS.md.

Install

npx skills install othmanadi/planning-with-files

Pi users get the scoped npm install: pi install npm:@tomxprime/planning-with-files.

v2.40.0 - Slug-mode resolution fix + hook perf cache + KV-cache hygiene + Pi false-positive fix

Bug-fix-and-maintenance release. No new features; 9 specific items from the v2.40 R+D experiment (proposal_v2_40.md on the master branch) ship together.

Fixed

Hook resolution order inverted (#1 in the proposal)

UserPromptSubmit, PreToolUse, and PreCompact hook bodies used to check if [ -f task_plan.md ] at the project root FIRST. .planning/.active_plan was consulted only for attestation lookup, never for content lookup. When both a root task_plan.md and a slug-mode plan existed, the root plan silently won and the user's pinned slug plan was bypassed. v2.40 inverts the resolution chain across all three hooks: $PLAN_ID env -> .planning/.active_plan -> newest .planning/<slug>/ by mtime -> root fallback.

.active_plan corruption guards (#2, #3)

.active_plan content is now validated against ^[A-Za-z0-9_][A-Za-z0-9._-]*$. Whitespace-only content, path traversal (../escape), and leading-dot dotfile names fall through cleanly to newest-mtime resolution instead of producing weird path lookups. Dead .active_plan targets (pointing at a deleted plan dir) likewise fall through.

check-complete.sh honors slug-mode (#4)

The script previously defaulted to ./task_plan.md when invoked without arguments. Any caller running in pure-slug-mode saw "No task_plan.md found" even with an active slug plan. The Stop hook in SKILL.md passed the resolved path explicitly, so this was silent. v2.40 wires the script into resolve-plan-dir.sh when no path argument is passed.

Pi extension git push false-positive (#5)

runtime.ts isDangerousBashCommand used substring matching against a flat list including the literal string "git push". Every benign git push origin <branch> fired the warning, training users to ignore it. v2.40 replaces the substring list with a DANGEROUS_BASH_PATTERNS regex array. Only destructive variants now trigger: git push --force / -f / --mirror / +ref, rm -rf, sudo, chmod 777 / chmod a+rwx, git reset --hard, git clean -fd, shell fork bombs, and dd ... of=/dev/[sh]d[a-z].

Performance

mtime-keyed SHA-256 attestation cache (#6)

Every UserPromptSubmit and PreToolUse fire used to run a fresh sha256sum on task_plan.md to compare against the stored attestation. On Windows Git Bash this is ~800ms per fire dominated by bash spawn and disk I/O. v2.40 caches the result under ${TMPDIR:-/tmp}/pwf-sha/<key> keyed by the absolute plan-file path, storing mtime and the hash. On the next fire, if mtime is unchanged, the cached hash is reused without re-running sha256sum. The cache is per-system, transient, and invalidated automatically by any plan edit.

KV-cache hygiene on injected progress.md tail (#7)

The auto-injection feature is most valuable when the model's prefix cache stays warm across turns. The previous injection embedded the literal tail -20 progress.md, including sub-second timestamps and timezone-suffix forms that change every fire. Those bytes mid-prefix prevented cache reuse. v2.40 pipes the tail through sed -E to normalize T<HH:MM:SS>(.<frac>)?Z and T<HH:MM:SS>(.<frac>)?(+|-)HH:MM to a stable form. The model still sees recent progress structure; only the volatile sub-fields are collapsed.

Portability + races

resolve-plan-dir.sh portable mtime (#19)

The old date -r FILE +%s || stat -c '%Y' FILE || echo 0 chain silently fell to 0 on systems lacking GNU coreutils. When mtime resolves to 0 for every dir, newest-by-mtime resolution becomes order-dependent rather than recency-based. v2.40 extends the chain to: GNU stat -c '%Y', BSD stat -f '%m', date -r FILE +%s, python3 -c os.stat, python -c os.stat, perl -e (stat $f)[9], then 0. Covers GNU + BSD + macOS + Windows Git Bash + Alpine + WSL natively; python/perl fallbacks cover the rest.

attest-plan.sh concurrent-write protection (#20)

Concurrent legacy-mode attestations (two sessions in the same cwd with no PLAN_ID) used to race on a non-atomic > .plan-attestation redirect, occasionally producing a truncated file that the hook then read as the expected hash and threw a false [PLAN TAMPERED]. v2.40 writes to a .plan-attestation.tmp.<pid> and renames into place, with flock -w 5 around the rename when flock is available. Test added that spawns 8 concurrent attestations and asserts no corruption.

Verification

130 pass / 2 pre-existing Windows exec-bit failures (test_script_permissions, unchanged from v2.39.0 and unrelated to this release). +20 new tests vs v2.39.0:

• tests/test_resolve_plan_dir.py (+5): corruption + dead-target + invalid-slug-scan coverage
• tests/test_check_complete_resolver.py (+5): resolver wire-up coverage
• tests/test_plan_attestation.py (+1): concurrent-writer test
• tests/test_pi_extension_capabilities.py (+1): word-boundary contract test
• tests/test_hook_body_v240.py (+8): hook-body behavioral tests covering slug-beats-root, legacy-root, silent no-plan, corrupt-.active_plan fall-through, SHA cache population, tamper-still-blocks, progress-timestamp normalization, PreToolUse injection

Changed

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.

Not changed (deliberate)

• No brainstorm-before-plan gate (#8 in the proposal). Deferred. Changes user-facing workflow shape and deserves its own focused cycle.
• No new sidecar files (decisions.md, lessons.md, await_approval.md, dispatch queue, checkpoints). All deferred to v2.41 or v3.0.
• No refactor of the canonical hook body into a dedicated script (#17). The inline pattern is preserved; the new logic ships within the same single-line idiom. Acknowledged as maintenance debt and tracked for v2.41.

Compatibility

• v1.x users (root task_plan.md only, no .planning/ dir): no behavior change.
• v2.36+ slug-mode users: slug plans now correctly take precedence over any leftover root file.
• v2.37+ attestation users: tamper detection is unchanged in semantics, faster on warm cache.
• v2.38+ delimiter users: ===BEGIN PLAN DATA=== framing preserved.
• Pi adapter users: git push origin <branch> no longer triggers false warnings; destructive variants still do.