goal

Syntax

goal: <text>

What it does

The objective, stated plainly — one line of natural language that names the outcome the loop is chasing. It is required in every loop: a loop without a goal does not parse, and each stage of a pipeline carries its own. The goal frames the work — it is what the planner reads first and what every cycle steers toward — but it does not decide success. That job belongs to done when, the machine-checkable predicate underneath it.

Reach for a sharp goal because it is the loop's compass, not its finish line. Write it as an outcome ("settings save when the name has an apostrophe"), not a task list ("edit the form and the API"), so the agent is free to find the smallest correct change instead of following your guessed steps. The authoring order puts goal first and done when immediately under it for a reason: if you cannot phrase a check for the goal, the goal is not yet understood — that is the signal to sharpen it before writing another line. A goal broad enough to need three tests is really three stages; a goal you cannot verify at all is a prompt, not a loop.

Example

goal: settings save when the company name has an apostrophe

Paired with its check

loop "fix billing apostrophe bug":
  goal: settings save when the company name has an apostrophe
  done when the test "billing.spec.ts::apostrophe" passes

Common mistakes

• Writing a task, not an outcome. "Refactor the settings form" tells the agent what to touch, not what "done" looks like — it will thrash. State the result you want and let the loop find the change.
• A goal you can't check. If no done when predicate can express the goal, it is too vague or too big. Sharpen it, or split it into stages that each have a check — a goal without a verifiable check is a normal prompt, not a loop.
• Cramming an epic into one goal line. A goal that needs several unrelated tests to confirm is really a pipeline of stages. Keep one goal to one checkable outcome.
• Leaning on the goal to gate risk. The goal frames intent; it does not stop the agent from doing something dangerous. Put risky work behind ask me before … or a human gate, not in prose the planner may reinterpret.

Related