planning-with-files
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.
npx skills add OthmanAdi/planning-with-files --skill planning-with-files --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
The skill provides Manus-style persistent file-based planning by maintaining task_plan.md, findings.md, and progress.md on disk. It is intended for planning out, breaking down, or organizing a multi-step project, research task, or any work requiring 5+ tool calls, with automatic session recovery after /clear.
How it works
- Restores context first by reading existing planning files if present, then checks for unsynced context from a previous session using a Python script session-catchup.py (and optionally a PowerShell path) to determine if context needs catch-up.
- If catch-up reports unsynced context, it runs git diff --stat to view changes, reads current planning files, and updates planning files based on catch-up and git diff before proceeding.
- Creates and uses three core files in the project: task_plan.md, findings.md, and progress.md, with templates provided under templates/. It logs phases, findings, and session progress, and requires updating after each phase and after actions.
- Provides a set of helper scripts for session initialization, plan management, and verification such as scripts/init-session.sh, scripts/set-active-plan.sh, scripts/resolve-plan-dir.sh, scripts/check-complete.sh, scripts/session-catchup.py, scripts/attest-plan.sh, and scripts/plan-doctor.sh.
- Integrates with Claude Code turn-loop primitives like /loop and /goal via /plan-goal and /plan-loop commands, and uses a PreCompact hook to remind about flushing in-context progress to progress.md prior to compaction.
When to use it
Use for multi-step tasks, research tasks, building/creating projects, or tasks spanning many tool calls where organization is crucial and there is a need to persist state across sessions or context loss.
What it can touch
The skill declares allowed tools Read Write Edit Bash Glob Grep and uses scripts/ within the skill to manage planning files. It expects planning files to live in your project directory and templates in templates/.
Caveats
The approach relies on disk-based planning files (task_plan.md, findings.md, progress.md) and scripts that interact with the project workspace. It includes hooks and commands that manage plan state and attestations, and references to external paths for CLI and PowerShell usage. Documentation notes the need to refresh planning files after phases and to log errors in the plan file.
# 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 Go
- FIRST: Restore Context (v2.2.0)
- Important: Where Files Go
- Quick Start
- The Core Pattern
- File Purposes
- Critical Rules
- 1. Create Plan First
- 2. The 2-Action Rule
- 3. Read Before Decide
- 4. Update After Act
- 5. Log ALL Errors
- 6. Never Repeat Failures
- 7. Continue After Completion
- The 3-Strike Error Protocol
Linux/macOS — auto-detects skill directory (plugin env or default install path)
Start task A
Start task B in a second terminal
Switch active plan
Or pin a terminal to a specific plan
export PLAN_ID=2026-01-10-backend-refactor
Or pin a thread to a project root, when the shell's cwd is somewhere else
export PWF_PLAN_ROOT=/workspace/project
user-wide
cp ${CLAUDE_PLUGIN_ROOT}/templates/loop.md ~/.claude/loop.mdWhat does the planning-with-files skill do?
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.
How do I install it?
Run `npx skills add OthmanAdi/planning-with-files --skill planning-with-files --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From OthmanAdi/planning-with-files, a repository with 25,969 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.