OthmanAdi/planning-with-files: Trending on GitHub

The Rise of Planning with Files: A Game-Changing Skill for AI Agents

In the ever-evolving landscape of artificial intelligence, a new skill has emerged that's revolutionizing the way AI agents work. Developed by Ahmad Othman Ammar Adi, the "planning-with-files" skill is based on the core workflow pattern of Manus, the AI agent company Meta acquired for $2 billion in December 2025. This skill has the potential to transform the way AI agents approach complex tasks, making them more efficient, organized, and effective.

The Problem: Volatile Memory and Goal Drift

Most AI agents, including Claude Code, suffer from two major issues: volatile memory and goal drift. Volatile memory refers to the tendency of AI agents to forget important information as soon as the context is reset. Goal drift, on the other hand, occurs when the original goals of a task are forgotten after multiple tool calls. These issues lead to hidden errors, context stuffing, and a lack of accountability.

The Solution: The 3-File Pattern

To address these issues, the planning-with-files skill implements a simple yet effective pattern: the 3-file pattern. For every complex task, create three files:

1. task_plan.md: This file tracks the phases and progress of the task.
2. notes.md: This file stores research and findings related to the task.
3. [deliverable].md: This file contains the final output of the task.

The Loop: How it Works

The planning-with-files skill follows a straightforward loop:

1. Create a task plan in task_plan.md with the goal and phases.
2. Research and gather information, saving it in notes.md.
3. Update the task plan in task_plan.md based on the research.
4. Create the final output in [deliverable].md.

Key Insight: Re-reading the Plan

The key to this pattern is re-reading the task plan before making major decisions. This ensures that the original goals and context are kept in the attention window, preventing goal drift and hidden errors.

Installation and Usage

To install the planning-with-files skill, follow these steps:

1. Clone the repository or download the planning-with-files folder.
2. Place the folder in your Claude Code skills directory.
3. Verify the installation by starting a complex task and mentioning "planning", "organize", or "track progress".

Once installed, the skill will automatically create a task plan, update progress with checkboxes, and store findings in notes.md. It will also log errors for future reference and re-read the plan before major decisions.

Example

Suppose you want to research the benefits of TypeScript and write a summary. The planning-with-files skill will create a task plan with the goal and phases, update the plan based on research, and create the final output in a markdown file.

The Manus Principles

The planning-with-files skill implements the key context engineering principles pioneered by Manus:

1. Filesystem as memory: Store information in files, not context.
2. Attention manipulation: Re-read the plan before decisions.
3. Error persistence: Log failures in the plan file.
4. Goal tracking: Use checkboxes to show progress.
5. Append-only context: Never modify history.

File Structure

The planning-with-files repository is organized into the following files:

1. SKILL.md: Core instructions (what Claude reads).
2. reference.md: Manus principles deep dive.
3. examples.md: Real usage examples.
4. README.md: This file.

When to Use

Use the planning-with-files skill for:

1. Multi-step tasks (3+ steps).
2. Research tasks.
3. Building/creating projects.
4. Tasks spanning many tool calls.
5. Anything requiring organization.

Skip for

1. Simple questions.
2. Single-file edits.
3. Quick lookups.

Acknowledgments

The planning-with-files skill is built on the pioneering work of Manus AI and the Agent Skills framework provided by Anthropic. Contributions are welcome, and the skill is released under the MIT License.

Conclusion

The planning-with-files skill is a game-changer for AI agents, providing a simple yet effective way to approach complex tasks. By implementing the 3-file pattern and re-reading the plan before decisions, AI agents can prevent goal drift and hidden errors, making them more efficient, organized, and effective.

Source: https://github.com/OthmanAdi/planning-with-files