How Planning-with-Files Reinvents AI Agent Context Engineering

Six Core Principles of Manus Context Engineering

Manus, an AI‑agent platform acquired by Meta, defines a workflow that treats the file system as the primary source of truth for long‑running tasks. The six principles are:

1. Files as the Single Source of Truth

Instead of relying on a linear chat history, the agent reads curated Markdown files that represent the latest state of a task. Each operation begins by loading the relevant file, guaranteeing decisions are based on up‑to‑date information.

2. Explicit State Representation

Progress is externalized in To‑Do style files. Completed items are marked with [x], pending items with []. Because the state lives on disk, the agent can be stopped, the machine rebooted, and later resume exactly where it left off by re‑reading the files.

3. Minimalist Context Window

The agent never feeds the entire repository into the model at once. Information is split into dedicated files such as notes.md, plan.md, and output.md. For each step the model loads only the fragment it needs, reducing token consumption and keeping attention focused.

4. Separate Thinking from Acting

All research, design sketches, and intermediate code snippets are first written to notes.md. Only after the plan is verified does the agent modify the target code or output files, preventing accidental pollution of the final artifact.

5. KV‑Cache‑Friendly Design

Agent tasks typically involve long inputs and short outputs. To maximise cache‑hit rates the workflow enforces three rules:

Keep the system‑prompt prefix stable; never inject dynamic content into the prompt.

Append new interaction records; never edit or delete earlier entries.

Serialize JSON objects with keys sorted alphabetically so identical states produce identical strings.

These practices lower latency and token cost.

6. Masking Instead of Removing Tools

When the tool library expands, unused tool descriptions remain in the prompt but are masked at decoding time. By zero‑ing the logits for illegal tool calls the KV‑Cache stays intact and the model is not confused by stale tool entries.

Project Overview: planning‑with‑files

planning‑with‑files is a Claude Code plugin that open‑sources the Manus workflow. By persisting task plans, progress, and knowledge in Markdown files, it solves two common agent problems: context loss after long conversations and goal drift.

The repository is MIT‑licensed, compatible with Claude Code v2.1, and has reached version 2.1.1, which adds Cursor support and beginner‑friendly examples.

Three Core File Mechanisms

After installation Claude automatically maintains three files that drive the workflow:

task_plan.md : records objectives, step breakdowns, completion status (using [x] / []), and the next action. The agent reads this file before every operation to stay on track.

notes.md : a sandbox for research, code snippets, and interim ideas. It keeps the chat window clean while providing a solid thinking base.

[deliverable].md : stores the final output—code, article, or report—without any extraneous reasoning artifacts.

This "three‑file model" treats the context window like volatile RAM and the file system like persistent disk, ensuring long‑term memory of important information.

Installation and Usage

The plugin is installed with two Claude Code commands:

/plugin marketplace add OthmanAdi/planning-with-files

/plugin install planning-with-files@planning-with-files

Once installed, invoking a phrase such as “plan task” causes Claude to automatically create task_plan.md and launch the Manus‑style workflow. No manual file handling is required.

Why the Project Resonated with the Agent Community

Precise pain‑point resolution : directly addresses “forgetting after long chats” and chaotic reasoning in large models.

Replication of top‑tier practice : open‑sources the core logic of the Meta‑acquired Manus system, giving small teams access to industry‑leading techniques.

Lightweight and easy to adopt : as a Claude Code plugin it integrates with existing workflows without heavy setup.

Efficiency vs. cost balance : KV‑Cache optimisations and minimalist context design boost productivity while reducing token usage.

For AI‑agent developers, planning‑with‑files serves both as a practical tool and a living case study of context engineering, offering concrete patterns that can be applied to any agent‑centric project.

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

Original Manus reference: https://manus.im/zh-cn/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus