Planning with Files - Manus-Style File-Based Planning

Work like Manus (the $2B AI agent Meta acquired): Use persistent markdown files as your "working memory on disk."

Core Principle

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

→ Anything important gets written to disk.

The 3-File Pattern

For every complex task, create THREE files in your project directory:

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

Templates are available at: .claude/templates/planning/

When to Use This Pattern

Use 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

Critical Timing Rules

These rules simulate hooks to ensure proper workflow:

📌 At Task Start (SessionStart)

MUST create all three files FIRST before any other work:

1. Create task_plan.md using the template
2. Create findings.md using the template
3. Create progress.md using the template
4. Fill in the Goal section in task_plan.md

Why: Without planning files, you'll forget goals after 50+ tool calls.

📌 Before Major Decisions (PreToolUse)

MUST re-read task_plan.md before:

• Writing or editing files
• Executing commands
• Making architectural decisions
• Implementing features

How: Use the Read tool to refresh the plan in your context.

Why: This keeps goals fresh in your attention window (Manus's "attention manipulation").

📌 After File Operations (PostToolUse)

MUST update status immediately after:

• Writing files
• Editing files
• Completing a task phase

How: Edit task_plan.md to update phase status:

- **Status:** pending → in_progress → complete

Why: Tracks progress and prevents losing track of what's done.

📌 Before Task End (Stop)

MUST verify completion:

• Check all phases marked as complete
• Review deliverables section
• Ensure no errors left unresolved

Why: Prevents premature completion with missing work.

The 6 Critical Rules

1. Create Plan First

Never start a complex task without task_plan.md. Non-negotiable.

## Goal

[One sentence describing the end state]

## Current Phase

Phase 1

## Phases

### Phase 1: Requirements & Discovery

- [ ] Understand user intent
- [ ] Identify constraints
- **Status:** in_progress

2. The 2-Action Rule

"After every 2 view/browser/search operations, IMMEDIATELY save key findings to findings.md."

This prevents visual/multimodal information from being lost.

## Visual/Browser Findings

- Screenshot shows login form with email and password fields
- API documentation indicates JSON response format

3. Read Before Decide

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

# Before implementing a feature:
Read tool → task_plan.md
# Now proceed with implementation

4. Update After Act

After completing any phase:

• Mark phase status: pending → in_progress → complete
• Log any errors encountered
• Note files created/modified

## Errors Encountered

| Error             | Attempt | Resolution             |
| ----------------- | ------- | ---------------------- |
| FileNotFoundError | 1       | Created default config |

5. Log ALL Errors

Every error goes in the plan file. This builds knowledge and prevents repetition.

6. Never Repeat Failures

if action_failed:
    next_action != same_action

Track what you tried. Mutate the approach.

The 3-Strike Error Protocol

ATTEMPT 1: Diagnose & Fix
  → Read error carefully
  → Identify root cause
  → Apply targeted fix

ATTEMPT 2: Alternative Approach
  → Same error? Try different method
  → Different tool? Different library?
  → NEVER repeat exact same failing action

ATTEMPT 3: Broader Rethink
  → Question assumptions
  → Search for solutions
  → Consider updating the plan

AFTER 3 FAILURES: Escalate to User
  → Explain what you tried
  → Share the specific error
  → Ask for guidance

File Purposes

File	Purpose	When to Update
task_plan.md	Phases, progress, decisions	After each phase
findings.md	Research, discoveries	After ANY discovery
progress.md	Session log, test results	Throughout session

Read vs Write Decision Matrix

Situation	Action	Reason
Just wrote a file	DON'T read	Content still in context
Viewed image/PDF	Write findings NOW	Multimodal → text before lost
Browser returned data	Write to file	Screenshots don't persist
Starting new phase	Read plan/findings	Re-orient if context stale
Error occurred	Read relevant file	Need current state to fix
Resuming after gap	Read all planning files	Recover state

The 5-Question Reboot Test

If you can answer these, your context management is solid:

Question	Answer Source
Where am I?	Current phase in task_plan.md
Where am I going?	Remaining phases
What's the goal?	Goal statement in plan
What have I learned?	findings.md
What have I done?	progress.md

Template Structure

task_plan.md Template

# Task Plan: [Brief Description]

## Goal

[One sentence describing the end state]

## Current Phase

Phase 1

## Phases

### Phase 1: Requirements & Discovery

- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress

### Phase 2: Planning & Structure

- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending

### Phase 3: Implementation

- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending

### Phase 4: Testing & Verification

- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending

### Phase 5: Delivery

- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending

## Key Questions

1. [Question to answer]
2. [Question to answer]

## Decisions Made

| Decision | Rationale |
| -------- | --------- |
|          |           |

## Errors Encountered

| Error | Attempt | Resolution |
| ----- | ------- | ---------- |
|       | 1       |            |

findings.md Template

# Findings & Decisions

## Requirements

_Add requirements captured from user request here._

## Research Findings

_Document key discoveries during exploration here._

## Technical Decisions

_Record decisions made with rationale._

| Decision | Rationale |
| -------- | --------- |
|          |           |

## Issues Encountered

_Document errors and how they were resolved._

| Issue | Resolution |
| ----- | ---------- |
|       |            |

## Resources

_Add URLs, file paths, and API references here._

## Visual/Browser Findings

_CRITICAL: Update after every 2 view/browser operations._

progress.md Template

# Progress Log

## Session: [DATE]

### Phase 1: [Title]

- **Status:** in_progress
- **Started:** [timestamp]
- Actions taken:
- Files created/modified:

## Test Results

| Test | Input | Expected | Actual | Status |
| ---- | ----- | -------- | ------ | ------ |
|      |       |          |        |        |

## Error Log

| Timestamp | Error | Attempt | Resolution |
| --------- | ----- | ------- | ---------- |
|           |       | 1       |            |

## 5-Question Reboot Check

| Question             | Answer           |
| -------------------- | ---------------- |
| Where am I?          | Phase X          |
| Where am I going?    | Remaining phases |
| What's the goal?     | [goal statement] |
| What have I learned? | See findings.md  |
| What have I done?    | See above        |

Iron Laws

1. ALWAYS create task_plan.md, findings.md, and progress.md before starting any complex task — filesystem memory survives context resets, working memory does not.
2. ALWAYS re-read task_plan.md before making major decisions — context windows are volatile, files persist indefinitely.
3. NEVER retry a failed action with identical inputs — log the failure in the plan file, diagnose the root cause, and mutate the approach.
4. ALWAYS write multimodal findings (screenshots, browser data) to findings.md immediately after capture — visual context cannot be retrieved once it leaves the attention window.
5. NEVER mark a task complete without verifying all phases are complete and all deliverables are present in the progress file.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Using session task tools for persistence	In-memory task tracking is volatile; lost on context reset	Create task_plan.md file on disk — survives resets
Stating goals once and forgetting them	Context fills; goals drift without anchoring	Re-read plan file before every major decision
Hiding errors and retrying silently	Silent retries repeat the same failure endlessly	Log every error to plan file with attempt count
Stuffing all research into context	Context window fills; earlier content gets lost	Store large content and discoveries in findings.md
Starting execution without a plan	Undefined scope leads to wasted work and missed steps	Create all three planning files FIRST before any action

The Manus Principles

Principle	Implementation
Filesystem as memory	Store in files, not context
Attention manipulation	Re-read plan before decisions
Error persistence	Log failures in plan file
Goal tracking	Checkboxes show progress
Completion verification	Check all phases before stopping

---

Remember: The more context you gather upfront and write to disk, the better your execution will be. Files are your persistent memory.