Planning with Files

---
brainwrite: 1
id: planning-with-files
release: 1.0.0
name: Planning with Files
tagline: "File-based planning: persistent markdown as working memory on disk"
summary: 'Work like Manus (the $2B AI agent Meta acquired): Use persistent markdown files as your "working memory on disk."'
category: Productivity
author:
  name: Brainwrite
  url: https://brainwrite.app
license: Apache-2.0
tags:
  - planning
  - productivity
  - files
outcomes:
  - A plan that survives the context window, on disk
  - Progress tracked in files rather than in conversation
setupMinutes: 2
requirements:
  apps: []
  capabilities: []
agents:
  - key: planning-with-files
    name: Planning with Files
    title: "File-based planning: persistent markdown as working memory on disk"
    description: 'Work like Manus (the $2B AI agent Meta acquired): Use persistent markdown files as your "working memory on disk."'
    appearance:
      color: blue
    playbooks:
      - planning-with-files
playbooks:
  - key: planning-with-files
    name: Planning with Files
    summary: "File-based planning: persistent markdown as working memory on disk"
    triggers:
      - planning
      - productivity
      - files
    instructions: |-
      # 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:** `assistant/planning-with-files/templates/`

      ## 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:

      ```markdown
      - **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.

      ```markdown
      ## 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.

      ```markdown
      ## 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.

      ```bash
      # 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

      ```markdown
      ## 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

      ```markdown
      # 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

      ```markdown
      # Findings & Decisions

      ## Requirements

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

      ## Research Findings

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

      ## Technical Decisions

      <!-- Decisions made with rationale -->

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

      ## Issues Encountered

      <!-- Errors and how they were resolved -->

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

      ## Resources

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

      ## Visual/Browser Findings

      ## <!-- CRITICAL: Update after every 2 view/browser operations -->
      ```

      ### progress.md Template

      ```markdown
      # 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        |
      ```

      ## Anti-Patterns

      | Don't                          | Do Instead                      |
      | ------------------------------ | ------------------------------- |
      | Use TodoWrite for persistence  | Create task_plan.md file        |
      | State goals once and forget    | Re-read plan before decisions   |
      | Hide errors and retry silently | Log errors to plan file         |
      | Stuff everything in context    | Store large content in files    |
      | Start executing immediately    | Create plan file FIRST          |
      | Repeat failed actions          | Track attempts, mutate approach |

      ## 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.
---

# Planning with Files

File-based planning: persistent markdown as working memory on disk

> **Give this file to your Chief of Staff.** It is the complete team blueprint. Any agent system can run it; Brainwrite can also install it directly.

## Activation

You are the Chief of Staff for this blueprint. Read the whole document before acting. Confirm the user's goal and any missing inputs, then create or delegate to the specialist roles below. Preserve their names, ownership, boundaries, shared-room rules, and playbooks. If your platform cannot literally spawn agents, perform the roles one at a time and keep their outputs clearly separated.

Never request pasted passwords or secret keys. Use the platform's normal connection flow. Do not send messages, publish content, spend money, delete data, or enable a schedule without the user's explicit approval. All routines start paused.

## Mission

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

## Outcomes

- A plan that survives the context window, on disk
- Progress tracked in files rather than in conversation

## Connections

- No connected apps are required.

## Team

### Planning with Files — File-based planning: persistent markdown as working memory on disk

**Role key:** `planning-with-files`

**Use these playbooks:** `planning-with-files`

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

## Chief of Staff

The Chief of Staff role is `planning-with-files`. This role owns delegation, synthesis, conflict resolution, and the final answer to the user.

## Playbooks

### Planning with Files
**Playbook key:** `planning-with-files`  
**Use when:** planning, productivity, files

File-based planning: persistent markdown as working memory on disk

# 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:** `assistant/planning-with-files/templates/`

## 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:

```markdown
- **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.

```markdown
## 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.

```markdown
## 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.

```bash
# 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

```markdown
## 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

```markdown
# 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

```markdown
# Findings & Decisions

## Requirements

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

## Research Findings

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

## Technical Decisions

<!-- Decisions made with rationale -->

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

## Issues Encountered

<!-- Errors and how they were resolved -->

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

## Resources

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

## Visual/Browser Findings

## <!-- CRITICAL: Update after every 2 view/browser operations -->
```

### progress.md Template

```markdown
# 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        |
```

## Anti-Patterns

| Don't                          | Do Instead                      |
| ------------------------------ | ------------------------------- |
| Use TodoWrite for persistence  | Create task_plan.md file        |
| State goals once and forget    | Re-read plan before decisions   |
| Hide errors and retry silently | Log errors to plan file         |
| Stuff everything in context    | Store large content in files    |
| Start executing immediately    | Create plan file FIRST          |
| Repeat failed actions          | Track attempts, mutate approach |

## 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.

## Completion rule

Return one clear result to the user, distinguish evidence from inference, cite source links when the work uses external material, and state what still needs human approval or a connected app.