/validate-ui

name: validate-ui
description: |
  Comprehensive end-to-end validation of the Archon Web UI using browser automation and codebase review.
  Use when: User wants to validate, test, or audit the Archon web interface, find UI/UX bugs,
  test workflow management, verify parallel agent orchestration, or run comprehensive browser-based E2E tests.
  Triggers: "validate ui", "test the ui", "e2e test", "browser test", "validate archon",
            "test archon ui", "ui audit", "ux review", "comprehensive test", "validate everything".
  Capability: Starts Archon, runs exhaustive browser automation tests via agent-browser CLI,
  performs codebase review, and produces a detailed bug/UX report.
  NOT for: Unit tests (use `bun test`), CLI-only validation (use /validation:validate-simple).
argument-hint: "[focus-area]"
disable-model-invocation: true
allowed-tools: Bash, Read, Grep, Glob, Edit, Write, Task

Archon Web UI — Comprehensive E2E Validation

Run exhaustive end-to-end browser automation tests and codebase review of the Archon Web UI. The goal: determine whether Archon is doing the best it possibly can to solve the problem of managing parallel agents, executing custom workflows, and providing full visibility into agent work.

Optional focus argument: `$ARGUMENTS` (e.g., "workflows", "chat", "projects"). If empty, run ALL sections.

---

Phase 0: Environment Setup

0.1 Kill Old Archon Processes

# Kill any running Archon dev servers (backend + frontend)
pkill -f "bun.*dev:server" 2>/dev/null || true
pkill -f "bun.*dev:web" 2>/dev/null || true
pkill -f "bun.*packages/server" 2>/dev/null || true
pkill -f "bun.*packages/web" 2>/dev/null || true
pkill -f "vite.*5173" 2>/dev/null || true

# Kill any leftover processes on our ports
lsof -ti:3090 | xargs kill -9 2>/dev/null || true
lsof -ti:5173 | xargs kill -9 2>/dev/null || true

# Wait for ports to free up
sleep 2

# Verify ports are free
! lsof -i:3090 && ! lsof -i:5173 && echo "Ports 3090 and 5173 are free" || echo "WARNING: Ports still in use"

0.2 Install agent-browser (if needed)

# Check if agent-browser is available
which agent-browser 2>/dev/null || npx agent-browser --version 2>/dev/null

# If not installed globally, install it:
# npm install -g agent-browser && agent-browser install
# On WSL2/Linux, use --with-deps to get Chromium system dependencies:
# agent-browser install --with-deps

# IMPORTANT: Do NOT use bunx — Bun skips postinstall scripts that agent-browser needs.
# Use npx or global npm install.

0.3 Start Archon Backend + Frontend

Start both services. Backend must be up before frontend SSE connections work.

# From the repo root: /path/to/archon

# Start backend (port 3090)
cd /path/to/archon && bun run dev:server &
sleep 5  # Wait for server initialization + DB

# Verify backend is healthy
curl -s http://localhost:3090/api/health | head -c 200

# Start frontend (port 5173)
cd /path/to/archon && bun run dev:web &
sleep 5  # Wait for Vite dev server

# Verify frontend is serving
curl -s http://localhost:5173 | head -c 200

**URLs:**

• Frontend: `http://localhost:5173`
• Backend API: `http://localhost:3090/api`
• SSE streams: `http://localhost:3090/api/stream/{conversationId}` (bypasses Vite proxy in dev)

0.4 Seed Test Data (if needed)

Check if there are existing codebases and conversations. If empty, create test data:

# Check existing codebases
curl -s http://localhost:3090/api/codebases | python3 -m json.tool 2>/dev/null || curl -s http://localhost:3090/api/codebases

# Register the current repo as a codebase (if none exist)
curl -s -X POST http://localhost:3090/api/codebases \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/archon"}'

# Create a test conversation
curl -s -X POST http://localhost:3090/api/conversations \
  -H "Content-Type: application/json" \
  -d '{}' | python3 -m json.tool 2>/dev/null

---

Phase 1: Browser Automation — End-to-End Testing

Use the `agent-browser` CLI for all browser interactions. Follow the snapshot-refs workflow: 1. `agent-browser open <url>` — navigate 2. `agent-browser snapshot -i` — get interactive elements with refs 3. Interact using refs (click, fill, etc.) 4. Re-snapshot after navigation or DOM changes

Take screenshots at each major test point: `agent-browser screenshot /tmp/archon-test-{name}.png`

Test Suite 1: Dashboard (Route: `/`)

**1.1 Initial Load**

• Open `http://localhost:5173`
• Verify dashboard renders: stats cards (Running Workflows, Conversations, System Status)
• Check system health indicator shows "Healthy" (green)
• Screenshot the full dashboard

**1.2 Stats Accuracy**

• Compare "Running Workflows" count against `GET /api/workflows/runs?status=running`
• Compare "Conversations" count against `GET /api/conversations`
• Verify numbers update after creating new data

**1.3 Recent Items**

• Verify "Recent Conversations" list shows up to 10 items
• Verify "Recent Workflow Runs" list shows up to 10 items
• Click a conversation — verify navigation to `/chat/{id}`
• Click a workflow run — verify navigation to `/workflows/runs/{id}`
• Use browser back button — verify return to dashboard

**1.4 Empty State**

• If no conversations/runs exist: verify the empty state with "New Chat" CTA renders
• Click "New Chat" from empty state — verify navigation to `/chat`

Test Suite 2: Project Management

**2.1 Add Project (GitHub URL)**

• Click the `+` button next to "Projects" in the sidebar
• Fill in a GitHub URL (e.g., `https://github.com/anthropics/claude-code`)
• Submit and verify the project appears in the sidebar
• Verify the project is auto-selected

**2.2 Add Project (Local Path)**

• Click `+` again
• Fill in a local path (e.g., `/path/to/archon`)
• Submit and verify the project appears
• Verify deduplication: if the path was already registered, it should not create a duplicate

**2.3 Select/Deselect Project**

• Click a project in the sidebar — verify it becomes selected (h