🔥 OthmanAdi/planning-with-files：面向AI编码代理的持久化文件规划

📣 v3.0.0 新变化： 面向长时间运行的代理运行提供了选择性加入的自主与门控模式，并包含一个完成门，在计划真正完成之前阻止代理继续。现有配置无需更改。

像 Manus 一样工作 ——这家 AI 代理公司已被 Meta 以 20 亿美元 收购。

planning-with-files 是一个面向 AI 编码代理 的持久化文件式规划技能。它在磁盘上维护 task_plan.md、findings.md 和 progress.md 文件，使代理能抵御 上下文丢失、/clear 和崩溃，并提供可选的完成门，要求代理在计划实际完成前不得停止。它通过 SKILL.md 标准支持 60 多种代理的安装。

💬 作者的话

向每一位为这个技能点亮星标、复刻和分享的朋友说一声谢谢。这个项目在不到 24 小时内就爆火了，来自社区的支持令人难以置信。

如果这个技能能帮助你更聪明地工作，那便是我的全部心愿。

🌍 社区成果

注册中心	说明
buzhangsan/skill-manager	双语言（EN/中文）技能中心，索引了 31,000 多个 Claude Code 技能 —— planning-with-files 可一键安装。

打造了什么东西？提交 issue 来上架！

🤝 贡献者

查看完整贡献者名单请见 CONTRIBUTORS.md。

📦 版本发布与会话恢复

版本	亮点
v3.2.0	仓库健康审计：session-catchup.py 在 Windows 上无法运行，以及“0/0 阶段”的虚假状态（修复 #191，涉及 #103，关闭 #188）。 session-catchup.py（用于“/clear 后恢复”的机制）从未正确清理 Windows 风格的路径，且三处读取缺少显式编码，导致在 Windows 上静默失败且无任何错误。inject-plan.sh 的容器守卫也会在 8.3 短名称或 /tmp 别名路径下静默丢弃计划注入和篡改检测。两者均已修复。与此同时，check-complete.sh/.ps1 和三个 IDE 专属的 Stop 钩子对任何不含 ### Phase 标题的 task_plan.md 报出虚假的“0/0 阶段完成”状态（#191，由 @mixian939 报告）；已在所有出现该模式的地方修复，同步更新规范脚本。--template analytics 标志（v2.29.0）在每个安装的技能包中都会静默回退到默认模板；现在分析模板会实际出现在 init-session.sh 读取的位置。合并 PR #187（@Stephen-abc: Windows 测试编码修复、过时的安装路径文档）和 PR #192（@igorcosta: Autohand Code 配置文档）。新增 SECURITY.md 并启用私有漏洞报告（@AvitalAviv）。更正了 AGENTS.md 中关于贡献者 PR 合并指南的错误，该指南引导代理以重新指定作者的方式压缩合并。测试套件：186 通过，5 跳过，0 失败。
v3.1.3	热修复：v3.1.2 中 SKILL.md frontmatter 为无效 YAML。 v3.1.2 的描述刷新加入了一个冒号，英文版 SKILL.md 的 description 未加引号，导致 YAML 拒绝 frontmatter（“不允许此处出现映射值”），可能会中断技能加载和模型触发描述。v3.1.3 在规范文件与七个英文 IDE 变体中为 description 添加引号（与已加引号的翻译变体保持一致；解析值不变），并新增 tests/test_skill_frontmatter_valid.py 以将每个 SKILL.md frontmatter 作为 YAML 进行验证。测试套件：184 通过。
v3.1.2	Session-catchup 命令可在插件运行时之外工作，.hermes 对等一致性，刷新技能描述（PR #186，作者 @shunfeng8421，关闭 #185，报告者 @xwang118）。文档中的恢复上下文命令使用了 ${CLAUDE_PLUGIN_ROOT}，该变量仅在钩子执行中由插件运行时设置，因此纯技能安装（npx skills add、Codex、Cursor）在 shell 中执行时会得到空变量和错误的 /scripts/... 路径。现在规范文件、.codebuddy 及五种语言变体中使用 SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"；.hermes 变体对 $HERMES_HOME 提供相同回退。八个英文 SKILL.md 描述已刷新，以面向 AI 编码代理的规划和上下文丢失存续能力开头；Use when 触发词与翻译变体保持不变。仅文档更新；测试套件：180 通过。
v3.1.1	Codex 验证命令检查规范的 hooks 功能标志（PR #184，作者 @Fat-Jan）。docs/codex.md 中的验证块运行 `codex features list
v3.1.0	Codex Stop 钩子不再因未完成的计划而阻塞，原生 Codex PreCompact 对等，Pi 扩展测试套件，以及精确的 SHA 缓存文档（PR #180，作者 @2023Anita，关闭 #178；PR #181，作者 @GongYuanCaiJi；PR #175 与 PR #174，作者 @mvanhorn，关闭 #163 与 #164）。.codex Stop 适配器去掉 {"decision":"block"} 路径，该路径会推动 Codex 代理自动继续未完成的阶段；它现在仅发出咨询性的进度同步提醒，与 v3 原则一致：未完成的计划本身绝不应阻止一次 stop。原生 .codex/hooks.json 路径补上了相对于规范 SKILL.md 缺失的 PreCompact 钩子（pre-compact.sh），此钩子在不触发该事件的运行态上静默。Pi 扩展新增 TypeScript 集成套件，覆盖全部八个生命周期处理器、四种运行时模式及验证门。docs/perf-notes.md 记录了验证 SHA 缓存，并更正为 v3 的 $XDG_CACHE_HOME/pwf-sha 位置。测试套件：180 通过。
v3.0.0	面向长运行代理任务的自主与门控模式、结构化运行账本、可选的完成门（无破坏性变更：无模式标记时钩子输出与 v2.43 逐字节相同）。init-session --autonomous 对强模型省略每个工具调用的计划重新注入，仅保留回合开始注入；--gated 添加一个刻意的 Stop 钩子完成门，只在满足五个条件时阻塞（门控模式、存在 in_progress 阶段、stop_hook_active 为 false、阻塞次数未达上限、自上次阻塞以来账本有进展），因此未完成的计划本身绝不会锁住会话。新增仅追加的 JSONL 运行账本（ledger-append、ledger-summary、phase-status，含 sh 与 ps1）替换 v3 模式中原始的 progress.md 尾部，提供固定格式摘要。v3 模式默认开启验证，未经验证的计划正文在注入时被拒绝。每次会话使用随机分隔符，SHA 缓存移至 $XDG_CACHE_HOME/pwf-sha，计划目录解析器中加入 realpath 容器约束。钩子标量被轻量分发器（inject-plan.sh、gate-stop.sh）取代，两者发布于两个 scripts/ 位置。新增 templates/task_plan_autonomous.md 模板，包含 DependsOn/Owner/AcceptanceCheck 字段，以及 MIGRATION.md 中的 v2 至 v3 迁移指南，文档化主机能力层级（硬阻塞、后续注入、仅通知）。测试套件：178 通过，外加位置对等与门控/账本/初始化模式/容器约束测试。
v2.43.0	CONTRIBUTING.md + OpenCode 文档修复 + .continue/.gemini/.kiro 变体同步至对等（PR #171，作者 @Skulli485；issue #172 由 @luyanfeng 报告；issues #159/#160/#161）：首个放在仓库根目录的 CONTRIBUTING.md，GitHub 在 PR 创建流程中自动展示。docs/opencode.md 的快速安装从 git clone 切换为 npx skills add，因为手动安装块引用了双重路径（planning-with-files/planning-with-files/SKILL.md）。三个历史上滞后的 IDE SKILL.md 变体升级至 v2.43.0 对等：.continue 从 v2.34.0（落后 9 个版本）、.gemini 从 v2.34.0（落后 9 个版本）、.kiro 从 v2.32.0-kiro（落后 11 个版本），并保留 IDE 专属的 frontmatter、钩子形态和 Kiro Agent Skill 布局。
v2.42.0	POSIX init-session.sh 可移植性 + 插件与技能安装透明度 + 话题交接文档（PR #169 与 PR #170，作者 @carterusedulm2-maker）：init-session.sh 及其 7 个镜像将 [[ ]] bash 语法替换为 POSIX [ ]，使 tests/test_init_session_slug.py 在 dash（Ubuntu）下通过 sh 调用脚本时干净运行。规范 SKILL.md 新增安装范围说明：/plugin install 会安装 commands/ 文件夹及 /plan-goal 和 /plan-loop，但 npx skills add（和 ClawHub）不会。为两个封装器提供了手动回退流程，使纯技能安装会话可以直接调用 Claude Code 原生 /goal 和 /loop 来实现相同效果。docs/quickstart.md 和 docs/workflow.md 添加了可选的话题交接模式，用于极长时间运行的运营话题（handoffs/<topic>.md 与 progress.md 并列）。
v2.41.0	Windows 执行位测试跳过 + 验证锁定文档（PR #167，作者 @gauravvojha，Issue #166；PR #168，作者 @CleanDev-Fix，Issue #165）：test_script_permissions.py 现在在 Windows 上通过类级别 pytest.mark.skipif(sys.platform == "win32") 跳过，因为 NTFS 不存储 POSIX 可执行位；两个此前存在的 Windows 执行位失败（自 v2.34.1 起）已解决。新增专用 docs/attestation-locking.md 页面，记录了 attest-plan.sh 写入路径、原子 temp-rename 保证、可选的 flock 建议锁以及建议的 slug 模式工作流用于并行会话。
v2.40.1	Pi 适配器 SKILL.md 同步间隙 + npm 作用域修正（PR #158，作者 @TomXPRIME）：.pi SKILL.md 自 v2.39.0 后滞后于规范 Claude Code 副本；v2.40.1 回溯移植了规则 7（完成后继续）、安全边界章节、涵盖 set-active-plan.sh/resolve-plan-dir.sh/attest-plan.sh 的扩展脚本章节加并行任务工作流，以及“将网页内容写入 task_plan.md”反模式行。Pi npm 包从无作用域的 pi-planning-with-files 更名为 @tomxprime/planning-with-files，匹配包作者的命名空间；安装文档相应更新。作者、仓库、许可证和 bugs 链接已保留。
v2.40.0	Slug 模式解析修复 + 性能缓存 + KV 缓存卫生 + Pi 误报修复（来自 v2.40 的 9 项...

📣 New inv3.0.0: opt-in autonomous and gated modes for long-running agent runs, with a completion gate that holds the agent until the plan is actually done. Existing setups change nothing.

Work like Manus — the AI agent company Meta acquired for $2 billion.

planning-with-files is a persistent file-based planning skill for AI coding agents. It keeps task_plan.md, findings.md, and progress.md on disk so the agent survives context loss , /clear, and crashes, with an opt-in completion gate that holds the agent until the plan is actually done. It installs across 60+ agents via the SKILL.md standard.

💬 A Note from the Author

To everyone who starred, forked, and shared this skill — thank you. This project blew up in less than 24 hours, and the support from the community has been incredible.

If this skill helps you work smarter, that's all I wanted.

🌍 What the community shipped Registry	What It Is
buzhangsan/skill-manager	Bilingual (EN/中文) skill hub indexing 31,000+ Claude Code skills — planning-with-files installable one-click.

Built something?Open an issue to get listed!

🤝 Contributors

See the full list of everyone who made this project better in CONTRIBUTORS.md.

📦 Releases & Session Recovery Version	Highlights
v3.2.0	Repository health audit: session-catchup.py was non-functional on Windows, plus the "0/0 phases" false status (closes #191, addresses #103, closes #188). session-catchup.py, the mechanism behind "resume after /clear," never sanitized Windows-style paths correctly and had no explicit encoding on three reads, so it silently did nothing on Windows with no error. inject-plan.sh's containment guard also silently dropped plan injection and tamper detection under 8.3 short-name or /tmp-aliased paths. Both fixed. Separately, check-complete.sh/.ps1 and three IDE-specific Stop hooks reported a false "0/0 phases complete" for any task_plan.md without ### Phase headings (#191, reported by @mixian939); fixed everywhere the pattern appeared, canonical scripts included. The --template analytics flag (v2.29.0) was silently falling back to default templates in every installed skill package; the analytics templates now actually ship where init-session.sh reads them. Merged PR #187 (@Stephen-abc: Windows test-encoding fixes, stale install-path docs) and PR #192 (@igorcosta: Autohand Code setup docs). Added SECURITY.md and enabled private vulnerability reporting (@AvitalAviv). Corrected AGENTS.md's contributor-PR-merge guidance, which told agents to squash-merge in a way that reassigns authorship. Suite at 186 passed, 5 skipped, 0 failed.
v3.1.3	Hotfix: SKILL.md frontmatter was invalid YAML in v3.1.2. The v3.1.2 description refresh added a colon, and the English SKILL.md keep description unquoted, so YAML rejected the frontmatter ("mapping values are not allowed here"), which could break skill loading and the model-triggering description. v3.1.3 quotes the description (matching the already-quoted translated variants; the parsed value is identical) across the canonical file and the seven English IDE variants, and adds tests/test_skill_frontmatter_valid.py to validate every SKILL.md frontmatter as YAML. Suite at 184 passed.
v3.1.2	Session-catchup command works outside the plugin runtime,.hermes parity, refreshed skill description (PR #186 by @shunfeng8421 closes #185, reported by @xwang118). The documented Restore Context command used ${CLAUDE_PLUGIN_ROOT}, which the plugin runtime sets only inside hook execution, so a skill-only install (npx skills add, Codex, Cursor) running it in a shell got an empty variable and a broken /scripts/... path. Now SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}" on the canonical file, .codebuddy, and the five language variants; the .hermes variant got the same fallback for $HERMES_HOME. The eight English SKILL.md descriptions were refreshed to lead with planning for AI coding agents and context-loss survival, with the Use when trigger and translated variants unchanged. Documentation only; suite at 180 passed.
v3.1.1	Codex verification command checks the canonicalhooks feature flag (PR #184 by @Fat-Jan). The docs/codex.md verify block ran `codex features list
v3.1.0	Codex Stop hook no longer blocks on an incomplete plan, native Codex PreCompact parity, Pi extension test suite, and accurate SHA-cache docs (PR #180 by @2023Anita closes #178, PR #181 by @GongYuanCaiJi, PR #175 and PR #174 by @mvanhorn close #163 and #164). The .codex Stop adapter dropped the {"decision":"block"} path that pushed Codex agents to auto-continue unfinished phases; it now emits an advisory progress-sync reminder only, matching the v3 principle that an incomplete plan alone never blocks a stop. The native .codex/hooks.json route gained the PreCompact hook (pre-compact.sh) it was missing relative to the canonical SKILL.md, dormant on runtimes that never fire the event. The Pi extension gained a TypeScript integration suite covering all eight lifecycle handlers, the four runtime modes, and the attestation gate. docs/perf-notes.md documents the attestation SHA cache, corrected to the v3 $XDG_CACHE_HOME/pwf-sha location. Suite at 180 passed.
v3.0.0	Autonomous and gated modes for long-running agentic runs, structured run ledger, opt-in completion gate (no breaking changes: with no mode marker the hooks produce byte-identical v2.43 output). init-session --autonomous drops the per-tool-call plan re-injection for strong models and keeps the turn-start injection; --gated adds a deliberate Stop-hook completion gate that blocks only when five conditions hold (gated mode, an in_progress phase, stop_hook_active false, block count under the cap, ledger progressed since the last block), so an incomplete plan alone never traps a session. New append-only JSONL run ledger (ledger-append, ledger-summary, phase-status, sh + ps1) replaces the raw progress.md tail in v3 modes with a fixed-shape summary. Attestation is default-on in v3 modes and unattested plan bodies are refused at injection. Per-session nonce delimiters, SHA cache moved to $XDG_CACHE_HOME/pwf-sha, realpath containment in the plan-dir resolver. Hook scalars replaced by thin dispatchers (inject-plan.sh, gate-stop.sh) shipped in both scripts/ locations. New templates/task_plan_autonomous.md with DependsOn/Owner/AcceptanceCheck fields, v2-to-v3 migration guide in MIGRATION.md, host capability tiers documented (hard block, follow-up inject, notify only). Suite at 178 passed plus location-parity and gate/ledger/init-mode/containment tests.
v2.43.0	CONTRIBUTING.md + OpenCode docs fix +.continue/.gemini/.kiro variant sync to parity (PR #171 by @Skulli485, issue #172 by @luyanfeng, issues #159/#160/#161): first CONTRIBUTING.md at repo root, auto-surfaced by GitHub in the PR creation flow. docs/opencode.md Quick Install switched from git clone to npx skills add after the manual-install block was found referencing a doubled path (planning-with-files/planning-with-files/SKILL.md). Three historically lagging IDE SKILL.md variants brought to v2.43.0 parity: .continue from v2.34.0 (9 versions behind), .gemini from v2.34.0 (9 versions behind), .kiro from v2.32.0-kiro (11 versions behind), preserving IDE-specific frontmatter, hook shapes, and Kiro Agent Skill layout.
v2.42.0	POSIXinit-session.sh portability + plugin-vs-skill install transparency + Topic Handoff docs (PR #169 and PR #170 by @carterusedulm2-maker): init-session.sh and its 7 mirrors swap the [[ ]] bashism for POSIX [ ] so tests/test_init_session_slug.py runs cleanly under dash (Ubuntu) when the test invokes the script via sh rather than the bash shebang. Canonical SKILL.md gains an install-scope clarification: /plugin install ships the commands/ folder with /plan-goal and /plan-loop, but npx skills add (and ClawHub) do not. A manual fallback procedure for both wrappers is documented inline so skill-only sessions can produce the same effect by invoking Claude Code's native /goal and /loop primitives directly. docs/quickstart.md and docs/workflow.md add an optional Topic Handoff Pattern for very long-running operational topics (handoffs/<topic>.md alongside progress.md).
v2.41.0	Windows exec-bit test skip + attestation-locking docs (PR #167 by @gauravvojha, Issue #166; PR #168 by @CleanDev-Fix, Issue #165): test_script_permissions.py now skips on Windows with a class-level pytest.mark.skipif(sys.platform == "win32") since NTFS does not store POSIX executable bits; the 2 pre-existing Windows exec-bit failures (present since v2.34.1) are resolved. New dedicated docs/attestation-locking.md page documents the attest-plan.sh write path, the atomic temp-rename guarantee, the optional flock advisory lock, and the recommended slug-mode workflow for parallel sessions.
v2.40.1	Pi adapter SKILL.md sync gap + npm scope correction (PR #158 by @TomXPRIME): the .pi SKILL.md lagged the canonical Claude Code copy after v2.39.0; v2.40.1 backports Rule 7 (Continue After Completion), the Security Boundary section, 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. The Pi npm package is renamed from the unscoped pi-planning-with-files to @tomxprime/planning-with-files, matching the package author's namespace; install docs updated accordingly. Author, repository, license, and bugs URLs preserved.
v2.40.0	Slug-mode resolution fixes + perf cache + KV-cache hygiene + Pi false-positive fix (9 items from the v2.40 R&D experiment): hook resolution order inverted so slug-mode wins over legacy root, .active_plan target dir + content validated against a safe-identifier regex, check-complete.sh honors $PLAN_ID and .active_plan, Pi extension isDangerousBashCommand swapped to a word-boundary regex array so benign git push origin <branch> no longer fires the warning, mtime-keyed SHA-256 cache cuts attestation-hook latency on Windows Git Bash, progress.md tail timestamps normalized for KV-cache prefix stability, resolve-plan-dir.sh mtime resolution made portable across GNU/BSD/macOS/Alpine/Git Bash with python+perl fallbacks, attest-plan.sh uses atomic temp-rename with optional flock to close the concurrent-writer race. 130 pass / 2 pre-existing Windows exec-bit fails, +20 new tests.
v2.39.0	Pi Coding Agent full hook parity extension + Codex hooks flag fix (PR #157 by @TomXPRIME, Issue #154 by @DLI1996): the .pi adapter ships a bundled TypeScript extension mapping eight Pi lifecycle events to the same behavior the skill provides on Claude Code, with a four-mode system (auto/parity/cache-safe/notify) that auto-detects DeepSeek and keeps the KV-cache prefix stable. Pi runtime reads the same .attestation file the canonical v2.37 attest-plan.sh writes, so attesting once locks the plan across both runtimes. Four slash commands (/plan-status, /plan-attest, /plan-goal, /plan-loop) mirror their Claude Code counterparts. Separately, docs/codex.md swaps from codex_hooks = true to hooks = true to match the current OpenAI canonical key, with an alias note so users on older configs are not pushed to migrate.
v2.38.1	Description field garbled in Claude Code skill picker (surfaced via Discussion #153 by @bmyury): hook commands embedded '---BEGIN PLAN DATA---' plan-injection delimiters; Claude Code's skill-discovery loader split frontmatter on the first --- and read the truncated value as the description. Swapped to ===BEGIN PLAN DATA=== / ===END PLAN DATA=== across canonical SKILL.md, all five language variants, the .codebuddy/.codex/.cursor adapter mirrors, and clawhub-upload. Hook execution and tamper attestation never affected; only the displayed metadata.
v2.38.0	Claude Code turn-loop integration + OpenCode SQLite fix : new PreCompact hook fires on /compact and autoCompact, surfaces a reminder to flush progress before compaction completes and prints the active Plan-SHA256 when attested. New /plan-goal slash command composes with Claude Code's /goal (v2.1.139, May 12 2026): derives a termination condition from the active plan. New /plan-loop composes with /loop (v2.1.72+): default 10-minute tick re-reads planning files and runs check-complete. New templates/loop.md for the bare /loop planning-aware default. Session-catchup rewritten for OpenCode's SQLite migration. Codex gets a PermissionRequest adapter that surfaces plan context at permission prompts.
v2.37.0	Hash attestation + parity bumper (closes #150, #151): /plan-attest locks task_plan.md with a SHA-256; hooks block injection on tamper. scripts/bump-version.py + parity test kill the "missed one variant" regression class behind v2.34.1, v2.36.0, v2.36.2, and v2.36.3. (thanks @oaabahussain!)
v2.36.3	Parallel planning scripts now ship in the skill : resolve-plan-dir.sh and set-active-plan.sh were missing from the installed skill in v2.36.0; now in canonical + all IDE mirrors + SKILL.md docs updated
v2.36.2	Canonical script sync (PR #149): skills/planning-with-files/scripts/init-session.sh was missing slug mode from v2.36.0; now synced with IDE mirrors + regression test. (thanks @voidborne-d!)
v2.36.1	Security hardening : Stop hook cache search removed, ExecutionPolicy Bypass changed to RemoteSigned, prompt injection delimiters added. (Gen Agent Trust Hub FAIL resolved)
v2.36.0	Parallel plan isolation + Codex session isolation (closes #146, #148): init-session.sh slug mode, set-active-plan.sh, resolve-plan-dir.sh, all Codex hooks route through resolver, session attachment gating. Hermes docs (closes #147): integration notes added to docs/hermes.md. 34 new tests. (thanks @githubYiheng, @09ashishkapoor, @shawnli1874!)
v2.35.1	Shebang portability fix : changed /bin/bash to /usr/bin/env bash in hook scripts, fixing compatibility on NixOS and other systems where bash is not at /bin/bash. (thanks @Emin017!)
v2.35.0	Hermes adapter + NLPM audit hardening : Hermes platform 17 support (thanks @bailob!), NLPM audit fixed Python PATH resolution, session-catchup injection cap, Pi PowerShell syntax (thanks @xiaolai!)
v2.34.1	Stop hook Windows portability fix (closes #133): export SD= failed in Windows Git Bash hook context; fallback path was wrong for plugin cache structure. Fixed across all 13 SKILL.md variants. (thanks @nazeshinjite!)
v2.34.0	Codex hooks fully restored (closes #132): .codex/hooks.json + lifecycle scripts back — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop. Tessl CI for SKILL.md quality reviews. Exec bit fix. 4 missing contributors added. (thanks @Leon-Algo, @popey!)
v2.33.0	Multi-language expansion : Arabic, German, and Spanish skill variants added (thanks to community contributors!)
v2.32.0	Codex session catchup rewrite (thanks @ebrevdo!), Loaditout A-grade security badge, Stop hook Git Bash fix
v2.31.0	Codex hooks.json integration with full lifecycle hooks (thanks @Leon-Algo!)
v2.30.1	Fix: Codex script executable bits restored (thanks @Leon-Algo!)
v2.30.0	CLAUDE_SKILL_DIR variable, IDE configs moved to per-IDE branches, plugin.json bumped from 2.23.0
v2.29.0	Analytics workflow template: --template analytics flag for data exploration sessions (thanks @mvanhorn!)
v2.28.0	Traditional Chinese (zh-TW) skill variant (thanks @waynelee2048!)
v2.26.2	Fix: --- in hook commands broke YAML frontmatter parsing, hooks now register correctly
v2.26.1	Fix: session catchup after /clear, path sanitization on Windows + content injection (thanks @tony-stark-eth!)
v2.26.0	IDE audit: Factory hooks, Copilot errorOccurred hook, Gemini hooks, bug fixes
v2.18.2	Mastra Code hooks fix (hooks.json + docs accuracy)
v2.18.1	Copilot garbled characters complete fix
v2.18.0	BoxLite sandbox runtime integration
v2.17.0	Mastra Code support + all IDE SKILL.md spec fixes
v2.16.1	Copilot garbled characters fix: PS1 UTF-8 encoding + bash ensure_ascii (thanks @Hexiaopi!)
v2.16.0	GitHub Copilot hooks support (thanks @lincolnwan!)
v2.27.0	Kiro Agent Skill layout (thanks @EListenX!)
v2.15.1	Session catchup false-positive fix (thanks @gydx6!)
v2.15.0	/plan:status command, OpenCode compatibility fix
v2.14.0	Pi Agent support, OpenClaw docs update, Codex path fix
v2.11.0	/plan command for easier autocomplete
v2.10.0	Kiro steering files support
v2.7.0	Gemini CLI support
v2.2.0	Session recovery, Windows PowerShell, OS-aware hooks

View all releases · CHANGELOG

Parallel plan isolation (.planning/YYYY-MM-DD-slug/ directories) and Codex session isolation shipped in v2.36.0. The experimental/isolated-planning branch was the earlier prototype; master is now the canonical location.

---

When your context fills up and you run /clear, this skill automatically recovers your previous session.

How it works:

1. Checks for previous session data in the active IDE's session store (~/.claude/projects/ for Claude Code, ~/.codex/sessions/ for Codex)
2. Finds when planning files were last updated
3. Extracts conversation that happened after (potentially lost context)
4. Shows a catchup report so you can sync

Pro tip: Disable auto-compact to maximize context before clearing:

🛠️ Supported IDEs (18+ Platforms)

Enhanced Support (hooks + lifecycle automation)

These IDEs have dedicated hook configurations that automatically re-read your plan before tool use, remind you to update progress, and verify completion before stopping:

Standard Agent Skills Support

These IDEs implement the Agent Skills open specification. Install with npx skills add — the installer places the skill in each IDE's discovery path automatically:

Note: If your IDE uses the legacy Rules system instead of Skills, see the legacy-rules-support branch.

🧱 Sandbox Runtimes (1 Platform) Runtime	Status	Guide	Notes
BoxLite	✅ Documented	BoxLite Setup	Run Claude Code + planning-with-files inside hardware-isolated micro-VMs

Note: BoxLite is a sandbox runtime, not an IDE. Skills load via ClaudeBox — BoxLite’s official Claude Code integration layer.

---

A Claude Code plugin that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage — the exact pattern that made Manus worth billions.

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

🌐 Available in 5 other languages

🇸🇦 العربية / Arabic

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-ar -g

🇩🇪 Deutsch / German

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g

🇪🇸 Español / Spanish

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-es -g

🇨🇳 中文版 / Chinese (Simplified)

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g

🇹🇼 正體中文版 / Chinese (Traditional)

npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zht -g

Works with Claude Code, Cursor, Codex, Gemini CLI, Autohand Code, and 40+ agents supporting the Agent Skills spec.

🔧 Claude Code Plugin (Advanced Features)

For Claude Code-specific features like /plan autocomplete commands:

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

That's it! Now use one of these commands in Claude Code:

Command	Autocomplete	Description
/planning-with-files:plan	Type /plan	Start planning session (v2.11.0+)
/planning-with-files:status	Type /plan:status	Show planning progress at a glance (v2.15.0+)
/planning-with-files:start	Type /planning	Original start command

Alternative: If you want /planning-with-files (without prefix), copy skills to your local folder:

macOS/Linux:

cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/

Windows (PowerShell):

Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"

See docs/installation.md for all installation methods.

On December 29, 2025, Meta acquired Manus for $2 billion. In just 8 months, Manus went from launch to $100M+ revenue. Their secret? Context engineering.

"Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables." — Manus AI

Claude Code (and most AI agents) suffer from:

• Volatile memory — TodoWrite tool disappears on context reset
• Goal drift — After 50+ tool calls, original goals get forgotten
• Hidden errors — Failures aren't tracked, so the same mistakes repeat
• Context stuffing — Everything crammed into context instead of stored

The Solution: 3-File Pattern

For every complex task, create THREE files:

task_plan.md      → Track phases and progress
findings.md       → Store research and findings
progress.md       → Session log and test results



Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.

Principle	Implementation
Filesystem as memory	Store in files, not context
Attention manipulation	Re-read plan before decisions (hooks)
Error persistence	Log failures in plan file
Goal tracking	Checkboxes show progress
Completion verification	Stop hook checks all phases

Once installed, the AI agent will:

1. Ask for your task if no description is provided
2. Createtask_plan.md, findings.md, and progress.md in your project directory
3. Re-read plan before major decisions (via PreToolUse hook in legacy mode; autonomous mode injects at session start and phase transitions instead, dropping the per-tool-call tax on strong models)
4. Remind you to update status after file writes (via PostToolUse hook)
5. Store findings in findings.md instead of stuffing context
6. Log errors for future reference
7. Verify completion before stopping (via Stop hook)

Invoke with:

• /planning-with-files:plan - Type /plan to find in autocomplete (v2.11.0+)
• /planning-with-files:start - Type /planning to find in autocomplete
• /planning-with-files - Only if you copied skills to ~/.claude/skills/

See docs/quickstart.md for the full 5-step guide.

Methodology note: the 96.7% figure comes from the v2.21.0 evaluation run on claude-sonnet-4-6 (2026-03-06). It measures file-pattern fidelity (does the agent create and maintain the 3-file structure), not goal-drift over long autonomous runs. Newer models and the autonomous-mode work are not yet covered by this number. Full methodology, dataset, and assertion list: docs/evals.md.

Formally evaluated using Anthropic's skill-creator framework (v2.22.0), model claude-sonnet-4-6, 2026-03-06. 10 parallel subagents, 5 task types, 30 objectively verifiable assertions, 3 blind A/B comparisons.

Test	with_skill	without_skill
Pass rate (30 assertions)	96.7% (29/30)	6.7% (2/30)
3-file pattern followed	5/5 evals	0/5 evals
Blind A/B wins	3/3 (100%)	0/3
Avg rubric score	10.0/10	6.8/10

Full methodology and results · Technical write-up

1. Create Plan First — Never start without task_plan.md
2. The 2-Action Rule — Save findings after every 2 view/browser operations
3. Log ALL Errors — They help avoid repetition
4. Never Repeat Failures — Track attempts, mutate approach

Use this pattern for:

• Multi-step tasks (3+ steps)
• Research tasks
• Building/creating projects
• Tasks spanning many tool calls

Skip for:

• Simple questions

• Single-file edits

• Quick lookups

  planning-with-files/ ├── commands/ # Plugin commands │ ├── plan.md # /planning-with-files:plan command (v2.11.0+) │ ├── plan-ar.md # Arabic /plan command (v2.33.0+) │ ├── plan-de.md # German /plan command (v2.33.0+) │ ├── plan-es.md # Spanish /plan command (v2.33.0+) │ └── start.md # /planning-with-files:start command ├── templates/ # Root-level templates (for CLAUDE_PLUGIN_ROOT) ├── scripts/ # Root-level scripts (for CLAUDE_PLUGIN_ROOT) ├── docs/ # Documentation │ ├── installation.md │ ├── quickstart.md │ ├── workflow.md │ ├── troubleshooting.md │ ├── gemini.md # Gemini CLI setup │ ├── cursor.md │ ├── windows.md │ ├── kilocode.md │ ├── codex.md │ ├── opencode.md │ ├── mastra.md # Mastra Code setup │ └── boxlite.md # BoxLite sandbox setup ├── examples/ # Integration examples │ └── boxlite/ # BoxLite quickstart │ ├── README.md │ └── quickstart.py ├── planning-with-files/ # Plugin skill folder │ ├── SKILL.md │ ├── templates/ │ └── scripts/ ├── skills/ # Skill variants │ ├── planning-with-files/ # English (default) │ │ ├── SKILL.md │ │ ├── examples.md │ │ ├── reference.md │ │ ├── templates/ │ │ └── scripts/ │ │ ├── init-session.sh │ │ ├── check-complete.sh │ │ ├── init-session.ps1 # Windows PowerShell │ │ └── check-complete.ps1 # Windows PowerShell │ ├── planning-with-files-ar/ # Arabic (v2.33.0+) │ │ ├── SKILL.md │ │ ├── templates/ │ │ └── scripts/ │ ├── planning-with-files-de/ # German (v2.33.0+) │ │ ├── SKILL.md │ │ ├── templates/ │ │ └── scripts/ │ ├── planning-with-files-es/ # Spanish (v2.33.0+) │ │ ├── SKILL.md │ │ ├── templates/ │ │ └── scripts/ │ ├── planning-with-files-zh/ # Chinese Simplified (v2.25.0+) │ └── planning-with-files-zht/ # Chinese Traditional (v2.28.0+) ├── .gemini/ # Gemini CLI skills + hooks │ ├── settings.json # Hook configuration (v2.26.0) │ ├── hooks/ # Hook scripts (SessionStart, BeforeTool, AfterTool, BeforeModel, SessionEnd) │ └── skills/ │ └── planning-with-files/ ├── .codex/ # Codex CLI skills + hooks │ └── skills/ ├── .opencode/ # OpenCode skills (custom session storage) │ └── skills/ ├── .claude-plugin/ # Plugin manifest ├── .cursor/ # Cursor skills + hooks │ ├── hooks.json # Hook configuration │ ├── hooks/ # Hook scripts (bash + PowerShell) │ └── skills/ ├── .codebuddy/ # CodeBuddy skills + hooks │ └── skills/ ├── .factory/ # FactoryAI Droid skills + hooks (v2.26.0) │ └── skills/ ├── .pi/ # Pi Agent skills (npm package) │ └── skills/ │ └── planning-with-files/ ├── .continue/ # Continue.dev skills + prompt files │ ├── prompts/ # .prompt file for slash commands │ └── skills/ ├── .github/ # GitHub Copilot hooks (incl. errorOccurred) │ └── hooks/ │ ├── planning-with-files.json # Hook configuration │ └── scripts/ # Hook scripts (bash + PowerShell) ├── .mastracode/ # Mastra Code skills + hooks │ └── skills/ ├── .kiro/ # Kiro Agent Skills (v2.27.0+) │ └── skills/ ├── CHANGELOG.md ├── CITATION.cff ├── LICENSE └── README.md

How do I stop my coding agent from losing its plan after /clear or a crash?

The plan lives on disk in task_plan.md, findings.md, and progress.md, not only in the context window. At the start of each turn the UserPromptSubmit hook re-injects the active plan, and after a /clear or a new session the skill re-reads the files from disk (session recovery), so the agent recovers its goals and progress automatically.

What is the difference between planning-with-files and an agent memory tool?

Agent memory tools (vector stores, knowledge graphs) help an agent recall facts from past sessions. planning-with-files manages active execution state: the phases, status, dependencies, and completion check for the task the agent is working on right now. The problem it solves is planning continuity, not retrieval, and the two are complementary.

How does this prevent context rot?

Context rot is the drift that sets in as the context window fills and earlier instructions get crowded out. Because the plan is re-injected at the start of each turn from disk, the goals and phase status stay in the model's attention window as the conversation grows. This is an implementation of what Anthropic calls structured note-taking: write durable state to files outside the window, then read it back in when needed.

Which coding agents does this work with?

Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, CodeBuddy, Factory, Mastra, and 60+ others via the SKILL.md open standard. Installation is one command; see Quick Install above.

All platform setup guides and documentation are in the docs/ folder.

• Manus AI — For pioneering context engineering patterns
• Anthropic — For Claude Code, Agent Skills, and the Plugin system
• Lance Martin — For the detailed Manus architecture analysis
• Based on Context Engineering for AI Agents

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

MIT License — feel free to use, modify, and distribute.

---

Author: Ahmad Othman Ammar Adi