plan — Manual

What it does

Runs the planner over the live session: it decomposes the goal into milestones and steps (each tagged with an executor — TOOL, AGENT or SELF) and populates the todo with those steps. It reads the conversation, memory, the todo and the scratchpad's findings/errors sections, so a re-plan sees what you have already learned.

It costs 2 LLM calls (complexity analysis + execution plan). Use it selectively, like reflect.

Requires an active agent run — outside one the call fails with plan is not available in this context.

Parameters

Parameter	Required	Description
`reason`	for re-planning	What changed — the discovery that makes the current plan stale, in one or two concrete sentences.
`updated_goal`	no	The new success criterion, only meaningful together with `reason`.

{}
{"reason": "the config is TOML, not JSON, so the parser step is wrong"}
{"reason": "the API needs pagination after all", "updated_goal": "sync all 12k records, not just the first page"}

When to call it

Call it before starting execution when the task is non-trivial:

multiple steps, or several files/systems involved;
research or an unknown codebase, where the shape of the work is itself unclear;
real risk — production, data loss, irreversible operations;
the work needs sub-agent scoping decided up front.

Skip it for trivial work: a single-file edit, a one-off command, a question, casual chat. Planning a one-liner wastes two LLM calls and produces a plan of one step.

Re-planning

Pass reason when the plan's overall structure is wrong — a step turned out unnecessary, the real problem differs from the assumed one, or new constraints appeared. The new plan replaces the todo; completed work survives in the conversation and the scratchpad.

Do not re-plan for a single failed step, or to drop/merge/reorder one or two steps — edit the todo directly with add/update. The choice between the two tools:

Situation	Tool
One step failed, or the order of a couple of steps changed	`todo`
You are unsure what is wrong; the approach needs questioning	`reflect`
The remaining plan's overall shape is wrong, or there is no plan	`plan`

What you get back

# Plan (fresh) or # Revised plan (with reason), followed by the milestones and steps, followed by an instruction that depends on the assessed complexity:

complex — present the plan to the user in a few sentences and wait for confirmation before executing. Do not start yet.
not complex — the todo has been populated; proceed from step 1, tracking progress with todo.

When planning produces no plan at all, the call fails rather than inventing one: proceed directly (fresh) or keep the current plan and revise the todo inline (re-plan). Neither is an error to retry.

Rules

One plan per task. Calling it again mid-task without reason throws away the current plan and its progress.
After a re-plan the todo reflects the new plan — the old steps are gone; do not update an index that no longer means what it did.
The plan is not a substitute for doing the work: nothing in it is executed by calling it.