Repolode
Submit
OthmanAdi

OthmanAdi/planning-with-files

A file-based planning skill for AI coding agents that keeps task plans on disk so they survive context resets, /clear, and crashes.

View on GitHubWebsite
Stars
27,923
Forks
2,313
Open issues
11
Last commit
3 days ago

What is it?

Planning with Files is a skill for AI coding agents that stores a task's plan, research notes, and progress in three markdown files inside the project: task_plan.md, findings.md, and progress.md. Because the state lives on disk rather than in the context window, an agent can resume at the current phase after /clear, context compaction, or a crash.

Lifecycle hooks re-inject the active plan context at the start of each turn, and a completion check reports whether the plan's phases are finished. Parallel tasks can use separate directories under .planning/, selected through an active-plan pointer. Automatic recovery reads only project files; reading local agent session records requires an explicit catchup mode.

The skill installs through npx skills, the Claude Code plugin marketplace, or npm, and has native plugin integrations for Claude Code, Codex CLI, Cursor, OpenCode, Hermes Agent and others, with translated variants in several languages.

Key features

  • 01Stores plan, findings and progress as markdown files in the project
  • 02Re-injects the active plan into each turn via lifecycle hooks
  • 03Recovers the plan after /clear, compaction or session crashes
  • 04Completion check reports whether all plan phases are finished
  • 05Isolated plan directories for parallel tasks
  • 06Installs across many coding agents via the Agent Skills standard

Use cases

  • Long-running refactors or migrations that span many sessions
  • Multi-step coding tasks where an agent must not lose track after /clear
  • Keeping an auditable record of decisions and test results during agent work

In collections

Claude Code tools, skills & pluginsOpen-source AI agent frameworks & appsAI coding assistants & agentsAI agent skill libraries

Topics

#agent-skills#ai-agents#claude-code#context-engineering#planning#llm-agents#coding-agent#autonomous-agents#claude#claude-code-skills

FAQ

What is planning-with-files?
A file-based planning skill for AI coding agents that keeps task plans on disk so they survive context resets, /clear, and crashes. Planning with Files is a skill for AI coding agents that stores a task's plan, research notes, and progress in three markdown files inside the project: task_plan.md, findings.md, and progress.md. Because the state lives on disk rather than in the context window, an agent can resume at the current phase after /clear, context compaction, or a crash.
Is planning-with-files free to use? What license does it have?
planning-with-files is open source under the MIT license. Check the license terms before using it in commercial products.
Is planning-with-files still maintained?
Actively maintained. The last commit to planning-with-files was on Nov 4, 2026.
What can I use planning-with-files for?
Long-running refactors or migrations that span many sessions Multi-step coding tasks where an agent must not lose track after /clear Keeping an auditable record of decisions and test results during agent work
Where can I get planning-with-files?
The source code and installation instructions are on GitHub: https://github.com/OthmanAdi/planning-with-files

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects