Planning with Files

Claude Code skill implementing Manus-style persistent markdown planning — the workflow pattern behind the $2B acquisition.

Overview

Work like Manus — the AI agent company Meta acquired for $2 billion.

This skill transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage. It implements the exact context engineering pattern that made Manus worth billions in just 8 months.

The Problem

Claude Code (and most AI agents) suffer from:

• Volatile memory — TodoWrite tool disappears on context reset
• Goal drift — After 50+ tool calls, original goals get forgotten
• Hidden errors — Failures aren't tracked, so the same mistakes repeat
• Context stuffing — Everything crammed into context instead of stored

The Solution: 3-File Pattern

For every complex task, create THREE files:

task_plan.md      → Track phases and progress
findings.md       → Store research and findings
progress.md       → Session log and test results

The Core Principle

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.

Key Features

Session Recovery (v2.2.0+)

When your context window fills up and you run /clear, this skill automatically recovers unsynced work from your previous session.

Optimal Workflow:

1. Disable auto-compact in Claude Code settings (use full context window)
2. Start a fresh session in your project
3. Run /planning-with-files when ready to work on a complex task
4. Work until context fills up (Claude will warn you)
5. Run /clear to start fresh
6. Run /planning-with-files again — it will automatically recover where you left off

Hook System

The skill uses three powerful hooks:

• PreToolUse Hook — Re-reads task_plan.md before major decisions
• PostToolUse Hook — Reminds you to update status after file writes
• Stop Hook — Verifies completion before stopping

Cross-IDE Support

Fully supported on:

• ✅ Claude Code (Plugin + SKILL.md)
• ✅ Cursor (Rules)
• ✅ Kilo Code (Rules)
• ✅ OpenCode (Personal/Project Skill)
• ✅ Codex (Personal Skill)

Quick Start

Installation

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

Basic Usage

Once installed, Claude will automatically:

1. Create task_plan.md before starting complex tasks
2. Re-read plan before major decisions (via PreToolUse hook)
3. Remind you to update status after file writes (via PostToolUse hook)
4. Store findings in findings.md instead of stuffing context
5. Log errors for future reference
6. Verify completion before stopping (via Stop hook)

Or invoke manually with /planning-with-files.

Key Rules

1. Create Plan First — Never start without task_plan.md
2. The 2-Action Rule — Save findings after every 2 view/browser operations
3. Log ALL Errors — They help avoid repetition
4. Never Repeat Failures — Track attempts, mutate approach

File Structure

For each complex task:

task_plan.md      → Phases with checkboxes, progress tracking
findings.md       → Research results, discoveries, important notes
progress.md       → Session logs, test results, error history

The Manus Principles

When to Use

Use this pattern for:

• Multi-step tasks (3+ steps)
• Research tasks
• Building/creating projects
• Tasks spanning many tool calls

Skip for:

• Simple questions
• Single-file edits
• Quick lookups

Use Cases

Complex Feature Development

Break down features into phases, track progress, and maintain context across sessions:

## Phase 1: Design

- [ ] Create architecture diagram
- [ ] Define API contracts
- [ ] Plan data model

## Phase 2: Implementation

- [ ] Implement core features
- [ ] Write tests
- [ ] Handle edge cases

## Phase 3: Testing

- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual testing

Research Projects

Store findings systematically instead of losing them in context:

# Findings: AI Agent Architectures

## Key Resources

- [Paper] Agentic Workflows (Andrew Ng)
- [Repo] LangGraph examples
- [Tool] Claude Code skills

## Discoveries

- Multi-agent systems require careful orchestration
- State management is critical
- Tool calling needs explicit schemas

Session Recovery

Pick up where you left off even after context clears:

## Last Session Summary

Completed: Phase 1 & Phase 2
In Progress: Phase 3 (unit tests at 80%)
Next: Integration tests

## Recovered Context

From conversation after last plan update:

- Discussed edge case handling
- Decided on retry logic for API calls
- User provided feedback on test coverage

Technical Details

Template System

The skill includes customizable templates for:

• task_plan.md — Planning document structure
• findings.md — Research notes format
• progress.md — Session logging format

Helper Scripts

• init-session.sh — Creates initial planning files
• check-complete.sh — Verifies all phases are done

IDE Integration

Each IDE has optimized installation:

• Claude Code: Plugin manifest + SKILL.md
• Cursor: .cursor/rules/planning-with-files.md
• Kilo Code: .kilocode/rules/planning-with-files.md
• OpenCode: .opencode/ directory setup
• Codex: .codex/ installation guide

Best Practices

Planning

• Start with a clear goal
• Break into logical phases
• Use checkboxes for tracking
• Add acceptance criteria

Execution

• Update progress.md after significant actions
• Store findings in findings.md not in context
• Log errors with context
• Re-read plan before major decisions

Session Management

• Use /clear when context fills up
• Run /planning-with-files in new sessions
• Review previous progress.md before starting
• Archive completed projects

Limitations

• Requires manual file creation (hooks don't auto-create)
• Initial setup takes 1-2 minutes
• Needs discipline to maintain files
• Best for complex tasks, overkill for simple ones

Related Skills

• Agent workflow management
• Context engineering techniques
• Knowledge management systems
• Project planning and tracking

Example Workflow

User Request

Build a REST API for a todo app

Skill Response

Creates task_plan.md:

# TODO API Development

## Phase 1: Design

- [ ] Define endpoints (CRUD)
- [ ] Design data model
- [ ] Plan authentication

## Phase 2: Implementation

- [ ] Set up Express server
- [ ] Implement routes
- [ ] Add validation
- [ ] Connect database

## Phase 3: Testing

- [ ] Write unit tests
- [ ] Test API endpoints
- [ ] Handle errors

After 20 tool calls, context fills up:

User runs /clear

New session starts, runs /planning-with-files:

Recovered from previous session:
- Phase 1: ✅ Complete
- Phase 2: ⏳ In Progress (Express setup done, routes started)
- Phase 3: ❌ Not started

Last context before reset:
- Working on route implementation
- Just added validation middleware
- Need to complete PUT /:id endpoint

User: "Continue where we left off"

Claude reads plan, resumes from Phase 2...

Community Impact

• 9,700+ GitHub stars
• 858 forks
• Featured in AI agent communities
• Used by teams worldwide
• Forked and customized for various workflows

License

MIT License — feel free to use, modify, and distribute.

Author: Ahmad Othman Ammar Adi

Installation Links

• Installation Guide
• Quick Start
• Troubleshooting