Planning With Files

Planning with Files

Work like Manus: Use persistent markdown files as your "working memory on disk."

Quick Start

Before ANY complex task:

1. Create `task_plan.md` in the working directory 2. Define phases with checkboxes 3. Update after each phase - mark [x] and change status 4. Read before deciding - refresh goals in attention window

The 3-File Pattern

For every non-trivial task, create THREE files:

Core Workflow

Loop 1: Create task_plan.md with goal and phases
Loop 2: Research → save to notes.md → update task_plan.md
Loop 3: Read notes.md → create deliverable → update task_plan.md
Loop 4: Deliver final output

The Loop in Detail

Before each major action:

Read task_plan.md  # Refresh goals in attention window

After each phase:

Edit task_plan.md  # Mark [x], update status

When storing information:

Write notes.md     # Don't stuff context, store in file

task_plan.md Template

Create this file FIRST for any complex task:

# Task Plan: [Brief Description]

## Goal
[One sentence describing the end state]

## Phases
- [ ] Phase 1: Plan and setup
- [ ] Phase 2: Research/gather information
- [ ] Phase 3: Execute/build
- [ ] Phase 4: Review and deliver

## Key Questions
1. [Question to answer]
2. [Question to answer]

## Decisions Made
- [Decision]: [Rationale]

## Errors Encountered
- [Error]: [Resolution]

## Status
**Currently in Phase X** - [What I'm doing now]

notes.md Template

For research and findings:

# Notes: [Topic]

## Sources

### Source 1: [Name]
- URL: [link]
- Key points:
  - [Finding]
  - [Finding]

## Synthesized Findings

### [Category]
- [Finding]
- [Finding]

Critical Rules

1. ALWAYS Create Plan First

Never start a complex task without task_plan.md. This is non-negotiable.

2. Read Before Decide

Before any major decision, read the plan file. This keeps goals in your attention window.

3. Update After Act

After completing any phase, immediately update the plan file:

• Mark completed phases with [x]
• Update the Status section
• Log any errors encountered

4. Store, Don't Stuff

Large outputs go to files, not context. Keep only paths in working memory.

5. Log All Errors

Every error goes in the "Errors Encountered" section. This builds knowledge for future tasks.

When to Use This Pattern

Use 3-file pattern for:

• Multi-step tasks (3+ steps)
• Research tasks
• Building/creating something
• Tasks spanning multiple tool calls
• Anything requiring organization

Skip for:

• Simple questions
• Single-file edits
• Quick lookups

Anti-Patterns to Avoid

Advanced Patterns

See reference.md for:

• Attention manipulation techniques
• Error recovery patterns
• Context optimization from Manus

See examples.md for:

• Real task examples
• Complex workflow patterns

Examples: Planning with Files in Action

Example 1: Research Task

User Request: "Research the benefits of morning exercise and write a summary"

Loop 1: Create Plan

Write task_plan.md

# Task Plan: Morning Exercise Benefits Research

## Goal
Create a research summary on the benefits of morning exercise.

## Phases
- [ ] Phase 1: Create this plan ✓
- [ ] Phase 2: Search and gather sources
- [ ] Phase 3: Synthesize findings
- [ ] Phase 4: Deliver summary

## Key Questions
1. What are the physical health benefits?
2. What are the mental health benefits?
3. What scientific studies support this?

## Status
**Currently in Phase 1** - Creating plan

Loop 2: Research

Read task_plan.md           # Refresh goals
WebSearch "morning exercise benefits"
Write notes.md              # Store findings
Edit task_plan.md           # Mark Phase 2 complete

Loop 3: Synthesize

Read task_plan.md           # Refresh goals
Read notes.md               # Get findings
Write morning_exercise_summary.md
Edit task_plan.md           # Mark Phase 3 complete

Loop 4: Deliver

Read task_plan.md           # Verify complete
Deliver morning_exercise_summary.md

---

Example 2: Bug Fix Task

User Request: "Fix the login bug in the authentication module"

task_plan.md

# Task Plan: Fix Login Bug

## Goal
Identify and fix the bug preventing successful login.

## Phases
- [x] Phase 1: Understand the bug report ✓
- [x] Phase 2: Locate relevant code ✓
- [ ] Phase 3: Identify root cause (CURRENT)
- [ ] Phase 4: Implement fix
- [ ] Phase 5: Test and verify

## Key Questions
1. What error message appears?
2. Which file handles authentication?
3. What changed recently?

## Decisions Made
- Auth handler is in src/auth/login.ts
- Error occurs in validateToken() function

## Errors Encountered
- [Initial] TypeError: Cannot read property 'token' of undefined
  → Root cause: user object not awaited properly

## Status
**Currently in Phase 3** - Found root cause, preparing fix

---

Example 3: Feature Development

User Request: "Add a dark mode toggle to the settings page"

The 3-File Pattern in Action

task_plan.md:

# Task Plan: Dark Mode Toggle

## Goal
Add functional dark mode toggle to settings.

## Phases
- [x] Phase 1: Research existing theme system ✓
- [x] Phase 2: Design implementation approach ✓
- [ ] Phase 3: Implement toggle component (CURRENT)
- [ ] Phase 4: Add theme switching logic
- [ ] Phase 5: Test and polish

## Decisions Made
- Using CSS custom properties for theme
- Storing preference in localStorage
- Toggle component in SettingsPage.tsx

## Status
**Currently in Phase 3** - Building toggle component

notes.md:

# Notes: Dark Mode Implementation

## Existing Theme System
- Located in: src/styles/theme.ts
- Uses: CSS custom properties
- Current themes: light only

## Files to Modify
1. src/styles/theme.ts - Add dark theme colors
2. src/components/SettingsPage.tsx - Add toggle
3. src/hooks/useTheme.ts - Create new hook
4. src/App.tsx - Wrap with ThemeProvider

## Color Decisions
- Dark background: #1a1a2e
- Dark surface: #16213e
- Dark text: #eaeaea

dark_mode_implementation.md: (deliverable)

# Dark Mode Implementation

## Changes Made

### 1. Added dark theme colors
File: src/styles/theme.ts
...

### 2. Created useTheme hook
File: src/hooks/useTheme.ts
...

---

Example 4: Error Recovery Pattern

When something fails, DON'T hide it:

Before (Wrong)

Action: Read config.json
Error: File not found
Action: Read config.json  # Silent retry
Action: Read config.json  # Another retry

After (Correct)

Action: Read config.json
Error: File not found

# Update task_plan.md:
## Errors Encountered
- config.json not found → Will create default config

Action: Write config.json (default config)
Action: Read config.json
Success!

---

The Read-Before-Decide Pattern

Always read your plan before major decisions:

[Many tool calls have happened...]
[Context is getting long...]
[Original goal might be forgotten...]

→ Read task_plan.md          # This brings goals back into attention!
→ Now make the decision       # Goals are fresh in context

This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a "goal refresh" mechanism.

Plan Skill

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

A Claude Code skill that transforms your workflow to use persistent markdown files for planning, progress tracking, and knowledge storage — the exact pattern that made Manus worth billions.

 

Star History


---

Why This Skill?

On December 29, 2025, Meta acquired Manus for $2 billion. In just 8 months, Manus went from launch to $100M+ revenue. Their secret? Context engineering.

This skill implements Manus's core workflow pattern:

"Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables."

— Manus AI

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
notes.md          → Store research and findings
[deliverable].md  → Final output

The Loop

1. Create task_plan.md with goal and phases
2. Research → save to notes.md → update task_plan.md
3. Read notes.md → create deliverable → update task_plan.md
4. Deliver final output

Key insight: By reading task_plan.md before each decision, goals stay in the attention window. This is how Manus handles ~50 tool calls without losing track.

Installation

Option 1: Clone directly (Recommended)

# Navigate to your Claude Code skills directory
cd ~/.claude/skills  # or your custom skills path

# Clone this skill
git clone https://github.com/kv0906/cc-skills.git
cp -r cc-skills/plan-skill ~/.claude/skills/

Option 2: Manual installation

1. Download or copy the plan-skill folder 2. Place it in your Claude Code skills directory:

• macOS/Linux: ~/.claude/skills/
• Windows: %USERPROFILE%\.claude\skills\

Verify Installation

In Claude Code, the skill will automatically activate when you:

• Start complex tasks
• Mention "planning", "organize", or "track progress"
• Ask for structured work

Usage

Once installed, Claude will automatically:

1. Create `task_plan.md` before starting complex tasks 2. Update progress with checkboxes after each phase 3. Store findings in notes.md instead of stuffing context 4. Log errors for future reference 5. Re-read plan before major decisions

Example

You: "Research the benefits of TypeScript and write a summary"

Claude creates:

# Task Plan: TypeScript Benefits Research

## Goal
Create a research summary on TypeScript benefits.

## Phases
- [x] Phase 1: Create plan ✓
- [ ] Phase 2: Research and gather sources (CURRENT)
- [ ] Phase 3: Synthesize findings
- [ ] Phase 4: Deliver summary

## Status
**Currently in Phase 2** - Searching for sources

Then continues through each phase, updating the file as it goes.

The Manus Principles

This skill implements these key context engineering principles:

File Structure

plan-skill/
├── SKILL.md        # Core instructions (what Claude reads)
├── reference.md    # Manus principles deep dive
├── examples.md     # Real usage examples
└── README.md       # This file

When to Use

Use this pattern for:

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

Skip for:

• Simple questions
• Single-file edits
• Quick lookups

Acknowledgments

• Manus AI — For pioneering context engineering patterns that made this possible
• Anthropic — For Claude Code and the Agent Skills framework
• Based on Context Engineering for AI Agents

Contributing

Contributions welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Submit a pull request

License

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

Thank You

To everyone who starred, forked, and shared this skill — thank you. This project blew up in less than 24 hours, and the support from the community has been incredible.

If this skill helps you work smarter, that's all I wanted.

---

Author: Ahmad Othman Ammar Adi

Reference: Manus Context Engineering Principles

This skill is based on the context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.

The 6 Manus Principles

1. Filesystem as External Memory

"Markdown is my 'working memory' on disk."

Problem: Context windows have limits. Stuffing everything in context degrades performance and increases costs.

Solution: Treat the filesystem as unlimited memory:

• Store large content in files
• Keep only paths in context
• Agent can "look up" information when needed
• Compression must be REVERSIBLE

2. Attention Manipulation Through Repetition

Problem: After ~50 tool calls, models forget original goals ("lost in the middle" effect).

Solution: Keep a task_plan.md file that gets RE-READ throughout execution:

Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]

By reading the plan file before each decision, goals appear in the attention window.

3. Keep Failure Traces

"Error recovery is one of the clearest signals of TRUE agentic behavior."

Problem: Instinct says hide errors, retry silently. This wastes tokens and loses learning.

Solution: KEEP failed actions in the plan file:

## Errors Encountered
- [2025-01-03] FileNotFoundError: config.json not found → Created default config
- [2025-01-03] API timeout → Retried with exponential backoff, succeeded

The model updates its internal understanding when seeing failures.

4. Avoid Few-Shot Overfitting

"Uniformity breeds fragility."

Problem: Repetitive action-observation pairs cause drift and hallucination.

Solution: Introduce controlled variation:

• Vary phrasings slightly
• Don't copy-paste patterns blindly
• Recalibrate on repetitive tasks

5. Stable Prefixes for Cache Optimization

Problem: Agents are input-heavy (100:1 ratio). Every token costs money.

Solution: Structure for cache hits:

• Put static content FIRST
• Append-only context (never modify history)
• Consistent serialization

6. Append-Only Context

Problem: Modifying previous messages invalidates KV-cache.

Solution: NEVER modify previous messages. Always append new information.

The Agent Loop

Manus operates in a continuous loop:

1. Analyze → 2. Think → 3. Select Tool → 4. Execute → 5. Observe → 6. Iterate → 7. Deliver

File Operations in the Loop:

Manus Statistics

Key Quotes

"If the model improvement is the rising tide, we want Manus to be the boat, not the piling stuck on the seafloor."

"For complex tasks, I save notes, code, and findings to files so I can reference them as I work."

"I used file.edit to update checkboxes in my plan as I progressed, rather than rewriting the whole file."

Source

Based on Manus's official context engineering documentation: https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus