planning-with-filesAI Coding Plans That Stick

AI coding agents are getting incredibly powerful, but they often stumble on a fundamental problem: memory. Imagine spending hours meticulously crafting a complex, multi-step plan with your AI assistant, only for it to vanish due to a context window overflow, a session crash, or an accidental /clear command. All that work, gone in an instant. This is precisely the pain point planning-with-files aims to solve, offering an open-source solution that makes your AI's plans as durable as your file system.

Plans on Disk: The Power of Persistence

The core idea behind planning-with-files is refreshingly simple: instead of relying on the ephemeral nature of memory or the limited context window, it stores your agent's long-term plans in ordinary Markdown files. Every time the agent takes a step or updates its state, that information is written back to the file. This means if the process terminates unexpectedly, your plan remains intact, ready to be picked up exactly where it left off. This approach is a game-changer for large-scale refactoring or development tasks that might span hours or even days.

Built with Python, the project has minimal dependencies, making it straightforward to integrate into existing development workflows. All you need is a compatible coding agent—like Claude Code, Codex CLI, or Cursor—and a simple declaration using the SKILL.md standard. Once configured, your agent can automatically read from and update its plan file, ensuring continuity.

Crash Protection and Completion Gating

planning-with-files introduces two distinct features that elevate its utility:

• Crash Protection: Every modification is immediately synchronized to disk. This means that even if your agent crashes mid-task or you manually clear its context, the plan remains fully available upon restart. It's like having an auto-save feature for your AI's thought process.
• Deterministic Completion Gating: Agents are required to explicitly mark a task as 'completed' before moving on. This eliminates ambiguity, making the entire planning process more predictable and auditable. You always know exactly what stage your agent is at and what's left to do.

Together, these mechanisms transform long-running agent tasks from opaque 'black boxes' into transparent, traceable, and recoverable processes. It's about bringing engineering rigor to AI-driven development.

Multi-Agent Collaboration and Ecosystem Compatibility

One of the standout features of planning-with-files is its support for multiple agents concurrently reading and writing to the same plan document. This is incredibly valuable in multi-agent architectures: imagine one agent handling high-level planning, another executing code, and a third performing validation. All agents share their state through the file system, eliminating the need for complex inter-agent communication protocols.

In terms of compatibility, the project adheres to the SKILL.md standard, which means it already works with over 60 popular coding agents, including Claude Code, Codex CLI, Cursor, Kiro, and OpenCode. Getting started is often as simple as placing the project's skill files into your agent's configuration directory.

Who Should Use This?

If you're a developer who relies on AI agents for complex, time-consuming coding tasks, planning-with-files is definitely worth exploring. Anyone who has experienced the frustration of an AI agent 'forgetting' its entire plan will immediately grasp its value. It's also a pragmatic solution for team collaboration, allowing shared file systems to synchronize AI-driven development plans.

However, it's not without its limitations. The plan files are plain-text Markdown, meaning you can't embed diagrams or binary attachments directly. The initial configuration might require a bit of manual setup, which could be a slight hurdle for absolute beginners. Furthermore, for extremely large-scale plans involving millions of lines, pure file I/O might eventually become a performance bottleneck.

Ultimately, planning-with-files offers a simple yet robust solution to a critical pain point in AI-assisted coding. It's not a flashy generative feature, but rather a foundational component that makes AI agents truly reliable. If you're looking for a way to ensure your AI coding assistant stays on track and doesn't 'drop the ball,' starting with a persistent file-based plan is a solid move.