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.

AutomationBeginner★ 26,167⑂ 2,188AI score 10/10Last updated: Aug 9, 2026

What it does

Before any complex task, creates three files in your project root: task_plan.md (phases and decisions), findings.md (research), progress.md (session log) — working memory on disk instead of in the context window.
On resume (or after /clear), it reads the planning files first, runs session-catchup.py, and reconciles with git diff --stat to pick up unsynced work.
Enforces an error discipline: log every error in a table and follow the 3-strike protocol (diagnose → alternative approach → rethink → escalate to the user).
Adds a "2-action rule" (save findings after every two view/search operations) and a security boundary: external/web content goes only into findings.md, never into the auto-read task_plan.md, to limit indirect prompt injection.

Who it's for

Anyone assigning multi-step work — migrations, feature builds, large refactors — that needs 5+ tool calls.
Users frustrated by long sessions where the agent forgets goals or retries the same failing action.
Non-developers doing structured research who need durable notes and a decision trail.

Example uses

"Migrate our payment integration" → a six-phase plan in task_plan.md, statuses flipped from in_progress to complete, failed API attempts recorded in the error table.
Returning days later → read all three planning files, run the catchup script to detect unrecorded changes, then continue from phase 4.
Multi-source research → after every two searches, key quotes and links are written to findings.md so evidence survives even when screenshots and page text drop out of context.

· · · 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/.hermes/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 .hermes/skills/planning-with-files folder from the GitHub repo OthmanAdi/planning-with-files into my ~/.claude/skills/othmanadi-planning-with-files-7/.
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/.hermes/skills/planning-with-files ~/.claude/skills/

⚠ 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/planning-with-files
Create the skills folder: mkdir -p ~/.claude/skills
Copy the skill: cp -r /tmp/planning-with-files/.hermes/skills/planning-with-files ~/.claude/skills/
Verify templates/ and scripts/ came along: ls ~/.claude/skills/planning-with-files
The docs use $HERMES_HOME/... paths, so either export HERMES_HOME=~/.claude or call the script directly as ~/.claude/skills/planning-with-files/scripts/session-catchup.py (Python 3 required).
Restart Claude Code and ask it to "plan this out step by step" to trigger the skill.

View source on GitHub ↗License: MIT