feat: Add automated testing with Vitest and Playwright

- Install Vitest (integration tests for API routes) and Playwright (E2E tests)
- Add vitest.config.ts, playwright.config.ts, src/test/setup.ts
- Add test scripts: npm test, npm run test:e2e, npm run test:all
- Backend skill: writes integration tests for each API route
- QA skill: checks Playwright browser install, runs both suites,
  writes E2E tests from acceptance criteria as permanent regression suite
- Fix all skill frontmatter: remove unsupported context/agent/model/allowed-tools,
  fix argument-hint to be a quoted string
- Fix broken relative paths to docs/production/ in deploy and backend skills
- Update README with playwright install step and test script reference

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/skills/architecture/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: architecture
 description: Design PM-friendly technical architecture for features. No code, only high-level design decisions.
-argument-hint: [feature-spec-path]
+argument-hint: "feature-spec-path"
 user-invocable: true
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion
-model: sonnet
 ---
 
 # Solution Architect

.claude/skills/backend/SKILL.md

@@ -1,11 +1,8 @@
 ---
 name: backend
 description: Build APIs, database schemas, and server-side logic with Supabase. Use after frontend is built.
-argument-hint: [feature-spec-path]
+argument-hint: "feature-spec-path"
 user-invocable: true
-context: fork
-agent: Backend Developer
-model: opus
 ---
 
 # Backend Developer
@@ -53,8 +50,17 @@ Use `AskUserQuestion` for:
 - Replace any mock data or localStorage with API calls
 - Handle loading and error states
 
-### 6. User Review
+### 6. Write Integration Tests
+For each API route created, write a Vitest integration test in `src/app/api/[route]/[route].test.ts`:
+- Test the happy path (valid input → expected response)
+- Test validation errors (invalid input → 400 with error message)
+- Test authentication (unauthenticated request → 401)
+- Test authorization (wrong user → 403)
+- Run tests: `npm test`
+
+### 7. User Review
 - Walk user through the API endpoints created
+- Show test results
 - Ask: "Do the APIs work correctly? Any edge cases to test?"
 
 ## Context Recovery
@@ -87,8 +93,8 @@ CREATE INDEX idx_tasks_status ON tasks(status);
 ```
 
 ## Production References
-- See [database-optimization.md](../../docs/production/database-optimization.md) for query optimization
+- See [database-optimization.md](../../../docs/production/database-optimization.md) for query optimization
-- See [rate-limiting.md](../../docs/production/rate-limiting.md) for rate limiting setup
+- See [rate-limiting.md](../../../docs/production/rate-limiting.md) for rate limiting setup
 
 ## Checklist
 See [checklist.md](checklist.md) for the full implementation checklist.

.claude/skills/deploy/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: deploy
 description: Deploy to Vercel with production-ready checks, error tracking, and security headers setup.
-argument-hint: [feature-spec-path or "to Vercel"]
+argument-hint: "feature-spec-path or 'to Vercel'"
 user-invocable: true
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion
-model: sonnet
 ---
 
 # DevOps Engineer
@@ -55,11 +53,11 @@ Guide the user through:
 
 For first deployment, guide the user through these setup guides:
 
-**Error Tracking (5 min):** See [error-tracking.md](../../docs/production/error-tracking.md)
+**Error Tracking (5 min):** See [error-tracking.md](../../../docs/production/error-tracking.md)
-**Security Headers (copy-paste):** See [security-headers.md](../../docs/production/security-headers.md)
+**Security Headers (copy-paste):** See [security-headers.md](../../../docs/production/security-headers.md)
-**Performance Check:** See [performance.md](../../docs/production/performance.md)
+**Performance Check:** See [performance.md](../../../docs/production/performance.md)
-**Database Optimization:** See [database-optimization.md](../../docs/production/database-optimization.md)
+**Database Optimization:** See [database-optimization.md](../../../docs/production/database-optimization.md)
-**Rate Limiting (optional):** See [rate-limiting.md](../../docs/production/rate-limiting.md)
+**Rate Limiting (optional):** See [rate-limiting.md](../../../docs/production/rate-limiting.md)
 
 ### 6. Post-Deployment Bookkeeping
 - Update feature spec: Add deployment section with production URL and date

.claude/skills/frontend/SKILL.md

@@ -1,11 +1,8 @@
 ---
 name: frontend
 description: Build UI components with React, Next.js, Tailwind CSS, and shadcn/ui. Use after architecture is designed.
-argument-hint: [feature-spec-path]
+argument-hint: "feature-spec-path"
 user-invocable: true
-context: fork
-agent: Frontend Developer
-model: opus
 ---
 
 # Frontend Developer

.claude/skills/help/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: help
 description: Context-aware guide that tells you where you are in the workflow and what to do next. Use anytime you're unsure.
-argument-hint: [optional question]
+argument-hint: "optional question"
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash
-model: opus
 ---
 
 # Project Help Guide

.claude/skills/qa/SKILL.md

@@ -1,11 +1,8 @@
 ---
 name: qa
 description: Test features against acceptance criteria, find bugs, and perform security audit. Use after implementation is done.
-argument-hint: [feature-spec-path]
+argument-hint: "feature-spec-path"
 user-invocable: true
-context: fork
-agent: QA Engineer
-model: opus
 ---
 
 # QA Engineer
@@ -20,6 +17,14 @@ You are an experienced QA Engineer AND Red-Team Pen-Tester. You test features ag
 4. Check recent bug fixes: `git log --oneline --grep="fix" -10`
 5. Check recently changed files: `git log --name-only -5 --format=""`
 
+### Check Playwright Browser Installation
+Run: `npx playwright install --dry-run 2>&1 | head -5`
+
+If browsers are not installed, tell the user:
+> "Playwright browsers need to be installed once. I'll do this now — it downloads ~300MB of browser binaries."
+> Then run: `npx playwright install chromium`
+> This is a one-time setup per machine. After cloning the repo, always run this once before E2E tests.
+
 ## Workflow
 
 ### 1. Read Feature Spec
@@ -51,11 +56,27 @@ Verify existing features still work:
 - Test core flows of related features
 - Verify no visual regressions on shared components
 
-### 5. Document Results
+### 5. Run Automated Tests
+Run existing test suites before manual testing:
+```bash
+npm test                  # Vitest: integration tests for API routes
+npm run test:e2e          # Playwright: E2E tests from previous QA runs
+```
+Note any failures — these are regressions and must be treated as High bugs.
+
+### 6. Write E2E Tests
+For each acceptance criterion that passed manual testing, write a Playwright test in `tests/PROJ-X-feature-name.spec.ts`:
+- One `test()` per acceptance criterion
+- Tests describe the user journey in plain language
+- Run to confirm all pass: `npm run test:e2e`
+
+These tests become the permanent regression suite for this feature.
+
+### 7. Document Results
 - Add QA Test Results section to the feature spec file (NOT a separate file)
 - Use the template from [test-template.md](test-template.md)
 
-### 6. User Review
+### 8. User Review
 Present test results with clear summary:
 - Total acceptance criteria: X passed, Y failed
 - Bugs found: breakdown by severity

.claude/skills/requirements/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: requirements
 description: Create detailed feature specifications with user stories, acceptance criteria, and edge cases. Use when starting a new feature or initializing a new project.
-argument-hint: [project-description or feature-idea]
+argument-hint: "project-description or feature-idea"
 user-invocable: true
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion
-model: sonnet
 ---
 
 # Requirements Engineer

README.md

@@ -12,6 +12,7 @@ This template uses [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
 git clone https://github.com/YOUR_USERNAME/ai-coding-starter-kit.git my-project
 cd my-project
 npm install
+npx playwright install chromium   # one-time: installs browser for E2E tests (~300MB)
 ```
 
 ### 2. (Optional) Supabase Setup
@@ -305,6 +306,9 @@ npm run dev        # Development server (localhost:3000)
 npm run build        # Production build
 npm run start        # Production server
 npm run lint         # ESLint
+npm test             # Vitest: integration tests for API routes
+npm run test:e2e     # Playwright: E2E tests for user flows
+npm run test:all     # Run both test suites
 ```
 
 ---

package.json

@@ -7,7 +7,12 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "next lint",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:all": "vitest run && playwright test"
   },
   "dependencies": {
     "@hookform/resolvers": "^5.2.2",
@@ -46,14 +51,21 @@
     "zod": "^4.3.5"
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/ui": "^4.1.2",
     "autoprefixer": "^10.0.1",
     "eslint": "^9",
     "eslint-config-next": "16.1.1",
+    "jsdom": "^29.0.1",
     "postcss": "^8",
     "tailwindcss": "^3.4.1",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vitest": "^4.1.2"
   }
 }

playwright.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'Mobile Safari', use: { ...devices['iPhone 13'] } },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+})

src/test/setup.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom'

vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+import { resolve } from 'path'
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./src/test/setup.ts'],
+  },
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, './src'),
+    },
+  },
+})