planning-with-files: a Manus-style plan management skill for Claude Code

The othmanadi/planning-with-files repository started going viral on GitHub with more than 12,500 stars, so I took a look.

what the skill does

It is a skill that brings Manus-style file-based plan management into AI coding tools such as Claude Code, Cursor, and Gemini CLI.

The core idea is simple: use the file system as extended memory.

• context window = RAM (volatile, limited)
• file system = disk (persistent, effectively unlimited)

When working on a complex task, you keep creating and updating three Markdown files.

file	role
task_plan.md	task planning, goals, and phase management
findings.md	notes from research
progress.md	tracking progress, errors, and state

how it differs from Claude Code’s built-in Plan Mode

Claude Code already has a built-in Plan Mode. You can toggle it with Shift+Tab or launch it with claude --permission-mode plan. It is a read-only mode that analyzes the codebase and generates a plan file.

So what is different?

	Claude Code Plan Mode	planning-with-files
file count	one	three, separated by purpose
structure	single plan	plan + findings + progress
operating rules	none in particular	strict protocol
session handoff	manually reread	catchup script included
setup	settings.json	described as a skill in CLAUDE.md

The idea is basically the same, but planning-with-files wraps it in much stricter operating rules.

operating rules

The main rules defined by planning-with-files are:

1. Create Plan First - always create the plan file before starting a complex task
2. Two-action rule - save to findings after every two search or read actions
3. Read Before Deciding - reread the plan file before making decisions
4. Update After Acting - update the status after each phase
5. Document All Errors - record every error
6. 3-strike error protocol - escalate to the user after three failures

The two-action rule is especially important because it makes recovery possible even if context gets lost.

5-question reboot test

When resuming a session, or after a long stretch of work, it checks whether you can answer these five questions:

1. Where am I?
2. Where am I going?
3. What is the goal?
4. What have I learned?
5. What have I done?

If you cannot answer them, you reread the plan files and restore state.

my take

What it is doing is very close to Claude Code’s TodoWrite tool. The difference is that the file-based approach gives you persistence across sessions.

Claude Code’s built-in Plan Mode can do the same thing if you enforce the rules yourself. planning-with-files mostly packages those rules up.

If you frequently need to carry state across sessions for long, complex tasks, this pattern is worth borrowing. If most of your work finishes in one session, the built-in Plan Mode or TodoWrite is usually enough.