A fresh coding-agent session can see your code but still miss why you changed it, which approach failed, or which check has not run. I use planning-with-files to keep that working state in the project, so I can inspect the handoff before the agent continues.

I’m Othman Adi, the project’s creator and maintainer. This is a workflow I use, and the small recovery example below is available for anyone to try.

What you need

Claude Code with access to a local project folder. The walkthrough uses its plugin integration. Git helps you compare the saved notes with the actual changes. The optional recovery fixture uses Python’s standard library.

1. Install the Claude Code plugin

Run these inside Claude Code:

/plugin marketplace add OthmanAdi/planning-with-files /plugin install planning-with-files@planning-with-files

Use the plugin route for this walkthrough: a skill-only install has different command and hook behavior.

2. Give the task a written home

Open the project and run /planning-with-files:plan with your task, constraints and checks.

Before coding, review the selected plan and its location. The working record has three files:

• task_plan.md: the goal, phases, current phase and next action.
• findings.md: decisions, discoveries and constraints worth preserving.
• progress.md: what changed, what was tried and what the checks actually returned.

If the project has several named plans, select the one this task owns. An unrelated plan in the project root should not become the handoff.

3. Save an honest stopping point

Before ending a session or clearing context, ask: “Update this task’s planning files with the current phase, changed files, test commands and their actual results. Separate completed work from work that still needs checking. Leave one specific next action.”

Then open the files yourself. A useful next action is “implement line_count and unique_words in counts.py; word_count is done.” “Continue working” is too vague. If a test could not run, keep that fact in the record.

4. Resume in the same project

Start a fresh session in the same project and select the same plan. Ask: “Read this task’s task_plan.md, findings.md and progress.md. Compare the saved state with the code and current diff. Tell me the current phase, what is verified, and the next action before editing. If the notes and code disagree, explain the discrepancy first.”

The Claude Code plugin restores selected planning context through its lifecycle hooks. This explicit check gives you a chance to catch stale notes or a wrong plan selection. It does not reconstruct unsaved decisions.

5. Verify the code and the handoff

First run the checks agreed for your task and record the actual results. Do not mark them as passed merely because the agent says the work is done.

For an optional, disposable recovery experiment, use the pinned file-only recovery fixture linked below. Its starting checkpoint has a working word_count function and two unfinished functions. The planning files record Phase 3 and the remaining work.

Follow the fixture’s setup instructions to create a separate work folder. Its exact fresh-session prompt is “Continue the work in this directory.” Use that prompt for the experiment, rather than the longer inspection prompt above. Then run the supplied grader from outside the work folder. It checks the functions and whether the recorded phase moved forward. Keep failed or inconclusive results in your notes too.

In my small paired trial, both the baseline and the file-only session completed the code. The file-only session also preserved and advanced the recorded phase. This experiment used planning files only, with no plugin or hook activation. It does not validate the plugin hooks described above. There was one valid run per arm, which does not establish a general speed or reliability advantage. The agent could not run Bash in that experiment; I ran the successful check separately.

Cost and limits

The skill is MIT-licensed and adds no subscription fee. Your coding agent’s existing subscription or API usage still applies. I have not measured a time-saving figure for this walkthrough.

Saved files can be stale, incomplete or wrong. Recovery reads project files; session-history inspection is a separate explicit action. Files do not grant tool permissions, prove that a test ran, or guarantee that a task will finish. Keep credentials and private customer data out of material you share.

Try it on an unfinished task where the next step is already known. The useful result is a fresh session that identifies the correct task state, completes the remaining work and leaves a record you can check.

Pinned recovery example: https://github.com/OthmanAdi/planning-with-files/tree/v3.28.1/examples/file-only-recovery

Repository and installation documentation: https://github.com/OthmanAdi/planning-with-files