Planning with Files

Manus-style persistent planning that keeps task_plan.md, findings.md and progress.md on disk so work survives compaction and /clear.

AutomationIntermediate★ 26,060⑂ 2,177AI score 9/10Last updated: Aug 9, 2026

What it does

It makes Claude Code treat the filesystem as working memory on disk by maintaining three markdown files in your project root:

task_plan.md — phases, status, next step, decisions log
findings.md — research and discoveries (written after every 2 view/search operations)
progress.md — session log, test results, errors encountered

Hooks on UserPromptSubmit, PreToolUse, PostToolUse, Stop and PreCompact re-inject the plan so the agent never loses orientation after /compact or /clear. session-catchup.py recovers context from a previous session and reconciles it with git diff.

Beyond the basics it ships a 3-strike error protocol, isolated plan directories (.planning/<date-slug>/) for parallel tasks, SHA-256 plan attestation against tampering/prompt injection, structure-aware injection (PWF_INJECT=smart), a parallel-write guard, and opt-in autonomous/gated modes with a Stop-hook completion gate.

Who it's for

Developers running long, multi-session work: migrations, refactors, greenfield builds
Anyone tired of the agent forgetting the goal when the context window fills up
Researchers who want discoveries persisted instead of lost in the transcript
Teams juggling several concurrent tasks inside one repository

Examples

API migration: ask to "move this project to the v2 API" and it writes a 6-phase task_plan.md, flipping each phase to complete as it goes; the next day a fresh session reads the plan back and resumes.
Technology research: comparing three libraries, key notes land in findings.md after every couple of lookups, so nothing is lost when context compacts.
Parallel work: run ./scripts/init-session.sh "Backend Refactor" and ./scripts/init-session.sh "Incident Investigation", then switch with set-active-plan.sh or pin a terminal via export PLAN_ID=....

· · · Install guide · · ·

Install in the Claude app (no terminal)

Download the ZIP with the button below.
In Claude, open Settings → Capabilities and turn on 'Code execution and file creation'. (one time)
Go to Customize → Skills → + → 'Upload a skill' and upload the ZIP.

↓ Download ZIP

Install in Claude Code

Let Claude do it — paste this into Claude Code

Install the skill I found on Claude Skill Mart.
Copy the skills/planning-with-files folder from the GitHub repo OthmanAdi/planning-with-files into my ~/.claude/skills/othmanadi-planning-with-files-11/.
When it's done, tell me in one line what this skill can do.

Install with a command instead

git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files && mkdir -p ~/.claude/skills && cp -r /tmp/planning-with-files/skills/planning-with-files ~/.claude/skills/

⚠ This is a third-party skill. Check the source repository before installing.

Open a terminal and cd to a folder where you keep source checkouts.
Clone the repo: git clone https://github.com/OthmanAdi/planning-with-files.git
Copy the skill into place: mkdir -p ~/.claude/skills && cp -r planning-with-files/skills/planning-with-files ~/.claude/skills/
If you also want the /plan-goal and /plan-loop slash commands, install via the plugin route inside Claude Code instead: /plugin marketplace add OthmanAdi/planning-with-files then /plugin install planning-with-files.
Make the helper scripts executable: chmod +x ~/.claude/skills/planning-with-files/scripts/*.sh
Restart Claude Code and try a prompt like "plan this project out step by step".
Verify the hooks with /plan-doctor or sh ~/.claude/skills/planning-with-files/scripts/plan-doctor.sh.
Remember: planning files are created in your project directory, not in the skill install folder. Start with the default (legacy) mode before experimenting with --autonomous or --gated.

View source on GitHub ↗License: MIT