Keep Your Coding Agent on Plan Across /clear with planning-with-files

Long agent tasks fail the same way: the context window gets wiped by /clear, a crash, or compaction — and the plan dies with it. planning-with-files, a 27k-star skill, keeps the plan on disk and re-injects it every turn, so a fresh session resumes at the current phase instead of asking you what you were doing.

Why This Skill Matters

The core is a three-file pattern: task_plan.md tracks phases and checkboxes, findings.md accumulates research notes and decisions, and progress.md logs sessions and test results. The principle behind them is blunt — treat the context window as RAM and the filesystem as disk, and write anything important down. Lifecycle hooks (SessionStart, UserPromptSubmit, PreCompact on the Claude Code plugin route) carry the current phase back into the window at the start of each turn.

The README reports a 96.7% assertion pass rate with the skill (29 of 30) and 3-of-3 blind A/B wins — the project's own evaluation, so read them as vendor numbers. Version 3 adds machinery for long runs: SHA-256 attestation that refuses a tampered plan at injection, a gated mode whose Stop hook holds the stop while an in_progress phase remains (with a block cap and stall detection so an incomplete plan alone never traps a session), and a parallel-write guard that warns when completed phases go down between turns.

Installation

On Claude Code, the plugin route ships the skill, the hooks, and the slash commands together:

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

Every other agent gets the one-line route through the Agent Skills standard, which the README says covers 60+ agents:

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

A simplified Chinese variant installs with --skill planning-with-files-zh. One documented caveat: skill-route installs can end up silently hook-less — if the hooks matter to you, use the plugin route and verify with /plan-doctor.

Real Workflow: Plan a Multi-Phase Refactor, Then Survive /clear

1. With the plugin installed, tell your agent plan this task (or type /plan). It creates the three planning files for the current task.
2. Work normally. Findings get appended to findings.md, finished phases get checked off in task_plan.md.
3. Now run /clear and ask the agent to continue. The UserPromptSubmit hook injects the plan data block from disk, and the agent picks up at the current phase — no re-explaining, no rediscovering finished work.

The skill's own trigger rule keeps this honest: a task needs 3+ steps or 5+ tool calls before the three files are worth creating.

Real Workflow: Run Two Tasks in Parallel

Parallel tasks get isolated directories instead of sharing the root plan. Start each one with a named slug and you get a .planning/YYYY-MM-DD-<slug>/ directory with its own three files; PLAN_ID pins a host to one of them, and set-active-plan.sh --list shows the saved plans with phase counts. The parallel-write guard covers the failure mode where two sessions overwrite each other: the next turn warns when checked items or completed phases decrease.

Tips

• Run /plan-doctor after installing. It self-checks plan resolution, injection, attestation, install surfaces, and per-fire latency — the fastest way to catch a silently hook-less install.
• The plan files are gitignored working memory, not deliverables. The next task overwrites the root plan, so promote anything worth keeping into code, a commit, or a doc.
• One hook fire measures about 289ms since the v3.6.0 optimization, per the README — fast enough to leave on for everyday work.
• The npm install planning-with-files route vendors the files for pinning a version, but registers no hooks on its own.

When Not to Use This

This skill manages execution state, not knowledge recall — the README contrasts it with agent memory tools, which retrieve facts from past sessions; the two are complementary. Single-step tasks do not need three files. And the automation is the hooks: if your host cannot run the plugin's lifecycle hooks, you get the file pattern without the re-injection that makes it survive a reset.

See the leaderboard for more skills.