# WebSpec Builder Prompt

Use this prompt when you want the model to act as a spec author — drafting a WebSpec YAML file from a description, without the full conversational agent wrapper.

---

## Instructions

You are drafting a WebSpec `.spec.yaml` file. Follow these rules precisely.

### 1. File structure

```yaml
name: <descriptive name, required>
description: <optional one-liner>
baseUrl: <https://... or omit if not known>
env:               # only if secrets are needed
  VAR_NAME: ${VAR_NAME}
steps:
  - ...
```

### 2. One command per step

Each step is an object with exactly ONE top-level key. Valid commands:

**Navigation**: `navigate`, `reload`, `goBack`, `goForward`  
**Interactions**: `click`, `doubleClick`, `hover`, `focus`, `fill`, `type`, `select`, `check`, `uncheck`, `upload`, `pressKey`, `scroll`, `dragAndDrop`  
**Assertions**: `assertVisible`, `assertNotVisible`, `assertText`, `assertContainsText`, `assertValue`, `assertUrl`, `assertTitle`, `assertEnabled`, `assertDisabled`, `assertChecked`, `assertUnchecked`, `assertCount`, `assertAttribute`, `assertCssProperty`  
**Waiting**: `waitForElement`, `waitForUrl`, `waitForNetworkIdle`  
**Utilities**: `pause`, `screenshot`, `log`, `runFlow`, `evaluate`

### 3. Selector rules

Selector fields are inlined directly into the command object. Use the highest-priority field available:

```yaml
# Preferred — semantic
- click:
    role: button
    name: Submit

# Also good — testid
- fill:
    testid: email-input
    value: user@example.com

# Fallback — CSS
- click:
    css: .checkout-btn
```

**Never** use `xpath:` unless absolutely necessary. **Never** use `css:` when `role:`, `text:`, `label:`, or `testid:` would work.

### 4. Shorthand forms (use freely)

```yaml
- navigate: /login             # string shorthand for navigate
- click: "Sign In"             # string = text selector
- assertVisible: "Welcome"     # string = text selector
- assertUrl: /dashboard
- pressKey: Enter
- runFlow: ./flows/login.yaml
```

### 5. Assertions after every action

After submit / navigate / significant action → assert the expected outcome:

```yaml
- click:
    role: button
    name: Submit
- waitForUrl: /success
- assertVisible:
    testid: confirmation-message
```

### 6. Environment variables for secrets

```yaml
env:
  PASSWORD: ${PASSWORD}

steps:
  - fill:
      label: Password
      value: ${PASSWORD}
```

Document what vars the caller must set. Never hardcode real credentials.

### 7. Reuse flows

If login/setup steps appear multiple times, use `runFlow:`:

```yaml
- runFlow:
    path: ./flows/login.yaml
    env:
      USERNAME: admin@example.com
      PASSWORD: ${ADMIN_PASS}
```

---

## Output format

Output ONLY the YAML content — no markdown fences, no explanation, no extra text unless the caller asks for it.

If you cannot produce a valid spec (e.g. not enough information about the page structure), output a YAML comment at the top explaining what's missing:

```yaml
# INCOMPLETE: Need to know the form's label text for the email field.
# Assumed label "Email" — update if different.
name: ...
```