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

Planning with Files

Keeps task_plan.md, findings.md and progress.md on disk as the agent's persistent working memory for multi-step work.

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

What it does

  • Creates task_plan.md (phases + status), findings.md (research), progress.md (session log) inside your project so important state lives on disk, not only in context.
  • Recovers state after a dropped session or compaction via resolve-plan-dir.sh plus a git diff --stat sanity check.
  • Registers lifecycle hooks (UserPromptSubmit / PreToolUse / PostToolUse / Stop / PreCompact) that re-inject the selected plan each turn.
  • Enforces a trackable format — ### Phase N with exactly one **Status:** pending|in_progress|complete line — validated by check-complete.sh.
  • Ships operating rules: log every error, the 3-strike protocol (diagnose → alternative → rethink → escalate), and the 2-action rule (write findings after every two view/search operations).
  • Supports named plans for parallel tasks (.planning/<date>-<slug>/), PLAN_ID/PWF_PLAN_ROOT pinning, autonomous/gated modes, and SHA-256 plan attestation.

Who it's for

  • Anyone handing the agent research, refactors or builds that span 5+ tool calls.
  • Users frustrated by agents forgetting the goal or repeating the same failing action in long sessions.
  • Teams running several agents in one repository that need per-task isolation.
  • People who want "done" judged from the plan file on disk rather than from the transcript.

Examples

  1. Large refactor: run init-session.sh "Backend Refactor", pin export PLAN_ID=..., flip phase statuses as you go, and resume days later by reading only the plan files.
  2. Technical research: after every two docs/web reads, findings are flushed to findings.md, so a context compaction never loses the evidence needed for the final write-up.
  3. Long unattended run: combine /plan-loop 10m for cadence with /plan-goal so the agent keeps working until all phases report complete.

· · · 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/.agents/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 .agents/skills/planning-with-files folder from the GitHub repo OthmanAdi/planning-with-files into my ~/.claude/skills/planning-with-files/.
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/.agents/skills/planning-with-files ~/.claude/skills/planning-with-files

⚠ 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 /tmp/pwf
  2. Before installing, inspect what will run: ls /tmp/pwf/.agents/skills/planning-with-files/scripts and skim skill-hook.sh (hooks fire on every prompt and tool call).
  3. Copy the skill into place: mkdir -p ~/.claude/skills && cp -r /tmp/pwf/.agents/skills/planning-with-files ~/.claude/skills/planning-with-files
  4. If you want the /plan-goal, /plan-loop and /plan-doctor slash commands, install via the plugin route instead: /plugin marketplace add OthmanAdi/planning-with-files, then /plugin install.
  5. Restart Claude Code, go to your project root, and run sh ~/.claude/skills/planning-with-files/scripts/init-session.sh to create the planning files.
  6. If hooks seem silent or something misbehaves, run sh ~/.claude/skills/planning-with-files/scripts/plan-doctor.sh for a self-check.
  7. For parallel tasks, export PLAN_ID=<id printed by init-session> in each terminal before starting the agent there.
View source on GitHub ↗License: MIT