Guiding the agent

Most flow steps should use deterministic RFL or Playwright TypeScript. A model participates only for an empty agent-driven step, recovery from a failed scripted step when self-heal is enabled, a semantic invariant, or end-of-run validation. With a provider key, that final validation runs when frontmatter sets validate: true, the agent participated, or any invariant is declared.

1. Name each executable step precisely

The step="…" attribute is the goal for an empty agent-driven step and for recovery from a failed scripted step. State one observable action or outcome:

```ts step="complete checkout with the standard test card"
click role=button name="Pay now"
expect page url~="/confirmation"
```

```ts step="the confirmation shows an order number and the correct total"
```

The second body is intentionally empty, so the agent drives the page toward the named outcome. If it succeeds, its RFL lines are attached to the run as a proposed content rewrite.

2. Use flow prose for the end goal

Markdown outside the named fences is retained as flow prose. When semantic end-of-run validation runs, this prose is its goal:

A signed-in user buys one item and reaches a valid order confirmation.
Discount codes are out of scope for this flow.

Pure scripted flows do not make a validation model call by default. Validation runs when frontmatter sets validate: true, the agent participated, or any invariant is declared; set validate: false to suppress it.

3. Put end-of-run checks in invariants

invariants is a frontmatter list checked after the executable steps pass. An RFL assertion is deterministic; other text is evaluated semantically when a provider key is available:

invariants:
  - 'expect role=status name="cart count" text="1"'
  - the page has no broken or overlapping controls

Use invariants for end-state contracts. They are not continuously evaluated between every action.

4. Load the built-in authoring guidance

The MCP get_context tool contains the shipped flow-format, suite-building, RFL, email, and harness guides. Call it with no arguments to list documents, then load only the guide needed for the current task. These server-provided guides replace the earlier unimplemented .reflow/context pack concept.

What takes precedence

During a step, the named step intent is the agent’s goal and the current page state grounds its actions. At the end of a run, deterministic invariants are checked first and the flow prose supplies the semantic validation goal.

Use the playground to record and replay deterministic lines against a live page. When an eligible selector fails during a run, the narrower autoheal contract controls whether Reflow can propose a replacement.