create-claude-workspace 1.1.86 → 1.1.87

package/dist/template/.claude/agents/backend-ts-architect.md

@@ -144,10 +144,17 @@ Which project patterns apply (onion layers, DI, UnitOfWork, etc.)
 Common mistakes to avoid for this specific task.
 
 ### TESTING
-Which files need tests and what to test. Be specific:
+Which files need tests and what to test. **You MUST specify test layers explicitly** — don't leave it to the orchestrator to guess:
+
+**Unit tests** (always, for files with logic):
 - `path/to/file.ts` — test cases: [list key scenarios, edge cases, error conditions]
 - `path/to/other.ts` — no tests needed (config / wiring only)
-This section is used by the orchestrator to decide whether to call `test-engineer` in STEP 4.
+
+**Integration tests** (REQUIRED for any task that adds/changes API endpoints, database operations, service interactions, or publishable library public API):
+- Endpoints/services to cover: [list with expected request/response patterns]
+- If no integration tests needed, write: "Integration: not applicable (no API/DB/service changes)"
+
+Be explicit about every layer — omitting a layer means no tests for it.
 
 ### API CONTRACT REVISION (only when re-invoked with frontend feedback)
 If the orchestrator re-delegates with frontend architect feedback about impractical API contract, re-output only the revised INTERFACES section. Include a brief changelog:

package/dist/template/.claude/agents/orchestrator.md

@@ -202,14 +202,90 @@ If `PLAN.md` exists in the project root, check whether it changed since the last
 - Log in MEMORY.md Notes: "Retroactive git sync completed — [N] issues created, [M] marked as done"
 - Skip if any trigger condition is not met (no remote, no TODO.md, markers already present, CLI missing, auth invalid)
 
-### 11. Kit version check (CLAUDE.md refresh on upgrade)
-- Read `.claude/.kit-version` — if it exists and differs from MEMORY.md `Kit_Version` (or `Kit_Version` is absent):
-  - The `create-claude-workspace` kit was updated. Agent instructions and templates may have changed.
-  - Run `/revise-claude-md` to reconcile the project's CLAUDE.md with any new conventions from the updated kit template (`.claude/templates/claude-md.md`).
-  - If `/revise-claude-md` is unavailable, manually compare CLAUDE.md against `.claude/templates/claude-md.md` and update sections that have new content (e.g., new preferred libraries, new rules, new patterns). Do NOT overwrite project-specific content (project name, tech stack choices, deployment config).
-  - Update MEMORY.md: set `Kit_Version: [value from .kit-version]`
-  - Commit if changes were made: `git add CLAUDE.md MEMORY.md && git commit -m "chore: update CLAUDE.md for kit version [version]"`. Push if remote exists.
-- Skip if `.claude/.kit-version` does not exist.
+### 11. Kit auto-upgrade (check npm + migrate project)
+Automatically check for newer `create-claude-workspace` versions, update kit files, analyze changes, and create migration tasks for the target project.
+
+#### 11a. Check npm registry for latest version
+```bash
+CURRENT=$(cat .claude/.kit-version 2>/dev/null || echo "0.0.0")
+LATEST=$(npm view create-claude-workspace version 2>/dev/null || echo "")
+```
+- If `LATEST` is empty (network failure, npm unavailable) → skip entire step 11
+- If `LATEST` equals `CURRENT` → skip (already up to date)
+- If `LATEST` is newer than `CURRENT` → proceed to 11b
+
+#### 11b. Update kit files
+```bash
+# Run update using the project's package runner
+{PKG_RUNNER} create-claude-workspace@latest --update
+```
+- This overwrites `.claude/` files (agents, profiles, templates, docker, router, .kit-version) with the latest version
+- Project-specific files (CLAUDE.md, PRODUCT.md, TODO.md, MEMORY.md) are NOT touched by the update command
+
+#### 11c. Capture and analyze diff
+```bash
+# Capture what changed in .claude/
+git diff .claude/
+```
+- If diff is empty (update ran but nothing changed) → skip to 11e
+- Categorize changes:
+  - **Template changes** (`.claude/templates/claude-md.md`) → new conventions, patterns, rules for project CLAUDE.md
+  - **Profile changes** (`.claude/profiles/*.md`) → new frontend patterns, review checklists
+  - **Agent changes** (`.claude/agents/*.md`) → updated agent behavior (self-updating, no project migration needed)
+  - **Docker changes** (`.claude/docker/*`) → updated container config
+  - **Router changes** (`.claude/CLAUDE.md`) → updated routing instructions
+
+#### 11d. Create migration tasks (if project changes needed)
+Only if template or profile changes affect the target project — delegate to `technical-planner`:
+
+"The `create-claude-workspace` kit was upgraded from v{CURRENT} to v{LATEST}. Below is the diff of changed files. Analyze what changed and determine if the TARGET PROJECT needs migration or refactoring tasks.
+
+**The diff:**
+```
+{git diff output}
+```
+
+**Focus on these change types (create a task for each that applies):**
+- New or changed preferred libraries → refactoring task (e.g., 'Migrate from X to Y per kit v{LATEST}')
+- New or changed code patterns/conventions → refactoring task (e.g., 'Apply new naming convention from kit v{LATEST}')
+- New or removed rules (e.g., new lint rule, banned pattern) → cleanup task (e.g., 'Fix all eslint-disable comments per kit v{LATEST}')
+- Changed profile conventions (frontend patterns) → style refactoring task
+- Changes ONLY in agent instructions (`.claude/agents/*.md`) → NO task needed (agents self-update)
+- Changes ONLY in Docker/router files → NO task needed
+
+**If migration tasks are needed:**
+- Insert them at the TOP of the current phase in TODO.md with tag `Kit-Upgrade: v{LATEST}`
+- Use Complexity: S or M (never L for migration tasks — split if large)
+- Each task must have clear scope: which files to change, what pattern to apply
+- Add dependency on each other if they must be sequential
+
+**If no project changes needed**, respond with: `MIGRATION: NONE — kit v{LATEST} changes are agent-only, no project impact.`
+
+Read the current TODO.md and MEMORY.md for context on the project's current phase and tech stack."
+
+- If planner returns `MIGRATION: NONE` → no tasks created, proceed to 11e
+- If planner creates tasks → if git integration active, delegate to `devops-integrator` to create issues for the new migration tasks
+- Log in MEMORY.md Notes: "Kit upgraded v{CURRENT} → v{LATEST}: [N migration tasks created / no project migration needed]"
+
+#### 11e. Commit update + refresh CLAUDE.md
+1. Run `/revise-claude-md` to reconcile the project's CLAUDE.md with new conventions from the updated template (`.claude/templates/claude-md.md`). If `/revise-claude-md` is unavailable, manually compare CLAUDE.md against the template and update sections with new content. Do NOT overwrite project-specific content (project name, tech stack choices, deployment config).
+2. Update MEMORY.md: set `Kit_Version: [value from .claude/.kit-version]`
+3. Commit all changes:
+   ```bash
+   git add .claude/ CLAUDE.md MEMORY.md TODO.md
+   git commit -m "chore: upgrade kit to v{LATEST}"
+   ```
+4. Push if remote exists: `git push origin HEAD`
+
+#### 11f. Migration task priority
+- After step 11 completes, if migration tasks were created in TODO.md, they become the **next tasks to pick** in STEP 1 (before any regular development tasks in the current phase)
+- This ensures the project stays aligned with kit conventions before new features are built on outdated patterns
+- Migration tasks follow the normal development cycle (STEP 1-12) — they get architect plans, tests, review, just like any other task
+
+#### Skip conditions
+- `.claude/.kit-version` does not exist → skip entire step 11
+- `npm view` fails (network, npm not installed) → skip, log in MEMORY.md Notes: "Kit version check skipped — npm registry unreachable"
+- Current version equals latest → skip (up to date)
 
 ### 12. Ingest external issues (if git integration active)
 - **Only run at phase transitions** — not every invocation
@@ -245,6 +321,7 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
 - Read MEMORY.md, find next incomplete item and current phase
 - Update MEMORY.md: set `Current Step: 1 — PICK`
 - Cross-reference with TODO.md — find the first unchecked `- [ ]` task in the current phase
+  - **Kit-upgrade tasks first**: if any `- [ ]` tasks in the current phase have `Kit-Upgrade:` tag, pick those before any regular tasks (regardless of position in the phase)
   - Skip tasks marked as `- [~]` (skipped/blocked)
 - **If no `[ ]` tasks remain in the current phase**: advance to the next phase. Update MEMORY.md `Current Phase` to the next phase heading from TODO.md. Then look for the first `- [ ]` task in that new phase. This IS a phase transition — the phase transition check below will trigger for the first task. If no `[ ]` tasks remain in ANY phase, go to the final completion sequence in STEP 12.
 - **Dependency check**: verify ALL tasks listed in "Depends on" are checked `[x]` in TODO.md. If any dependency is incomplete, skip this task and pick the next one without unmet dependencies.
@@ -361,20 +438,28 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
     - Used within ONE domain group -> `libs/[domain]/shared/`
     - Used within ONE library -> keep it local
 
-**STEP 4: WRITE TESTS — DELEGATE to `test-engineer` (when applicable)**
+**STEP 4: WRITE TESTS — DELEGATE to `test-engineer` (MANDATORY)**
 - Update MEMORY.md (on main): set `Current Step: 4 — TESTS`
-- Check the architect's **TESTING** section from STEP 2 — it lists which files need tests and what to test
-- If TESTING section lists files that need tests -> delegate to `test-engineer` agent
-- **Include the architect's TESTING section in the prompt** so test-engineer knows what was already decided
-- **Fallback**: If the architect's plan has no TESTING section, assume tests are needed for all new `business/` and `domain/` files
-- In your Agent tool prompt, include:
+- **This step is NOT optional.** Every task that changes code MUST go through test-engineer. The only exception is tasks that change ONLY config/CI/docs with zero logic.
+- Read the architect's **TESTING** section from STEP 2. It specifies test layers explicitly:
+  - **Unit tests** — files + test cases
+  - **Integration tests** — endpoints/services/DB operations (backend tasks)
+  - **E2E tests** — user flows/routes (frontend tasks)
+  - **VRT tests** — pages/views for visual regression (frontend tasks)
+- **Fallback if TESTING section is missing or vague**: Assume ALL layers are needed based on task type:
+  - Backend task → unit + integration tests
+  - Frontend task → unit + E2E tests (+ VRT if new pages)
+  - Fullstack task → unit + integration + E2E tests
+- **Build the test-engineer prompt with ALL applicable layers in a single delegation.** Include:
   - **Working directory: {worktree-abs-path}** — all file reads/edits/test runs must use this path
-  - The TESTING section from the architect's plan (file paths + test cases)
+  - The full TESTING section from the architect's plan
   - List of new/changed files
-  - Ask for: TEST PLAN, then full .spec.ts implementation, then RUN all tests and report results
-- Skip this step ONLY if the architect's TESTING section explicitly says "no tests needed"
-- **E2E tests (frontend)**: If the task involves user-facing flows (multi-step interactions, navigation, form submissions, authentication), explicitly request E2E tests from test-engineer using Playwright. Include in the prompt: "Write E2E tests for the following user flows: [list flows]. Use Playwright. Ensure E2E project is set up (scaffold via `nx g @nx/playwright:configuration` if missing)."
-- **Integration tests (backend/packages)**: If the task involves API endpoints, database operations, service interactions, or publishable library public API surface, explicitly request integration tests from test-engineer. Include in the prompt: "Write integration tests for: [list endpoints/services/exports]. Test real request/response cycles (use test server or supertest), database operations against test DB, and public API contracts. Keep integration tests in `*.integration.spec.ts` files (co-located next to source, same as unit tests)."
+  - Explicit request for each test layer the architect specified (or the fallback layers)
+  - Ask for: TEST PLAN per layer, then full implementation, then RUN all tests and report results
+- **E2E tests**: Include in the prompt: "Write E2E tests for the following user flows: [list flows from TESTING section]. Use Playwright. Ensure E2E project is set up (scaffold via `nx g @nx/playwright:configuration` if missing)."
+- **Integration tests**: Include in the prompt: "Write integration tests for: [list endpoints/services from TESTING section]. Test real request/response cycles (use test server or supertest), database operations against test DB, and public API contracts. Keep integration tests in `*.integration.spec.ts` files (co-located next to source, same as unit tests)."
+- **Visual regression tests**: Include in the prompt: "Write visual regression tests (`*.vrt.spec.ts`) for these pages/views: [list from TESTING section]. Use the VRT template with 3-viewport matrix (mobile 375px, tablet 768px, desktop 1280px). Use `maxDiffPixelRatio: 0.01` and `fullPage: true` for page screenshots. Mask dynamic content (timestamps, user avatars) with `mask` option."
+- **Baseline updates for intentional visual changes**: If the architect's plan describes intentional visual changes to existing pages (redesign, new theme, layout restructure), add to the test-engineer prompt: "Existing VRT baselines will need updating. After writing/updating VRT tests, run `nx e2e [APP]-e2e -- --update-snapshots` to regenerate baselines. Include the updated baseline images in the commit."
 - **Error recovery**: If test-engineer agent fails, write basic smoke tests yourself and note in MEMORY.md
 
 **STEP 5: BUILD, LINT & TEST (with coverage)**
@@ -402,6 +487,7 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
   bunx kill-port 4200 2>/dev/null || npx kill-port 4200 2>/dev/null || true
   ```
 - E2E and integration test failures are treated the same as unit test failures — fix before proceeding.
+- **VRT first-run note**: If VRT tests (`*.vrt.spec.ts`) were newly created in STEP 4, the first E2E run will fail because no baseline screenshots exist yet. This is expected — not a real failure. Re-run E2E once: first run creates baselines, second run compares against them. If the second run passes, the baselines are correct. Ensure `*-snapshots/` directories are staged for commit in STEP 11.
 - **Stylelint** (for tasks with SCSS changes): run `stylelint "libs/**/*.scss" "apps/**/*.scss" --max-warnings=0` via the PKG runner (e.g., `bunx stylelint ...` / `npx stylelint ...`) or `nx stylelint [PROJECT]` if configured as Nx target
 - Pipe output through `| tail -30` for readability
 - Only use `--skip-nx-cache` if you suspect stale cache
@@ -415,6 +501,7 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
 **STEP 6: VISUAL VERIFICATION (UI tasks only)**
 - Update MEMORY.md (on main): set `Current Step: 6 — VISUAL VERIFY`
 - Skip this step for backend-only tasks
+- **Note**: Automated VRT (pixel comparison via `toHaveScreenshot()`) runs in STEP 5 and catches regressions against baselines. This manual verification step complements VRT by checking subjective quality: does the page look good? Does it match the design intent? Are proportions and spacing aesthetically correct? VRT catches what changed; this step judges whether the change looks right.
 - For frontend tasks, use Playwright MCP to verify visual output:
   1. Start dev server **from the worktree**. **Important**: each Bash tool call runs in a separate shell, so PID variables don't persist. Start the server in one Bash call and leave it running:
      ```bash
@@ -513,6 +600,7 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
   cd {worktree-path} && git add [source files] [test files] [migration files] TODO.md MEMORY.md
   ```
   - Include ALL files that are part of this task: source, tests, migrations, config changes, PLUS tracking files (TODO.md, MEMORY.md)
+  - Include VRT baseline snapshots (`*-snapshots/` directories) if VRT tests were created or baselines updated in this task
   - If unsure about a file, check `git -C {worktree-path} diff [file]` — if it's related to this task, include it
 - Descriptive message, English, focus on "why" not "what"
 - Conventional commits: feat/fix/refactor/chore/docs
@@ -774,10 +862,38 @@ If a bug is caused by a third-party dependency (confirmed by isolating the issue
 4. At the next dependency freshness check (phase transition or manual), check if a newer version of the package is available. If so, upgrade and re-attempt the blocked task.
 5. If no other tasks are available, log the blocker and end the session with `status: blocked, action: needs_package_update`. The external loop will retry in the next invocation — the dependency freshness check at each session start will detect new versions.
 
+## User Interaction (Interactive Mode)
+
+When the user sends a message during an interactive session (not UNATTENDED mode), **delegate rather than answer directly**:
+
+| User intent | Delegate to | Example |
+|---|---|---|
+| Frontend question/request (components, styling, UI patterns, a11y) | `ui-engineer` (opus) | "How should I structure this form?" |
+| Backend question/request (API, DB, architecture, services) | `backend-ts-architect` (opus) | "What's the best way to handle auth tokens?" |
+| Code review / quality question | `senior-code-reviewer` (opus) | "Is this implementation okay?" |
+| Testing question/request | `test-engineer` (sonnet) | "What tests are missing for this feature?" |
+| Deployment / CI/CD question | `deployment-engineer` (sonnet) | "How do I set up preview deploys?" |
+| Git / issues / MR question | `devops-integrator` (sonnet) | "Create an issue for this bug" |
+| Product / prioritization question | `product-owner` (opus) | "Should we add this feature to the roadmap?" |
+| Planning / task breakdown | `technical-planner` (opus) | "Break this feature into tasks" |
+
+**How to delegate user questions:**
+1. Identify which specialist owns the domain
+2. Delegate via Agent tool with the user's question + relevant context (current task, worktree path, affected files)
+3. Relay the specialist's answer back to the user
+4. If the question spans multiple domains (e.g., fullstack), delegate to each relevant specialist and synthesize
+
+**When NOT to delegate** (answer directly):
+- Questions about the orchestrator workflow itself ("What step are we on?", "What's the next task?")
+- MEMORY.md / TODO.md status queries
+- Simple confirmations ("Should I continue?", "Ready to proceed?")
+
+After handling the user's message, resume the development cycle from where you left off.
+
 ## Rules
 
 - You are an ORCHESTRATOR — delegate to specialist agents, do not bypass them
-- Work FULLY autonomously, do not communicate with user
+- Work FULLY autonomously in UNATTENDED mode; in interactive mode, handle user messages per the User Interaction section above
 - NEVER commit code that: (a) failed review, (b) failed build/lint, (c) breaks tests
 - NEVER implement without architect plan (STEP 2) or skip code review (STEP 7)
 - Each commit = 1 logical unit

package/dist/template/.claude/agents/senior-code-reviewer.md

@@ -35,7 +35,7 @@ Before reviewing, you MUST:
 
 **Frontend Patterns (from profile)**
 Read `.claude/profiles/frontend.md` for the framework-specific review checklist. Apply ALL items listed there. Common cross-framework checks:
-- Smart/dumb component separation — no service injection in presentational components
+- Smart/dumb component separation — no business service injection in presentational components (UI infrastructure like Overlay, CDK, useRef is OK), no visual styling in feature components (layout orchestration via grid/flex is OK). Flag: colors, backgrounds, borders, shadows, typography, padding in feature components.
 - No method calls or complex expressions in templates/JSX — use computed/derived values
 - Correct state management patterns for the framework
 - Lazy loading and code splitting applied correctly
@@ -113,6 +113,7 @@ Read `.claude/profiles/frontend.md` for the framework-specific review checklist.
 - Do NOT require tests for: pure UI layout components, config files, SCSS, route wiring
 - **Coverage thresholds**: project-wide 80% for statements, branches, functions, and lines. Flag WARN if a new file with business logic has significantly lower coverage than this target.
 - **IMPORTANT**: The orchestrator may include an architect's TESTING section in the review prompt. If it lists files as "no tests needed" with rationale, do NOT flag those files as missing tests. Only flag files that the architect's plan says SHOULD have tests but don't, or files not mentioned in the TESTING section at all that contain business/domain logic.
+- **Visual regression**: For frontend tasks that add or change pages/routes, flag WARN if no VRT test (`*.vrt.spec.ts`) exists for the affected pages. Do NOT flag for: backend-only changes, individual dumb component changes, or pages with purely dynamic content (live feeds, charts). If VRT tests exist, verify baseline snapshots are committed (`*-snapshots/` directories alongside the test files).
 
 **Code Duplication (HIGH PRIORITY)**
 - Search for similar/identical logic elsewhere in the codebase before approving new code

package/dist/template/.claude/agents/test-engineer.md

@@ -302,6 +302,103 @@ describe('my-lib public API (integration)', () => {
 - Keep integration tests focused — test the contract/behavior, not internals
 - Integration tests are slower than unit tests — that's expected. Don't optimize for speed at the cost of coverage.
 
+## Visual Regression Testing (Playwright `toHaveScreenshot()`)
+
+Automated pixel-by-pixel comparison against baseline screenshots. Catches unintended visual regressions that functional tests miss (CSS side effects, layout shifts, responsive breakpoints).
+
+### When to write VRT tests
+- **Page-level views** — each route/page gets a VRT test covering default state
+- **Key interactive states** — modal open, form validation errors, empty state, loaded state, skeleton/loading
+- **Multi-component compositions** — dashboards, listings, onboarding flows
+- **Do NOT write VRT for**: individual dumb components in isolation, backend-only tasks, pages with highly dynamic content (live charts, video feeds, real-time data)
+
+### VRT file naming
+- `*.vrt.spec.ts` suffix — co-located with functional E2E tests in `apps/[APP]-e2e/src/` or `e2e/`
+- Example: `checkout.vrt.spec.ts` beside `checkout.spec.ts`
+- Baselines auto-stored in `*.vrt.spec.ts-snapshots/` directories — **commit these to git**
+
+### Viewport matrix
+```typescript
+const VIEWPORTS = [
+  { name: 'mobile', width: 375, height: 812 },
+  { name: 'tablet', width: 768, height: 1024 },
+  { name: 'desktop', width: 1280, height: 720 },
+] as const;
+```
+
+### VRT test template
+```typescript
+import { test, expect } from '@playwright/test';
+
+const VIEWPORTS = [
+  { name: 'mobile', width: 375, height: 812 },
+  { name: 'tablet', width: 768, height: 1024 },
+  { name: 'desktop', width: 1280, height: 720 },
+] as const;
+
+test.describe('Checkout Page — Visual Regression', () => {
+  for (const vp of VIEWPORTS) {
+    test.describe(vp.name, () => {
+      test.use({ viewport: { width: vp.width, height: vp.height } });
+
+      test('default state', async ({ page }) => {
+        await page.goto('/checkout');
+        await page.waitForLoadState('networkidle');
+        await expect(page).toHaveScreenshot(`checkout-default-${vp.name}.png`, {
+          maxDiffPixelRatio: 0.01,
+          fullPage: true,
+        });
+      });
+
+      test('validation errors', async ({ page }) => {
+        await page.goto('/checkout');
+        await page.getByRole('button', { name: 'Pay' }).click();
+        await expect(page).toHaveScreenshot(`checkout-errors-${vp.name}.png`, {
+          maxDiffPixelRatio: 0.01,
+        });
+      });
+    });
+  }
+});
+```
+
+### VRT configuration
+- `maxDiffPixelRatio: 0.01` (1%) — tolerates minor anti-aliasing differences across environments
+- `fullPage: true` for page-level screenshots (captures below-fold content)
+- Omit `fullPage` for component-state screenshots (captures only the viewport)
+- Screenshot name includes viewport name — ensures unique baselines per breakpoint
+- `animations: 'disabled'` in Playwright config `expect.toHaveScreenshot` — prevents flaky diffs from CSS transitions
+
+### Baseline management
+- Baselines live in `*-snapshots/` directories next to the test file — **always commit them to git**
+- When visual changes are **intentional**: run with `--update-snapshots` flag, then commit new baselines
+- **First run** always fails (no baselines exist) — run twice: first creates baselines, second verifies
+- In CI: use the Playwright Docker image (`mcr.microsoft.com/playwright`) for consistent rendering
+
+### Running VRT tests
+```bash
+# Run all E2E (includes VRT)
+nx e2e [APP]-e2e
+
+# Update baselines after intentional visual changes
+nx e2e [APP]-e2e -- --update-snapshots
+
+# Run only VRT tests
+nx e2e [APP]-e2e -- --grep "Visual Regression"
+```
+
+### Anti-flakiness rules (STRICT)
+- Always `await` content visibility before screenshot: `await expect(page.getByText('...')).toBeVisible()`
+- Use `page.waitForLoadState('networkidle')` before page screenshots if the page fetches data
+- Mask dynamic content (timestamps, avatars, user-specific data) using `mask` option:
+  ```typescript
+  await expect(page).toHaveScreenshot('name.png', {
+    mask: [page.locator('.timestamp'), page.locator('.avatar')],
+  });
+  ```
+- If a VRT test is flaky after 3 runs, **delete it** rather than increase the threshold — flaky VRT is worse than no VRT
+- NEVER set `maxDiffPixelRatio` above `0.02` — if more tolerance is needed, the test is measuring the wrong thing
+
 ## Running Tests (MANDATORY)
 
 After writing ALL test files, you MUST run them and report results:

package/dist/template/.claude/agents/ui-engineer.md

@@ -55,13 +55,23 @@ Write clean, elegant code that is easy to test and reason about:
 
 **Dumb components (ui/):**
 - Pure presentational — inputs + event emitters/callbacks + slots/content projection
-- No service injection, no router, no HTTP
+- UI infrastructure injection is allowed (Overlay, ElementRef, Renderer2, CDK, useRef, etc.) — these are UI plumbing, not business logic
+- No business services, no router, no HTTP, no data fetching
 - Fully reusable and testable in isolation
 
 **Feature components (feature/ or pages/):**
 - Smart orchestrators — inject services, manage state
-- Coordinate dumb components
+- Coordinate dumb components via composition and content projection/slots
 - Tied to specific use cases
+- **NO visual styling** — no colors, backgrounds, borders, shadows, typography, padding on content areas, animations. All visual styling belongs in dumb components.
+- **Layout orchestration is OK** — arranging child components via grid/flex (`display: grid/flex`, `grid-template-areas`, `gap`) is acceptable, especially for page-level route components. This is layout plumbing, not visual design.
+- When a page layout pattern is **reused across multiple routes**, extract it to a dumb layout shell component. Single-use layout stays in the feature component — don't create single-use wrapper components just for purity.
+
+**Anti-patterns to watch for:**
+- Dumb component with 8+ inputs → restructure via compound component pattern, slots/projection, or context/provide
+- Feature component coordinating 10+ child components → extract sub-features
+- Single-use layout shell component → unnecessary indirection, keep layout in the feature component
+- Prop drilling through 3+ levels → use slots/projection instead of passing inputs down
 
 ## Approach
 
@@ -121,10 +131,21 @@ Which project patterns apply (smart/dumb, directives/hooks/composables, content
 Common mistakes to avoid for this specific task.
 
 ### TESTING
-Which files need tests and what to test. Be specific:
+Which files need tests and what to test. **You MUST specify test layers explicitly** — don't leave it to the orchestrator to guess:
+
+**Unit tests** (always, for files with logic):
 - `path/to/file.ts` — test cases: [list key scenarios, edge cases, error conditions]
 - `path/to/other.ts` — no tests needed (pure UI layout / config / styles)
-This section is used by the orchestrator to decide whether to call `test-engineer` in STEP 4.
+
+**E2E tests** (REQUIRED for any task that adds/changes user-facing flows — navigation, forms, multi-step interactions, authentication, CRUD operations):
+- Routes/flows to cover: [list routes and user scenarios]
+- If no E2E needed, write: "E2E: not applicable (no user-facing flow changes)"
+
+**VRT tests** (REQUIRED for any task that adds new pages or significantly changes page layout/visual appearance):
+- Pages/views to screenshot: [list routes with viewport matrix]
+- If no VRT needed, write: "VRT: not applicable (no page-level visual changes)"
+
+Be explicit about every layer — omitting a layer means no tests for it.
 
 ### API CONTRACT FEEDBACK (optional, fullstack tasks only)
 If you received an API contract from the backend architect and it is impractical for the UI (too many round trips, missing pagination, wrong data shape for components, missing fields needed for display), list the specific issues and suggest changes. The orchestrator will send this feedback to the backend architect for revision.
@@ -136,6 +157,7 @@ Only include this section if splitting is genuinely needed — do NOT split task
 
 ### VERIFICATION
 How to verify the implementation is correct (build, visual check, test scenarios).
+If the task adds or changes page-level UI, include: "Update VRT baselines if visual output changed intentionally." This signals to the orchestrator that STEP 4 should include VRT baseline updates.
 
 ---
 

package/dist/template/.claude/profiles/angular.md

@@ -69,9 +69,20 @@ After generation, the architect's plan specifies what code to write IN the gener
 - Each component = separate `.ts`, `.html`, `.scss` files
 
 **Feature vs Dumb components (STRICT separation):**
-- **Dumb (ui/)**: Pure presentational. Input signals + output emitters + content projection. No inject(), no services, no router, no HTTP. Fully reusable.
-- **Feature (feature/ or pages/)**: Smart orchestrators. Inject services, manage state, coordinate dumb components. NOT reusable — tied to a specific use case.
-- Rule: if a component needs `inject()`, it belongs in `feature/` or `pages/`, not `ui/`
+- **Dumb (ui/)**: Pure presentational. Input signals + output emitters + content projection. No business services, no router, no HTTP, no data fetching. Fully reusable.
+  - **UI infrastructure `inject()` is allowed**: `Overlay`, `ElementRef`, `Renderer2`, `ViewContainerRef`, `AnimationBuilder`, `DestroyRef`, CDK primitives — these are UI plumbing, not business logic. The component stays presentational.
+  - **NOT allowed**: data services, `HttpClient`, `Router`, `ActivatedRoute`, stores, any service that fetches/mutates application state.
+- **Feature (feature/ or pages/)**: Smart orchestrators. Inject services, manage state, coordinate dumb components via composition and `<ng-content>`. NOT reusable — tied to a specific use case.
+  - **NO visual styling**: no colors, backgrounds, borders, shadows, typography, padding on content areas, animations. All visual styling belongs in dumb components.
+  - **Layout orchestration is OK**: `:host { display: block/grid/flex }`, `grid-template-areas`, `grid-template-columns`, `gap` are acceptable for arranging child dumb components — this is layout plumbing, not visual design.
+  - When a layout pattern is **reused across multiple routes**, extract it to a dumb layout shell (e.g., `lib-dashboard-layout`). Single-use page layout stays in the feature component.
+- Rule: if a component injects **business services** (data, state, API, router), it belongs in `feature/` or `pages/`, not `ui/`. UI infrastructure injection (`Overlay`, `ElementRef`, CDK) is fine in `ui/`.
+
+**Anti-patterns:**
+- Dumb component with 8+ inputs → restructure via compound component pattern, `<ng-content>`, or hierarchical DI (`provide`/`inject`)
+- Feature component coordinating 10+ child components → extract sub-features
+- Single-use layout shell component → unnecessary indirection, keep layout in the feature component
+- Prop drilling through 3+ levels → use content projection instead of passing inputs down
 
 **Content projection (composite pattern):**
 - Prefer `<ng-content>` and `<ng-content select="...">` over deep @Input trees
@@ -299,9 +310,9 @@ npx themecraft generate    # generates type-safe SCSS from tokens.json
 4. `@themecraft/core/themes` → `variables()` mixin emits CSS custom properties at `:root`
 5. `@themecraft/angular` → `provideTheme()` for runtime switching, `provideThemeServer()` for SSR (no FOUC)
 
-**Component SCSS** — import via package name, NEVER use relative paths, NEVER call `color-var()`/`size-var()` directly:
+**Component SCSS** — import via workspace package name, NEVER use relative paths or `generated/` paths, NEVER call `color-var()`/`size-var()` directly:
 ```scss
-// Import via package name (configured in tsconfig/package.json paths)
+// Import via workspace package name (linked in package.json)
 // SCSS @use automatically uses the last path segment as namespace — no `as` needed
 @use 'theme/colors';
 @use 'theme/sizes';
@@ -318,56 +329,48 @@ npx themecraft generate    # generates type-safe SCSS from tokens.json
 ```
 
 **SCSS import rules:**
-- ALWAYS import via package/library name (e.g. `@use 'theme/colors'`)
-- NEVER use relative paths (`../../theme/src/generated/...`) — they break on refactoring and are unreadable
+- ALWAYS import via workspace package name (e.g. `@use 'theme/colors'` or `@use '@[scope]/theme/colors'`)
+- NEVER use relative paths (`../../theme/src/...`) — they break on refactoring and are unreadable
+- NEVER use `generated/` paths (`@use 'generated/theme/colors'`) — the package link abstracts this away
 - NEVER use redundant `as` aliases that match the last path segment (`@use 'theme/colors' as colors` → just `@use 'theme/colors'`). Only use `as` when you need a different name.
 
-**Making theme resolvable by package name (priority order):**
-1. **Workspace dependency in package.json** (preferred) — add the theme library as a workspace dependency so SCSS resolves it from `node_modules`:
-   ```jsonc
-   // package.json (root or consuming app)
-   {
-     "dependencies": {
-       "@[prefix]/theme": "workspace:./libs/shared/ui/theme"  // bun/pnpm
-       // or "file:./libs/shared/ui/theme" for npm
-     }
-   }
-   ```
-   Then `<PM> install` creates the link. SCSS `@use '@[prefix]/theme/colors'` resolves automatically.
-2. **`stylePreprocessorOptions.includePaths`** (fallback) — if workspace dependency is not feasible:
-   ```jsonc
-   // project.json or angular.json
-   {
-     "build": {
-       "options": {
-         "stylePreprocessorOptions": {
-           "includePaths": ["libs/shared/ui/theme/src"]
-         }
-       }
-     }
-   }
-   ```
-
-**How it works:** `npx themecraft generate` reads `tokens.json` and produces typed SCSS files (`generated/theme/colors.scss`, `sizes.scss`, `typography.scss`) that wrap `color-var()`/`size-var()` internally. Components consume these generated variables — never the raw accessor functions.
+**Making theme resolvable by package name (MANDATORY):**
+
+Add the theme library as a workspace dependency in `package.json` so SCSS resolves `@use 'theme/...'` from `node_modules`:
+```jsonc
+// package.json (root or consuming app)
+{
+  "dependencies": {
+    "theme": "workspace:./libs/shared/ui/theme"       // pnpm/bun
+    // or "file:./libs/shared/ui/theme" for npm
+    // If repo has a scope: "@[scope]/theme": "workspace:./libs/shared/ui/theme"
+  }
+}
+```
+Then run `<PM> install` to create the link. SCSS `@use 'theme/colors'` (or `@use '@[scope]/theme/colors'` with scope) resolves automatically.
+
+**NEVER use `stylePreprocessorOptions.includePaths`** — workspace dependency is the only supported approach. `includePaths` breaks IDE autocomplete, makes imports ambiguous, and doesn't survive refactoring.
+
+**How it works:** `npx themecraft generate` runs inside the theme library (`libs/shared/ui/theme/`) and produces typed SCSS files (`src/colors.scss`, `sizes.scss`, `typography.scss`) that wrap `color-var()`/`size-var()` internally. Because the library is linked as a package, `@use 'theme/colors'` resolves to these generated files. Components consume the generated variables — never the raw accessor functions, never `generated/` paths.
 
 **Token source (pick one):**
 - **With Figma:** `npx themecraft figma-sync` pulls design variables into `tokens.json`, then `npx themecraft generate`
 - **Without Figma:** `npx themecraft init` creates `tokens.json` scaffold → manually define token names (color groups, size groups, typography levels) → `npx themecraft generate`
 
-Either way, the result is the same: typed SCSS files in `generated/theme/` ready to import.
+Either way, the result is the same: typed SCSS files inside the theme library, importable via `@use 'theme/colors'`.
 
 **Theme definition** (`themes/light.scss`):
 ```scss
 @use '@themecraft/core/theming' as theming;
-@use '@themecraft/core/themes' as themes;
-
-themes.$themes: (
-  light: theming.define-light-theme((
-    color: theming.define-color-scheme(( surface: #ffffff, on-surface: #1a1a1a, primary: #0066cc )),
-    size: theming.define-sizes(( card-padding: theming.size(12px, 16px, 24px) )),
-    typography: ( body-primary: theming.define-typography-level(16px, 1.5, 400, 'Inter, sans-serif') ),
-    breakpoint: ( medium: 768px, large: 1200px ),
-  ))
+@use '@themecraft/core/themes' as themes with (
+  $themes: (
+    light: theming.define-light-theme((
+      color: theming.define-color-scheme(( surface: #ffffff, on-surface: #1a1a1a, primary: #0066cc )),
+      size: theming.define-sizes(( card-padding: theming.size(12px, 16px, 24px) )),
+      typography: ( body-primary: theming.define-typography-level(16px, 1.5, 400, 'Inter, sans-serif') ),
+      breakpoint: ( medium: 768px, large: 1200px ),
+    ))
+  )
 );
 
 @include themes.variables();
@@ -460,6 +463,38 @@ describe('CardBadge', () => {
 });
 ```
 
+## Playwright VRT Configuration
+
+Add to `playwright.config.ts` in the E2E project (`apps/[APP]-e2e/` or `e2e/`):
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './src',
+  testMatch: ['**/*.spec.ts', '**/*.vrt.spec.ts'],
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  use: {
+    baseURL: 'http://localhost:4200',
+    trace: 'on-first-retry',
+  },
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.01,
+      animations: 'disabled',
+    },
+  },
+  webServer: {
+    command: 'nx serve [APP]',
+    url: 'http://localhost:4200',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+In CI, use the Playwright Docker image for consistent rendering: `mcr.microsoft.com/playwright:v[version]-jammy`.
+
 ## Angular Review Checklist
 
 When reviewing Angular code, check:
@@ -467,7 +502,7 @@ When reviewing Angular code, check:
 - Forms: signal forms API used (no legacy FormControl/FormGroup/FormBuilder)
 - Component file organization: each component in its own subdirectory (not flat in lib/)
 - ZERO method calls in templates — all derived state in computed()
-- Feature vs dumb separation — no inject() in ui/ components
+- Feature vs dumb separation — no business service injection in ui/ components (UI infrastructure like Overlay, ElementRef, CDK is OK), no visual styling in feature/ components (layout orchestration via `:host { display: grid/flex }` + `gap` + `grid-template` is OK)
 - Content projection (composite pattern) over deep @Input trees
 - Behavior extracted to directives (not duplicated across components)
 - @for has track expression (by unique id, not index)
@@ -478,8 +513,9 @@ When reviewing Angular code, check:
 - Resource disposal (ImageBitmap.close(), stream.stop(), BroadcastChannel.close())
 - No memory leaks in effects or event listeners
 - Theme compliance: generated @themecraft SCSS variables — no hardcoded colors/sizes, no direct `color-var()`/`size-var()` calls
-- SCSS imports: via package name (no relative paths), no redundant `as` aliases
+- SCSS imports: via workspace package name (no relative paths, no `generated/` paths), no redundant `as` aliases
 - Lazy loading via loadComponent/loadChildren, no eager page imports
 - @defer for heavy below-fold components
 - Naming: PascalCase components, lib- selectors, kebab-case files
-- i18n: ALL user-facing text has `i18n` attribute (templates) or `$localize` (TS) — no bare text
+- i18n: ALL user-facing text has `i18n` attribute (templates) or `$localize` (TS) — no bare text
+- VRT: new pages/routes have corresponding `*.vrt.spec.ts` with 3-viewport coverage (375px, 768px, 1280px), baseline snapshots committed

package/dist/template/.claude/profiles/react.md

@@ -54,9 +54,20 @@ src/
 - One component per file, named after its default/named export
 
 **Container vs Presentational components (STRICT separation):**
-- **Presentational (ui/)**: Pure rendering. Props in, JSX out. No hooks that cause side effects, no data fetching, no direct service calls. Fully reusable and trivially testable.
+- **Presentational (ui/)**: Pure rendering. Props in, JSX out. No data fetching, no application state hooks, no direct service calls. Fully reusable and trivially testable.
+  - **UI-infrastructure hooks are allowed**: `useRef` for DOM measurement, `useState` for local UI state (open/closed, animation phase), `useCallback` for stable callbacks. The component stays presentational.
+  - **NOT allowed**: data-fetching hooks, application state hooks, `useEffect` for side effects, direct API calls.
 - **Container (components/ or pages/)**: Smart orchestrators. Use hooks, fetch data, manage state, coordinate presentational components. Tied to a specific use case.
-- Rule: if a component calls `useEffect`, fetches data, or accesses context directly, it belongs in `components/` or `pages/`, not `ui/`
+  - **NO visual styling**: no colors, backgrounds, borders, shadows, typography, padding on content areas, animations. All visual styling belongs in presentational components.
+  - **Layout orchestration is OK**: arranging child components via grid/flex (`display: grid/flex`, `grid-template-areas`, `gap`) is acceptable, especially for page-level route components. This is layout plumbing, not visual design.
+  - When a layout pattern is **reused across multiple routes**, extract it to a presentational layout component. Single-use page layout stays in the container.
+- Rule: if a component calls `useEffect` for data fetching, accesses application state context, or calls APIs, it belongs in `components/` or `pages/`, not `ui/`
+
+**Anti-patterns:**
+- Presentational component with 8+ props → restructure via compound component pattern, `children`, or context
+- Container coordinating 10+ child components → extract sub-containers
+- Single-use layout wrapper → unnecessary indirection, keep layout in the container
+- Prop drilling through 3+ levels → use composition (`children`/render props) or context
 
 **Compound components (composition over prop drilling):**
 - Prefer `children` and render slots over deep prop trees
@@ -190,7 +201,7 @@ npx themecraft generate    # generates type-safe SCSS from tokens.json
 4. `@themecraft/core/themes` → `variables()` mixin emits CSS custom properties at `:root`
 5. `ThemeManager` (from `@themecraft/core/runtime`) — runtime theme switching, storage persistence, FOUC prevention
 
-**Component SCSS** (`.module.scss`) — import via package name, NEVER use relative paths, NEVER call `color-var()`/`size-var()` directly:
+**Component SCSS** (`.module.scss`) — import via workspace package name, NEVER use relative paths or `generated/` paths, NEVER call `color-var()`/`size-var()` directly:
 ```scss
 // Import via package name — SCSS @use uses last path segment as namespace automatically
 @use 'theme/colors';
@@ -208,31 +219,35 @@ npx themecraft generate    # generates type-safe SCSS from tokens.json
 ```
 
 **SCSS import rules:**
-- ALWAYS import via package/library name (e.g. `@use 'theme/colors'`)
-- NEVER use relative paths (`../../theme/src/generated/...`) — they break on refactoring and are unreadable
+- ALWAYS import via workspace package name (e.g. `@use 'theme/colors'` or `@use '@[scope]/theme/colors'`)
+- NEVER use relative paths (`../../theme/src/...`) — they break on refactoring and are unreadable
+- NEVER use `generated/` paths (`@use 'generated/theme/colors'`) — the package link abstracts this away
 - NEVER use redundant `as` aliases that match the last path segment (`@use 'theme/colors' as colors` → just `@use 'theme/colors'`). Only use `as` when you need a different name.
 
-**Making theme resolvable by package name (priority order):**
-1. **Workspace dependency in package.json** (preferred) — add the theme library as a workspace dependency so SCSS resolves it from `node_modules`:
-   ```jsonc
-   // package.json (root or consuming app)
-   {
-     "dependencies": {
-       "@[prefix]/theme": "workspace:./libs/shared/ui/theme"  // bun/pnpm
-       // or "file:./libs/shared/ui/theme" for npm
-     }
-   }
-   ```
-   Then `<PM> install` creates the link. SCSS `@use '@[prefix]/theme/colors'` resolves automatically.
-2. **Bundler/framework SCSS config** (fallback) — e.g. `sassOptions.includeDirs` in `next.config.js`, or Vite `css.preprocessorOptions.scss.includePaths`.
-
-**How it works:** `npx themecraft generate` reads `tokens.json` and produces typed SCSS files (`generated/theme/colors.scss`, `sizes.scss`, `typography.scss`) that wrap `color-var()`/`size-var()` internally. Components consume these generated variables — never the raw accessor functions.
+**Making theme resolvable by package name (MANDATORY):**
+
+Add the theme library as a workspace dependency in `package.json` so SCSS resolves `@use 'theme/...'` from `node_modules`:
+```jsonc
+// package.json (root or consuming app)
+{
+  "dependencies": {
+    "theme": "workspace:./libs/shared/ui/theme"       // pnpm/bun
+    // or "file:./libs/shared/ui/theme" for npm
+    // If repo has a scope: "@[scope]/theme": "workspace:./libs/shared/ui/theme"
+  }
+}
+```
+Then run `<PM> install` to create the link. SCSS `@use 'theme/colors'` (or `@use '@[scope]/theme/colors'` with scope) resolves automatically.
+
+**NEVER use `sassOptions.includeDirs` or `css.preprocessorOptions.scss.includePaths`** — workspace dependency is the only supported approach.
+
+**How it works:** `npx themecraft generate` runs inside the theme library and produces typed SCSS files (`src/colors.scss`, `sizes.scss`, `typography.scss`) that wrap `color-var()`/`size-var()` internally. Because the library is linked as a package, `@use 'theme/colors'` resolves to these generated files. Components consume the generated variables — never the raw accessor functions, never `generated/` paths.
 
 **Token source (pick one):**
 - **With Figma:** `npx themecraft figma-sync` pulls design variables into `tokens.json`, then `npx themecraft generate`
 - **Without Figma:** `npx themecraft init` creates `tokens.json` scaffold → manually define token names (color groups, size groups, typography levels) → `npx themecraft generate`
 
-Either way, the result is the same: typed SCSS files in `generated/theme/` ready to import.
+Either way, the result is the same: typed SCSS files inside the theme library, importable via `@use 'theme/colors'`.
 
 **Runtime setup** (in layout or `_app.tsx`):
 ```typescript
@@ -321,12 +336,44 @@ describe('CardBadge', () => {
 - Test behavior, not implementation — don't assert on state variables or hook internals
 - Mock server state with MSW (Mock Service Worker) or TanStack Query's test utilities
 
+## Playwright VRT Configuration
+
+Add to `playwright.config.ts` in the E2E project:
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './src',
+  testMatch: ['**/*.spec.ts', '**/*.vrt.spec.ts'],
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+  },
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.01,
+      animations: 'disabled',
+    },
+  },
+  webServer: {
+    command: 'nx serve [APP]',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+Adjust `baseURL`/`url` to match the dev server port (Next.js: 3000, Vite: 5173). In CI, use the Playwright Docker image for consistent rendering.
+
 ## React Review Checklist
 
 When reviewing React code, check:
 - Hooks rules: no conditional hooks, no hooks inside loops or nested functions
 - `useMemo`/`useCallback` usage: present where needed (expensive computations, stable references for children), absent where unnecessary (premature optimization)
-- Container vs presentational separation — no data fetching or side effects in ui/ components
+- Container vs presentational separation — no data fetching or app state in ui/ components (UI hooks like useRef/useState for UI state are OK), no visual styling in container components (layout orchestration via grid/flex is OK)
 - Composition via children/compound components over deep prop drilling
 - Custom hooks extracted for shared behavior (not duplicated across components)
 - `key` prop on list items uses unique stable id, never array index
@@ -337,10 +384,11 @@ When reviewing React code, check:
 - Server/client separation: Flag WARN if a module mixes server and browser logic without clear boundaries
 - No memory leaks in effects, event listeners, or subscriptions
 - Theme compliance: generated @themecraft SCSS variables — no hardcoded colors/sizes, no direct `color-var()`/`size-var()` calls
-- SCSS imports: via package name (no relative paths), no redundant `as` aliases
+- SCSS imports: via workspace package name (no relative paths, no `generated/` paths), no redundant `as` aliases
 - Code splitting: `React.lazy` + `Suspense` for heavy routes/components, no eager imports of page-level components
 - Dynamic imports for heavy third-party libraries
 - Naming: PascalCase components, camelCase hooks, kebab-case files
 - i18n: ALL user-facing text goes through `t()` — no bare strings in JSX or UI logic
 - No unstable nested component definitions (components defined inside render)
 - `React.memo` only on components with measured re-render cost — not as a default
+- VRT: new pages/routes have corresponding `*.vrt.spec.ts` with 3-viewport coverage (375px, 768px, 1280px), baseline snapshots committed

package/dist/template/.claude/profiles/svelte.md

@@ -48,8 +48,17 @@ src/
 **Feature vs Dumb components (STRICT separation):**
 - **Dumb (ui/)**: Pure presentational. `$props()` for inputs, callback props for events, slots/snippets for composition. No data fetching, no navigation, no global state access. Fully reusable.
 - **Feature (features/ or routes/)**: Smart orchestrators. Access load data, manage state, call APIs, coordinate dumb components. NOT reusable — tied to a specific use case.
+  - **NO visual styling**: no colors, backgrounds, borders, shadows, typography, padding on content areas, animations. All visual styling belongs in dumb components.
+  - **Layout orchestration is OK**: arranging child components via grid/flex (`display: grid/flex`, `grid-template-areas`, `gap`) is acceptable, especially for page-level route components.
+  - When a layout pattern is **reused across multiple routes**, extract it to a dumb layout component (e.g., `DashboardLayout.svelte`). Single-use page layout stays in the feature component.
 - Rule: if a component fetches data or accesses global state, it belongs in `features/` or `routes/`, not `ui/`
 
+**Anti-patterns:**
+- Dumb component with 8+ props → restructure via compound component pattern, `<slot>`s, or context
+- Feature component coordinating 10+ child components → extract sub-features
+- Single-use layout shell component → unnecessary indirection, keep layout in the feature component
+- Prop drilling through 3+ levels → use slots or Svelte context
+
 **Composition patterns:**
 - Prefer slots (`<slot>`) and named slots (`<slot name="header">`) over deep prop drilling
 - Use snippet blocks (`{#snippet}`) for typed, reusable template fragments within a component
@@ -190,7 +199,7 @@ npx themecraft generate    # generates type-safe SCSS from tokens.json
 4. `@themecraft/core/themes` → `variables()` mixin emits CSS custom properties at `:root`
 5. `ThemeManager` (from `@themecraft/core/runtime`) — runtime switching, storage, FOUC prevention
 
-**Component SCSS** — import via package name, NEVER use relative paths, NEVER call `color-var()`/`size-var()` directly:
+**Component SCSS** — import via workspace package name, NEVER use relative paths or `generated/` paths, NEVER call `color-var()`/`size-var()` directly:
 ```svelte
 <style lang="scss">
   // Import via package name — SCSS @use uses last path segment as namespace automatically
@@ -210,31 +219,35 @@ npx themecraft generate    # generates type-safe SCSS from tokens.json
 ```
 
 **SCSS import rules:**
-- ALWAYS import via package/library name (e.g. `@use 'theme/colors'`)
-- NEVER use relative paths (`../../theme/src/generated/...`) — they break on refactoring and are unreadable
+- ALWAYS import via workspace package name (e.g. `@use 'theme/colors'` or `@use '@[scope]/theme/colors'`)
+- NEVER use relative paths (`../../theme/src/...`) — they break on refactoring and are unreadable
+- NEVER use `generated/` paths (`@use 'generated/theme/colors'`) — the package link abstracts this away
 - NEVER use redundant `as` aliases that match the last path segment (`@use 'theme/colors' as colors` → just `@use 'theme/colors'`). Only use `as` when you need a different name.
 
-**Making theme resolvable by package name (priority order):**
-1. **Workspace dependency in package.json** (preferred) — add the theme library as a workspace dependency so SCSS resolves it from `node_modules`:
-   ```jsonc
-   // package.json (root or consuming app)
-   {
-     "dependencies": {
-       "@[prefix]/theme": "workspace:./libs/shared/ui/theme"  // bun/pnpm
-       // or "file:./libs/shared/ui/theme" for npm
-     }
-   }
-   ```
-   Then `<PM> install` creates the link. SCSS `@use '@[prefix]/theme/colors'` resolves automatically.
-2. **SvelteKit SCSS config** (fallback) — `css.preprocessorOptions.scss.includePaths` in `vite.config.ts`.
-
-**How it works:** `npx themecraft generate` reads `tokens.json` and produces typed SCSS files (`generated/theme/colors.scss`, `sizes.scss`, `typography.scss`) that wrap `color-var()`/`size-var()` internally. Components consume these generated variables — never the raw accessor functions.
+**Making theme resolvable by package name (MANDATORY):**
+
+Add the theme library as a workspace dependency in `package.json` so SCSS resolves `@use 'theme/...'` from `node_modules`:
+```jsonc
+// package.json (root or consuming app)
+{
+  "dependencies": {
+    "theme": "workspace:./libs/shared/ui/theme"       // pnpm/bun
+    // or "file:./libs/shared/ui/theme" for npm
+    // If repo has a scope: "@[scope]/theme": "workspace:./libs/shared/ui/theme"
+  }
+}
+```
+Then run `<PM> install` to create the link. SCSS `@use 'theme/colors'` (or `@use '@[scope]/theme/colors'` with scope) resolves automatically.
+
+**NEVER use `css.preprocessorOptions.scss.includePaths`** — workspace dependency is the only supported approach.
+
+**How it works:** `npx themecraft generate` runs inside the theme library and produces typed SCSS files (`src/colors.scss`, `sizes.scss`, `typography.scss`) that wrap `color-var()`/`size-var()` internally. Because the library is linked as a package, `@use 'theme/colors'` resolves to these generated files. Components consume the generated variables — never the raw accessor functions, never `generated/` paths.
 
 **Token source (pick one):**
 - **With Figma:** `npx themecraft figma-sync` pulls design variables into `tokens.json`, then `npx themecraft generate`
 - **Without Figma:** `npx themecraft init` creates `tokens.json` scaffold → manually define token names (color groups, size groups, typography levels) → `npx themecraft generate`
 
-Either way, the result is the same: typed SCSS files in `generated/theme/` ready to import.
+Either way, the result is the same: typed SCSS files inside the theme library, importable via `@use 'theme/colors'`.
 
 **Runtime setup** (in `+layout.svelte` or `hooks.server.ts`):
 ```typescript
@@ -324,6 +337,38 @@ describe('CardBadge', () => {
 });
 ```
 
+## Playwright VRT Configuration
+
+Add to `playwright.config.ts` in the E2E project:
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './src',
+  testMatch: ['**/*.spec.ts', '**/*.vrt.spec.ts'],
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  use: {
+    baseURL: 'http://localhost:5173',
+    trace: 'on-first-retry',
+  },
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.01,
+      animations: 'disabled',
+    },
+  },
+  webServer: {
+    command: 'nx serve [APP]',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+In CI, use the Playwright Docker image for consistent rendering: `mcr.microsoft.com/playwright:v[version]-jammy`.
+
 ## Svelte Review Checklist
 
 When reviewing Svelte code, check:
@@ -332,7 +377,7 @@ When reviewing Svelte code, check:
 - `$derived()` for all computed values — no recalculation in templates or reactive statements
 - `$state.raw()` for large data that doesn't need deep reactivity
 - `{#each}` has key expression `(item.id)` — NEVER keyed by index
-- Feature vs dumb separation — no data fetching or global state in `ui/` components
+- Feature vs dumb separation — no data fetching or global state in `ui/` components, no visual styling in feature/ components (layout orchestration via grid/flex is OK)
 - Composition via slots/snippets over deep prop drilling
 - Reusable DOM behavior extracted to actions (`use:`) — not duplicated across components
 - SSR safety: no `window`/`document`/`navigator` in server-reachable code, use `browser` guard or `onMount`
@@ -340,10 +385,11 @@ When reviewing Svelte code, check:
 - `$lib/` imports — no deep relative paths (`../../../`)
 - `$lib/server/` for server-only modules — enforced by SvelteKit
 - Theme compliance: generated @themecraft SCSS variables — no hardcoded colors/sizes, no direct `color-var()`/`size-var()` calls
-- SCSS imports: via package name (no relative paths), no redundant `as` aliases
+- SCSS imports: via workspace package name (no relative paths, no `generated/` paths), no redundant `as` aliases
 - Lazy loading: routes auto-split, dynamic `import()` for heavy non-route components
 - i18n: ALL user-facing text goes through translation functions — no bare strings in templates
 - Accessibility: all Svelte compiler a11y warnings resolved (not suppressed)
 - No `{@html}` without sanitization
 - Callback props for outputs (not `createEventDispatcher` — that's Svelte 4)
 - Resource cleanup in `onDestroy` or `$effect` return for manual subscriptions
+- VRT: new pages/routes have corresponding `*.vrt.spec.ts` with 3-viewport coverage (375px, 768px, 1280px), baseline snapshots committed

package/dist/template/.claude/profiles/vue.md

@@ -58,9 +58,19 @@ src/
 
 **Feature vs Dumb components (STRICT separation):**
 - **Dumb (ui/components/)**: Pure presentational. `defineProps` + `defineEmits` + slots. No store access, no router, no HTTP, no side effects. Fully reusable.
+- **Dumb UI-infrastructure usage is allowed**: `useTemplateRef`, `nextTick`, `useSlots` — these are UI plumbing, not business logic.
 - **Feature (features/[domain]/components/ or pages/)**: Smart orchestrators. Use composables, access stores, call APIs, coordinate dumb components. NOT reusable — tied to a specific use case.
+  - **NO visual styling**: no colors, backgrounds, borders, shadows, typography, padding on content areas, animations. All visual styling belongs in dumb components.
+  - **Layout orchestration is OK**: arranging child components via grid/flex (`display: grid/flex`, `grid-template-areas`, `gap`) is acceptable, especially for page-level route components.
+  - When a layout pattern is **reused across multiple routes**, extract it to a dumb layout component (e.g., `DashboardLayout.vue`). Single-use page layout stays in the feature component.
 - Rule: if a component imports a store or calls an API, it belongs in `features/` or `pages/`, not `ui/`
 
+**Anti-patterns:**
+- Dumb component with 8+ props → restructure via compound component pattern, `<slot>`s, or `provide`/`inject`
+- Feature component coordinating 10+ child components → extract sub-features
+- Single-use layout shell component → unnecessary indirection, keep layout in the feature component
+- Prop drilling through 3+ levels → use slots or `provide`/`inject`
+
 **Slots (composite pattern):**
 - Prefer slots over deep prop drilling for component composition
 - Default slot for primary content: `<slot />`
@@ -217,7 +227,7 @@ npx themecraft generate    # generates type-safe SCSS from tokens.json
 4. `@themecraft/core/themes` → `variables()` mixin emits CSS custom properties at `:root`
 5. `ThemeManager` (from `@themecraft/core/runtime`) — runtime switching, storage, FOUC prevention
 
-**Component SCSS** — import via package name, NEVER use relative paths, NEVER call `color-var()`/`size-var()` directly:
+**Component SCSS** — import via workspace package name, NEVER use relative paths or `generated/` paths, NEVER call `color-var()`/`size-var()` directly:
 ```vue
 <style scoped lang="scss">
 // Import via package name — SCSS @use uses last path segment as namespace automatically
@@ -237,31 +247,35 @@ npx themecraft generate    # generates type-safe SCSS from tokens.json
 ```
 
 **SCSS import rules:**
-- ALWAYS import via package/library name (e.g. `@use 'theme/colors'`)
-- NEVER use relative paths (`../../theme/src/generated/...`) — they break on refactoring and are unreadable
+- ALWAYS import via workspace package name (e.g. `@use 'theme/colors'` or `@use '@[scope]/theme/colors'`)
+- NEVER use relative paths (`../../theme/src/...`) — they break on refactoring and are unreadable
+- NEVER use `generated/` paths (`@use 'generated/theme/colors'`) — the package link abstracts this away
 - NEVER use redundant `as` aliases that match the last path segment (`@use 'theme/colors' as colors` → just `@use 'theme/colors'`). Only use `as` when you need a different name.
 
-**Making theme resolvable by package name (priority order):**
-1. **Workspace dependency in package.json** (preferred) — add the theme library as a workspace dependency so SCSS resolves it from `node_modules`:
-   ```jsonc
-   // package.json (root or consuming app)
-   {
-     "dependencies": {
-       "@[prefix]/theme": "workspace:./libs/shared/ui/theme"  // bun/pnpm
-       // or "file:./libs/shared/ui/theme" for npm
-     }
-   }
-   ```
-   Then `<PM> install` creates the link. SCSS `@use '@[prefix]/theme/colors'` resolves automatically.
-2. **Vite SCSS config** (fallback) — `css.preprocessorOptions.scss.includePaths` in `vite.config.ts`.
-
-**How it works:** `npx themecraft generate` reads `tokens.json` and produces typed SCSS files (`generated/theme/colors.scss`, `sizes.scss`, `typography.scss`) that wrap `color-var()`/`size-var()` internally. Components consume these generated variables — never the raw accessor functions.
+**Making theme resolvable by package name (MANDATORY):**
+
+Add the theme library as a workspace dependency in `package.json` so SCSS resolves `@use 'theme/...'` from `node_modules`:
+```jsonc
+// package.json (root or consuming app)
+{
+  "dependencies": {
+    "theme": "workspace:./libs/shared/ui/theme"       // pnpm/bun
+    // or "file:./libs/shared/ui/theme" for npm
+    // If repo has a scope: "@[scope]/theme": "workspace:./libs/shared/ui/theme"
+  }
+}
+```
+Then run `<PM> install` to create the link. SCSS `@use 'theme/colors'` (or `@use '@[scope]/theme/colors'` with scope) resolves automatically.
+
+**NEVER use `css.preprocessorOptions.scss.includePaths`** — workspace dependency is the only supported approach.
+
+**How it works:** `npx themecraft generate` runs inside the theme library and produces typed SCSS files (`src/colors.scss`, `sizes.scss`, `typography.scss`) that wrap `color-var()`/`size-var()` internally. Because the library is linked as a package, `@use 'theme/colors'` resolves to these generated files. Components consume the generated variables — never the raw accessor functions, never `generated/` paths.
 
 **Token source (pick one):**
 - **With Figma:** `npx themecraft figma-sync` pulls design variables into `tokens.json`, then `npx themecraft generate`
 - **Without Figma:** `npx themecraft init` creates `tokens.json` scaffold → manually define token names (color groups, size groups, typography levels) → `npx themecraft generate`
 
-Either way, the result is the same: typed SCSS files in `generated/theme/` ready to import.
+Either way, the result is the same: typed SCSS files inside the theme library, importable via `@use 'theme/colors'`.
 
 **Runtime setup** (in `App.vue` or plugin):
 ```typescript
@@ -348,13 +362,45 @@ describe('UserCard', () => {
 
 **Pinia stores:** Use `setActivePinia(createPinia())` in `beforeEach`, then test store actions/getters directly.
 
+## Playwright VRT Configuration
+
+Add to `playwright.config.ts` in the E2E project:
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './src',
+  testMatch: ['**/*.spec.ts', '**/*.vrt.spec.ts'],
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  use: {
+    baseURL: 'http://localhost:5173',
+    trace: 'on-first-retry',
+  },
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.01,
+      animations: 'disabled',
+    },
+  },
+  webServer: {
+    command: 'nx serve [APP]',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+Adjust `baseURL`/`url` to match the dev server port (Vite: 5173, Nuxt: 3000). In CI, use the Playwright Docker image for consistent rendering.
+
 ## Vue Review Checklist
 
 When reviewing Vue code, check:
 - Composition API only — no Options API (`data()`, `methods`, `computed` object syntax)
 - `<script setup>` in all SFCs — no `defineComponent()` with `setup()` function
 - ZERO method calls in templates — all derived state in `computed()`
-- Feature vs dumb separation — no store access or API calls in `ui/` components
+- Feature vs dumb separation — no store access or API calls in `ui/` components (UI infrastructure like `useTemplateRef`/`nextTick` is OK), no visual styling in feature/ components (layout orchestration via grid/flex is OK)
 - Slots used for composition over deep prop drilling
 - Composables (`use*`) for shared stateful logic — not mixins, not utility classes
 - Custom directives for shared DOM behavior — not duplicated across components
@@ -368,10 +414,11 @@ When reviewing Vue code, check:
 - SSR/Client separation: Flag WARN if a composable mixes server and browser logic
 - `<style scoped>` on all components — no unscoped styles leaking globally
 - Theme compliance: generated @themecraft SCSS variables — no hardcoded colors/sizes, no direct `color-var()`/`size-var()` calls
-- SCSS imports: via package name (no relative paths), no redundant `as` aliases
+- SCSS imports: via workspace package name (no relative paths, no `generated/` paths), no redundant `as` aliases
 - Lazy loading: `defineAsyncComponent` for heavy components, dynamic imports for routes
 - No `v-html` without sanitization (XSS risk)
 - Props defined with TypeScript types via `defineProps<{ ... }>()` — not runtime-only validation
 - Emits declared via `defineEmits<{ ... }>()` — not untyped string arrays
 - Naming: PascalCase components, `Base` prefix for atoms, `use` prefix for composables
 - i18n: ALL user-facing text goes through `$t()` / `t()` — no bare strings in templates or script
+- VRT: new pages/routes have corresponding `*.vrt.spec.ts` with 3-viewport coverage (375px, 768px, 1280px), baseline snapshots committed

package/dist/template/.claude/templates/claude-md.md

@@ -281,6 +281,16 @@ Framework-specific best practices, component architecture, state management, SSR
 - Coverage aggregated at workspace root under `coverage/` (add to `.gitignore`)
 - Run: `nx test [PROJECT] --coverage` or `nx affected --target=test -- --coverage`
 
+### Visual Regression Testing
+
+Page-level VRT using Playwright `toHaveScreenshot()` at 3 viewports (375px, 768px, 1280px). Catches unintended visual regressions across pages.
+
+- **Files**: `*.vrt.spec.ts` in E2E project (co-located with functional E2E tests)
+- **Baselines**: `*-snapshots/` directories — committed to git
+- **Threshold**: `maxDiffPixelRatio: 0.01` (1%), animations disabled
+- **Update baselines**: `nx e2e [APP]-e2e -- --update-snapshots` after intentional visual changes
+- **CI**: use Playwright Docker image (`mcr.microsoft.com/playwright`) for consistent rendering
+
 ### Code Quality & Linting
 
 Config templates are in `.claude/templates/` — copy to project root during Phase 0 scaffolding:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-workspace",
-  "version": "1.1.86",
+  "version": "1.1.87",
   "description": "Scaffold a project with Claude Code agents for autonomous AI-driven development",
   "type": "module",
   "bin": {