Skip to content
Get packs

planning-with-files

A file-based planning skill that keeps AI coding agents on track across resets and crashes.

GitHub Download v3.27.0
Stars
27.8k
Forks
2.3k
Licence
MIT
Language
Shell
Last update
6 days ago
Type
Dev tool

What it is

This is a skill for AI coding agents that stores a task plan, research notes, and progress log as markdown files in your project. Lifecycle hooks re-inject that planning context so the agent can pick up where it left off after /clear, context compaction, or a crash. The README says it works across 60+ agents via the Agent Skills standard, with native plugins for several hosts including Claude Code and Codex CLI.

  • Keep task_plan.md, findings.md, and progress.md updated while an agent works through a multi-phase feature
  • Resume a long refactor after running /clear without re-explaining the task
  • Run parallel tasks in separate .planning/ directories selected via .active_plan
  • Use the completion gate so the agent's stop is held until the plan reports complete

Great for

  • Developers running long multi-step tasks in Claude Code or Codex CLI
  • People who lose agent progress when the context window fills or is cleared
  • Teams wanting a plan that lives in the project as plain markdown files
  • Users of agents that support the Agent Skills standard

Not ideal for

  • Short one-off questions where a plan file adds overhead
  • People who want a hosted service rather than local files in their repo
  • Users of hosts not listed in the README, since native support depends on the host and results may vary
Step-by-step guide: how to use planning-with-filesInstall, first run, examples, tips and FAQs
planning-with-files alternativesplanning-with-files vs Understand Anythingplanning-with-files vs RufloOpenSpec vs planning-with-filesoh-my-claudecode vs planning-with-filesbook-to-skill vs planning-with-files9Router vs planning-with-filesOpenHands vs planning-with-filesplanning-with-files vs wshobson/agents

How to get it

  1. 1

    Install with a package manager

    Install the skill globally via npx skills

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

    Run it

    • Run the npx skills add command to install the skill globally.
    • Start a task in your coding agent that the skill supports.
    • Let the agent create task_plan.md, findings.md, and progress.md in your project.
    • After a /clear or context reset, check that the agent resumes from the plan file.
  3. 3

    Get the most out of it

    • Use the per-task .planning/ directories with .active_plan when running several tasks in parallel.
    • Enable the completion gate so the agent's stop is held until the plan is marked complete.
    • Read the platform setup guides for your specific host, since commands and hooks differ by integration.
    • Review docs/languages.md if you want the localized skill variants.

Downloads

Source code (.zip)master branch · straight from GitHubRelease v3.27.0Release notes and sourceOfficial website & docsgilded-laurel-c7nj.here.now/

Strengths

  • Plain markdown files on disk that you can read, edit, and version-control or gitignore
  • Works through the Agent Skills standard across many agents, with native plugins for several hosts
  • MIT licensed with a published benchmark and install options via npm, the Claude Code marketplace, or npx

Trade-offs

  • Benchmark figures are from the project's own measurements and are reported with stated limits; independent verification is not shown in the README
  • Commands and tools vary by host, so the experience differs between integrations
  • Session catchup modes can read local agent session records, which the README says requires an explicit opt-in

How it compares

ProjectStarsTypeLevelUpdatedBest for
planning-with-files (this)27.8kDev toolbeginner6 days agoDevelopers running long multi-step tasks in Claude Code or Codex CLI
OpenHands92.5kAppintermediate4 days agoDevelopers who want coding agents running on a server while their laptop is off
humanizer63.8kAI model / agentbeginner9 days agoWriters who draft with an AI and want the final text to sound more natural
marketingskills57.9kLearning resourcebeginner6 days agoTechnical marketers who already use AI coding agents
huashu-design28.5kCLIbeginner6 days agoDesigners or founders who want quick visual drafts from a short text prompt
agents42.1kDev toolbeginner4 days agoDevelopers who already use one of the listed AI coding tools and want ready-made specialist agents

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.