Planning-with-Files: Persistent Markdown Planning Skill for AI Coding Agents

Planning-with-Files is an innovative open-source project by OthmanAdi that implements a persistent markdown-based planning system for AI coding agents. Inspired by Manus’s planning approach, the project uses a structured 3-file system to maintain a living plan document that evolves as the AI agent works through tasks. It’s designed as both a Claude Code skill and a standalone integration via the Agents SDK.

The core insight behind Planning-with-Files is that AI coding agents – particularly those working on complex, multi-step tasks – benefit enormously from persistent, structured planning that survives across conversation turns and model context window limitations. By maintaining plans in markdown files that are read, updated, and written back as work progresses, the system enables AI agents to maintain coherent long-term strategies even when context windows are exhausted.

How does the 3-file system work?

The planning system maintains three distinct markdown files that work together to provide comprehensive task management. The plan file contains the high-level strategy and task breakdown. The progress file tracks what has been completed, what is in progress, and what remains. The scratchpad file provides space for intermediate reasoning, notes, and discoveries that don’t belong in the plan itself.

What is Manus-style planning?

Manus is an AI coding assistant known for its methodical, plan-first approach to complex tasks. Before starting implementation, Manus creates a detailed plan, validates it against requirements, and then executes step by step, updating the plan as new information emerges. Planning-with-Files brings this same methodology to any AI coding agent by encoding the planning discipline into persistent markdown files that the agent reads and updates.

flowchart LR
    A[User Request] --> B[Initialize Plan]
    B --> C[Create PLAN.md]
    C --> D[Create PROGRESS.md]
    D --> E[Create SCRATCHPAD.md]
    E --> F{Execute Task}
    F --> G[Update PROGRESS.md]
    G --> H[Update SCRATCHPAD.md]
    H --> I{Task Complete?}
    I -->|No| F
    I -->|Yes| J[Finalize PLAN.md]
    J --> K[Submit Result]

Installation and Setup

What problems does Planning-with-Files solve?

AI coding agents, even with large context windows, face several fundamental challenges. Context window overflow occurs when the conversation history exceeds the model’s capacity. Loss of task focus happens when agents drift from the original objective during long sessions. Difficulty tracking progress means agents may redo completed work or miss requirements. Lack of persistence means when a session ends, all planning context is lost. Planning-with-Files addresses all of these by externalizing the planning state into files that persist across sessions and survive context window resets.

sequenceDiagram
    participant Agent as AI Agent
    participant Plan as PLAN.md
    participant Progress as PROGRESS.md
    participant Scratch as SCRATCHPAD.md
    participant User as User

    User->>Agent: Complex task request
    Agent->>Plan: Create task breakdown
    Agent->>Progress: Initialize tracking
    loop Per Step
        Agent->>Plan: Read current plan
        Agent->>Progress: Update status
        Agent->>Scratch: Record observations
        Scratch-->>Agent: Recall context
        Agent->>User: Report progress
        User->>Agent: Feedback/review
        Agent->>Progress: Adjust plan
    end
    Agent->>User: Task complete with summary

What AI coding tools support this system?

The system is primarily designed for Claude Code, where it works as a skill that can be invoked with slash commands. It also supports Cursor IDE through cursorrules configuration. The plan files format is intentionally vendor-neutral – the same markdown files work with any AI coding assistant, and the system can be integrated into custom agent frameworks through the Agents SDK. The file format is plain markdown, so it can also be read and edited by humans.

What is the philosophy behind planning with files?

The philosophy is straightforward: AI agents should externalize their planning state in human-readable formats. By using markdown files rather than proprietary database formats or tool-specific storage, the plans become inspectable, editable, and shareable between humans and AI. This creates a transparent collaboration model where both parties can see the current state of work, understand what has been done, and agree on what comes next. It also enables interesting workflows like reviewing an agent’s plan before execution begins, or having multiple agents coordinate through shared plan files.

Frequently Asked Questions

What is Planning-with-Files? It is a persistent markdown planning system for AI coding agents that uses three files (PLAN.md, PROGRESS.md, SCRATCHPAD.md) to manage complex tasks.

How does the 3-file system work? PLAN.md holds the task breakdown and strategy, PROGRESS.md tracks real-time status of each task, and SCRATCHPAD.md stores working memory and intermediate reasoning.

How do I install it? Install as a Claude Code skill via claude add skill othmanadi/planning-with-files, or manually clone the repository and configure for your AI tool.

What AI tools are compatible? Designed for Claude Code, also works with Cursor IDE via cursorrules, and programmatically via the Agents SDK.

What problems does it solve? Context window overflow, loss of task focus, difficulty tracking progress, and lack of persistence across sessions for AI coding agents.

Further Reading

• Planning-with-Files GitHub Repository
• Claude Code Documentation
• Manus AI Official Site
• Agents SDK Documentation
• Cursor AI Official Site