hub / github.com/OthmanAdi/planning-with-files

github.com/OthmanAdi/planning-with-files @v3.1.3 sqlite

repository ↗ · DeepWiki ↗ · release v3.1.3 ↗

477 symbols 1,236 edges 38 files 89 documented · 19%

README

Planning with Files

📣 New in v3.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

Forks & Extensions

Fork	Author	What They Built
devis	@st01cs	Interview-first workflow, `/devis:intv` and `/devis:impl` commands, guaranteed activation
multi-manus-planning	@kmichels	Multi-project support, SessionStart git sync
plan-cascade	@Taoidle	Multi-level task orchestration, parallel execution, multi-agent collaboration
agentfund-skill	@RioTheGreat-ai	Crowdfunding for AI agents with milestone-based escrow on Base
openclaw-github-repo-commander	@wd041216-bit	7-stage GitHub repo audit, optimization, and cleanup workflow for OpenClaw

Used in the Wild

Project	What It Is
lincolnwan/Planning-with-files-copilot-agent	Entire Copilot agent repo built around the planning-with-files skill
cooragent/ClarityFinance	AI finance agent framework — Planning-with-Files approach directly credited
oeftimie/vv-claude-harness	Claude Code harness built on Manus-style persistent markdown planning
jessepwj/CCteam-creator	Multi-agent team orchestration skill using file-based planning

Skill Registries & Hubs

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

Current Version: v3.1.3

Version	Highlights
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 canonical `hooks` feature flag (PR #184 by @Fat-Jan). The `docs/codex.md` verify block ran `codex features list \\| rg '^codex_hooks\s'`, but Codex moved its canonical feature key from `codex_hooks` to `hooks` in 0.129.0 (openai/codex#20522). The alias still resolves in config, yet `codex features list` prints only `hooks`, so the old pattern matched nothing on current Codex and routed correctly configured users to the upgrade path. The command now greps `^(hooks\\|codex_hooks)\s` and the troubleshooting sentence covers both names, matching the `hooks = true` guidance carried in the file since v2.39.0. Documentation only; suite at 180 passed.
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	POSIX `init-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

Core symbols most depended-on inside this repo

_build_manifest

called by 8

scripts/sync-ide-folders.py

yaml_escape

called by 4

scripts/_v240_update_hook_bodies.py

file_hash

called by 4

scripts/sync-ide-folders.py

json_loads

called by 3

skills/planning-with-files-es/scripts/session-catchup.py

text_content

called by 3

skills/planning-with-files-es/scripts/session-catchup.py

json_loads

called by 3

skills/planning-with-files/scripts/session-catchup.py

normalize_for_compare

called by 3

skills/planning-with-files/scripts/session-catchup.py

text_content

called by 3

skills/planning-with-files/scripts/session-catchup.py

Shape

Method 244

Function 193

Class 40

Languages

Python100%

Modules by API surface

tests/test_hook_body_v240.py37 symbols

skills/planning-with-files/scripts/session-catchup.py26 symbols

skills/planning-with-files-zht/scripts/session-catchup.py23 symbols

skills/planning-with-files-zh/scripts/session-catchup.py23 symbols

skills/planning-with-files-es/scripts/session-catchup.py23 symbols

skills/planning-with-files-de/scripts/session-catchup.py23 symbols

skills/planning-with-files-ar/scripts/session-catchup.py23 symbols

tests/test_ledger.py22 symbols

tests/test_gate.py22 symbols

tests/test_hermes_adapter.py21 symbols

tests/test_precompact_hook.py16 symbols

tests/test_session_catchup_opencode.py14 symbols

For agents

$ claude mcp add planning-with-files \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact