1. What this skill is
Planning with Files uses task_plan.md, findings.md, and progress.md as persistent working memory for long-running agent tasks, with optional hooks and completion gates on supported clients.
2. What it can help with
It records phases, evidence, failures, and next steps outside the context window, then helps an agent re-read that state after compaction or a new session.
3. Recommended first use
Try the three-file pattern manually on a multi-step task before enabling hooks. If you install the plugin, run its documented doctor command and confirm where files are written.
4. Requirements
The plain skill works across many compatible agents, but plugin hooks and commands vary. It needs permission to create and update Markdown files in the task directory.
5. Who it suits
Useful for research, migrations, refactors, and any task that spans many tool calls or sessions.
6. Limits and safety
Planning files can become noise when used for tiny tasks, and stale notes can mislead later sessions. Project-specific documentation remains the source of truth. Do not place secrets or raw credentials in planning files. Review recovery behavior before allowing access to agent session stores, and keep generated notes out of commits when appropriate.
7. Project and license
Repository content is provided under MIT; check the current LICENSE before reuse. Repository: https://github.com/OthmanAdi/planning-with-files
Break the goal into input, action, and output before adding review checkpoints.
Keep examples, failure conditions, and review criteria so the tutorial stays reusable.