Planning with Files

A Manus-style skill that keeps your plan, findings, and progress in markdown files on disk so work survives /clear, compaction, and context loss.

AutomationIntermediate★ 26,060⑂ 2,177AI score 9/10Last updated: Aug 9, 2026

What it does

It teaches the agent the "working memory on disk" pattern: the context window is RAM, the filesystem is disk. Before any complex task it creates and continuously maintains three files in your project root:

task_plan.md — phases, status, and key decisions
findings.md — research and discoveries (all untrusted external content lands here only)
progress.md — session log, test results, error history

On top of that it registers UserPromptSubmit, PreToolUse, PostToolUse, Stop and PreCompact hooks to re-inject the plan each turn, and ships session-catchup.py to rebuild context after /clear. It also includes a 3-strike error protocol, the 2-action rule (flush findings to disk after every two view/search operations), parallel plan directories under .planning/<date>-<slug>/, SHA-256 plan attestation, and opt-in autonomous/gated modes for long unattended runs.

Who it's for

Anyone running multi-step tasks or research that needs 5+ tool calls
Users frustrated by agents forgetting the goal or repeating the same failure mid-session
Teams juggling several parallel tasks in one repository who want isolated plans
People who lose all state after auto-compaction

Examples

Large refactor: ask for "refactor the auth module" and the agent writes a six-phase plan into task_plan.md, flips each phase to complete, and logs every error in a table. Even after /clear, the next turn re-reads the plan and continues.
Competitor research: after every two web searches, key takeaways are written straight into findings.md, so nothing is lost when pages fall out of context.
Parallel work: run ./scripts/init-session.sh "Backend Refactor" and ./scripts/init-session.sh "Incident Investigation" to get two isolated plan directories, then switch between them with set-active-plan.sh.

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

↓ 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 .agents/skills/planning-with-files folder from the GitHub repo OthmanAdi/planning-with-files into my ~/.claude/skills/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/planning-with-files && mkdir -p ~/.claude/skills && cp -r /tmp/planning-with-files/.agents/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 to a temp folder: git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
Before installing, skim the shell scripts in /tmp/planning-with-files/.agents/skills/planning-with-files/scripts/ — this skill runs them automatically via hooks.
Copy the skill folder into place: mkdir -p ~/.claude/skills && cp -r /tmp/planning-with-files/.agents/skills/planning-with-files ~/.claude/skills/
(Optional) Install via the plugin route to also get the /plan-goal and /plan-loop slash commands: inside Claude Code run /plugin marketplace add OthmanAdi/planning-with-files, then /plugin install.
Restart Claude Code and confirm planning-with-files shows up in your skill list.
In any project folder, ask "plan this out step by step" and check that task_plan.md is created in the project root.
If hooks seem silent, run scripts/plan-doctor.sh from the skill folder for a self-check.

View source on GitHub ↗License: MIT