Planning with Files is an agent skill that keeps a coding agent's working plan on disk rather than in its context window. It maintains three markdown files in the project: a task plan with phases and checkboxes, a findings file for research notes and decisions, and a progress log for session history and test results. Lifecycle hooks re-inject the active plan at the start of every turn, so the plan outlives a context reset, compaction, or a crash, and a fresh session resumes at the current phase. The pattern follows the context-engineering approach Manus described, treating the context window as volatile memory and the filesystem as persistent storage.
The skill installs through the Agent Skills standard and runs on a tiered set of hosts. Enhanced hosts (Claude Code, Codex, Hermes, OpenCode, DeepSeek Harness, Cursor, GitHub Copilot, Gemini CLI, Kiro, Qoder CLI, CodeBuddy, Factory Droid, Mastra Code) get native plugins with plan injection every turn, progress reminders, and a completion check. Standard hosts (Continue, Pi, OpenClaw, Kilo Code, Antigravity, Autohand Code, AdaL CLI) discover the skill without lifecycle hooks, and tools that read the Agent Skills standard path (Zed, Amp, Warp, Devin, Gemini CLI, Cursor) pick it up from a plain checkout.
Hook counts differ per host: the Claude Code plugin runs 6 lifecycle hooks, Codex 7, Pi 8, the Hermes plugin 3, and the OpenCode and DeepSeek Harness plugins 4 each. All hosts read the same files, attestation, and gate counters, so a plan can be handed from one agent to another mid-run. Multi-agent runs use the markdown on disk as shared state: one orchestrator owns the task plan, each worker appends to its own JSONL ledger, and parallel tasks get isolated plan directories selected by a plan ID.
The v3 line adds modes for long-running runs. Autonomous mode drops per-tool-call plan recitation and turns on SHA-256 attestation of the plan file, and gated mode adds a Stop gate that holds the agent until every completion condition is met, capped at 20 consecutive blocks by default. Session recovery reads project files only. Reading local session records for aggregate counts or bounded replay requires an explicit catchup mode, and neither mode makes a network request.
The project reports an evaluation run with Anthropic's skill-creator framework on claude-sonnet-4-6 (skill v2.21.0, 2026-03-06) covering file-pattern fidelity, plus an internal recovery benchmark in which a fresh session told only to continue the work resumed in 5.0 turns on average with the planning files against 13.3 turns for an agent with no planning method.
| 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 | 0/3 |
| Avg rubric score | 10.0/10 | 6.8/10 |
Features
- Three-file plan: a task plan with phases and checkboxes, a findings file for notes and decisions, and a progress log, all plain markdown in the project and gitignored by default
- Turn-start injection: lifecycle hooks re-read the plan from disk at the start of every turn, so it survives a context reset, compaction, and crashes
- Tiered host support: native plugins with hooks for Claude Code, Codex, Hermes, OpenCode, DeepSeek Harness, Cursor, Copilot, Gemini CLI and Kiro, and Agent Skills discovery for Continue, Pi, OpenClaw, Kilo Code, Zed, Amp, Warp and Devin
- Autonomous and gated modes: autonomous mode drops per-call recitation and attests the plan, gated mode adds a Stop gate that releases only when every completion condition holds
- SHA-256 plan attestation: locks the task plan, and hooks refuse to inject a tampered plan body
- Multi-agent shared state: one orchestrator owns the plan, workers append to per-agent JSONL ledgers, and a fixed-shape ledger summary replaces the raw progress tail
- Plan isolation: each parallel task gets its own dated plan directory, pinned to a terminal by plan ID or bound to a project root by absolute path
- Parallel-write guard: warns on the next turn when checked items or completed phases decrease, an advisory check rather than a lock
- Session recovery: automatic recovery reads project files only, and an explicit catchup mode reads local session records for aggregate counts or bounded excerpts
- Slash commands: plan creation, status, a self-check doctor, attestation, a run-until-complete goal, a planning-aware loop, and plan start in German, Arabic, Spanish, and Chinese
- Pi runtime modes: auto, parity, cache-safe (a stable reminder for KV-cache-sensitive models), and notify (status line only)
- Translations: the skill ships in English, Arabic, German, Spanish, and Chinese
