Planning with Files — Manus-Style Persistent Planning Skill

What it is

Planning with Files is a Claude Code skill that implements persistent markdown-based planning using a 3-file pattern: task_plan.md for the overall plan, findings.md for research and discoveries, and progress.md for tracking completion status. This pattern ensures that planning context survives context window resets, which is critical for long-running tasks that exceed the context limit.

This skill is designed for Claude Code users working on complex, multi-step tasks where losing planning context mid-execution would waste significant time and tokens.

How it saves time or tokens

When Claude Code hits a context window limit during a complex task, it loses all in-memory planning context. Without persistent planning files, the agent must re-analyze the codebase and re-derive the plan from scratch. This skill writes the plan, findings, and progress to disk so that after a context reset, the agent reads these files and resumes exactly where it left off. This eliminates the token cost of re-planning and the time lost to repeated analysis.

How to use

1. Install the planning skill:

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

Or manually copy the SKILL.md to .claude/skills/planning-with-files.md.

1. When starting a complex task, ask Claude Code to create a plan:

Create a plan for refactoring the authentication module.
Use the planning-with-files skill to persist the plan.

1. The skill creates three files in your project:

task_plan.md     — Step-by-step execution plan
findings.md      — Research notes and discoveries
progress.md      — Completion tracking with checkboxes

Example

A typical progress.md file during execution:

# Progress: Auth Module Refactoring

Status: In Progress (Step 3 of 7)

• [x] Step 1: Audit current auth flow
• [x] Step 2: Design JWT token structure
• [ ] Step 3: Implement token generation (CURRENT)
• [ ] Step 4: Update middleware
• [ ] Step 5: Migrate session data
• [ ] Step 6: Update API endpoints
• [ ] Step 7: Write integration tests

Last Updated: 2026-04-15T14:30:00Z

Context: Working on src/auth/token.ts

After a context reset, Claude Code reads progress.md and immediately knows to continue from Step 3.

Related on TokRepo

• Coding tools — Browse AI-assisted development tools
• Automation tools — Explore workflow automation tools

Common pitfalls

• Not cleaning up planning files after task completion. The three files remain in your project directory. Delete them or add them to .gitignore to keep your repository clean.
• Using the skill for trivial tasks that fit within a single context window. The overhead of creating and maintaining planning files is not worth it for simple, quick tasks.
• Not reviewing the task_plan.md before execution. The AI-generated plan may include unnecessary steps or miss important considerations. Review and edit the plan before letting the agent execute.