/verify-setup

Run once before using /verify on a new project. This skill does everything inline, no npm install needed.

Prerequisites

• Dev server running locally (any framework)

Steps

Follow these steps in order. Do not skip ahead.

Step 1: Scaffold .verify/

mkdir -p .verify

Check if .gitignore already contains .verify/:

grep -q '^\.verify/$' .gitignore 2>/dev/null || echo '.verify/' >> .gitignore

If .gitignore didn't exist, create it with .verify/ as the first line.

Step 2: Detect dev server port

Find the dev server port. Check in this order:

1. package.json scripts (dev, start, serve) — look for -p, --port, or PORT= flags
2. .env.local, .env.development, .env — look for PORT=XXXX
3. Framework configs (vite.config.*, next.config.*) — look for port settings

If the detected port is 0, warn the user and ask for the actual port. If no port found, default to 3000 and tell the user.

Step 3: Ping the dev server

curl -sf http://localhost:{PORT} > /dev/null 2>&1

If this fails, wait 3 seconds and retry once:

sleep 3 && curl -sf http://localhost:{PORT} > /dev/null 2>&1

If it still fails, tell the user: "Dev server not running at http://localhost:{PORT}. Start it and re-run /verify-setup." Stop here.

Step 4: Write config.json

Use the Write tool to create .verify/config.json:

{
  "baseUrl": "http://localhost:{PORT}"
}

If .verify/config.json already exists, read it first and only update the baseUrl field. Preserve any other fields.

Step 5: Index routes

Find all user-facing pages and routes in this app. Look for route definitions, page components, URL patterns.

Check any framework:

• Next.js: app/ directory (route segments) or pages/ directory
• Remix: routes/ directory
• React Router: look for <Route> components or createBrowserRouter configs
• Express/Hono/Fastify: look for .get(), .post() route definitions
• SvelteKit: routes/ directory
• Nuxt: pages/ directory

This may be a monorepo. Check under apps/, packages/, src/.

Skip API routes (/api/*). Only include user-facing pages.

Build a JSON object with this schema:

{"routes": {"/path": {"component": "file/path.tsx"}}}

Each key is a URL path. Each value has a component field with the source file path.

If no routes are found, use {"routes": {}}.

Step 6: Index selectors from tests

Find the e2e/integration test suite in this project. Look for:

• Playwright tests (.spec.ts, .test.ts in e2e/, tests/, test/)
• Cypress tests (.cy.ts, .cy.js)

This may be a monorepo. Check under packages/, apps/, tests/, e2e/.

For each test file, extract the URLs navigated to and selectors used. Group selectors by URL/page. Keep it compact — max 10 selectors per page. Prefer data-testid and role selectors.

Build a JSON object with this schema:

{"pages": {"/url": {"selectors": {"name": {"value": ".selector", "source": "file:line"}}, "source_tests": ["file.spec.ts"]}}}

If no test files are found, use {"pages": {}}.

Step 7: Write app.json

Merge the routes and pages into a single JSON object and write it using the Write tool to .verify/app.json:

{
  "indexed_at": "<current ISO timestamp>",
  "routes": { ... },
  "pages": { ... }
}

Step 8: Configure Playwright MCP

Check if Playwright MCP is already configured: use ListMcpResourcesTool with server="playwright". If it returns results, Playwright is configured.

If not configured, tell the user:

Playwright MCP is required for /verify. Install it:

claude mcp add playwright -- npx @playwright/mcp@latest --storage-state .verify/auth.json --isolated

Then restart Claude Code and re-run /verify-setup to confirm.

If already configured, skip this step.

Step 9: Done

Print a summary:

Setup complete:
  Base URL: http://localhost:{PORT} (source: {PORT_SOURCE})
  Routes:   {N} routes indexed
  Pages:    {N} pages with selectors
  Config:   .verify/config.json
  Index:    .verify/app.json

Run /verify to verify your changes.

Troubleshooting

"Dev server not running" — Start your dev server first, then re-run /verify-setup.

Wrong port detected — Tell the skill the correct port: "My dev server runs on port 5173".

Playwright MCP not found — Run claude mcp add playwright -- npx @playwright/mcp@latest --storage-state .verify/auth.json --isolated and restart Claude Code.

Auth expired during /verify — Log into your app in the Playwright browser session, or provide credentials when prompted by /verify.