planningwithfiles
Open source · v3.28.1

Pick up where
the work stopped.

Keep your agent’s plan, decisions and unfinished checks
in the project, ready for the next session.

Install Planning with Files Run the recovery exercise

Open-source planning for coding agents. Plain Markdown you can inspect.

Context resets.
The plan stays.

Try clearing the conversation

Interactive illustrationState saved to the project
Current session

“Implementation done.”

Expiry boundary tests still pending

task_plan.md✓ saved

Ship the expiry fix

  • ✓ Find the cause
  • ✓ Write the patch
  • Add boundary tests

Next: test just before & at expiry.

The unfinished step is saved, even if the chat disappears.

A sketch of the workflow, not a live agent run.

Stop keeping the whole
project in the conversation.

Long tasks outlive a single conversation. Keep decisions and unfinished work in files you can review and carry into the next session.

task_plan.mdExample file
# Ship the expiry fix

## Goal
Reject expired tokens at the exact boundary.

## Phases
[x] Reproduce the bug
[x] Implement the fix
[ ] Verify expiry boundaries

## Next step
Test one second before expiry, then at expiry.

Plain Markdown. Readable by you and your agents. Only recorded work can be recovered.

Works with your agent.
On its terms.

Keep the file-based workflow across tools. Add the lifecycle support your host actually provides.

Find your host’s setup

Bring the plan back

Activated integrations surface selected planning context at supported lifecycle points.

Catch unfinished phases

Optional gated mode can block a stop or ask for another pass, with retry and stall limits. Some hosts can only notify.

Give parallel work its own plan

Pin each task to its own plan or use separate worktrees. One shared selection is not a boundary between sessions.

Completion checks read recorded state. Tests and review establish whether the code is right.

Claude CodeCodexCursorOpenCodePiSee all setups

New session.
Same next step.

Save the task before the conversation ends. Let the next session start with what remains.

5-second illustrated walkthrough
Existing project illustration. Recovery depends on saved state and host setup.
Run it yourself · Python standard library

A real task.
A checkable handoff.

Download a small, interrupted coding task. Give a fresh agent the saved files, then grade its work outside the agent’s workspace.

File-only recovery exercise

The starting code counts words. Two functions remain unfinished. The plan records the next step; the grader checks the code and the final plan state.

Pinned to v3.28.1 · MIT license · Python 3
Download the exercise

  1. Check the starting point

    Extract the ZIP and open examples/file-only-recovery/. Run:

    python grade.py --self-check

    This checks the fixture’s unfinished and completed examples. It does not run an AI model.

  2. Start a fresh session

    Follow the included README to copy TASK.md and the checkpoint files into a new work directory. Open that directory in your coding agent and ask:

    Continue the work in this directory.

    Keep the grader outside that directory. Leave session replay off for the file-only trial.

  3. Check what actually finished

    From the fixture directory, grade the agent’s work using the path to your new directory:

    python grade.py <work-directory>

    The result is pass, fail or inconclusive. Record the host, model and result with the included receipt template.

One small task lets you inspect the workflow. Results depend on the agent, its setup and the record it receives.

Read the complete exercise

Put the next step
in the project.

Choose the setup for your coding agent.
The core stays free and open source.

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

This command installs the current standalone skill. Native plugins, startup hooks and commands have host-specific setup.

Choose your host’s setup Download v3.28.1
Use the pinned release locally

Download and extract the source ZIP. It includes the skill, scripts, templates, host integrations and documentation. For Claude Code, run this from the folder containing the extracted release:

claude --plugin-dir ./planning-with-files-v3.28.1

Use the included docs/installation.md for other hosts. This ZIP is pinned to the published release; the install command above follows the current repository.

Verify SHA-256 checksums · Read release notes