planning-with-files

name	planning-with-files
version	2.10.0
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":"SCRIPT_DIR=\"${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts\"\n\nIS_WINDOWS=0\nif [ \"${OS-}\" = \"Windows_NT\" ]; then\n IS_WINDOWS=1\nelse\n UNAME_S=\"$(uname -s 2>/dev/null || echo '')\"\n case \"$UNAME_S\" in\n CYGWIN*|MINGW*|MSYS*) IS_WINDOWS=1 ;;\n esac\nfi\n\nif [ \"$IS_WINDOWS\" -eq 1 ]; then\n if command -v pwsh >/dev/null 2>&1; then\n pwsh -ExecutionPolicy Bypass -File \"$SCRIPT_DIR/check-complete.ps1\" 2>/dev/null ||\n powershell -ExecutionPolicy Bypass -File \"$SCRIPT_DIR/check-complete.ps1\" 2>/dev/null ||\n sh \"$SCRIPT_DIR/check-complete.sh\"\n else\n powershell -ExecutionPolicy Bypass -File \"$SCRIPT_DIR/check-complete.ps1\" 2>/dev/null ||\n sh \"$SCRIPT_DIR/check-complete.sh\"\n fi\nelse\n sh \"$SCRIPT_DIR/check-complete.sh\"\nfi\n"}]}]}

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:

# Linux/macOS
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"

# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)

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 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
6. If files already exist, append a dated run section first — never erase prior run history