A file-based planning skill for AI coding agents that persists task state in Markdown files on disk, preventing context loss and goal drift during long tasks. It adds a completion gate and plan attestation to enforce structured execution.
Project overview
Uses the filesystem as durable shared state for AI agents, avoiding the volatility of in-context memory and TodoWrite-style tools during extended workflows.
Project type
AI Agent · Prompt Engineering
Use cases
Coding & Development · Automation
Deployment
Refer to project documentation
License
MIT
Best for
Developers and AI engineers managing long-duration AI coding agent tasks that require structured phases, on-disk research persistence, and strict completion verification.
Key capabilities
Creates and maintains task_plan.md, findings.md, and progress.md to track execution phases, store research data, and log session activity.
Implements a Stop hook that holds the AI agent in place until all predefined completion conditions have been satisfied.
Locks the task_plan.md file using a SHA-256 attestation to detect and prevent unauthorized tampering with the plan.
Limitations and risks
The planning overhead makes this unnecessarily heavy for simple queries, single-file edits, or quick lookups.
If file-based persistence is bypassed or unavailable, AI agents remain vulnerable to volatile memory and goal drift.
Getting started
Installation is rated easy and can be completed in one command using npx via the provided skills add utility.
Alternatives and comparisons
A library of 358 reusable skills, agents, and personas that add modular domain expertise to AI coding tools, serving as an alternative for expanding agent capabilities.
A Python agent framework providing type-safety, model-agnostic support, and structured output validation as an alternative approach to building production GenAI applications.
GitHub project description: Persistent file-based planning for AI coding agents and long-running agentic tasks. Crash-proof markdown plans that survive context loss and /clear, plus a deterministic completio…
README: planning-with-files is a persistent file-based planning skill for AI coding agents. It keeps task_plan.md, findings.md, and progress.md on disk so the agent survives context loss,…
README: Claude Code (and most AI agents) suffer from: - Volatile memory — TodoWrite tool disappears on context reset - Goal drift — After 50+ tool calls, original goals get forgotten - Hi…