Planning with Files

Workflow

Persistent file-based planning skill: keeps task_plan.md, findings.md, progress.md on disk so agents survive /clear and crashes.

by Ahmad Othman Ammar Adi (OthmanAdi)OthmanAdi/planning-with-files

Stars27.6k

Forks2.3k

Watchers118

Open issues10

LicenseMIT

Last pushyesterday

Install

install

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

Update

update

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

Re-run the same `npx skills add` command to pull the latest release into each agent's discovery path. Plugin users: `/plugin marketplace update planning-with-files`.

When to use it

Multi-step coding or research tasks (3+ steps) spanning many tool calls where the agent tends to forget the original goal
You want the agent to recover its plan and progress automatically after /clear, a crash, or a context reset
You want a Stop-hook completion gate that blocks the agent from stopping until every phase is checked off
You run long autonomous agent sessions and need durable on-disk state instead of volatile TodoWrite/context

Commands & flags

npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g: Install globally across any Agent Skills-compatible agent (Claude Code, Cursor, Codex, Gemini CLI, 60+ others).
/plugin marketplace add OthmanAdi/planning-with-files: Claude Code plugin route that also ships /plan slash commands; then /plugin install planning-with-files@planning-with-files.
/planning-with-files:plan: Start a planning session (type /plan in autocomplete); creates task_plan.md, findings.md, progress.md.
/planning-with-files:status: Show planning progress at a glance (alias /plan:status) from the on-disk plan files.
init-session --autonomous: Opt-in autonomous mode: drops per-tool-call plan re-injection for strong models, keeps turn-start injection.
init-session --gated: Add a Stop-hook completion gate that blocks the agent from stopping until the plan is actually done.

How to use it

Install once, then drive it with slash commands or the auto-firing hooks.

# Global install across any Agent Skills agent
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

# Claude Code plugin route (adds /plan slash commands)
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

In a session, run /plan to start (creates task_plan.md, findings.md, progress.md) and /plan:status to check progress. Hooks re-inject the active plan at turn start, remind you to flush progress after file writes, and verify completion on Stop. For long runs, opt into init-session --autonomous (skip per-tool-call re-injection on strong models) or init-session --gated (Stop-hook completion gate). Other languages: append --skill planning-with-files-ar|-de|-es|-zh|-zht.

Why it earns its place

Implements the Manus "filesystem as working memory" pattern (Manus was acquired by Meta for $2B in Dec 2025), turning context-window volatility into durable on-disk plan state. README cites a skill-creator eval at 96.7% pass rate (29/30) vs 6.7% (2/30) without it, and 3/3 blind A/B wins for 3-file-pattern fidelity. It is unusually broad and well-maintained: one-command install across 60+ agents via the SKILL.md/Agent Skills standard, 17+ platform integrations with dedicated hooks, MIT-licensed, and shipping frequent releases (v3.x adds autonomous and gated modes plus SHA-256 attestation via /plan-attest).

Try it

claude

> /plan Build a REST API for a todo app with auth, persistence, and tests — track phases in task_plan.md and don't stop until every phase is checked off.