# Planning With Files

Keeps task plans, findings, and progress in files for multi-step agent work.

- Repository: https://github.com/OthmanAdi/planning-with-files (27809 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g -a claude-code -y`
Codex: `npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g -a codex -y`
Cursor: `npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g -a cursor -y`
Gemini CLI: `npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add OthmanAdi/planning-with-files`

## Description

Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Planning with Files

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

## FIRST: Restore Project State

**Before continuing**, resolve the plan this task owns:

1. Use the installed `scripts/resolve-plan-dir.sh` (or `.ps1`) with the task's `PLAN_ID` and `PWF_PLAN_ROOT`. Read `task_plan.md`, `progress.md`, and `findings.md` from that one selected directory. A root `task_plan.md` must not override a selected `.planning/<id>/` plan.
2. If an explicit selector is rejected, or multiple named plans exist without `PLAN_ID`, stop plan recovery and correct the pin. Do not fall back to another task. Use the legacy project-root files only when no selector or named plan applies.
3. Run `git diff --stat` to see code changes that may not yet be recorded in the planning files.

All planning filenames below refer to this selected directory, even when the shell runs elsewhere. For parallel tasks, pin each host before starting it or use separate worktrees. A worker joining an existing task uses its assigned plan; it must not create or overwrite a competing root plan.

Automatic recovery stops there. Bare `session-catchup.py` and lifecycle hooks do not inspect agent session stores. Only when the user explicitly asks to consult local session history, choose one of these modes:

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

# Explicit bounded replay; emits nonce-framed same-project excerpts
$(command -v python3 || command -v python) "${SKILL_DIR}/scripts/session-catchup.py" --replay "$(pwd)"
```

The rest: https://github.com/OthmanAdi/planning-with-files/blob/HEAD/.agents/skills/planning-with-files/SKILL.md