Planning with Files
Manus-style persistent planning that keeps task_plan.md, findings.md and progress.md on disk so multi-step work survives context loss and /clear.
What it does
Your context window is RAM — volatile. This skill treats the filesystem as disk and maintains three markdown files in your project directory:
task_plan.md— phases, status, decisionsfindings.md— research and external/web content (external text goes here only)progress.md— session log and test results
It ships hooks (UserPromptSubmit, PreToolUse, PreCompact, Stop) that re-inject the active plan after compaction or /clear, plus session-catchup.py to recover state from a previous session. The docs codify the "2-action rule", a 3-strike error protocol, a read-vs-write decision matrix, a security boundary for untrusted content, and an anti-pattern table.
Who it's for
- Anyone assigning multi-step work that needs 5+ tool calls
- Developers tired of re-explaining "where were we?" after a cleared session
- Researchers who want discoveries captured before they scroll out of context
Examples
- Large refactor: ask for "extract the billing module into a service layer" and the agent writes a six-phase
task_plan.md, flipping each phase tocompleteas it goes. - Tech evaluation: while comparing libraries, every two searches get summarized into
findings.md, so browser output isn't lost. - Next-day resume: run
session-catchup.pyandgit diff --stat, reconcile the planning files with real code changes, then continue where you stopped.
· · · 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.
Install in Claude Code
Let Claude do it — paste this into Claude Code
Install the skill I found on Claude Skill Mart. Copy the .factory/skills/planning-with-files folder from the GitHub repo OthmanAdi/planning-with-files into my ~/.claude/skills/othmanadi-planning-with-files-5/. 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/pwf && mkdir -p ~/.claude/skills && cp -r /tmp/pwf/.factory/skills/planning-with-files ~/.claude/skills/ && chmod +x ~/.claude/skills/planning-with-files/scripts/*⚠ This is a third-party skill. Check the source repository before installing.
- Open a terminal.
- Clone the repo:
git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/pwf - Create the skills folder:
mkdir -p ~/.claude/skills - Copy the skill in:
cp -r /tmp/pwf/.factory/skills/planning-with-files ~/.claude/skills/ - Make the helper scripts executable:
chmod +x ~/.claude/skills/planning-with-files/scripts/* - Restart Claude Code, then ask it to "plan this out step by step" and confirm a
task_plan.mdappears in your project. - (Optional) If you installed elsewhere, add
export PWF_SCRIPT_DIR=/path/to/planning-with-files/scriptsto your shell profile so the hooks can find the scripts.