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, andprogress.mdon 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.
-brightgreen){kind=icon}
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.
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!
See the full list of everyone who made this project better in CONTRIBUTORS.md.
Current Version: v3.4.1
| Version | Highlights |
|---|---|
| v3.5.1 | Codex Windows shell resolver skips WSL bash launchers, pwf-hook.cmd hardens Python discovery, and Pi recitations are delivered as nextTurn so interactive tools are not broken. |
| v3.5.0 | Codex Windows hooks emit valid JSON and survive Unicode (PR #205 by @yolo0731, closes #204), the Pi extension stops re-nagging closed and complete plans (#203 by @ziyu4huang), and the plan lifecycle is documented (#202 by @kcinzgg). On Windows the Codex front door forwarded plain stdout where Codex expects hookSpecificOutput.additionalContext or PreCompact JSON, and UTF-8 broke on both decode and encode; the fix serializes each event in its supported shape with ASCII-safe output, decodes shell output as UTF-8, and writes the .active_plan pointer without a BOM, with the containment resolver hardened to fail closed (audited clean before merge). The Pi resolveNewestPlanDir now ranks by task_plan.md file mtime instead of directory mtime and honors the close marker, so a finished plan no longer loses to an incomplete sibling. Four language commands that referenced a non-existent skill namespace were corrected, a Traditional Chinese /plan-zht command was added, and the README now documents the full v3 command, hook, and mode surface that had shipped but was never listed. |
| v3.4.1 | Codex hooks now run on Windows (closes #201, reported by @mahdiit). The .codex/hooks.json commands were POSIX only, so on Windows the native command interpreter choked on python3 (the Store alias), 2>/dev/null, and the || true success guard whose true is not a Windows command, and every hook reported hook exited with code 1. Each hook now carries a per-hook commandWindows override (the POSIX command is untouched, so macOS and Linux are unchanged) that routes through a new pwf-hook.cmd launcher (real Python via py -3, falling back to python, never the Store python3 alias) and, for the three shell hooks, a new run_sh.py front door. codex_hook_adapter resolves the Git for Windows sh.exe by anchoring on git.exe, so the shell scripts run even when Git's usr\bin is off PATH. Codex hook suites green (17 tests) plus new cross-platform and Windows-only coverage. |
| v3.4.0 | PLANNING_DISABLED=1 per-invocation opt-out for one-shot sessions (closes #195, reported by @marcmuon). One-shot codex exec runs (CI review bots, read-only research agents, nested orchestrators) that merely shared a cwd with an incomplete plan were hijacked: plan context injected, the actual output redirected into progress.md, a fabricated completed phase appended to task_plan.md. All Codex hook entry points, the Python adapter route, and the canonical dispatchers (inject-plan.sh, gate-stop.sh, check-complete.sh/.ps1) now exit before reading the plan when PLANNING_DISABLED=1 is set; PreToolUse keeps emitting its allow decision so tool calls proceed. The guard ships in every distributed copy including the five language variants. Also corrected docs/codex.md's stale claim that the Stop hook blocks (non-blocking since v3.1.0). Suite at 200 passed. |
| v3.3.0 | Pi extension hooks now wait for explicit user approval via /plan-execute (PR #193 by @Dikshj, closes #190, requested by @lazyst). The Pi extension previously activated all hooks as soon as task_plan.md existed, so plan injection, pre-tool recitation, post-write reminders, and auto-continue could start while the user was still reviewing a draft plan. The extension now stays passive with a status line until the active plan is approved with /plan-execute; approval is scoped to the current session and plan path, resets on session lifecycle events, and /plan-execute reset returns to passive review. A plan with a tampered SHA-256 attestation cannot be approved. Suite at 188 passed plus 21 Pi extension vitest tests. |
| 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. |