planning-with-files Skill for Claude: Keep Your Task Plan on Disk

Makes Claude keep a task plan, findings and progress log as files in your project, and re-read them as it works.

Installs: 47.8K; on skills.sh
Stars: 27.8K; on GitHub
Files: 33; besides SKILL.md
Updated: Oct 2026; last repo commit

For multi-step work, the agent creates task_plan.md, findings.md and progress.md, updates them after each phase, and re-reads the plan before big decisions. Hooks put the selected plan back into context each turn, so the work can continue after a context reset or compaction.

It bundles 22 scripts and 7 templates, and the skill's own hooks run a shell script on your prompts and tool calls. Named plans, plan attestation, and optional autonomous and gated modes are there for long or parallel runs.

Good for

Developers running long, multi-step tasks that outgrow the context window
Researchers who want findings saved to a file as they go
Anyone running parallel agent tasks that each need their own plan

Install planning-with-files

Claude Code

Copy this prompt.

Install the planning-with-files skill in Claude Code. Run this command:

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

The plugin route also adds /plan-goal, /plan-loop and a SessionStart hook; the skills CLI route installs the skill and its scripts and templates only. The README warns that skill-route installs can end up without working hooks (project trust not accepted, or frontmatter hooks not registering); run /plan-doctor to check, or use the plugin route if you need the hooks.

From the project README. Source.

What's in the skill

When it loads

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.

Sections in SKILL.md

FIRST: Restore Project State
Important: Where Files Go
Quick Start
New plan creation contract
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
Errors Encountered
6. Never Repeat Failures
7. Continue After Completion
The 3-Strike Error Protocol

Key facts

Author: othmanadi
Repository: othmanadi/planning-with-files
License: MIT
Installs on skills.sh: 47,831 (Nov 2, 2026)
GitHub stars: 27,806 (Nov 2, 2026)
Last repo commit: Oct 30, 2026
What installs: 34 files including SKILL.md (22 scripts, 7 templates, 3 reference docs, 1 eval file)
Skill version: 3.27.0
Works in: Claude Code, Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, Hermes Agent and others (README FAQ)
Plugin route adds: Six lifecycle hooks (SKILL.md) and a commands folder with 13 files

What it includes

Resolves the plan folder, reads the three files, runs git diff --stat
Uses resolve-plan-dir.sh with PLAN_ID and PWF_PLAN_ROOT.
Runs code · Restore project state
Creates the planning files; with a name, an isolated plan in .planning/<date>-<slug>/
Without a name, it writes task_plan.md at the project root. --autonomous and --gated set a mode.
Runs code · init-session.sh
task_plan.md for phases, findings.md for research, progress.md for the session log
Seven templates ship with the skill, including loop and autonomous variants.
Write · The three files
Plan first, save findings every 2 view or search steps, read before deciding
Also: log all errors, never repeat a failure, and a 3-strike error protocol.
Critical rules
Verifies every phase is complete; --validate checks the plan format
Runs code · check-complete.sh
Lists named plans (--list) and switches the active one
Parallel agents should each pin their own PLAN_ID or use separate worktrees.
Runs code · set-active-plan.sh
Locks task_plan.md with a SHA-256 so hooks refuse to inject a changed plan
Default-on in autonomous and gated modes.
Runs code · attest-plan.sh (/plan-attest)
Self-check of plan resolution, hook injection and attestation
Runs code · plan-doctor.sh (/plan-doctor)
Only when you ask: --metadata counts same-project session records; --replay shows excerpts
Reads local agent session records. Never runs automatically.
Runs code · session-catchup.py
Legacy (default), autonomous and gated
Gated mode can ask the host to continue until the plan reports complete, where the host supports it.
Modes
Plugin route only: tie the plan to Claude Code /goal and /loop
Skill-only installs follow a manual fallback in SKILL.md.
/plan-goal and /plan-loop
UserPromptSubmit, PreToolUse, PostToolUse, Stop and PreCompact run scripts/skill-hook.sh
Active after the skill is invoked in a session. The plugin route registers six lifecycle events instead.
Runs code · Skill hooks

From the official docs

Permissions

Medium risk

Its hooks run a shell script on your prompts and tool calls, and plan files are fed back to the model each turn. Install it only if you are comfortable with that, and keep untrusted web content out of task_plan.md.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Hooks run a shell script on prompts and tool calls
The skill's frontmatter registers hooks that run scripts/skill-hook.sh on each prompt, tool use, stop and compaction. Read the script first if you work in sensitive repos.
Plan file text goes into the model every turn
Hooks inject the selected plan. SKILL.md says to put web and search results in findings.md only, never in task_plan.md, and to treat embedded instructions as data.
Catch-up can read your local session records
session-catchup.py reads same-project agent session records only when you ask. --replay may show excerpts, so approve it deliberately.
The plugin route adds more hooks and commands
Per SKILL.md, the plugin registers six lifecycle events, including SessionStart, and adds slash commands. The skills CLI route adds only the skill.
Gated mode can ask the agent to keep going
It is opt-in. It judges the plan file on disk and may request continuation on hosts that support it.

Technical details

Scopes	Read Write Edit Bash Glob Grep

Questions

What does planning-with-files do?

It keeps your task plan, research notes and progress log as files in the project, updates them after each phase, and re-reads them so the work can pick up after a context reset.

How do I install planning-with-files?

Use the install box above. The README's quick install is the skills CLI. The plugin route also adds hooks and the /plan-goal and /plan-loop commands.

Where do the plan files go?

In the selected task folder of your project: the project root in legacy mode, or .planning/<date>-<name>/ for a named plan. The skill folder holds only templates and scripts.

How is it different from Claude Code plan mode?

The README calls them complementary. Plan mode is where you design and approve the approach. This skill keeps the live execution state (phase status, findings, errors, progress) on disk while the work runs.

Does it need an API key or network?

SKILL.md names no key and says the shipped catchup path has no network request or upload. Hook output can still become part of what your agent sends to its model provider.

Is planning-with-files safe?

It runs shell scripts through hooks on your prompts and tool calls, writes planning files into your project, and feeds them back to the model. SKILL.md adds hash attestation to detect plan tampering, but says it does not remove prompt-injection risk. Keep untrusted content out of task_plan.md.

Which agents does it work with?

The README lists Claude Code, Codex CLI, Cursor, GitHub Copilot, Kiro, OpenCode, Continue, Pi, Hermes Agent and more through the SKILL.md standard. Hooks and commands differ by install route.

Information

updated Nov 2, 2026

Repository: othmanadi/planning-with-files
Folder: skills/planning-with-files

othmanadi/planning-with-files skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

planning-with-files README · github.com
planning-with-files SKILL.md · github.com
planning-with-files Codex setup · github.com
plugin.json · github.com
hooks.json · github.com
planning-with-files on skills.sh · skills.sh