Planning with Files

Keeps task_plan.md, findings.md and progress.md on disk so an agent never loses its goal or progress across long, multi-step work.

AutomationIntermediate★ 27,074⑂ 2,254AI score 10/10Last updated: Sep 22, 2026

What it does

Enforces a "working memory on disk" pattern: context window = RAM, filesystem = persistent disk.
Creates and maintains three files in your project: task_plan.md (phases, decisions), findings.md (research), progress.md (session log).
Lifecycle hooks (UserPromptSubmit, PreToolUse, PostToolUse, Stop, PreCompact) re-inject the selected plan context, so state survives compaction and session breaks.
Ships helper scripts: init-session.sh to initialize a plan dir, check-complete.sh to verify phases, set-active-plan.sh --list to list saved plans, and session-catchup.py --metadata for same-project session aggregation.
Adds operating discipline: the 2-Action save rule, a 3-strike error protocol that escalates to the user, a no-repeat-failures rule, and a security boundary that keeps untrusted web content out of task_plan.md.

Who it's for

Anyone running research, refactors, or build tasks that need 5+ tool calls.
Users frustrated by an agent drifting from the original goal in long sessions.
Teams resuming work across sessions or splitting work into orchestrator/worker roles with pinned PLAN_IDs.

Examples

Before a big refactor, run scripts/init-session.sh "Auth refactor", pin the printed PLAN_ID, then work phase by phase with status updates.
Resuming days later, run session-catchup.py --metadata "$(pwd)" and re-read the three planning files to rebuild state before touching code.
During web/document research, dump key points into findings.md every two searches so nothing is lost when the context is compacted.

· · · Install guide · · ·

Try it now, no install

Paste this into Claude to use the skill without installing anything.

Read the instructions in this file and follow them to help me:
https://raw.githubusercontent.com/OthmanAdi/planning-with-files/HEAD/.factory/skills/planning-with-files/SKILL.md

What I want: (describe your task here)

If Claude can't open the link, open it yourself and paste the contents instead.

↓ If it works for you, download the ZIP below and install it. Then it runs on its own — no pasting each time.

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 .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/

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

Open a terminal and 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 scripts executable: chmod +x ~/.claude/skills/planning-with-files/scripts/*.sh
(Optional) If you installed to a non-standard path, add export PWF_SCRIPT_DIR=~/.claude/skills/planning-with-files/scripts to your shell profile.
Verify Python is available with python3 --version (needed for session-catchup.py).
Restart Claude Code, then from your project root ask it to "plan this task in files" to confirm the hooks and plan files work.

View source on GitHub ↗License: MIT