Planning With Files

What it does

• Three files on disk — task_plan.md, findings.md, progress.md — with a UserPromptSubmit hook re-injecting the active plan at the start of every turn
• Survives /clear, compaction and crashes: after a wipe the skill re-reads project files from disk; the recovery path reads project files only, not agent transcripts
• Installs across 60+ agents via the Agent Skills standard, with native plugins for Claude Code, Codex CLI, Qoder, Pi, Hermes Agent, OpenCode and DeepSeek Harness
• v3 long-running features: per-agent run ledgers, PLAN_ID plan isolation for parallel tasks, a stall-aware completion gate, and a parallel-write guard

When to use it

Long multi-phase tasks where "my agent forgot the plan halfway" is the failure mode: refactors, migrations, builds that span days. Complements rather than replaces plan mode — accept the plan, have it written into task_plan.md, and the hooks hold it in the attention window. Also covers orchestrator/worker setups where one plan is handed across hosts (Claude Code, Codex, Pi, Hermes and OpenCode read the same files).

Getting started

Claude Code plugin route (skill + hooks + slash commands):

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

Every other agent, one line (60+ agents):

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

npm install planning-with-files exists for pinning a version, but does not register hooks.

Things to know

What each route ships differs: only the Claude Code plugin (and the native Pi/Hermes/OpenCode/DSH plugins) bring hooks; a bare npx skills add gets the pattern, with frontmatter hooks depending on the host. Plan files are gitignored working memory by default — the next task overwrites the root plan, so promote anything worth keeping into code or docs. Hook cost is 289ms per fire since v3.6.0 (KV-cache stable). A Chinese-language skill variant (planning-with-files-zh) ships separately.