plan from

Syntax

plan from "docs/plan.md"

What it does

By default the loop's plan step has the agent write the plan. plan from "<file>" overrides that: the loop reads its plan from the quoted file (a hand-written .md, say) so it executes a plan you control instead of one the agent invents. Omit it and the agent writes the plan as usual. The path is relative to the .loop file. The source is extensible — a URL or command could be added later — but the file form is the one that exists today.

Reach for it when the sequence of work matters and you don't want the agent to reinvent it every cycle. Common cases: a plan you wrote by hand and reviewed, a plan produced by an earlier planning loop, or a spec generated by a method (BMAD, a design doc) that you want executed verbatim. Because the plan lives in a file, it is version-controlled, diffable, and editable between runs — you tweak one step and re-run instead of re-prompting. It pairs naturally with plan, then act, then observe: the plan step still runs, but it loads your document rather than composing a fresh one, which keeps every cycle anchored to the same intent. This is the difference between directing the loop and merely launching it — a boundary-tier capability line that narrows the agent's freedom to the ordering you already decided on, while leaving act and the done when check to do the real, verifiable work.

Example

loop "execute the billing plan":
  goal: implement the plan in docs/plan.md
  plan from "docs/plan.md"
  each cycle: plan, then act, then observe
  done when "pnpm test" passes

Common mistakes

• Pointing at a stale plan. The loop executes what the file says today, not what you meant last week. If the codebase moved on, the plan silently drives the agent at the wrong targets. Re-read the file before a run and edit it in place — that is the whole point of keeping the plan in version control.
• Assuming it replaces done when. plan from only sets how the plan is chosen; it does not verify anything. You still need a real done when predicate — a controlled plan with no check is a loop that can run forever without ever proving it succeeded.
• Wrong relative path. The quoted path resolves relative to the .loop file, not your shell's working directory. A file that exists but sits one folder over will fail to load; keep the plan next to the loop or write the correct relative path.
• Over-specifying. A plan so detailed it dictates every edit leaves no room for reflect to adapt after a failure. Describe the ordered intent, not the exact keystrokes — let the cycle recover.

Related