Planning with Files
Gives AI agents persistent on-disk working memory through task_plan.md, findings.md and progress.md so multi-step work survives context loss.
What it does
Treats the context window as RAM and the filesystem as disk. Before any complex task, the agent must create and maintain three planning files:
- task_plan.md — phases with explicit
pending/in_progress/completestatus lines and decisions - findings.md — research, web results, notes extracted from images or PDFs
- progress.md — session log and test results
It ships helper scripts for initialization (init-session.sh), format validation (check-complete.sh --validate), parallel plans via PLAN_ID and set-active-plan.sh, and optional SHA-256 plan attestation (attest-plan.sh) that blocks tampered plan content from reaching model context. Operating rules are explicit: save findings after every 2 lookups, never repeat a failed action, escalate to the user after 3 failures.
Who it's for
- Anyone handing the agent long tasks that need 5+ tool calls — refactors, research, migrations
- People frustrated by agents drifting off goal in long sessions
- Developers running parallel agents in multiple terminals who need isolated plans
- Teams worried about prompt injection from fetched web content
Examples
- Large refactor: run
init-session.sh "Backend Refactor", define Phases 1–6, and have the agent flip statuses as it goes instead of wandering. - Technical research: while skimming a dozen docs, key points are written to
findings.mdevery two lookups, so the final write-up still has its evidence. - Resuming next day: the agent reads all three files plus
git diff --statand restores exactly where it left off — "Phase 3 in progress, 2 tests failing".
· · · 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/.continue/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.
Install in Claude Code
Let Claude do it — paste this into Claude Code
Install the skill I found on AI Skill Mart. Copy the .continue/skills/planning-with-files folder from the GitHub repo OthmanAdi/planning-with-files into my ~/.claude/skills/othmanadi-planning-with-files-3/. 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/.continue/skills/planning-with-files ~/.claude/skills/planning-with-files⚠ This is a third-party skill. Check the source repository before installing.
- Open a terminal and go to a scratch directory.
- 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/.continue/skills/planning-with-files ~/.claude/skills/planning-with-files - Make the scripts executable:
chmod +x ~/.claude/skills/planning-with-files/scripts/*.sh - (Recommended) Skim
scripts/session-catchup.pyand confirm you are comfortable with it reading local same-project session records. - Restart Claude Code, then from your project root ask something like "track this task with planning files" to trigger the skill.
- Remember: the planning files belong in your project root, not in the skill install folder.