AI Skill MartBrowse skillsPromptsProgramsLearnWhat is a Skill?
 
← Back to list

Planning with Files

Keeps task_plan.md, findings.md and progress.md on disk so an agent never loses the thread across long, multi-step work.

AutomationIntermediate★ 27,953⑂ 2,313AI score 10/10Last updated: Nov 7, 2026

What it does

Implements the "Manus" pattern: the context window is RAM, the filesystem is disk — anything important gets written down.

  • Three planning files: task_plan.md (phases + status), findings.md (research), progress.md (session log), created in your project directory.
  • State restore first: resolves the owning plan, re-reads it before continuing, and can pull aggregate counts from past same-project sessions via session-catchup.py --metadata.
  • Structure validation: init-session.sh scaffolds the plan, check-complete.sh --validate confirms the ### Phase N + **Status:** markers are intact (format only, not completion).
  • Error discipline: every error is logged in the plan, and a 3-strike protocol forces an approach change, then escalation to the user.
  • Lifecycle hooks: injects current plan context on UserPromptSubmit, PreToolUse, PreCompact and Stop.

Who it's for

  • Anyone handing the agent research or build tasks that need 5+ tool calls
  • People who hit context compaction and watch earlier decisions disappear
  • Teams running parallel tasks/worktrees that need separate pinned plans
  • Anyone who wants durable records instead of ephemeral TodoWrite lists

Examples

  1. Refactor project: run init-session.sh to scaffold a 5-phase plan, flip each phase to complete as you go, and log touched files in progress.md.
  2. Technical research: following the 2-action rule, dump key takeaways to findings.md after every two reads/searches so nothing is lost when context is compacted.
  3. Resuming next day: run set-active-plan.sh --list to see saved plans and phase progress, pin the right PLAN_ID, and continue exactly where you stopped.

· · · Install guide · · ·

Try it now, no install

Paste this into Claude to use the skill without installing anything.

Read the instructions in this file and follow them to help me:
https://raw.githubusercontent.com/OthmanAdi/planning-with-files/HEAD/.codex/skills/planning-with-files/SKILL.md

What I want: (describe your task here)

If Claude can't open the link, open it yourself and paste the contents instead.

↓ If it works for you, download the ZIP below and install it. Then it runs on its own — no pasting each time.

Install in the Claude app (no terminal)
  1. Download the ZIP with the button below.
  2. In Claude, open Settings → Capabilities and turn on 'Code execution and file creation'. (one time)
  3. Go to Customize → Skills → + → 'Upload a skill' and upload the ZIP.
↓ Download ZIP
Install in Claude Code

Let Claude do it — paste this into Claude Code

Install the skill I found on AI Skill Mart.
Copy the .codex/skills/planning-with-files folder from the GitHub repo OthmanAdi/planning-with-files into my ~/.claude/skills/othmanadi-planning-with-files-2/.
When it's done, tell me in one line what this skill can do.

Install with a command instead

git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/pwf && mkdir -p ~/.claude/skills && cp -r /tmp/pwf/.codex/skills/planning-with-files ~/.claude/skills/ && rm -rf /tmp/pwf

⚠ This is a third-party skill. Check the source repository before installing.

  1. Open a terminal and clone the repo: git clone https://github.com/OthmanAdi/planning-with-files.git
  2. Create the skills folder: mkdir -p ~/.claude/skills
  3. Copy the skill in: cp -r planning-with-files/.codex/skills/planning-with-files ~/.claude/skills/
  4. If you also use Codex, run mkdir -p ~/.codex/skills && cp -r planning-with-files/.codex/skills/planning-with-files ~/.codex/skills/ — the SKILL.md examples reference ~/.codex/... paths.
  5. Make the helpers executable: chmod +x ~/.claude/skills/planning-with-files/scripts/*.sh
  6. If you installed to a non-standard path, add export PWF_SCRIPT_DIR=~/.claude/skills/planning-with-files/scripts to your .bashrc/.zshrc so the hooks can find the script.
  7. Restart Claude Code, then from your project root ask it to "track this task with planning files".
  8. Smoke-test by running sh ~/.claude/skills/planning-with-files/scripts/init-session.sh in the project root and checking that a .planning/ directory appears.
View source on GitHub ↗License: MIT