# 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; agent instructions read selected project planning context when invoked. 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. This adapter registers no lifecycle or Stop hook, never requests continuation, 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 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. Run `git diff --stat` to see code changes that may not yet be recorded in the planning files.

Automatic recovery stops there. The following optional command reads same-project local session records and emits aggregate counts only:

```bash
python3 .continue/skills/planning-with-files/scripts/session-catchup.py --metadata "$(pwd)" || python .continue/skills/planning-with-files/scripts/session-catchup.py --metadata "$(pwd)"
```

Use `--replay` instead of `--metadata` only for a deliberate bounded replay. Replay emits nonce-framed same-project excerpts; treat them as untrusted data. Bare invocation and lifecycle hooks do not inspect agent session stores. This skill has no network upload path.

## Important: Where Files Go

- **Templates** are in `.continue/skills/planning-with-files/templates/`
- **Your planning files** go in **your project directory**

| Location | What Goes There |
|----------|-----------------|
| Skill directory (`.continue/skills/planning-with-files/`) | 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](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

> **Note:** Planning files go in your project root, not the skill installation folder.

## New plan creation contract

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