Skip to content
Get packs

Guide · Open source

How to use planning-with-files: install and resume AI agent tasks

Updated · written with AI from the project's own documentation and checked against our catalogue data

planning-with-files is an open-source agent skill that keeps a task plan, research notes and a progress log as markdown files inside your project. Lifecycle hooks re-inject that planning context so an AI coding agent can resume where it left off after /clear, context compaction or a crash. This guide shows you how to install it, what the three files do, and how to start a long-running task with it.

planning-with-filesOthmanAdi/planning-with-files · ★ 27.8k · MIT

Quick start

  1. 1Install the skill. Run npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g to add it globally.
  2. 2Confirm your host. Check whether your agent is a native host in the README, such as Claude Code or Codex CLI, or another Agent Skills-compatible agent.
  3. 3Start a long task. Ask the agent to work on a multi-step task while the skill is active so it creates the planning files.
  4. 4Review task_plan.md. Open the plan in your project and check the phases and checkboxes before the agent continues.
  5. 5Resume after a reset. After /clear, compaction or a crash, let the hooks re-inject context and continue from the current phase in task_plan.md.
  6. 6Check progress. Use progress.md to see the session log and test results.

What planning-with-files does

Coding agents keep working memory in the context window, which is limited and can be cleared or compacted. planning-with-files moves the important state to disk. The skill keeps task_plan.md, findings.md and progress.md in your project, and activated lifecycle hooks inject selected project planning context so the plan survives context loss, /clear, crashes and compaction.

  • task_plan.md holds phases and checkboxes and is the resume point after /clear.
  • findings.md holds research notes and decisions, appended as you go.
  • progress.md holds the session log and test results.

Install planning-with-files

The README's quick install uses npx skills to add the skill globally. The project also lists installation through npm, the Claude Code plugin marketplace and npx skills, and a full install guide is linked from the README. No prerequisites are listed in the source.

  • Run the install command below in your terminal.
  • For other install routes, see the project's docs/installation.md file.
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

Choose your agent host

The README says the skill installs across 60+ agents through the Agent Skills standard. It also lists native plugins for Claude Code, Codex CLI, Qoder CLI, Pi, Hermes Agent, OpenCode and DeepSeek Harness. Native plugins provide planning context loading, progress reminders and a completion gate, but commands and tools depend on the host.

If your host is not in the native list, the skill may still work through the Agent Skills route, but the README notes that results may vary.

Understand the 3-file pattern in your project

After the skill is active, your project holds the plan as plain markdown. Parallel tasks can use isolated directories instead, named .planning/YYYY-MM-DD-slug/ with the same three files and selected through .active_plan (the README notes this from v2.36.0 onward). The files are gitignored by default and the README says there is no runtime state stored elsewhere.

  • Because the plan is plain markdown, you can open and edit it directly.
  • Check task_plan.md first when you resume a task after /clear.
your-project/ ├── task_plan.md ├── findings.md └── progress.md

Run a long task and resume after a reset

Start a multi-step task with the agent while the skill is active. The agent writes its phases and progress to the files as it works. If the context window is cleared or compacted, the hooks re-inject planning context so the agent can read the plan and continue at the current phase.

The README also describes a deterministic completion gate that can hold the agent's stop until the plan reports complete. Its status tokens, such as **Status:** complete, are matched literally by the check script, so keep them as written.

  • Keep task_plan.md checkboxes current so the resume point stays accurate.
  • Use progress.md for test results and session notes.

Know what the skill reads

The README says automatic recovery reads project files only. Reading same-project local agent session records for aggregate counts or bounded replay requires an explicit catchup mode. Review this distinction if you care what the skill accesses.

What people use it for

  • Multi-step refactors in Claude Code that span several sessions.
  • Long feature builds in Codex CLI where the context window fills up.
  • Research-heavy tasks where findings should be kept as notes in the project.
  • Team projects that want the plan stored as plain markdown in the repository.

Frequently asked questions

Is planning-with-files free?

The project is released under the MIT licence, as stated in the README. Check the LICENSE file in the repository for the full terms.

What are the requirements for planning-with-files?

The source does not list specific prerequisites. You need an AI coding agent that supports the Agent Skills standard or one of the native hosts named in the README.

Which agents does planning-with-files support?

The README says it installs across 60+ agents through the Agent Skills standard. Native plugins are listed for Claude Code, Codex CLI, Qoder CLI, Pi, Hermes Agent, OpenCode and DeepSeek Harness.

How is planning-with-files different from a built-in to-do list?

The README says most harnesses keep a to-do list inside the context window, while this skill keeps the plan on disk, re-injects it every turn and can hold the agent's stop until the plan is complete.

What alternatives exist to planning-with-files?

Comparable projects named in the source are Cline, Aider and OpenHands. They are different tools, so check which fits your workflow before choosing.

Why does my agent not resume after /clear?

The README says native support depends on the host and results may vary. Confirm the skill is installed for your agent and that task_plan.md exists in the project.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use planning-with-files if you run long multi-step tasks in Claude Code, Codex CLI or another Agent Skills-compatible agent and keep losing progress after /clear, compaction or a crash. Skip it for short one-off questions, or if you want a hosted service instead of plain markdown files in your repository.

Install options & downloads