Agent behavior

The system prompt is assembled at run start from the project's files: the device profile's prompt, tests/ui.md, utils/format.md, and each folder's rules.md and ui.md. It applies to every test in the project. When tests fail consistently, this is often the fix, which file holds what: What goes where.

Error discipline: built in

The agent's identity and its always-on rules are built into the app, they are not a file you edit. The core is the error discipline:

## Error Handling
- You have a maximum of **2 attempts per step**. If a step does not
  succeed after 2 attempts, stop immediately. Do not try a third time.
- Never try creative or alternative ways to accomplish a step that
  didn't work as written.

• Two attempts, then FAILED: no third try, no workarounds, no navigating back to retry. A green run means the steps actually passed, not that the agent improvised its way to "done".
• Infrastructure errors are different: connection lost, session expired, RPC error → status BROKEN, a diagnosis hint in the report, and exception_tool aborts the whole run (nothing can pass on broken infrastructure). The triage this enables: Analyzing failures.

When a suite genuinely needs different behaviour, write a rule: rules land at the end of the system prompt and take precedence over the built-in instructions.

Device prompt: only what the agent can't see

Each device profile carries a Prompt field (Devices page → Edit) with quirks of this machine that the screen doesn't show. The agent sees the screen, OS and display basics rarely need describing.

* Always execute on display 1 — display 2 shows the corporate dashboard.
* The corporate lock screen appears after 5 minutes of inactivity.

The text lives with the profile in devices.json, so retargeting a project at a different machine means picking a different profile, no file editing.

UI information: your biggest lever

tests/ui.md is where the agent learns your application. The agent has no built-in knowledge of your app, everything it must recognise has to be written down. This is the file you invest the most in, and the first place to look when the agent wanders.

You are operating: Contoso Orders — order entry for the sales back office.

## Navigation
The application has these primary areas:
- Dashboard — overview & KPIs
- Records — data entry & search
- Settings — account & configuration

## State indicators
Login state is shown top-right: a green dot means signed in, red means
the session expired — sign in again.

## Dialogs & quirks
Destructive actions open a centered confirmation dialog that must be
confirmed or dismissed before continuing. The confirmation pop-up stays
open until you click OK — clicking elsewhere does not close it.

What belongs here:

• Navigation: the primary areas and where key actions live.
• State indicators: what "signed in", "loading", "error" look like, so the agent reads the screen correctly.
• Non-standard interactions: anything that would surprise a first-time user: drag-and-drop patterns, lazy loading, single-page navigation.
• Naming conventions: what areas and views are called, so tests can reference them by name.
• What not to do: destructive actions that are easy to trigger.

A suite that exercises a different part of the system can add its own ui.md in its folder, it accumulates after the top-level file, closest to the test last.

Report format: the report contract

utils/format.md defines the report the agent writes: the Markdown structure and the status vocabulary (PASSED, FAILED, SKIPPED, WARN, BROKEN). Edit it under Extending → Report Format. Keep the standard vocabulary, the runner parses the report's **Status:** line, and the Runs and Dashboard pages count results from it. Tailor the sections if your organisation needs different evidence; the shape is explained in Run report.

Rules: targeted patches that win

A rules.md next to your tests patches the prompt, tests/rules.md for the whole project, a folder's rules.md for that suite only. Rules are appended at the very end of the system prompt behind an explicit note that they take precedence, so this is the place to correct built-in behaviour. A good rule reads like a bug fix:

• How the agent identifies the situation: what it sees on screen.
• What to do: the exact sequence.
• What not to do: rule out the wrong approach explicitly.

## Interaction
- Never use keyboard shortcuts — operate the application through its
  menus, like our users do.

## Recoveries
- If the scanner stops responding, run the restart_scanner tool and
  repeat the step. Do not mark the step FAILED on the first scanner
  timeout.

Style principles

• Plain Markdown, one concern per ## section: that's what the scaffold ships and what keeps the files auditable.
• One language: clear English throughout the prompt, tests, and all inputs. Mixed languages degrade performance.
• No contradictions: two rules that conflict produce undefined behaviour, and a rule that contradicts ui.md makes the agent guess. Review across files.
• Overly specific is right: if you feel you are being too detailed, you are doing it right. Only you know your UI.

After a prompt change, run the affected folder and read the run report, the Agent Interpretation per step shows whether the new wording landed the way you meant it. The run's conversation log also records the exact system prompt per phase, expand the System prompt section under the act header to see precisely what the agent got.