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.
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#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.
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 domain-specific planning templates for data analytics and
exploration workflows. The existing 5-phase template assumes a
software development cycle - analytics sessions need different
phases (Data Discovery, Exploratory Analysis, Hypothesis Testing,
Synthesis) and different tracking structures (Data Sources,
Hypothesis Log, Query Results, Statistical Findings).
New files:
- templates/analytics_task_plan.md: 4-phase analytics plan
- templates/analytics_findings.md: data source and hypothesis tracking
Modified files:
- scripts/init-session.sh: add --template/-t flag
- scripts/init-session.ps1: add -Template parameter
Usage: ./init-session.sh --template analytics
Default behavior is unchanged when flag is omitted.
Relates to #103
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.
PowerShell's parser fails on three categories of special characters inside
double-quoted strings in check-complete.ps1:
1. UTF-8 em-dash (U+2014) in comments — misinterpreted as code tokens
2. Square brackets [planning-with-files] — parsed as array index syntax
3. Parentheses ($COMPLETE/$TOTAL) and phase(s) — parsed as subexpressions
Fix: replace double-quoted Write-Host strings with single-quoted strings
and string concatenation, and replace em-dashes with ASCII double-hyphens.
Applied to all 12 tool variant copies (adal, codebuddy, codex, continue,
gemini, kiro, mastracode, openclaw, opencode, pi, scripts, skills).
Verified on Windows 11 with PowerShell 5.1 — all scenarios pass.
Closes#87
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
- check-complete.sh/.ps1: Always exit 0 — incomplete task is a normal
state, not an error. Uses stdout for informational status reporting.
Fixes stop hook error in Claude Code. (#68)
- README.md, docs/quickstart.md: Clarify that the AI creates planning
files (not the user manually). Align all docs on workflow. (#69)
- README.md: Add Plan Cascade by @Taoidle to Community Forks (#63)
- Updated all 21 check-complete script copies across IDE folders
- check-complete.sh/.ps1: Add fallback for [complete] inline bracket
status format in addition to existing **Status:** bold format
- Updated all 21 script copies across IDE folders
- docs/kilocode.md: Remove all references to non-existent
.kilocode/rules/ directory (migrated to skills/ in v2.10.0)
- README.md: Update Kilo Code section to reference .kilocode/skills/
The Stop hook was failing with "No such file or directory" error when
CLAUDE_PLUGIN_ROOT was not properly set in the environment, resulting in
the script path resolving to "/scripts/check-complete.sh" instead of the
full path.
Changes:
- Add SCRIPT_DIR variable with fallback to explicit path
- Use $HOME/.claude/plugins/planning-with-files/scripts as fallback when
CLAUDE_PLUGIN_ROOT is not set
- Make check-complete.sh executable (chmod +x)
- Apply fix to both Unix and Windows paths in the hook command
This ensures the Stop hook runs successfully even when CLAUDE_PLUGIN_ROOT
is not available in the shell environment.
Fixes the error: "bash: /scripts/check-complete.sh: No such file or directory"
The session-catchup.py script now properly scans across ALL sessions to find
unsynced context since the last planning file update.
Changes:
- Skip the current session (most recently modified)
- Find the most recent planning file update across all previous sessions
- Collect ALL conversation from that point forward, across all sessions
- Show session markers [Session: xxx...] when context spans multiple sessions
- Include intermediate sessions that have no planning updates but have work
- Show up to 100 messages (was 20), with note if truncated
Example: If planning was updated in session A, then work continued in sessions
B and C without updates, the catchup now shows context from A, B, and C.
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Merging feature/session-catchup-recovery from @lasmarois (PR #33)
This fast-follow release adds automatic session recovery for seamless
work continuation after running /clear when context fills up.
New Features:
- Session recovery via session-catchup.py script
- Analyzes previous session JSONL files in ~/.claude/projects/
- Finds last planning file update
- Extracts unsynced conversation after that point
- Automatic recovery when invoking /planning-with-files
Enhanced Hooks:
- PreToolUse now includes Read/Glob/Grep operations
- Keeps task_plan.md in attention during research phases
- Better context management throughout workflow
Files Added:
- scripts/session-catchup.py (all 3 locations)
- Session recovery instructions in SKILL.md
- README session recovery documentation
Version Updates:
- Version bumped to 2.2.1 in all manifests
- Updated CHANGELOG.md with v2.2.1 release notes
- Added @lasmarois to CONTRIBUTORS.md
Conflicts resolved:
- CHANGELOG: Combined v2.2.1 and v2.2.0 entries
- README: Added session recovery to v2.2.1, kept v2.2.0 features
- SKILL.md: Merged session recovery with existing hooks
Contributors:
- @lasmarois (session recovery implementation)
- Ahmad Othman Ammar Adi (conflict resolution, version management)
Automatically detect and recover unsynced work from previous sessions
when context fills up and user runs /clear.
New features:
- session-catchup.py: Analyzes previous session JSONL to find unsynced context
- Recovery triggered automatically when invoking /planning-with-files
- PreToolUse hook now includes Read/Glob/Grep for better attention management
Optimal workflow:
1. Disable auto-compact in Claude Code settings
2. Start fresh session
3. Run /planning-with-files when ready for complex task
4. Work until context fills up
5. Run /clear
6. Run /planning-with-files again — automatically recovers where you left off
How recovery works:
- SKILL.md instructs Claude to first run session-catchup.py
- Script checks ~/.claude/projects/ for previous session JSONL
- Finds last planning file update, extracts conversation after that point
- Claude updates planning files based on catchup + git diff
Changes:
- SKILL.md: Added session recovery section, preserved all original content
- README: Added optimal workflow and setup instructions
- Removed SessionStart hook (doesn't work per Issue #24)
- Version bumped to 2.2.0
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This release adds comprehensive Windows compatibility and recognizes
community contributors.
Features:
- PowerShell scripts (check-complete.ps1, init-session.ps1)
- OS-aware hook execution with automatic fallback
- Cross-platform script support (Windows, Mac, Linux)
Fixes:
- Issue #32: Stop hook error on Windows PowerShell
- Issue #25: check-complete.sh not found errors
- ${CLAUDE_PLUGIN_ROOT} resolution across platforms
Documentation:
- Added CONTRIBUTORS.md recognizing community contributions
- Added COMPREHENSIVE_ISSUE_ANALYSIS.md with detailed issue research
- Updated CHANGELOG.md with v2.2.0 changes
- Updated README.md with new version info
Technical Changes:
- Created PowerShell equivalents for all bash scripts
- Updated SKILL.md Stop hook to detect OS and use appropriate script
- Scripts deployed to all three locations (root, plugin, skills)
- Graceful fallback chain: pwsh → powershell → bash
- Version bumped to 2.2.0 in all manifests
This update enables Windows users to use planning-with-files without
compatibility issues while maintaining full backwards compatibility
for Unix/Linux/Mac users.
Fixes#18 - Templates not found in cache after update
Root cause: ${CLAUDE_PLUGIN_ROOT} resolves to repo root, but templates
were only in subfolders (planning-with-files/ and skills/planning-with-files/).
Solution: Added templates/ and scripts/ at repo root level so they're
accessible regardless of how CLAUDE_PLUGIN_ROOT resolves.
Changes:
- Add templates/ directory at repo root
- Add scripts/ directory at repo root
- Bump version to 2.1.2 in all manifests
- Update CHANGELOG with fix details
- Update troubleshooting.md with cache clearing instructions
- Update README file structure diagram
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
carterusedulm2-maker