Planning with Files

Keeps task_plan.md, findings.md, and progress.md on disk so multi-step agent work survives context compaction and session breaks.

AutomationIntermediate★ 27,953⑂ 2,313AI score 10/10Last updated: Nov 7, 2026

What it does

Creates and maintains task_plan.md (phases + status), findings.md (research), and progress.md (session log) inside your project directory.
Uses lifecycle hooks (UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) to re-inject the selected plan so state is recovered after compaction or a dropped session.
Ships init-session.sh to scaffold plans and check-complete.sh --validate to enforce the **Status:** pending/in_progress/complete phase markers.
set-active-plan.sh --list (with optional --json) inventories saved plans and progress; archiving only happens with explicit user approval.
Encodes working rules: write findings after every 2 view/search operations, a 3-strike error protocol that escalates to the user, and never repeating a failed action verbatim.

Who it's for

Anyone running tasks that need 5+ tool calls: large refactors, research sprints, project scaffolding.
Users tired of re-explaining goals after long sessions get truncated.
Teams running parallel agents who need plans pinned per host via PLAN_ID or separate worktrees.

Examples

Starting a refactor: run init-session.sh, lay out Phase 1–5, and flip each status to complete as work lands.
Competitive research: after every two page/PDF reads, dump key points into findings.md so multimodal detail isn't lost.
Resuming yesterday's work: run session-catchup.py --metadata . for aggregate same-project session counts, then re-read all three planning files to restore state.

· · · 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/.codebuddy/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 AI Skill Mart.
Copy the .codebuddy/skills/planning-with-files folder from the GitHub repo OthmanAdi/planning-with-files into my ~/.claude/skills/othmanadi-planning-with-files/.
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/planning-with-files && cp -r /tmp/pwf/.codebuddy/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 clone the repo: git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/pwf
Create the skill folder: mkdir -p ~/.claude/skills/planning-with-files
Copy the skill in: cp -r /tmp/pwf/.codebuddy/skills/planning-with-files/* ~/.claude/skills/planning-with-files/
Make the helpers executable: chmod +x ~/.claude/skills/planning-with-files/scripts/*.sh
If a hook reports that the script wasn't found, add export PWF_SCRIPT_DIR="$HOME/.claude/skills/planning-with-files/scripts" to ~/.zshrc or ~/.bashrc and reopen the terminal.
Verify Python exists with python3 --version (needed for session-catchup.py).
Restart Claude Code, go to your project root, and ask it to "plan this task first" — you should see task_plan.md appear.

View source on GitHub ↗License: MIT