planning-with-files

The planning-with-files skill provides a robust architectural framework for managing complex, multi-step tasks by treating the filesystem as an external, persistent working memory. Designed for AI agents, this system solves the 'lost in the middle' phenomenon by maintaining project state in dedicated markdown files, which the agent periodically refreshes to keep goals within its immediate attention window. It is ideal for developers, researchers, and project managers who require high-structure output and verifiable progress tracking across long-running sessions.

• Enables the 3-file pattern (task_plan.md, notes.md, and deliverable.md) to isolate concerns and manage memory usage efficiently.

• Forces explicit phase-based execution, ensuring that goals, research findings, and final deliverables are handled in logical, traceable steps.

• Includes standardized templates for task plans, research notes, and status reporting, minimizing cognitive load and context switching.

• Maintains a dedicated section for 'Errors Encountered' to document failure traces and resolution paths, fostering iterative learning and better debugging capabilities.

• Promotes atomic, commit-ready updates to documentation after every major phase or action, ensuring the project state is always synchronized with the filesystem.

• Users should invoke this skill when beginning tasks that exceed three steps or require multi-tool coordination, such as architectural research, complex refactoring, or multi-phase software development.

• Expected inputs include task definitions, research queries, or feature requests; expected outputs are structured markdown files that act as the source of truth.

• Practical constraints: Users should avoid using this for trivial or single-action queries, as the overhead of file creation may be unnecessary. It relies on consistent adherence to the 'read-before-decide' rule to ensure the agent maintains goal alignment throughout the task lifecycle. Use this to prevent context stuffing and to ensure large research findings remain organized in external notes rather than ephemeral memory buffers.