Persistent File Planning
Keep coding agents on track through context loss, /clear, and crashes with durable planning files and completion checks.
The evidence shows scoped writes to project planning files plus path containment, hash attestation, injection framing, and gate caps. However, Bash, Write, and Edit are broad permissions; hooks execute shell commands and read/inject local files; attestation is opt-in in legacy mode; and explicit user confirmation, complete data-flow disclosure, and rollback are incomplete, so points are deducted.
The scripts include path resolution, input validation, diagnostics, block caps, and stall detection, indicating a fairly complete intended happy path. This review did not execute anything or find committed test evidence, and behavior depends on Claude-style hooks, Unix utilities, PowerShell, and host-specific semantics, so abnormal-environment coverage is limited and the score remains below the static-review ceiling.
The audience and use cases are clear: multi-step, long-running work and context recovery, with legacy, parallel, and multi-host modes. Trigger conditions are still broad, non-fit boundaries and Chinese-language behavior are not well specified, and host differences are only partly documented. The core function is local and does not entirely depend on overseas services, so no extra mainland-network deduction is applied.
The skill has useful progressive structure, templates, examples, script documentation, version metadata, and host limitations. However, license details, maintenance ownership, release/update path, and changelog governance are not sufficiently established in the target skill documentation; installation and troubleshooting retain hidden assumptions, and publisher identity is unverified, so points are deducted.
Persistent plans, recovery procedures, progress logs, and completion gates plausibly address the core planning task, and the examples show directly usable artifacts. Still, crash-proof behavior, cross-host/multi-agent claims, and gate effectiveness lack static execution evidence; users must maintain planning artifacts, and comparative benefit versus simpler methods is not demonstrated, so the score is conservative.
Comments, examples, and implementation details provide some auditable evidence, including deterministic rules and failure paths. There is no visible committed test suite, CI coverage, or independent reproduction evidence, and the external references do not provide corroborated evidence within the supplied material, so the score remains low.
- Broad Bash, Write, and Edit permissions plus local hook execution may expand filesystem impact; review the working directory, script paths, and plan contents before use.
- Plan attestation is not enabled by default in legacy mode, and untrusted plan content may be injected into model context; treat plan data strictly as data.
- Host and utility differences may cause silent hook failure or downgrade completion gating; validate key paths in the intended environment.
- The supplied material lacks execution tests, CI coverage, and clear maintenance ownership; publisher identity is also unverified by the FollowSkills registry.
What does this skill do, and when should you use it?
planning-with-files is a file-based planning skill for AI coding agents. It maintains task_plan.md, findings.md, and progress.md on disk to preserve phases, research, errors, and progress. Lifecycle hooks re-read the plan, remind the agent to update state, and check completion before stopping. The repository supports Claude Code, Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, and other Agent Skills-compatible environments, with English, Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese variants.
Creates and maintains task_plan.md, findings.md, and progress.md; re-injects plan context at session starts, tool events, or phase transitions; reminds the agent to update progress after writes; records findings and errors; checks plan completion through Stop hooks; restores context after /clear, compaction, or a new session using local session data and planning files; and optionally provides autonomous mode, gated mode, a structured run ledger, parallel plan isolation, and SHA-256 plan attestation.
- A developer is handling a task with three or more steps and needs phase and goal continuity across many tool calls.
- A research-oriented agent must preserve findings and avoid filling the active context with every observation.
- A long-running autonomous coding run needs to recover after context compaction, /clear, or a crash.
- Multiple agents or parallel sessions need shared or isolated execution state on disk.
- A user of Claude Code, Codex CLI, or another Agent Skills-compatible client wants automated progress and completion checks.
What are this skill's strengths and limitations?
- Planning state persists on disk through context loss, /clear, and crashes.
- Error logs, phase checkboxes, and completion checks support long-running work.
- Optional autonomous mode, gated mode, plan isolation, ledgers, and SHA-256 attestation add control mechanisms.
- Supports many coding-agent environments and multiple languages.
- Released under the MIT License.
- The agent must be able to run shell scripts and read and write local files.
- Full lifecycle automation depends on the target platform's hook support, which varies by platform.
- The actual SKILL.md content is not provided, so its exact frontmatter and complete runtime behavior cannot be independently verified from this source.
- The workflow adds planning-file maintenance and hook processing overhead.
- The 96.7% benchmark covers file-pattern fidelity for v2.21.0 with claude-sonnet-4-6, not overall effectiveness across all versions, models, or platforms.
How do you install this skill?
Run the documented npx command: npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g. Other language variants can be installed by changing the skill name, such as planning-with-files-zh. Claude Code's advanced plugin flow is /plugin marketplace add OthmanAdi/planning-with-files followed by /plugin install planning-with-files@planning-with-files. The source does not document one universal manual installation path for every environment.
How do you use this skill?
After installation, invoke the planning workflow for a complex task, for example /planning-with-files:plan in Claude Code, or /planning-with-files:start. The agent then creates and updates the three planning files during execution. The README recommends skipping the skill for simple questions, single-file edits, and quick lookups.
How does this skill compare with similar options?
The README distinguishes this skill from agent memory tools: memory tools help retrieve facts across sessions, while planning-with-files manages the active task's phases, status, dependencies, and completion checks. It presents the two approaches as complementary.