Planning with Files

Install

Manual install

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

This is third-party code. Review the repository files before installing.

What it does

The skill makes the agent keep its plan not in the context window but in three markdown files in the project: task_plan.md with phases and checkboxes, findings.md with notes and decisions, and progress.md with a session log. Lifecycle hooks at session start, on prompt submit and before compaction re-inject the current phase into context, so work is not lost after /clear, compaction or a crash. Recovery reads only the project's plan files; a separate catchup mode, run explicitly, can read the same project's local session records for aggregate counts or bounded excerpts. There is a gated mode: the Stop hook holds the stop while an unfinished phase remains, with a cap and stall protection. Plan integrity is checked with a SHA-256 hash: a plan body changed past the approved hash is flagged as tampering. Parallel tasks get separate plan directories. It installs in Claude Code as a plugin and in dozens of other agents through the Agent Skills standard.

Who it is for. For developers and anyone running long, multi-step agent tasks that must not reset when the context clears.

Example request

Plan this task in files and resume from the current phase even after the context is cleared

Limitations

The full effect comes from the lifecycle hooks, which are registered by the plugin or npx skills install but not by the npm package alone. The completion gate and continuation mode work only on hosts that support them. Plan files are gitignored by default and live locally; hosts do not sync them with each other. The recovery-turn figures in the README are described by the author as historical and from their own runs rather than a fresh measurement of current behavior.

How to disable. Remove the planning-with-files plugin via /plugin in Claude Code, or delete the skill folder from the agent's skills directory. The task_plan.md, findings.md and progress.md files can be deleted from the project by hand.

Security check

• Registers lifecycle hooks that run scripts every turn
• Reads project files and writes plan files to disk

README in short

The README presents a persistent planning skill for coding agents: the task plan lives in three markdown files on disk, and lifecycle hooks re-inject the current phase into context every turn so work survives /clear, compaction and crashes. It describes optional modes: a completion gate that holds the stop until the plan is ready, a SHA-256 hash that catches plan tampering, and an autonomous mode that saves tokens. The approach cites Manus's principle of the filesystem as working memory. It installs in Claude Code via a plugin and in other agents via npx skills and the Agent Skills standard, with native plugins for Codex, Pi, Hermes, OpenCode and DeepSeek Harness. The author's own benchmarks are included. MIT licensed.

SKILL.md

---
name: planning-with-files
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
user-invocable: true
allowed-tools: "Read Write Edit Bash Glob Grep"
metadata:
  version: "3.20.1"
---

# Planning with Files

Work like Manus: Use persistent markdown files as your "working memory on disk."

## FIRST: Restore Project State

Before continuing, resolve the plan this task owns: use the installed resolve-plan-dir script with the task's PLAN_ID and PWF_PLAN_ROOT, and read task_plan.md, progress.md and findings.md from that one selected directory. Run git diff --stat to see code changes not yet recorded in the planning files.

Related