planning-with-files: a persistent file-based planning skill that prevents AI coding agents from losing track of complex tasks during context wipes

What it solves

AI coding agents often suffer from context loss, crashes, or memory wipes (such as when using /clear), causing them to lose track of complex, multi-step tasks. This project provides a persistent, file-based planning system that allows agents to maintain their state and progress across sessions.

How it works

The system implements a "skill" that forces the agent to maintain three specific Markdown files on disk: task_plan.md, findings.md, and progress.md. By keeping the plan and progress external to the conversation history, the agent can recover its state after a crash or context clear. It integrates with over 60 agents via the SKILL.md standard and uses lifecycle hooks to inject the current plan back into the agent's context at critical moments.

Who it’s for

Developers using AI coding agents (such as Claude Code, Codex, Pi, or Copilot) who are working on long-running, complex software engineering tasks that require structured planning and persistence.

Highlights

• Context Survival: Prevents progress loss during crashes or manual context clears.
• Broad Compatibility: Installs across 60+ agents using the SKILL.md standard.
• Autonomous & Gated Modes: Includes an opt-in completion gate that prevents the agent from stopping until the plan is actually finished.
• Tamper Protection: Uses SHA-256 hash attestation to lock plans and block injection if the file has been tampered with.
• Session Recovery: Includes a session-catchup command to restore context quickly.