|
|
|
@@ -1,79 +1,23 @@
|
|
|
|
|
---
|
|
|
|
|
name: planning-with-files
|
|
|
|
|
version: "2.4.1"
|
|
|
|
|
description: 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. Now with automatic session recovery after /clear.
|
|
|
|
|
user-invocable: true
|
|
|
|
|
allowed-tools:
|
|
|
|
|
- Read
|
|
|
|
|
- Write
|
|
|
|
|
- Edit
|
|
|
|
|
- Bash
|
|
|
|
|
- Glob
|
|
|
|
|
- Grep
|
|
|
|
|
- WebFetch
|
|
|
|
|
- WebSearch
|
|
|
|
|
hooks:
|
|
|
|
|
PreToolUse:
|
|
|
|
|
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
|
|
|
|
|
hooks:
|
|
|
|
|
- type: command
|
|
|
|
|
command: "cat task_plan.md 2>/dev/null | head -30 || true"
|
|
|
|
|
PostToolUse:
|
|
|
|
|
- matcher: "Write|Edit"
|
|
|
|
|
hooks:
|
|
|
|
|
- type: command
|
|
|
|
|
command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
|
|
|
|
|
Stop:
|
|
|
|
|
- hooks:
|
|
|
|
|
- type: command
|
|
|
|
|
command: |
|
|
|
|
|
if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
|
|
|
|
|
pwsh -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.ps1" 2>/dev/null || bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
|
|
|
|
|
else
|
|
|
|
|
bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"
|
|
|
|
|
fi
|
|
|
|
|
description: 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.
|
|
|
|
|
license: MIT
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Planning with Files
|
|
|
|
|
|
|
|
|
|
Work like Manus: Use persistent markdown files as your "working memory on disk."
|
|
|
|
|
|
|
|
|
|
## FIRST: Check for Previous Session (v2.2.0)
|
|
|
|
|
|
|
|
|
|
**Before starting work**, check for unsynced context from a previous session:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If catchup report shows unsynced context:
|
|
|
|
|
1. Run `git diff --stat` to see actual code changes
|
|
|
|
|
2. Read current planning files
|
|
|
|
|
3. Update planning files based on catchup + git diff
|
|
|
|
|
4. Then proceed with task
|
|
|
|
|
|
|
|
|
|
## Important: Where Files Go
|
|
|
|
|
|
|
|
|
|
- **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
|
|
|
|
|
- **Your planning files** go in **your project directory**
|
|
|
|
|
|
|
|
|
|
| Location | What Goes There |
|
|
|
|
|
|----------|-----------------|
|
|
|
|
|
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs |
|
|
|
|
|
| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |
|
|
|
|
|
|
|
|
|
|
## Quick Start
|
|
|
|
|
|
|
|
|
|
Before ANY complex task:
|
|
|
|
|
|
|
|
|
|
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
|
|
|
|
|
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
|
|
|
|
|
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
|
|
|
|
|
1. **Create `task_plan.md`** — Use templates/task_plan.md as reference
|
|
|
|
|
2. **Create `findings.md`** — Use templates/findings.md as reference
|
|
|
|
|
3. **Create `progress.md`** — 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:** Planning files go in your project root, not the skill installation folder.
|
|
|
|
|
|
|
|
|
|
## The Core Pattern
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
@@ -113,68 +57,18 @@ After completing any phase:
|
|
|
|
|
### 5. Log ALL Errors
|
|
|
|
|
Every error goes in the plan file. This builds knowledge and prevents repetition.
|
|
|
|
|
|
|
|
|
|
```markdown
|
|
|
|
|
## 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
|
|
|
|
|
|
|
|
|
|
| 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 |
|
|
|
|
|
|
|
|
|
|
## When to Use This Pattern
|
|
|
|
|
|
|
|
|
|
**Use for:**
|
|
|
|
@@ -182,7 +76,6 @@ If you can answer these, your context management is solid:
|
|
|
|
|
- Research tasks
|
|
|
|
|
- Building/creating projects
|
|
|
|
|
- Tasks spanning many tool calls
|
|
|
|
|
- Anything requiring organization
|
|
|
|
|
|
|
|
|
|
**Skip for:**
|
|
|
|
|
- Simple questions
|
|
|
|
@@ -191,24 +84,20 @@ If you can answer these, your context management is solid:
|
|
|
|
|
|
|
|
|
|
## Templates
|
|
|
|
|
|
|
|
|
|
Copy these templates to start:
|
|
|
|
|
|
|
|
|
|
- [templates/task_plan.md](templates/task_plan.md) — Phase tracking
|
|
|
|
|
- [templates/findings.md](templates/findings.md) — Research storage
|
|
|
|
|
- [templates/progress.md](templates/progress.md) — Session logging
|
|
|
|
|
- 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
|
|
|
|
|
- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)
|
|
|
|
|
- scripts/init-session.sh — Initialize all planning files
|
|
|
|
|
- scripts/check-complete.sh — Verify all phases complete
|
|
|
|
|
- scripts/session-catchup.py — Recover context from previous session
|
|
|
|
|
|
|
|
|
|
## Advanced Topics
|
|
|
|
|
|
|
|
|
|
- **Manus Principles:** See [reference.md](reference.md)
|
|
|
|
|
- **Real Examples:** See [examples.md](examples.md)
|
|
|
|
|
- **Manus Principles:** See reference.md
|
|
|
|
|
- **Real Examples:** See examples.md
|
|
|
|
|
|
|
|
|
|
## Anti-Patterns
|
|
|
|
|
|
|
|
|
|