claudegoodies
Skill

planning-with-files

From OthmanAdi

Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear.

Maintains task_plan.md, findings.md, progress.md on disk so multi-step work survives /clear and context loss.

Use it when

  • Planning multi-phase coding or research tasks needing 5+ tool calls
  • Want session recovery after /clear or context compaction
  • Need a persistent log of findings and progress across a long session
  • Working across multiple context windows on the same project

Skip it if

  • Task is short or single-step, overhead of plan files not worth it
  • Relies on hooks (UserPromptSubmit, PreToolUse, Stop, PreCompact) that inject shell/PowerShell scripts into every action
  • Requires Python and shell/PowerShell available on the system to run session-catchup and gate scripts
  • Clutters project root with task_plan.md, findings.md, progress.md files

Facts

Repository
OthmanAdi/planning-with-files
Status
Actively maintained
Last commit
Declared tools
Read Write Edit Bash Glob Grep
Source file
.codebuddy/skills/planning-with-files/SKILL.md

Source preview

The instructions Claude Code reads when this skill runs.

# Planning with Files

Work like Manus: Use persistent markdown files as your "working memory on disk."

## FIRST: Restore Context (v2.2.0)

**Before doing anything else**, check if planning files exist and read them:

1. If `task_plan.md` exists, read `task_plan.md`, `progress.md`, and `findings.md` immediately.
2. Then check for unsynced context from a previous session:

```bash
# Linux/macOS — auto-detects skill directory (plugin env or default install path)
SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" "$(pwd)"
```

```powershell
# 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`, `progr
View full source on GitHub →

Other skills