Planning With Files

Planning with Files

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

This is not just an optional planning style. It should be the default persistence layer for complex Codex work.

Use it proactively when:

• the task will likely take more than a few tool calls
• progress needs to be tracked across phases
• findings or evidence must be preserved while working
• the task may branch, pause, or resume later
• relying on chat context alone would be fragile

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.

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