/planning-with-files

name: planning-with-files
version: "3.2.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 and optional Git worktree mode.
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - WebFetch
  - WebSearch
hooks:
  PreToolUse:
    # Location verification for worktree mode (Write/Edit operations only)
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: |
            SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/planning-with-files}/scripts"
            # Check for worktree config and verify location
            if [ -f ".planning-config.json" ]; then
              # Determine which verification script to use
              if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
                pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/verify-location.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/verify-location.ps1" 2>/dev/null || bash "$SCRIPT_DIR/verify-location.sh"
              else
                bash "$SCRIPT_DIR/verify-location.sh"
              fi
              # Exit code 1 means wrong location - block the operation
              if [ $? -eq 1 ]; then
                exit 1
              fi
            fi
    # Show task_plan context for all operations (except in worktree mode for read/grep/glob)
    - matcher: "Write|Edit|Bash|Read|Glob|Grep"
      hooks:
        - type: command
          command: |
            # In worktree mode, silence read/grep/glob operations
            if [ -f ".planning-config.json" ]; then
              MODE=$(jq -r '.mode' .planning-config.json 2>/dev/null || echo "")
              if [ "$MODE" = "worktree" ]; then
                # Silent for read/grep/glob in worktree mode
                case "$CLAUDE_TOOL_NAME" in
                  Read|Glob|Grep) exit 0 ;;
                esac
              fi
            fi
            # Show task_plan for write/edit/bash or standard mode
            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"
            if command -v pwsh &> /dev/null && [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OS" == "Windows_NT" ]]; then
              pwsh -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null || powershell -ExecutionPolicy Bypass -File "$SCRIPT_DIR/check-complete.ps1" 2>/dev/null || bash "$SCRIPT_DIR/check-complete.sh"
            else
              bash "$SCRIPT_DIR/check-complete.sh"
            fi

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
uv run 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

Standard Mode

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 4. **Re-read plan before decisions** — Refreshes goals in attention window 5. **Update after each phase** — Mark complete, log errors

Worktree Mode (Multi-Task Parallel Development)

For **parallel multi-task development** with isolated Git worktrees:

1. **Start worktree mode** — Use `/planning-with-files:worktree [task-name] [target-branch]`

• Example: `/planning-with-files:worktree feature-auth main`
• Creates a new Git worktree directory (`.worktree/feature-auth/`)
• Creates a task branch with planning files inside the worktree
• **Main directory stays on original branch** (no switching!)
• **Multiple worktrees can exist simultaneously** for parallel tasks

2. **Navigate to worktree** — `cd .worktree/feature-auth`

• Work on your task in this isolated environment
• Follow standard planning workflow

3. **Complete and merge** — Use `/planning-with-files:complete [target-branch]` from **inside the worktree**

• Deletes planning files from worktree
• Navigates to root directory
• Merges task branch to target
• Removes the worktree directory
• Deletes the task branch

**Multi-Task Example:**

# Start task 1
/planning-with-files:worktree fix-auth-bug
cd .worktree/fix-auth-bug

# In another terminal, start task 2 (parallel!)
/planning-with-files:worktree refactor-api
cd .worktree/refactor-api

# Each task has its own directory and branch
# No conflicts, no branch switching need