Planning With Files

1---
2name: planning-with-files
3version: "2.1.2"
4description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
5user-invocable: true
6allowed-tools:
7  - Read
8  - Write
9  - Edit
10  - Bash
11  - Glob
12  - Grep
13  - WebFetch
14  - WebSearch
15hooks:
16  SessionStart:
17    - hooks:
18        - type: command
19          command: "echo '[planning-with-files] Ready. Auto-activates for complex tasks, or invoke manually with /planning-with-files'"
20  PreToolUse:
21    - matcher: "Write|Edit|Bash"
22      hooks:
23        - type: command
24          command: "cat task_plan.md 2>/dev/null | head -30 || true"
25  PostToolUse:
26    - matcher: "Write|Edit"
27      hooks:
28        - type: command
29          command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
30  Stop:
31    - hooks:
32        - type: command
33          command: "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
34---
35 
36# Planning with Files
37 
38Work like Manus: Use persistent markdown files as your "working memory on disk."
39 
40## Important: Where Files Go
41 
42When using this skill:
43 
44- **Templates** are stored in the skill directory at `${CLAUDE_PLUGIN_ROOT}/templates/`
45- **Your planning files** (`task_plan.md`, `findings.md`, `progress.md`) should be created in **your project directory** — the folder where you're working
46 
47| Location | What Goes There |
48|----------|-----------------|
49| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
50| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
51 
52This ensures your planning files live alongside your code, not buried in the skill installation folder.
53 
54## Quick Start
55 
56Before ANY complex task:
57 
581. **Create `task_plan.md`** in your project — Use [templates/task_plan.md](templates/task_plan.md) as reference
592. **Create `findings.md`** in your project — Use [templates/findings.md](templates/findings.md) as reference
603. **Create `progress.md`** in your project — Use [templates/progress.md](templates/progress.md) as reference
614. **Re-read plan before decisions** — Refreshes goals in attention window
625. **Update after each phase** — Mark complete, log errors
63 
64> **Note:** All three planning files should be created in your current working directory (your project root), not in the skill's installation folder.
65 
66## The Core Pattern
67 
68```
69Context Window = RAM (volatile, limited)
70Filesystem = Disk (persistent, unlimited)
71 
72→ Anything important gets written to disk.
73```
74 
75## File Purposes
76 
77| File | Purpose | When to Update |
78|------|---------|----------------|
79| `task_plan.md` | Phases, progress, decisions | After each phase |
80| `findings.md` | Research, discoveries | After ANY discovery |
81| `progress.md` | Session log, test results | Throughout session |
82 
83## Critical Rules
84 
85### 1. Create Plan First
86Never start a complex task without `task_plan.md`. Non-negotiable.
87 
88### 2. The 2-Action Rule
89> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."
90 
91This prevents visual/multimodal information from being lost.
92 
93### 3. Read Before Decide
94Before major decisions, read the plan file. This keeps goals in your attention window.
95 
96### 4. Update After Act
97After completing any phase:
98- Mark phase status: `in_progress` → `complete`
99- Log any errors encountered
100- Note files created/modified
101 
102### 5. Log ALL Errors
103Every error goes in the plan file. This builds knowledge and prevents repetition.
104 
105```markdown
106## Errors Encountered
107| Error | Attempt | Resolution |
108|-------|---------|------------|
109| FileNotFoundError | 1 | Created default config |
110| API timeout | 2 | Added retry logic |
111```
112 
113### 6. Never Repeat Failures
114```
115if action_failed:
116    next_action != same_action
117```
118Track what you tried. Mutate the approach.
119 
120## The 3-Strike Error Protocol
121 
122```
123ATTEMPT 1: Diagnose & Fix
124  → Read error carefully
125  → Identify root cause
126  → Apply targeted fix
127 
128ATTEMPT 2: Alternative Approach
129  → Same error? Try different method
130  → Different tool? Different library?
131  → NEVER repeat exact same failing action
132 
133ATTEMPT 3: Broader Rethink
134  → Question assumptions
135  → Search for solutions
136  → Consider updating the plan
137 
138AFTER 3 FAILURES: Escalate to User
139  → Explain what you tried
140  → Share the specific error
141  → Ask for guidance
142```
143 
144## Read vs Write Decision Matrix
145 
146| Situation | Action | Reason |
147|-----------|--------|--------|
148| Just wrote a file | DON'T read | Content still in context |
149| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
150| Browser returned data | Write to file | Screenshots don't persist |
151| Starting new phase | Read plan/findings | Re-orient if context stale |
152| Error occurred | Read relevant file | Need current state to fix |
153| Resuming after gap | Read all planning files | Recover state |
154 
155## The 5-Question Reboot Test
156 
157If you can answer these, your context management is solid:
158 
159| Question | Answer Source |
160|----------|---------------|
161| Where am I? | Current phase in task_plan.md |
162| Where am I going? | Remaining phases |
163| What's the goal? | Goal statement in plan |
164| What have I learned? | findings.md |
165| What have I done? | progress.md |
166 
167## When to Use This Pattern
168 
169**Use for:**
170- Multi-step tasks (3+ steps)
171- Research tasks
172- Building/creating projects
173- Tasks spanning many tool calls
174- Anything requiring organization
175 
176**Skip for:**
177- Simple questions
178- Single-file edits
179- Quick lookups
180 
181## Templates
182 
183Copy these templates to start:
184 
185- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
186- [templates/findings.md](templates/findings.md) — Research storage
187- [templates/progress.md](templates/progress.md) — Session logging
188 
189## Scripts
190 
191Helper scripts for automation:
192 
193- `scripts/init-session.sh` — Initialize all planning files
194- `scripts/check-complete.sh` — Verify all phases complete
195 
196## Advanced Topics
197 
198- **Manus Principles:** See [reference.md](reference.md)
199- **Real Examples:** See [examples.md](examples.md)
200 
201## Anti-Patterns
202 
203| Don't | Do Instead |
204|-------|------------|
205| Use TodoWrite for persistence | Create task_plan.md file |
206| State goals once and forget | Re-read plan before decisions |
207| Hide errors and retry silently | Log errors to plan file |
208| Stuff everything in context | Store large content in files |
209| Start executing immediately | Create plan file FIRST |
210| Repeat failed actions | Track attempts, mutate approach |
211| Create files in skill directory | Create files in your project |
212