How to Configure Browser Verification for Frontend UI Stories with the dev-browser Skill

To configure browser verification for frontend UI stories in Ralph, append the literal acceptance criterion "Verify in browser using dev-browser skill" to the story's acceptance criteria list, which triggers the agent to automatically load the dev-browser skill and validate the UI in a headless Chromium instance.

The Ralph autonomous agent enforces a strict quality gate for any user story that modifies frontend code. According to the snarktank/ralph source code, a frontend UI story cannot be marked as complete until the visual changes are verified in a real browser using the dev-browser skill. This verification workflow is defined across three critical files: skills/ralph/SKILL.md, prompt.md, and README.md.

Why Browser Verification is Mandatory

Ralph treats frontend UI stories as incomplete by default to prevent false positives where code compiles but renders incorrectly. The dev-browser skill runs a headless Chromium instance that navigates to the relevant page, exercises the UI interactions defined by the story, and confirms the acceptance criterion is satisfied. This ensures deterministic CI outcomes and eliminates the need for external test harnesses.

Step-by-Step Configuration

Declare the Mandatory Acceptance Criterion

Every frontend UI story must declare a specific acceptance criterion that instructs the agent to perform browser verification. In skills/ralph/SKILL.md (line 1012), the Ralph PRD Converter automatically injects this entry when it detects a UI-related story.

The criterion must appear as the last item in the acceptanceCriteria array and use the exact literal string:

{
  "id": "US-002",
  "title": "Display status badge on task cards",
  "description": "As a user, I want to see task status at a glance.",
  "acceptanceCriteria": [
    "Each task card shows a colored status badge",
    "Badge colors: gray=pending, blue=in_progress, green=done",
    "Typecheck passes",
    "Verify in browser using dev-browser skill"
  ],
  "priority": 2,
  "passes": false,
  "notes": ""
}

The presence of this string in prd.json makes the verification step discoverable by tooling and mandatory for the agent.

Configure the Agent Prompt

The agent's behavior is guided by the global prompt defined in prompt.md (line 83). This file contains a dedicated "Browser Testing (Required for Frontend Stories)" block that instructs the agent to load the skill before finishing any frontend story.

The prompt specifies four sequential steps:

1. Load the dev-browser skill
2. Navigate to the relevant page
3. Verify the UI changes work as expected
4. Take a screenshot if helpful for the progress log

## Browser Testing (Required for Frontend Stories)

1. Load the `dev-browser` skill
2. Navigate to the relevant page
3. Verify the UI changes work as expected
4. Take a screenshot if helpful for the progress log

Runtime Execution Flow

When the agent processes a story where the passes flag remains false, it executes the verification workflow described in README.md (line 203):

• The agent loop invokes the dev-browser skill
• A headless Chromium instance launches and visits the target URL
• The skill executes the interaction script defined by the story requirements
• Upon successful verification, the skill returns a success signal and the agent flips the passes flag to true

If verification fails, the flag remains false and the agent logs the failure for the next iteration.

Implementation Examples

PRD JSON Structure

The following example from prd.json.example demonstrates the complete structure for a UI story requiring browser verification:

{
  "id": "US-002",
  "title": "Display status badge on task cards",
  "description": "As a user, I want to see task status at a glance.",
  "acceptanceCriteria": [
    "Each task card shows a colored status badge",
    "Badge colors: gray=pending, blue=in_progress, green=done",
    "Typecheck passes",
    "Verify in browser using dev-browser skill"
  ],
  "priority": 2,
  "passes": false,
  "notes": ""
}

Progress Log Output

After successful execution, progress.txt records the verification step:

## 2026-04-13 14:20 – US-002

Thread: https://ampcode.com/threads/xyz123
- Added badge component to TaskCard.tsx
- Updated CSS for badge colors
- Loaded dev-browser skill → navigation to /tasks succeeded
- Badge displayed correctly, screenshot captured
- passes: true

Key Configuration Files

File	Role	Key Location
skills/ralph/SKILL.md	Defines PRD-to-JSON conversion rules and the mandatory acceptance criterion string	Line 1012
prompt.md	Global agent prompt containing the "Browser Testing (Required for Frontend Stories)" execution block	Line 83
README.md	Human-readable specification of the browser verification workflow	Line 203
prd.json.example	Reference implementation showing proper acceptance criteria structure	Example UI stories

Summary

• Mandatory criterion: Every frontend UI story must include the literal string Verify in browser using dev-browser skill as the final acceptance criterion.
• Automatic execution: The agent reads the global prompt.md configuration and automatically loads the dev-browser skill when this criterion is present.
• Headless validation: The skill runs a headless Chromium browser to perform visual verification before the story's passes flag can be set to true.
• Self-contained workflow: All verification logic resides within the Ralph repository; no external testing frameworks are required.
• Traceability: The verification requirement is encoded directly in prd.json, making it parsable by CI/CD tooling.

Frequently Asked Questions

What is the exact acceptance criterion string required for browser verification?

The string must be exactly: "Verify in browser using dev-browser skill". This literal text is detected by the Ralph PRD Converter in skills/ralph/SKILL.md and triggers the agent to load the dev-browser skill during execution. Any variation in capitalization or wording will not activate the verification workflow.

Can I use the dev-browser skill for backend-only stories?

No. The dev-browser skill is specifically designed for frontend UI stories that require visual verification in a browser. Backend stories that only modify API endpoints or database schemas should not include this acceptance criterion, as the skill attempts to navigate to pages and interact with DOM elements that would not exist in non-UI contexts.

Where does Ralph define the browser verification logic?

The verification workflow is defined across three files: the conversion rules reside in skills/ralph/SKILL.md (line 1012), the agent execution instructions are in prompt.md (line 83) under the "Browser Testing (Required for Frontend Stories)" section, and the high-level behavior specification is documented in README.md (line 203).

What happens if the browser verification fails?

If the dev-browser skill detects that the UI does not behave as expected—such as missing elements, incorrect styling, or failed interactions—it returns a failure signal to the agent loop. The story's passes flag remains false, preventing the story from being marked complete, and the failure details are logged in progress.txt for the next iteration cycle.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}