Planning with Files
Persistent disk-backed plans for coding agents that must survive context loss.
Per-dimension scores and reasoning
Evidence shows: scripts run with least privilege, no network calls, file operations limited to project directory; user confirmation mechanisms (e.g., Pi's /plan-execute); data flow transparency (documented injection format and hooks); sensitive data handling with SHA-256 verification and path isolation; no external dependencies; external effects limited to local file writes; rollback limited (no automatic rollback, but manual recovery possible); source attribution clear (MIT license, author attribution). Deductions: rollback mechanism incomplete, no automatic rollback or backup provided.
Evidence shows: script logic consistent, tests cover sync and cross-project protection; dependency availability high (no external dependencies, uses system tools); failure messages clear (e.g., plan-doctor). Deductions: no obvious flaws, but static review cannot verify runtime behavior.
Evidence shows: targets multiple AI agents and scenarios, provides detailed tiered support; capability boundaries clear (e.g., hook limitations); trigger precision (e.g., /plan command); environment fit broad (supports multiple IDEs and OS). Deductions: some platform support may not be fully verified.
Evidence shows: information architecture clear (README, docs, tests); install notes detailed; naming stable (versioned commands); examples and FAQ rich; known limitations documented; MIT license clear; versioning changelog present; maintenance responsibility clear (author maintains). Deductions: changelog may be incomplete.
Evidence shows: output usability high (clear plan file format); marginal value high (solves context loss problem); cost-benefit reasonable (simple install, low performance overhead). Deductions: cost-benefit not quantified, lacks performance benchmarks.
Evidence shows: claims traceable (README references docs and tests); cross-source corroboration limited (mainly relies on own docs); fact-inference separation (internal benchmarks clearly labeled). Deductions: cross-source corroboration insufficient, lacks independent verification.
- Static review cannot verify runtime behavior; actual testing is recommended.
- Rollback mechanism is incomplete; consider backing up plan files before critical operations.
- Cross-source corroboration is insufficient; consider independent evaluations or community feedback.
What does this agent do, and when should you use it?
Planning with Files is a persistent planning skill for AI coding agents and long-running engineering tasks. It maintains task_plan.md, findings.md, and progress.md in the working project to hold phases, research, execution logs, and test results outside the context window. Enhanced integrations use lifecycle hooks to re-inject plan state each turn and to prompt for progress or evaluate completion around compaction and stopping. The repository also includes session recovery, SHA-256 plan attestation, isolated parallel-plan directories, and optional autonomous or gated modes. It ships as a Claude Code plugin or through the Agent Skills installer; platforms without enhanced hooks can still use the file pattern but may not receive the same automation.
For qualifying multi-step work, the skill creates task_plan.md, findings.md, and progress.md. It records phases and checkboxes in task_plan.md, appends research and decisions to findings.md, and logs actions and test results in progress.md. The UserPromptSubmit hook injects the on-disk plan inside an ===BEGIN PLAN DATA=== block; documented Claude Code hooks also include PreToolUse, PostToolUse, Stop, and PreCompact, while Codex configures SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, and Stop. session-catchup examines the active IDE's session store, compares planning-file updates, and produces a catchup report. /plan-attest locks task_plan.md with SHA-256, /pwf --autonomous and --gated enable long-running modes, and .planning/YYYY-MM-DD-slug/ plus .active_plan isolate parallel plans.
- A Claude Code user refactoring authentication middleware who needs to resume unfinished regression tests after /clear.
- A Codex CLI user running a long task with research, code changes, and verification who wants the current phase placed back into context each turn.
- A developer handling several unrelated workstreams who needs .planning/YYYY-MM-DD-slug/ directories to keep each task's state separate.
- A team using Cursor, GitHub Copilot, or Kiro that wants to add documented plan injection and completion checks where host hooks are supported.
- An engineer returning after a crash or compaction who needs a coding agent to reconstruct the active task from disk-based phases, findings, and logs.
What are this agent's strengths and limitations?
- The three-file workflow keeps active execution state on disk and re-injects it per turn, directly addressing loss after /clear, crashes, and compaction.
- It documents concrete lifecycle-hook integrations for Claude Code and Codex rather than relying only on planning prompts.
- Long-running-task features include session catchup, SHA-256 plan attestation, an append-only JSONL run ledger, and isolated parallel plans.
- It offers both a Claude Code plugin and an Agent Skills route, alongside mirrored integrations for multiple coding environments.
- Full automation depends on host lifecycle hooks; the standard Agent Skills route may provide only the file pattern, and installs can silently lack hooks.
- Planning files are gitignored by default and are not automatically archived; a subsequent root-level task can overwrite the previous plan.
- Session recovery depends on each IDE's local session store and path handling; release notes document past portability issues across platforms and unusual paths.
- The reported 96.7% pass rate and recovery-turn results are author-run internal evaluations of file-pattern fidelity and re-orientation cost, not independent evidence of long-run task success.
How do you install or deploy this agent?
For the Claude Code plugin route, run /plugin marketplace add OthmanAdi/planning-with-files, then /plugin install planning-with-files@planning-with-files. For other Agent Skills-compatible agents, run npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g in a shell; this route needs working npx and network access. The plugin route ships slash commands and hooks. The skill route can be hook-less when project trust is not accepted or frontmatter hooks do not register.
How do you use this agent?
In Claude Code, run /plan or /pwf to create the planning files and start a session; asking the agent to “plan this task” is also documented as a trigger. During work, append findings to findings.md, write actions and test results to progress.md, and check completed phases in task_plan.md. Use /pwf --autonomous or /pwf --gated for the documented long-running modes, and /plan-doctor to diagnose installation and injection. On Pi, the skill creates the files first, then /plan-execute explicitly activates its hooks.
How does this agent compare with similar options?
The repository distinguishes this from memory tools: vector stores and knowledge graphs retrieve facts from past sessions, while Planning with Files manages the active task's phases, dependencies, errors, and completion state. It is also positioned as complementary to Claude Code Plan Mode: Plan Mode designs and approves an approach, while this skill persists live execution state after work begins.