Planning With Files

Planning with Files

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

Important: Where Files Go

When using this skill:

• Templates are stored in the skill directory at ${CLAUDE_PLUGIN_ROOT}/templates/
• Your planning files (task_plan.md, findings.md, progress.md) should be created in your project directory — the folder where you're working

This ensures your planning files live alongside your code, not buried in the skill installation folder.

Quick Start

Before ANY complex task:

1. Create `task_plan.md` in your project — Use templates/task_plan.md as reference 2. Create `findings.md` in your project — Use templates/findings.md as reference 3. Create `progress.md` in your project — Use templates/progress.md as reference 4. Re-read plan before decisions — Refreshes goals in attention window 5. Update after each phase — Mark complete, log errors

Note: All three planning files should be created in your current working directory (your project root), not in the skill's installation folder.

The Core Pattern

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

→ Anything important gets written to disk.

File Purposes

Critical Rules

1. Create Plan First

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

2. The 2-Action Rule

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

This prevents visual/multimodal information from being lost.

3. Read Before Decide

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

4. Update After Act

After completing any phase:

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

5. Log ALL Errors

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

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |

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

Read vs Write Decision Matrix

The 5-Question Reboot Test

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

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

Templates

Copy these templates to start:

• templates/task_plan.md — Phase tracking
• templates/findings.md — Research storage
• templates/progress.md — Session logging

Scripts

Helper scripts for automation:

• scripts/init-session.sh — Initialize all planning files
• scripts/check-complete.sh — Verify all phases complete

Advanced Topics

• Manus Principles: See reference.md
• Real Examples: See examples.md

Anti-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 context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.

The 6 Manus Principles

Principle 1: Design Around KV-Cache

"KV-cache hit rate is THE single most important metric for production AI agents."

Statistics:

• ~100:1 input-to-output token ratio
• Cached tokens: $0.30/MTok vs Uncached: $3/MTok
• 10x cost difference!

Implementation:

• Keep prompt prefixes STABLE (single-token change invalidates cache)
• NO timestamps in system prompts
• Make context APPEND-ONLY with deterministic serialization

Principle 2: Mask, Don't Remove

Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.

Best Practice: Use consistent action prefixes (e.g., browser_, shell_, file_) for easier masking.

Principle 3: Filesystem as External Memory

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

The Formula:

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

Compression Must Be Restorable:

• Keep URLs even if web content is dropped
• Keep file paths when dropping document contents
• Never lose the pointer to full data

Principle 4: Manipulate Attention Through Recitation

"Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."

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

Solution: Re-read task_plan.md before each decision. Goals appear in the attention window.

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

Principle 5: Keep the Wrong Stuff In

"Leave the wrong turns in the context."

Why:

• Failed actions with stack traces let model implicitly update beliefs
• Reduces mistake repetition
• Error recovery is "one of the clearest signals of TRUE agentic behavior"

Principle 6: Don't Get Few-Shotted

"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

---

The 3 Context Engineering Strategies

Based on Lance Martin's analysis of Manus architecture.

Strategy 1: Context Reduction

Compaction:

Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only

RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)

Summarization:

• Applied when compaction reaches diminishing returns
• Generated using full tool results
• Creates standardized summary objects

Strategy 2: Context Isolation (Multi-Agent)

Architecture:

┌─────────────────────────────────┐
│         PLANNER AGENT           │
│  └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│       KNOWLEDGE MANAGER         │
│  └─ Reviews conversations       │
│  └─ Determines filesystem store │
├─────────────────────────────────┤
│      EXECUTOR SUB-AGENTS        │
│  └─ Perform assigned tasks      │
│  └─ Have own context windows    │
└─────────────────────────────────┘

Key Insight: Manus originally used todo.md for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.

Strategy 3: Context Offloading

Tool Design:

• Use <20 atomic functions total
• Store full results in filesystem, not context
• Use glob and grep for searching
• Progressive disclosure: load information only as needed

---

The Agent Loop

Manus operates in a continuous 7-step loop:

┌─────────────────────────────────────────┐
│  1. ANALYZE CONTEXT                      │
│     - Understand user intent             │
│     - Assess current state               │
│     - Review recent observations         │
├─────────────────────────────────────────┤
│  2. THINK                                │
│     - Should I update the plan?          │
│     - What's the next logical action?    │
│     - Are there blockers?                │
├─────────────────────────────────────────┤
│  3. SELECT TOOL                          │
│     - Choose ONE tool                    │
│     - Ensure parameters available        │
├─────────────────────────────────────────┤
│  4. EXECUTE ACTION                       │
│     - Tool runs in sandbox               │
├─────────────────────────────────────────┤
│  5. RECEIVE OBSERVATION                  │
│     - Result appended to context         │
├─────────────────────────────────────────┤
│  6. ITERATE                              │
│     - Return to step 1                   │
│     - Continue until complete            │
├─────────────────────────────────────────┤
│  7. DELIVER OUTCOME                      │
│     - Send results to user               │
│     - Attach all relevant files          │
└─────────────────────────────────────────┘

---

File Types Manus Creates

---

Critical Constraints

• Single-Action Execution: ONE tool call per turn. No parallel execution.
• Plan is Required: Agent must ALWAYS know: goal, current phase, remaining phases
• Files are Memory: Context = volatile. Filesystem = persistent.
• Never Repeat Failures: If action failed, next action MUST be different
• Communication is a Tool: Message types: info (progress), ask (blocking), result (terminal)

---

Manus Statistics

---

Key Quotes

"Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."

"if action_failed: next_action != same_action. Track what you tried. Mutate the approach."

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

"KV-cache hit rate is the single most important metric for a production-stage AI agent."

"Leave the wrong turns in the context."

---

Source

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

Findings & Decisions

<!-- WHAT: Your knowledge base for the task. Stores everything you discover and decide. WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited. WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule). -->

Requirements

<!-- WHAT: What the user asked for, broken down into specific requirements. WHY: Keeps requirements visible so you don't forget what you're building. WHEN: Fill this in during Phase 1 (Requirements & Discovery). EXAMPLE:

• Command-line interface
• Add tasks
• List all tasks
• Delete tasks
• Python implementation

--> <!-- Captured from user request --> -

Research Findings

<!-- WHAT: Key discoveries from web searches, documentation reading, or exploration. WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately. WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule). EXAMPLE:

• Python's argparse module supports subcommands for clean CLI design
• JSON module handles file persistence easily
• Standard pattern: python script.py <command> [args]

--> <!-- Key discoveries during exploration --> -

Technical Decisions

<!-- WHAT: Architecture and implementation choices you've made, with reasoning. WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge. WHEN: Update whenever you make a significant technical choice. EXAMPLE: | Use JSON for storage | Simple, human-readable, built-in Python support | | argparse with subcommands | Clean CLI: python todo.py add "task" | --> <!-- Decisions made with rationale -->

Issues Encountered

<!-- WHAT: Problems you ran into and how you solved them. WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors). WHEN: Document when you encounter blockers or unexpected challenges. EXAMPLE: | Empty file causes JSONDecodeError | Added explicit empty file check before json.load() | --> <!-- Errors and how they were resolved -->

Resources

<!-- WHAT: URLs, file paths, API references, documentation links you've found useful. WHY: Easy reference for later. Don't lose important links in context. WHEN: Add as you discover useful resources. EXAMPLE:

• Python argparse docs: https://docs.python.org/3/library/argparse.html
• Project structure: src/main.py, src/utils.py

--> <!-- URLs, file paths, API references --> -

Visual/Browser Findings

<!-- WHAT: Information you learned from viewing images, PDFs, or browser results. WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text. WHEN: IMMEDIATELY after viewing images or browser results. Don't wait! EXAMPLE:

• Screenshot shows login form has email and password fields
• Browser shows API returns JSON with "status" and "data" keys

--> <!-- CRITICAL: Update after every 2 view/browser operations --> <!-- Multimodal content must be captured as text immediately --> -

--- <!-- REMINDER: The 2-Action Rule After every 2 view/browser/search operations, you MUST update this file. This prevents visual information from being lost when context resets. --> Update this file after every 2 view/browser/search operations This prevents visual information from being lost

Progress Log

<!-- WHAT: Your session log - a chronological record of what you did, when, and what happened. WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks. WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md. -->

Session: [DATE]

<!-- WHAT: The date of this work session. WHY: Helps track when work happened, useful for resuming after time gaps. EXAMPLE: 2026-01-15 -->

Phase 1: [Title]

<!-- WHAT: Detailed log of actions taken during this phase. WHY: Provides context for what was done, making it easier to resume or debug. WHEN: Update as you work through the phase, or at least when you complete it. -->

• Status: in_progress
• Started: [timestamp]

<!-- STATUS: Same as task_plan.md (pending, in_progress, complete) TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00") -->

• Actions taken:

<!-- WHAT: List of specific actions you performed. EXAMPLE:

• Created todo.py with basic structure
• Implemented add functionality
• Fixed FileNotFoundError

--> -

• Files created/modified:

<!-- WHAT: Which files you created or changed. WHY: Quick reference for what was touched. Helps with debugging and review. EXAMPLE:

• todo.py (created)
• todos.json (created by app)
• task_plan.md (updated)

--> -

Phase 2: [Title]

<!-- WHAT: Same structure as Phase 1, for the next phase. WHY: Keep a separate log entry for each phase to track progress clearly. -->

• Status: pending
• Actions taken:

-

• Files created/modified:

-

Test Results

<!-- WHAT: Table of tests you ran, what you expected, what actually happened. WHY: Documents verification of functionality. Helps catch regressions. WHEN: Update as you test features, especially during Phase 4 (Testing & Verification). EXAMPLE: | Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ | | List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ | -->

Error Log

<!-- WHAT: Detailed log of every error encountered, with timestamps and resolution attempts. WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes. WHEN: Add immediately when an error occurs, even if you fix it quickly. EXAMPLE: | 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check | | 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling | --> <!-- Keep ALL errors - they help avoid repetition -->

5-Question Reboot Check

<!-- WHAT: Five questions that verify your context is solid. If you can answer these, you're on track. WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively. WHEN: Update periodically, especially when resuming after a break or context reset.

THE 5 QUESTIONS: 1. Where am I? → Current phase in task_plan.md 2. Where am I going? → Remaining phases 3. What's the goal? → Goal statement in task_plan.md 4. What have I learned? → See findings.md 5. What have I done? → See progress.md (this file) --> <!-- If you can answer these, context is solid -->

--- <!-- REMINDER:

• Update after completing each phase or encountering errors
• Be detailed - this is your "what happened" log
• Include timestamps for errors to track when issues occurred

--> Update after completing each phase or encountering errors

Task Plan: [Brief Description]

<!-- WHAT: This is your roadmap for the entire task. Think of it as your "working memory on disk." WHY: After 50+ tool calls, your original goals can get forgotten. This file keeps them fresh. WHEN: Create this FIRST, before starting any work. Update after each phase completes. -->

Goal

<!-- WHAT: One clear sentence describing what you're trying to achieve. WHY: This is your north star. Re-reading this keeps you focused on the end state. EXAMPLE: "Create a Python CLI todo app with add, list, and delete functionality." --> [One sentence describing the end state]

Current Phase

<!-- WHAT: Which phase you're currently working on (e.g., "Phase 1", "Phase 3"). WHY: Quick reference for where you are in the task. Update this as you progress. --> Phase 1

Phases

<!-- WHAT: Break your task into 3-7 logical phases. Each phase should be completable. WHY: Breaking work into phases prevents overwhelm and makes progress visible. WHEN: Update status after completing each phase: pending → in_progress → complete -->

Phase 1: Requirements & Discovery

<!-- WHAT: Understand what needs to be done and gather initial information. WHY: Starting without understanding leads to wasted effort. This phase prevents that. -->

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

<!-- STATUS VALUES:

• pending: Not started yet
• in_progress: Currently working on this
• complete: Finished this phase

-->

Phase 2: Planning & Structure

<!-- WHAT: Decide how you'll approach the problem and what structure you'll use. WHY: Good planning prevents rework. Document decisions so you remember why you chose them. -->

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

Phase 3: Implementation

<!-- WHAT: Actually build/create/write the solution. WHY: This is where the work happens. Break into smaller sub-tasks if needed. -->

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

Phase 4: Testing & Verification

<!-- WHAT: Verify everything works and meets requirements. WHY: Catching issues early saves time. Document test results in progress.md. -->

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

Phase 5: Delivery

<!-- WHAT: Final review and handoff to user. WHY: Ensures nothing is forgotten and deliverables are complete. -->

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

Key Questions

<!-- WHAT: Important questions you need to answer during the task. WHY: These guide your research and decision-making. Answer them as you go. EXAMPLE: 1. Should tasks persist between sessions? (Yes - need file storage) 2. What format for storing tasks? (JSON file) --> 1. [Question to answer] 2. [Question to answer]

Decisions Made

<!-- WHAT: Technical and design decisions you've made, with the reasoning behind them. WHY: You'll forget why you made choices. This table helps you remember and justify decisions. WHEN: Update whenever you make a significant choice (technology, approach, structure). EXAMPLE: | Use JSON for storage | Simple, human-readable, built-in Python support | -->

Errors Encountered

<!-- WHAT: Every error you encounter, what attempt number it was, and how you resolved it. WHY: Logging errors prevents repeating the same mistakes. This is critical for learning. WHEN: Add immediately when an error occurs, even if you fix it quickly. EXAMPLE: | FileNotFoundError | 1 | Check if file exists, create empty list if not | | JSONDecodeError | 2 | Handle empty file case explicitly | -->

Notes

<!-- REMINDERS:

• Update phase status as you progress: pending → in_progress → complete
• Re-read this plan before major decisions (attention manipulation)
• Log ALL errors - they help avoid repetition
• Never repeat a failed action - mutate your approach instead

-->

• Update phase status as you progress: pending → in_progress → complete
• Re-read this plan before major decisions (attention manipulation)
• Log ALL errors - they help avoid repetition