devlyn-cli 1.2.1 → 1.3.0

package/bin/devlyn.js

@@ -154,6 +154,7 @@ const OPTIONAL_ADDONS = [
   { name: 'Leonxlnx/taste-skill', desc: 'Premium frontend design skills — modern layouts, animations, and visual refinement', type: 'external' },
   // MCP servers (installed via claude mcp add)
   { name: 'codex-cli', desc: 'Codex MCP server for cross-model evaluation via OpenAI Codex', type: 'mcp', command: 'npx -y codex-mcp-server' },
+  { name: 'playwright', desc: 'Playwright MCP for browser testing — powers devlyn:browser-validate Tier 2', type: 'mcp', command: 'npx -y @anthropic-ai/mcp-playwright' },
 ];
 
 function log(msg, color = 'reset') {
@@ -544,8 +545,10 @@ async function init(skipPrompts = false) {
   const pipelinePermissions = [
     'Write(.claude/done-criteria.md)',
     'Write(.claude/EVAL-FINDINGS.md)',
+    'Write(.claude/BROWSER-RESULTS.md)',
     'Edit(.claude/done-criteria.md)',
     'Edit(.claude/EVAL-FINDINGS.md)',
+    'Edit(.claude/BROWSER-RESULTS.md)',
     'Bash(git add *)',
     'Bash(git commit *)',
     'Bash(git diff *)',

package/config/skills/devlyn:auto-resolve/SKILL.md

@@ -19,6 +19,7 @@ $ARGUMENTS
    - `--skip-review` (false) — skip team-review phase
    - `--security-review` (auto) — run dedicated security audit. Auto-detects: runs when changes touch auth, secrets, user data, API endpoints, env/config, or crypto. Force with `--security-review always` or skip with `--security-review skip`
    - `--skip-clean` (false) — skip clean phase
+   - `--skip-browser` (false) — skip browser validation phase (auto-skipped for non-web changes)
    - `--skip-docs` (false) — skip update-docs phase
    - `--with-codex` (false) — use OpenAI Codex as a cross-model evaluator/reviewer via `mcp__codex-cli__*` MCP tools. Accepts: `evaluate`, `review`, or `both` (default when flag is present without value). When enabled, Codex provides an independent second opinion from a different model family, creating a GAN-like dynamic where Claude builds and Codex critiques.
 
@@ -32,7 +33,7 @@ $ARGUMENTS
 ```
 Auto-resolve pipeline starting
 Task: [extracted task description]
-Phases: Build → Evaluate → [Fix loop if needed] → Simplify → [Review] → [Security] → [Clean] → [Docs]
+Phases: Build → [Browser] → Evaluate → [Fix loop if needed] → Simplify → [Review] → [Security] → [Clean] → [Docs]
 Max evaluation rounds: [N]
 Cross-model evaluation (Codex): [evaluate / review / both / disabled]
 ```
@@ -75,6 +76,24 @@ The task is: [paste the task description here]
 3. If no changes were made, report failure and stop
 4. **Checkpoint**: Run `git add -A && git commit -m "chore(pipeline): phase 1 — build complete"` to create a rollback point
 
+## PHASE 1.5: BROWSER VALIDATE (conditional)
+
+Skip if `--skip-browser` was set.
+
+1. **Check relevance**: Run `git diff --name-only` and check for web-relevant files (`*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.css`, `*.html`, `page.*`, `layout.*`, `route.*`). If none found, skip and note "Browser validation skipped — no web changes detected."
+
+2. **Run validation**: Spawn a subagent using the Agent tool with `mode: "bypassPermissions"`.
+
+Agent prompt — pass this to the Agent tool:
+
+You are a browser validation agent. Read the skill instructions at `.claude/skills/devlyn:browser-validate/SKILL.md` and follow the full workflow to validate this web application. The dev server should be started, tested, and left running (pass `--keep-server` internally) — the pipeline will clean it up later. Write your findings to `.claude/BROWSER-RESULTS.md`.
+
+**After the agent completes**:
+1. Read `.claude/BROWSER-RESULTS.md`
+2. Extract the verdict
+3. If `BLOCKED` → the app doesn't even render. Go directly to PHASE 2.5 fix loop with browser findings as context.
+4. Otherwise → continue to PHASE 2 (the evaluator will read `BROWSER-RESULTS.md` as additional evidence)
+
 ## PHASE 2: EVALUATE
 
 Spawn a subagent using the Agent tool with `mode: "bypassPermissions"` to evaluate the work. Include all evaluation instructions inline.
@@ -250,6 +269,9 @@ After all phases complete:
 1. Clean up temporary files:
    - Delete `.claude/done-criteria.md`
    - Delete `.claude/EVAL-FINDINGS.md`
+   - Delete `.claude/BROWSER-RESULTS.md` (if exists)
+   - Delete `.claude/screenshots/` directory (if exists)
+   - Kill any dev server process still running from browser validation
 
 2. Run `git log --oneline -10` to show commits made during the pipeline
 
@@ -264,6 +286,7 @@ After all phases complete:
 | Phase | Status | Notes |
 |-------|--------|-------|
 | Build (team-resolve) | [completed] | [brief summary] |
+| Browser validate | [completed / skipped / auto-skipped] | [verdict, tier used, console errors, flow results] |
 | Evaluate (Claude) | [PASS/NEEDS WORK after N rounds] | [verdict + key findings] |
 | Evaluate (Codex) | [completed / skipped] | [Codex-only findings count, merged verdict] |
 | Fix rounds | [N rounds / skipped] | [what was fixed] |

package/config/skills/devlyn:browser-validate/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: devlyn:browser-validate
+description: Browser-based validation for web applications — smoke tests, user flow testing, visual checks, and runtime error detection. Starts the dev server, navigates the app, and reports what's broken with screenshot evidence. Use this skill whenever the user says "test in browser", "check if it works", "smoke test", "browser test", "validate the UI", "does the app run", or when auto-resolve needs to verify web changes actually render and function correctly. Also use proactively after implementing UI changes to catch runtime errors that static analysis misses.
+---
+
+Browser validation for web applications. Starts a dev server, tests in a real browser (or falls back to Playwright/curl), and reports findings with evidence. Designed to catch the bugs that pass every static check but break when a user actually clicks something — runtime errors, failed API calls, blank pages, broken interactions.
+
+<config>
+$ARGUMENTS
+</config>
+
+<workflow>
+
+## PHASE 1: DETECT
+
+1. **Framework detection**: Read `package.json` → identify framework from dependencies (`next`, `vite`, `react-scripts`, `nuxt`, `astro`, `svelte`, `remix`, `angular`). Find the start command from `scripts.dev`, `scripts.start`, or `scripts.preview`.
+
+2. **Port inference**: Check framework config files for custom ports. Defaults — Next.js: 3000, Vite: 5173, CRA: 3000, Nuxt: 3000, Astro: 4321, Angular: 4200. Override with `--port` flag if provided.
+
+3. **Affected routes**: Run `git diff --name-only` and map changed files to routes (e.g., `app/dashboard/page.tsx` → `/dashboard`, `src/pages/about.vue` → `/about`). These are the pages that need testing.
+
+4. **Tier selection** — pick the best available browser tool:
+   - Check if `mcp__claude-in-chrome__*` tools exist in available tools → **Tier 1** (Chrome DevTools). Read `references/tier1-chrome.md`.
+   - Else check if `mcp__playwright__*` tools exist (Playwright MCP installed via `npx devlyn-cli`) OR run `npx playwright --version 2>/dev/null` → **Tier 2** (Playwright). Read `references/tier2-playwright.md`.
+   - Else → **Tier 3** (HTTP smoke). Read `references/tier3-curl.md`.
+
+5. **Skip gate**: If no web-relevant files changed (no `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.astro`, `*.css`, `*.scss`, `*.html`, `page.*`, `layout.*`, `route.*`, `+page.*`, `+layout.*`), skip the entire phase. Report: "Browser validation skipped — no web changes detected."
+
+6. **Parse flags** from `<config>`:
+   - `--skip-flow` — skip flow testing, only run smoke + visual
+   - `--port PORT` — override detected port
+   - `--tier N` — force a specific tier (1, 2, or 3)
+   - `--mobile-only` — only test mobile viewport
+   - `--desktop-only` — only test desktop viewport
+
+Announce:
+```
+Browser validation starting
+Framework: [detected] | Port: [PORT] | Tier: [N — name]
+Affected routes: [list]
+Phases: Smoke → [Flow] → Visual → Report
+```
+
+## PHASE 2: SERVER
+
+1. Start the dev server in background: run the detected start command via Bash with `run_in_background: true`.
+2. Health-check loop: poll `http://localhost:PORT` every 2 seconds using `curl -s -o /dev/null -w "%{http_code}"`. Timeout after 20 seconds.
+3. If the server fails to start, capture stderr output and report as BLOCKED:
+   ```
+   Verdict: BLOCKED
+   Reason: Dev server failed to start within 20s
+   Error: [stderr output]
+   ```
+   Write this to `.claude/BROWSER-RESULTS.md` and stop.
+4. Record the server PID for cleanup.
+
+## PHASE 3: SMOKE
+
+Test that the app renders and the runtime is clean. Follow the tier-specific reference file for exact tool calls.
+
+For each affected route (and always `/` as the first):
+1. Navigate to the page
+2. Verify the page has meaningful content (not a blank page, not a raw error)
+3. Capture console messages — filter for errors (ignore React dev-mode warnings, HMR noise, favicon 404s)
+4. Capture network requests — flag any 4xx/5xx responses or CORS failures (ignore HMR websocket, source maps)
+5. Take a screenshot as evidence
+
+A route **fails smoke** if: the page is blank, shows an unhandled error, has console errors (excluding known dev noise), or has failed network requests to the app's own API.
+
+## PHASE 4: FLOW (conditional)
+
+Skip if `--skip-flow` is set or if `.claude/done-criteria.md` doesn't exist.
+
+Read `references/flow-testing.md` for how to convert done-criteria into browser test steps. Then execute each test step using the tier-specific tools.
+
+For each flow test:
+1. Execute the action sequence (navigate → find → interact → verify)
+2. After each interaction, check console + network for new errors
+3. Screenshot at each verification point
+4. Record pass/fail with evidence
+
+## PHASE 5: VISUAL
+
+Test layout integrity at two viewports (skip one if `--mobile-only` or `--desktop-only` is set):
+
+1. **Mobile** (375x812): resize → navigate to each affected route → screenshot → check for overflow, overlapping elements, unreadable text
+2. **Desktop** (1280x800): resize → navigate to each affected route → screenshot → check for broken layouts, missing sections
+
+This is judgment-based — the agent looks at screenshots and reports visible issues. Not pixel-diff.
+
+## PHASE 6: REPORT
+
+Write `.claude/BROWSER-RESULTS.md`:
+
+```markdown
+# Browser Validation Results
+
+## Verdict: [PASS / PASS WITH ISSUES / NEEDS WORK / BLOCKED]
+Verdict rules: BLOCKED = app won't start or root page crashes. NEEDS WORK = flow tests fail or console errors on affected routes. PASS WITH ISSUES = visual issues or minor warnings. PASS = clean across all checks.
+
+## Environment
+- Framework: [detected]
+- Dev server: [command] on port [PORT]
+- Browser tier: [1/2/3 — name]
+- Startup time: [N]s
+
+## Smoke Test
+| Route | Renders | Console Errors | Network Failures | Screenshot |
+|-------|---------|---------------|-----------------|------------|
+| / | YES/NO | [count]: [details] | [count]: [details] | [path] |
+
+## Flow Tests
+| Criterion | Steps | Result | Evidence |
+|-----------|-------|--------|----------|
+| [text] | [N] | PASS/FAIL | [screenshot, errors] |
+
+## Visual Check
+| Viewport | Route | Issues |
+|----------|-------|--------|
+| Mobile (375px) | / | [issues or "Clean"] |
+| Desktop (1280px) | / | [issues or "Clean"] |
+
+## Runtime Errors (full log)
+[all unique console errors, deduplicated]
+
+## Failed Network Requests
+[all failed requests with URL, status, and context]
+```
+
+## PHASE 7: CLEANUP
+
+Kill the dev server process using the stored PID. If running inside auto-resolve pipeline and the `--keep-server` flag was passed (set by the pipeline orchestrator), skip cleanup — the pipeline will handle it.
+
+</workflow>

package/config/skills/devlyn:browser-validate/references/flow-testing.md

@@ -0,0 +1,118 @@
+# Flow Testing: Done-Criteria to Browser Steps
+
+How to read `.claude/done-criteria.md` and convert testable criteria into browser action sequences. This is the bridge between "what should work" and "prove it works in the browser."
+
+Read this file only during PHASE 4 (FLOW) when done-criteria exists.
+
+---
+
+## Step 1: Classify Each Criterion
+
+Read `.claude/done-criteria.md` and classify each criterion:
+
+**Browser-testable** — the criterion describes something a user can see or do in the UI:
+- "User can create a new project from the dashboard"
+- "Error message appears when form is submitted with empty fields"
+- "Navigation shows active state on current page"
+- "Data table loads and displays 10 rows"
+
+**Not browser-testable** — the criterion is about backend logic, data integrity, or code quality:
+- "API returns 401 for unauthenticated requests"
+- "Database migration runs without errors"
+- "Test coverage exceeds 80%"
+- "No TypeScript errors"
+
+Skip non-browser-testable criteria. Note them as "Skipped — not browser-testable" in the report.
+
+## Step 2: Convert to Action Sequences
+
+For each browser-testable criterion, generate a sequence of steps:
+
+### Pattern: Navigation + Verification
+```
+Criterion: "Dashboard shows project count"
+Steps:
+  1. Navigate to /dashboard
+  2. Find element containing project count (look for text matching a number pattern)
+  3. Verify: element exists and contains a numeric value
+  4. Screenshot
+```
+
+### Pattern: Form Interaction
+```
+Criterion: "User can create a new project"
+Steps:
+  1. Navigate to /dashboard (or wherever the create action lives)
+  2. Find "Create" or "New Project" button
+  3. Click it
+  4. Find form fields (name, description, etc.)
+  5. Fill with test data: name="Test Project", description="Browser validation test"
+  6. Find and click submit button
+  7. Verify: success indicator appears (toast, redirect, new item in list)
+  8. Screenshot at steps 3, 6, and 7
+```
+
+### Pattern: Error State
+```
+Criterion: "Error message shows when form submitted empty"
+Steps:
+  1. Navigate to the form page
+  2. Find submit button
+  3. Click submit without filling any fields
+  4. Verify: error message(s) visible
+  5. Screenshot showing error state
+```
+
+### Pattern: Conditional UI
+```
+Criterion: "Empty state shows when no data exists"
+Steps:
+  1. Navigate to the list/table page
+  2. Check if data exists — if so, this test needs a clean state
+  3. If clean state achievable: verify empty state message/illustration
+  4. If not: skip with note "Cannot verify empty state — data already exists"
+  5. Screenshot
+```
+
+## Step 3: Handle Data Dependencies
+
+Some flow tests need specific data to exist (or not exist). Approach:
+
+1. **Read-only tests preferred** — test flows that verify existing state rather than create/modify
+2. **Create test data if safe** — if the flow creates something (like a project), use obvious test names ("Browser Validation Test — safe to delete")
+3. **Skip if destructive** — don't test delete flows, don't modify existing data, don't test flows that send emails or notifications
+4. **Note dependencies** — if a test can't run because of missing data, note it as "Skipped — requires [specific data state]"
+
+## Step 4: Handle Auth-Protected Pages
+
+If a route requires authentication:
+1. Check if the app redirects to a login page
+2. If login is a simple form (email + password): note "Auth required — skipping unless test credentials available"
+3. If login uses OAuth/SSO: skip entirely, note "Skipped — requires OAuth flow"
+4. Do not attempt to log in with guessed credentials
+
+## Test Data Guidelines
+
+When filling forms during flow tests, use obviously fake but valid data:
+- Name: "Test User" or "Browser Validate Test"
+- Email: "test@browser-validate.local"
+- Description: "Created by browser-validate skill — safe to delete"
+- Numbers: use small, obvious values (1, 10, 100)
+
+This makes test data easy to identify and clean up later.
+
+## Output Format
+
+For each flow test, report:
+
+```
+Criterion: [original text from done-criteria]
+Classification: browser-testable | skipped
+Steps executed: [N of total]
+Result: PASS | FAIL | SKIPPED
+Evidence:
+  - Screenshot: [path]
+  - Console errors during flow: [count] — [details]
+  - Network failures during flow: [count] — [details]
+  - Failure point: [which step failed and why]
+```

package/config/skills/devlyn:browser-validate/references/tier1-chrome.md

@@ -0,0 +1,132 @@
+# Tier 1: Chrome DevTools (claude-in-chrome)
+
+The richest testing tier. Requires the claude-in-chrome MCP extension running in a Chrome browser. Provides full DOM interaction, console monitoring, network inspection, screenshots, and GIF recording.
+
+Read this file only when Tier 1 was selected during DETECT phase.
+
+---
+
+## Setup
+
+Before any browser interaction, load the tools you need via ToolSearch:
+```
+ToolSearch: "select:mcp__claude-in-chrome__tabs_context_mcp"
+ToolSearch: "select:mcp__claude-in-chrome__tabs_create_mcp"
+ToolSearch: "select:mcp__claude-in-chrome__navigate"
+ToolSearch: "select:mcp__claude-in-chrome__get_page_text"
+ToolSearch: "select:mcp__claude-in-chrome__read_page"
+ToolSearch: "select:mcp__claude-in-chrome__find"
+ToolSearch: "select:mcp__claude-in-chrome__computer"
+ToolSearch: "select:mcp__claude-in-chrome__form_input"
+ToolSearch: "select:mcp__claude-in-chrome__resize_window"
+ToolSearch: "select:mcp__claude-in-chrome__read_console_messages"
+ToolSearch: "select:mcp__claude-in-chrome__read_network_requests"
+ToolSearch: "select:mcp__claude-in-chrome__gif_creator"
+ToolSearch: "select:mcp__claude-in-chrome__javascript_tool"
+```
+
+Then call `tabs_context_mcp` first to understand current browser state. Create a new tab for testing — never reuse existing user tabs.
+
+## Tool Mapping by Action
+
+### Navigate to a page
+```
+tabs_create_mcp → create new tab with URL http://localhost:{PORT}{route}
+  OR
+navigate → go to URL in existing tab
+```
+After navigating, wait 2-3 seconds for client-side rendering, then call `get_page_text` to verify content loaded.
+
+### Check if page rendered
+```
+get_page_text → extract visible text content
+```
+Page fails if: text is empty, contains only boilerplate (e.g., just "Loading..."), or contains raw error stack traces.
+
+### Read page structure
+```
+read_page → get DOM structure and layout info
+```
+Use this to understand component hierarchy before interacting.
+
+### Find interactive elements
+```
+find → locate buttons, links, inputs by text content or attributes
+```
+Returns element positions for clicking.
+
+### Click elements
+```
+computer → click at coordinates returned by find
+```
+After clicking, wait 1-2 seconds, then check console + network for errors.
+
+### Fill form fields
+```
+form_input → set values on input fields, selects, textareas
+```
+Identify fields with `find` first, then use `form_input` with the field selector.
+
+### Take screenshots
+```
+computer → screenshot action captures the visible viewport
+```
+Save screenshots with descriptive names: `smoke-root.png`, `flow-create-project-step3.png`, `visual-mobile-dashboard.png`.
+
+### Resize viewport
+```
+resize_window → set width and height
+```
+Mobile: `resize_window(375, 812)`. Desktop: `resize_window(1280, 800)`.
+
+### Read console messages
+```
+read_console_messages → get all console output
+```
+Use `pattern` parameter to filter. Useful patterns:
+- `"error|Error|ERROR"` — catch errors
+- `"warn|Warning"` — catch warnings
+- Exclude known noise: React dev warnings (`"Warning: "` prefix), HMR messages (`"[vite]"`, `"[HMR]"`, `"[Fast Refresh]"`), favicon 404s
+
+### Read network requests
+```
+read_network_requests → get all HTTP requests with status codes
+```
+Flag: any request with status 4xx or 5xx (excluding `/favicon.ico`). Flag: any CORS error. Ignore: HMR websocket connections, source map requests (`.map`).
+
+### Record multi-step flows
+```
+gif_creator → record a sequence of actions as an animated GIF
+```
+Use for flow tests with 3+ steps. Capture extra frames before and after actions for smooth playback. Name meaningfully: `flow-user-registration.gif`.
+
+### Run custom assertions
+```
+javascript_tool → execute JS in the page context
+```
+Useful for checking specific DOM state that other tools can't easily verify:
+- `document.querySelectorAll('.error-message').length` — count error elements
+- `window.__NEXT_DATA__` — check Next.js hydration data
+- `document.title` — verify page title
+
+Avoid triggering alerts or confirms — they block the extension. Use `console.log` + `read_console_messages` instead.
+
+## Error Filtering
+
+Not every console message is a real problem. Apply these filters:
+
+**Ignore (dev noise)**:
+- `[HMR]`, `[vite]`, `[Fast Refresh]`, `[webpack-dev-server]`
+- `Warning: ReactDOM.render is no longer supported` (React 18 dev warning)
+- `Download the React DevTools`
+- `/favicon.ico` 404
+- Source map warnings
+
+**Flag as errors**:
+- `Uncaught` anything
+- `TypeError`, `ReferenceError`, `SyntaxError`
+- `Failed to fetch` (network errors)
+- `CORS` errors
+- `Hydration` mismatches
+- `ChunkLoadError` (code splitting failures)
+- Any `console.error` call from application code

package/config/skills/devlyn:browser-validate/references/tier2-playwright.md

@@ -0,0 +1,178 @@
+# Tier 2: Playwright (Headless Browser)
+
+Solid middle-ground tier. No browser extension needed — works in CI, SSH, Docker, and headless environments. Provides DOM interaction, console monitoring, screenshots, and network inspection. No GIF recording.
+
+Read this file only when Tier 2 was selected during DETECT phase.
+
+---
+
+## Two Modes
+
+Playwright Tier 2 has two sub-modes depending on what's available. The skill auto-detects which to use.
+
+### Mode A: Playwright MCP (preferred)
+
+If `mcp__playwright__*` tools are available (installed via `npx devlyn-cli` → select "playwright" MCP), use them directly. This gives interactive browser control similar to Tier 1:
+
+- `mcp__playwright__browser_navigate` — navigate to URL
+- `mcp__playwright__browser_screenshot` — capture screenshot
+- `mcp__playwright__browser_click` — click elements
+- `mcp__playwright__browser_type` — type into inputs
+- `mcp__playwright__browser_console` — read console messages
+- `mcp__playwright__browser_network` — read network requests
+- `mcp__playwright__browser_resize` — resize viewport
+
+When Playwright MCP is available, follow the same interaction pattern as Tier 1 (navigate → check → interact → screenshot) but using `mcp__playwright__*` tools instead of `mcp__claude-in-chrome__*`.
+
+Load tools via ToolSearch before use: `ToolSearch: "select:mcp__playwright__browser_navigate"` etc.
+
+### Mode B: Script Generation (fallback)
+
+If Playwright MCP is not installed but `npx playwright` CLI is available, generate and execute test scripts. This is the approach documented below.
+
+## Setup (Mode B only)
+
+Playwright runs via `npx` with auto-download. No global install needed. If browsers aren't installed yet:
+```bash
+npx playwright install chromium 2>/dev/null
+```
+This downloads only Chromium (~130MB), not all browsers. It's a one-time cost.
+
+## Approach (Mode B)
+
+Generate a temporary test script from the test steps, run it with Playwright's JSON reporter, then parse the results. This avoids needing a persistent test infrastructure — the script is created, executed, and cleaned up.
+
+## Script Generation
+
+For each phase (smoke, flow, visual), generate a test script at `.claude/browser-test.spec.ts`.
+
+### Smoke Test Script Template
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+const PORT = {PORT};
+const ROUTES = {ROUTES_JSON_ARRAY};
+
+test.describe('Smoke Tests', () => {
+  for (const route of ROUTES) {
+    test(`smoke: ${route}`, async ({ page }) => {
+      const errors: string[] = [];
+      const failedRequests: string[] = [];
+
+      page.on('console', msg => {
+        if (msg.type() === 'error') errors.push(msg.text());
+      });
+
+      page.on('response', response => {
+        if (response.status() >= 400 && !response.url().includes('favicon')) {
+          failedRequests.push(`${response.status()} ${response.url()}`);
+        }
+      });
+
+      await page.goto(`http://localhost:${PORT}${route}`, { waitUntil: 'networkidle', timeout: 15000 });
+
+      const bodyText = await page.textContent('body');
+      expect(bodyText?.trim().length).toBeGreaterThan(0);
+
+      await page.screenshot({ path: `.claude/screenshots/smoke${route.replace(/\//g, '-') || '-root'}.png`, fullPage: true });
+
+      if (errors.length > 0) {
+        test.info().annotations.push({ type: 'console_errors', description: errors.join(' | ') });
+      }
+      if (failedRequests.length > 0) {
+        test.info().annotations.push({ type: 'network_failures', description: failedRequests.join(' | ') });
+      }
+
+      expect(errors.filter(e => !e.includes('[HMR]') && !e.includes('favicon'))).toHaveLength(0);
+      expect(failedRequests).toHaveLength(0);
+    });
+  }
+});
+```
+
+### Flow Test Script Template
+
+For each flow test step from done-criteria, generate a test block:
+
+```typescript
+test('flow: [criterion description]', async ({ page }) => {
+  // Navigate
+  await page.goto(`http://localhost:${PORT}{start_route}`);
+
+  // Find and interact
+  await page.click('[text or selector]');
+  await page.fill('[selector]', '[value]');
+  await page.click('[submit selector]');
+
+  // Verify
+  await expect(page.locator('[verification selector]')).toBeVisible();
+
+  // Screenshot
+  await page.screenshot({ path: '.claude/screenshots/flow-[name].png' });
+});
+```
+
+### Visual Test Script Template
+
+```typescript
+test.describe('Visual - Mobile', () => {
+  test.use({ viewport: { width: 375, height: 812 } });
+  for (const route of ROUTES) {
+    test(`visual-mobile: ${route}`, async ({ page }) => {
+      await page.goto(`http://localhost:${PORT}${route}`, { waitUntil: 'networkidle' });
+      await page.screenshot({ path: `.claude/screenshots/visual-mobile${route.replace(/\//g, '-') || '-root'}.png`, fullPage: true });
+    });
+  }
+});
+
+test.describe('Visual - Desktop', () => {
+  test.use({ viewport: { width: 1280, height: 800 } });
+  for (const route of ROUTES) {
+    test(`visual-desktop: ${route}`, async ({ page }) => {
+      await page.goto(`http://localhost:${PORT}${route}`, { waitUntil: 'networkidle' });
+      await page.screenshot({ path: `.claude/screenshots/visual-desktop${route.replace(/\//g, '-') || '-root'}.png`, fullPage: true });
+    });
+  }
+});
+```
+
+## Execution
+
+```bash
+mkdir -p .claude/screenshots
+npx playwright test .claude/browser-test.spec.ts \
+  --reporter=json \
+  --output=.claude/playwright-results \
+  2>&1 | tee .claude/playwright-output.json
+```
+
+## Parsing Results
+
+Read `.claude/playwright-output.json`. The JSON structure contains:
+- `suites[].specs[].tests[].results[].status` — `"passed"`, `"failed"`, `"timedOut"`
+- `suites[].specs[].tests[].results[].errors` — error messages with stack traces
+- `suites[].specs[].tests[].annotations` — custom annotations (console_errors, network_failures)
+
+Map these to BROWSER-RESULTS.md findings:
+- `failed` → route fails smoke, include error message
+- Annotations with `console_errors` → list in Runtime Errors section
+- Annotations with `network_failures` → list in Failed Network Requests section
+
+## Cleanup
+
+After parsing results:
+```bash
+rm -f .claude/browser-test.spec.ts
+rm -rf .claude/playwright-results
+rm -f .claude/playwright-output.json
+```
+
+Keep `.claude/screenshots/` — those are evidence referenced by the report.
+
+## Limitations vs Tier 1
+
+- No GIF recording (can't capture multi-step flow animations)
+- No live DOM exploration (tests are scripted, not interactive)
+- Screenshots are full-page captures, not viewport-specific (use `fullPage: true`)
+- Console filtering is code-based (less flexible than chrome MCP pattern matching)

package/config/skills/devlyn:browser-validate/references/tier3-curl.md

@@ -0,0 +1,56 @@
+# Tier 3: HTTP Smoke (curl)
+
+Bare-minimum fallback. No browser, no JavaScript execution, no interaction testing. This tier confirms the dev server responds and pages return valid HTML. It catches "app doesn't start" and "page returns 500" but nothing subtler.
+
+Read this file only when Tier 3 was selected during DETECT phase.
+
+---
+
+## What You Can Test
+
+- Server responds on the expected port
+- Pages return HTTP 200
+- HTML contains a `<body>` with content (not an empty shell)
+- No server-side error indicators in the HTML
+
+## What You Cannot Test
+
+- Client-side rendering (SPA content won't appear in curl output)
+- JavaScript errors or console output
+- Network requests made by the client
+- Interactive elements (forms, buttons, navigation)
+- Visual layout or responsive behavior
+- Screenshots
+
+## Smoke Test
+
+For each affected route:
+
+```bash
+# Check HTTP status
+STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:{PORT}{route} --max-time 10)
+
+# Get HTML content
+HTML=$(curl -s http://localhost:{PORT}{route} --max-time 10)
+```
+
+### Pass Criteria
+
+A route passes if:
+1. `STATUS` is `200` (or `304`)
+2. HTML contains `<body` tag
+3. HTML body has more than 100 characters of text content (not just empty divs)
+4. HTML does not contain server error indicators: `Internal Server Error`, `500`, `ECONNREFUSED`, `Cannot GET`, `404`
+
+### Parsing HTML Content
+
+Since curl returns raw HTML (no JS execution), for SPAs the body may only contain a root `<div id="root"></div>` or `<div id="__next"></div>`. This is normal and counts as a PASS for Tier 3 — note it as "SPA shell detected, client-side rendering not verifiable at this tier."
+
+For SSR frameworks (Next.js with server components, Nuxt, Astro), the HTML should contain actual rendered content.
+
+## Report Adjustments
+
+When writing BROWSER-RESULTS.md from Tier 3:
+- Set confidence level to LOW
+- Leave Console Errors, Network Failures, Flow Tests, and Visual Check sections as "N/A — Tier 3 (HTTP only)"
+- Note the limitation: "Tier 3 testing provides HTTP-level validation only. Client-side behavior, JavaScript errors, and visual rendering were not tested. For comprehensive browser validation, install the claude-in-chrome extension (Tier 1) or Playwright (Tier 2)."

package/config/skills/devlyn:evaluate/SKILL.md

@@ -297,14 +297,9 @@ LOW (note):
 4. For each catch block: is the error surfaced to the user or silently swallowed?
 5. Check for React anti-patterns: uncontrolled-to-controlled switches, direct DOM mutation, missing cleanup
 6. Compare against existing components for pattern consistency
-7. **Live app testing** (when browser tools are available): If `mcp__claude-in-chrome__*` tools are available, test the running application directly:
-   - Navigate to the affected pages
-   - Click through the user flow end-to-end
-   - Test interactive elements (forms, buttons, modals, navigation)
-   - Verify loading, error, and empty states render correctly
-   - Screenshot any visual issues as evidence
-   - Test responsive behavior at mobile/tablet/desktop widths
-   If browser tools are NOT available, skip this step and note "Live testing skipped — no browser tools" in your deliverable.
+7. **Browser evidence** (when available): Read `.claude/BROWSER-RESULTS.md` if it exists — it contains pre-collected smoke test results, flow test results, console errors, network failures, and screenshots from the `devlyn:browser-validate` skill. Use this as additional evidence in your evaluation. Do not re-run smoke tests that are already covered.
+   If the dev server is still running and you need deeper investigation on a specific interaction, use browser tools directly (check if `mcp__claude-in-chrome__*` tools are available, or fall back to Playwright). Focus on verifying specific findings, not duplicating the full smoke/flow suite.
+   If neither `.claude/BROWSER-RESULTS.md` exists nor browser tools are available, note "Live testing skipped — no browser validation available" in your deliverable.
 
 **Your deliverable**: Send a message to the team lead with:
 1. Component quality assessment for each new/changed component
@@ -312,7 +307,7 @@ LOW (note):
 3. Silent failure points that violate error handling policy
 4. React anti-patterns found
 5. Pattern consistency with existing components
-6. Live testing results (if browser tools were available): screenshots, interaction bugs, visual regressions
+6. Browser validation results (from BROWSER-RESULTS.md or live testing): screenshots, interaction bugs, runtime errors, visual regressions
 
 Read the team config at ~/.claude/teams/{team-name}/config.json to discover teammates. Coordinate with api-contract-evaluator about client-server type alignment via SendMessage.
 </frontend_evaluator_prompt>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Claude Code configuration toolkit for teams",
   "bin": {
     "devlyn": "bin/devlyn.js"