planning-with-files

Organizes complex multi-step tasks using persistent markdown planning files on disk.

Updated Mar 28, 2026

Search Tags:#automation #workflow #planning #markdown #context management #task tracking #session recovery

Ready to run

npx skills add https://github.com/whatswithavi/Ecchelon_project --skill planning-with-files-whatswithavi

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: planning-with-files
Source: https://github.com/whatswithavi/Ecchelon_project/tree/main/.agent/skills/planning-with-files
Command: npx skills add https://github.com/whatswithavi/Ecchelon_project --skill planning-with-files-whatswithavi

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Long-running AI tasks lose track of goals after many tool calls because context windows are volatile and limited. This Skill stores plans, findings, and progress in persistent markdown files so work survives context resets and session interruptions. ## Core Features & Use Cases - File-Based Planning: Creates task_plan.md, findings.md, and progress.md in your project directory to track phases, decisions, and errors. - Session Recovery: Detects unsynced context from previous sessions via a catchup script and restores state after /clear or new sessions. - Lifecycle Hooks: Automatically re-injects the current plan before tool calls and reports phase completion status when work stops. - Use Case: When asked to research a topic and produce a report, the Skill creates a phased plan, logs discoveries to findings.md after every few searches, and resumes cleanly even if the session is cleared mid-task. ## Quick Start Ask the AI to plan out and break down your multi-step project using file-based planning before starting any work.

Frequently Asked Questions about planning-with-files

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I keep an AI agent on track during long multi-step tasks?▼

Use file-based planning: create a task_plan.md with phases and a goal statement, then re-read it before major decisions. This keeps goals in the model's attention window even after dozens of tool calls.

How does planning-with-files recover after clearing the session?▼

The session-catchup.py script scans the previous session transcript for messages after the last planning file update, then prints unsynced context. You run git diff --stat, read the planning files, and update them before continuing.

What files does the planning-with-files skill create?▼

It creates three markdown files in your project directory: task_plan.md for phases and decisions, findings.md for research and discoveries, and progress.md for session logs and test results. Templates for each are included.

When should I not use file-based planning?▼

Skip it for simple questions, single-file edits, and quick lookups. The pattern is designed for tasks with three or more steps, research work, or anything spanning many tool calls where context loss is a real risk.

Why should web search results not go into task_plan.md?▼

A PreToolUse hook re-reads task_plan.md before every tool call, so untrusted external content there gets repeatedly injected into context, amplifying prompt injection risk. Write web findings to findings.md instead.