create-claude-workspace 2.3.4 → 2.3.6

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

@@ -8,6 +8,12 @@ You are a QA Engineer specializing in integration testing, E2E testing with Play
 
 You always RUN the tests after writing them and report results.
 
+## Before Starting (Mandatory)
+
+Read these standards files before any work:
+- `.claude/standards/coding-standards.md`
+- `.claude/standards/testing-standards.md`
+
 ## Core Competencies
 
 - **Integration testing**: API endpoint tests (real HTTP calls), DB operations, service collaboration
@@ -78,15 +84,7 @@ Before writing ANY test, detect which test framework the project uses:
 
 ## Test File Convention
 
-**Co-located tests** — every `.spec.ts` file lives next to the source file it tests:
-```
-libs/[domain]/src/lib/business/price-calculator.ts
-libs/[domain]/src/lib/business/price-calculator.spec.ts   # <- same directory
-```
-
-**NEVER** create `__tests__/` directories or group tests into a separate folder. Each test file mirrors its source file 1:1 in the same directory. This keeps navigation trivial and makes it obvious when a file lacks tests.
-
-**One test file per source file** — do NOT bundle multiple source files' tests into a single `.spec.ts`. If `get-image.ts` and `parse-html.ts` both need tests, create `get-image.spec.ts` and `parse-html.spec.ts` separately.
+Follow co-located test conventions from `.claude/standards/coding-standards.md` — tests live next to source files, one test file per source file, no `__tests__/` directories.
 
 ## Output Format
 
@@ -308,6 +306,8 @@ describe('my-lib public API (integration)', () => {
 
 Automated pixel-by-pixel comparison against baseline screenshots. Catches unintended visual regressions that functional tests miss (CSS side effects, layout shifts, responsive breakpoints).
 
+**Key behavior:** `toHaveScreenshot()` has built-in auto-retry — it takes consecutive screenshots until two consecutive captures match (page is stable), THEN compares against the golden baseline. This means it inherently waits for rendering to settle.
+
 ### 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
@@ -317,7 +317,7 @@ Automated pixel-by-pixel comparison against baseline screenshots. Catches uninte
 ### 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**
+- Baselines auto-stored in `*-snapshots/` directories — **commit these to git**
 
 ### Viewport matrix
 ```typescript
@@ -345,59 +345,123 @@ test.describe('Checkout Page — Visual Regression', () => {
 
       test('default state', async ({ page }) => {
         await page.goto('/checkout');
-        await page.waitForLoadState('networkidle');
+        // Wait for fonts — critical for consistent rendering
+        await page.waitForFunction(() => document.fonts.ready);
+        // Wait for key content to be visible
+        await expect(page.locator('[data-testid="checkout-form"]')).toBeVisible();
+        // toHaveScreenshot() auto-retries until two consecutive captures match
         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.waitForFunction(() => document.fonts.ready);
         await page.getByRole('button', { name: 'Pay' }).click();
-        await expect(page).toHaveScreenshot(`checkout-errors-${vp.name}.png`, {
-          maxDiffPixelRatio: 0.01,
-        });
+        await expect(page).toHaveScreenshot(`checkout-errors-${vp.name}.png`);
       });
     });
   }
 });
 ```
 
-### 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
+### VRT Playwright config
+Set global defaults in `playwright.config.ts` — individual tests inherit these and only override when needed:
+```typescript
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.01,  // 1% tolerance for minor anti-aliasing
+      threshold: 0.2,            // per-pixel YIQ color tolerance (Playwright default)
+      animations: 'disabled',    // fast-forward CSS animations to end state
+      scale: 'css',              // consistent size on HiDPI displays
+    },
+  },
+  // Remove {platform} from path — baselines generated in Docker (Linux-only)
+  snapshotPathTemplate: '{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}{-projectName}{ext}',
+});
+```
+
+**Config options reference:**
+- `maxDiffPixelRatio: 0.01` (1%) — fraction of total pixels allowed to differ
+- `threshold: 0.2` — per-pixel YIQ color difference tolerance (0 = exact, 1 = anything)
+- `animations: 'disabled'` — finite animations fast-forwarded to end, infinite reset
+- `scale: 'css'` — consistent screenshot size regardless of device pixel ratio
+- `fullPage: true` for page-level screenshots (captures below-fold), omit for component-state
+- `mask: Locator[]` — overlay elements with colored boxes (hides dynamic content)
+- `stylePath: string | string[]` — CSS file injected before screenshot, **penetrates Shadow DOM** (unlike `mask`)
+
+### Cross-platform baselines (CRITICAL)
+
+Playwright renders fonts and anti-aliasing differently per OS. By default, Playwright appends `{browser}-{platform}` to snapshot names (e.g., `landing-chromium-linux.png`). **This means Windows baselines will never match Linux CI.**
+
+**Docker-first workflow (recommended):**
+1. Write VRT tests locally (they will fail — no baselines yet)
+2. Generate baselines inside the Playwright Docker image:
+   ```bash
+   # Match the exact Playwright version from your project
+   docker run --rm -v $(pwd):/work -w /work mcr.microsoft.com/playwright:v1.52.0-jammy \
+     npx playwright test --grep "Visual Regression" --update-snapshots
+   ```
+3. Commit the generated baselines from `*-snapshots/` directories
+4. CI runs the same Docker image — baselines match
+
+**Alternative — CI-first workflow:**
+1. Write VRT tests, push to branch
+2. CI job runs with `allow_failure: true`, generates baselines as artifacts
+3. Download artifacts, commit baselines, push again
+4. Subsequent CI runs compare against committed baselines
+
+**`snapshotPathTemplate` for Docker-only VRT:**
+Remove `{platform}` from the path since all baselines are Linux. Set in `playwright.config.ts` (see config section above). This prevents Playwright from appending OS-specific suffixes.
+
+**Self-host fonts** used in the app — CDN fonts may load differently or be unavailable in Docker. Bundle fonts in the project for deterministic rendering.
 
 ### 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
+- When visual changes are **intentional**: run with `--update-snapshots` inside Docker, then commit new baselines
+- **First run** creates baselines (auto-retry takes two identical screenshots to confirm stability)
+- In CI: use the Playwright Docker image (`mcr.microsoft.com/playwright`) — same version as local Docker generation
 
 ### Running VRT tests
 ```bash
+# Run VRT via Nx (CI or Docker)
+nx e2e [APP]-e2e -- --grep "Visual Regression"
+
+# Update baselines after intentional visual changes (inside Docker)
+docker run --rm -v $(pwd):/work -w /work mcr.microsoft.com/playwright:v1.52.0-jammy \
+  npx playwright test --grep "Visual Regression" --update-snapshots
+
 # Run all E2E (includes VRT)
 nx e2e [APP]-e2e
+```
 
-# Update baselines after intentional visual changes
-nx e2e [APP]-e2e -- --update-snapshots
+### Wait strategy before screenshots
+Do NOT use `networkidle` — it is banned by `playwright/no-networkidle` lint rule.
 
-# Run only VRT tests
-nx e2e [APP]-e2e -- --grep "Visual Regression"
-```
+**Recommended wait sequence:**
+1. **Wait for fonts** (always): `await page.waitForFunction(() => document.fonts.ready)`
+2. **Wait for key content** (when page loads data): `await expect(page.locator('...')).toBeVisible()`
+3. **Let `toHaveScreenshot()` auto-retry handle the rest** — its built-in stability detection (two consecutive identical captures) covers most rendering settling
+
+`waitForLoadState('load')` is useful for pages with images but is NOT a substitute for font readiness. `waitForLoadState('domcontentloaded')` is too early — fonts and images likely not loaded yet.
 
 ### 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:
+- Always wait for fonts: `await page.waitForFunction(() => document.fonts.ready)`
+- Always wait for key content visibility before screenshot
+- Mask dynamic content (timestamps, avatars, user-specific data):
   ```typescript
   await expect(page).toHaveScreenshot('name.png', {
     mask: [page.locator('.timestamp'), page.locator('.avatar')],
   });
   ```
+- For elements inside Shadow DOM, use `stylePath` instead of `mask`:
+  ```typescript
+  await expect(page).toHaveScreenshot('name.png', {
+    stylePath: path.join(__dirname, 'vrt-overrides.css'),
+  });
+  ```
 - 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
 
@@ -440,7 +504,7 @@ exit $E2E_EXIT
 
 **Default thresholds: 80% for statements, branches, functions, and lines.**
 
-Read the target project's CLAUDE.md `Test Coverage` section for the canonical Vitest coverage configuration (provider, reporters, thresholds, include/exclude patterns, reportsDirectory). If no CLAUDE.md exists or it lacks a Test Coverage section, use these defaults:
+See `.claude/standards/testing-standards.md` for coverage config defaults (provider, reporters, thresholds, CI integration). Read the target project's CLAUDE.md `Test Coverage` section for any project-specific overrides. If neither exists, use these defaults:
 - Provider: `v8`
 - Reporters: `text`, `text-summary`, `cobertura` (for CI), `html` (for local browsing)
 - Thresholds: 80% across all four metrics

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

@@ -7,6 +7,12 @@ steps: plan
 
 You are a frontend architect specializing in modern frontend development within monorepo architecture. Your mission is to plan component architecture, identify reuse opportunities, and produce structured design specs. You do NOT implement code — implementation is done by framework-specific agents (angular-engineer, react-engineer, vue-engineer, svelte-engineer).
 
+## Before Starting (Mandatory)
+
+Read these standards files before any work — they contain the coding rules you must follow:
+- `.claude/standards/coding-standards.md`
+- `.claude/standards/architecture.md`
+
 ## Your Role
 
 - **Plan** frontend architecture (component structure, smart/dumb split, data flow)
@@ -24,28 +30,6 @@ You are a frontend architect specializing in modern frontend development within
 - **Performance**: Lazy loading, code splitting, deferred rendering, no unnecessary re-renders
 - **Accessibility**: WCAG compliance, ARIA, keyboard navigation, focus management
 
-## Code Quality Standards
-
-- Self-documenting code — no comments unless complex business logic
-- Strict TypeScript — no `any`, no `eslint-disable`, use `unknown` + narrowing
-- File size limits: 200 lines TS, 200 lines SCSS/CSS, 100 lines template/JSX
-- Single-purpose files: each `.ts` file exports ONE class, ONE function, or ONE closely related set of helpers (e.g., a type + its factory). Barrel `index.ts` files are exempt. Name after its export: `get-image.ts`, `parse-html.ts`. No `utils.ts` or `helpers.ts` bundles.
-- Co-located tests: test files live next to source files (`foo.spec.ts` beside `foo.ts`). No `__tests__/` directories.
-- `readonly` on all fields that don't need reassignment
-- Explicit access modifiers: `public`, `protected`, `private`
-
-## Code Style Philosophy
-
-Write clean, elegant code that is easy to test and reason about:
-
-- **Pure computed state**: all derived values are computed/derived — pure transformations with no side effects
-- **Minimal branching**: max 2 levels of nesting — use early returns or lookup maps to flatten deeper logic
-- **Side effects at boundaries only**: services for I/O, effect handlers for side effects. Components and computed/derived values stay pure.
-- **Small focused functions**: each function does ONE thing, max ~20 lines of logic, max 4 parameters. Extract complex logic into pure helper functions that are trivially testable.
-- **Data transformations over mutations**: prefer immutable patterns over mutations.
-- **Declarative templates**: templates describe WHAT to render, not HOW. No imperative DOM manipulation.
-- **Testability drives design**: if a computed value or helper function is hard to test, it does too much — split it.
-
 ## Component Architecture
 
 **Dumb components (ui/):**

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

@@ -8,6 +8,12 @@ steps: implement, rework
 You are a Vue frontend engineer. You implement Vue applications following the architect's plan (from ui-engineer).
 Read the codebase before making changes. Follow the conventions below strictly.
 
+## Before Starting (Mandatory)
+
+Read these standards files before any work — they contain the coding rules you must follow:
+- `.claude/standards/coding-standards.md`
+- `.claude/standards/testing-standards.md`
+
 ## Implementation Responsibilities
 - Implement production code according to the architect's plan
 - Write unit tests for all new/modified code (co-located: foo.spec.ts beside foo.ts)
@@ -384,35 +390,10 @@ describe('UserCard', () => {
 
 ## 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.
+See `.claude/standards/testing-standards.md` for shared VRT config (viewport matrix, maxDiffPixelRatio, animations). Vue-specific settings:
+- `baseURL` / `webServer.url`: `http://localhost:5173` (Vite) or `http://localhost:3000` (Nuxt)
+- `webServer.command`: `nx serve [APP]`
+- CI: use `mcr.microsoft.com/playwright:v[version]-jammy`
 
 ## Vue Review Checklist
 

package/dist/template/.claude/standards/architecture.md

@@ -0,0 +1,108 @@
+# Architecture Standards
+
+Structural and architectural rules for monorepo projects using Nx.
+
+## App Separation Principle
+
+- **`apps/` are thin shells** — each app is just configuration + routing + bootstrap. Minimal code.
+- **`libs/` contain all logic** — each domain/feature has its **own library group** with sub-libraries per layer. Apps import only from entry points.
+- **Feature-first library organization (STRICT)** — every distinct feature/domain gets its own group of libraries:
+  ```
+  libs/
+    scan/           # feature: scan
+      domain/       # scan types, schemas, interfaces
+      ui/           # scan UI components
+      feature/      # scan smart components
+      data-access/  # scan HTTP/DB services
+    streak/         # feature: streak
+      domain/
+      ui/
+      feature/
+    achievement/    # feature: achievement
+      domain/
+      feature/
+    shared/         # ONLY truly cross-domain code
+      ui/           # generic UI primitives (buttons, modals)
+      domain/       # cross-domain types (if any)
+      infrastructure/
+  ```
+  **NEVER dump multiple features into a single library** (e.g. `shared/types` with `scan.ts`, `streak.ts`, `achievement.ts`). Each feature owns its types in its own `domain/` library.
+- **Frontend and backend are separate apps** with separate build configurations per environment:
+  - `apps/my-app/` — Frontend application
+  - `apps/api/` — Backend API (if applicable)
+- **Environment configs**: each app has per-target settings via Nx `configurations` in `project.json` (API URLs, feature flags, etc.)
+- **Entry point pattern**: each domain lib has a root `index.ts` that re-exports the public API. Apps and other libs import ONLY from `@myorg/<lib-name>`, never from deep paths like `@myorg/<lib-name>/src/lib/internal/...`
+
+## CLI-First Principle
+
+**ALWAYS prioritize CLI commands and generators over manual file creation.** This applies to:
+- Nx workspace scaffolding (`create-nx-workspace`)
+- Libraries, components, applications (`nx generate`)
+- Adding plugins (`nx add`)
+- Package installation (package manager CLI)
+- Git operations (`gh`, `glab`)
+
+NEVER manually create `project.json`, `tsconfig.*`, or boilerplate files that a generator would produce. Generators configure dependencies, paths, and targets correctly.
+
+**NEVER use `nx:run-commands` executor** in project.json. Always use the proper built-in executor (`@nx/js:node` for serve, `@nx/vite:build` for build, `@nx/eslint:lint` for lint, etc.). `nx:run-commands` is an escape hatch for one-off scripts, not for standard targets.
+
+## Nx Generators
+
+**Generator defaults** are configured in `nx.json` — no need to repeat flags like `--unitTestRunner`, `--linter`, `--style` in every command. See `.claude/profiles/frontend.md` for framework-specific generator commands.
+
+**Creating libraries:**
+```bash
+# Plain TypeScript library (for domain models, business logic, shared utils)
+nx g @nx/js:library --directory=libs/[domain]/[layer] --no-interactive
+
+# Framework-specific library — see frontend profile for the correct generator
+```
+
+**Bundler rule (STRICT):** Internal monorepo libs do NOT need a bundler — Nx handles compilation. NEVER install or configure tsup, tsdown, rollup, or any standalone bundler for internal libs. Only add `--bundler=esbuild|tsc|swc` to `nx generate` for **publishable** libraries (npm packages). If `nx generate` created a lib without `--bundler`, do NOT retroactively add one.
+
+After generation, the architect's plan specifies what code to write IN the generated files. The generator handles project.json, tsconfig paths, and build targets.
+
+## Onion Architecture (per domain)
+
+```
++-----------------------------------------------------+
+|                     apps/[app]                        |
+|  App shell — assembles features into routing          |
++-----------------------------------------------------+
+|                      feature/                         |
+|  Smart components, orchestrate UI + data              |
++-----------------------------------------------------+
+|         ui/                |       data-access/       |
+|  Presentational components |  HTTP / DB services      |
+|  (dumb, input/output)      |                          |
++-----------------------------------------------------+
+|                       api/                            |
+|  API routes, validation (if backend)                  |
++-----------------------------------------------------+
+|                     business/                         |
+|  Use cases, business logic                            |
++-----------------------------------------------------+
+|                      domain/                          |
+|  TypeBox schemas (single source of truth), types,     |
+|  repository interfaces, value objects                 |
++-----------------------------------------------------+
+|                   infrastructure/                     |
+|  Repository implementations (database, API, mock)     |
++-----------------------------------------------------+
+```
+
+Dependency rules:
+- domain -> only shared/domain
+- business -> domain, shared/infrastructure/di
+- api -> business, domain
+- infrastructure -> domain, shared/infrastructure
+- data-access -> domain (for types)
+- ui -> shared/ui, domain (for types)
+- feature -> ui, data-access, shared/ui
+
+**TypeBox as single source of truth**: Define TypeBox schemas in `domain/` layer (`libs/[domain]/domain/`). These schemas are the canonical definition — derive everything from them:
+- **TypeScript types**: `Static<typeof MySchema>` — no separate interface definitions
+- **API validation**: `openAPIRouteHandler` uses the same schemas for request/response validation + OpenAPI spec
+- **Frontend types**: Frontend imports types from domain lib via `@myorg/[domain]-domain` — no copy-paste
+- **DB mapping**: Infrastructure layer maps between DB rows and domain types
+- NEVER duplicate type definitions. If a type exists as a TypeBox schema, use `Static<>` everywhere.

package/dist/template/.claude/standards/backend-patterns.md

@@ -0,0 +1,82 @@
+# Backend Patterns
+
+Backend-specific rules for TypeScript server-side development. Consumed by `backend-ts-architect` and `senior-code-reviewer`.
+
+## @cibule/* Ecosystem (Preferred Libraries)
+
+**ALWAYS prefer `@cibule/*` packages** over custom implementations or third-party alternatives for: DI, database access, file storage, image processing, and Nx workspace scaffolding. These are driver-agnostic abstractions designed for the onion architecture pattern.
+
+| Package | Purpose | Replaces |
+|---------|---------|----------|
+| `@cibule/di` | Dependency injection (InjectionToken, Injector, inject()) | Custom DI |
+| `@cibule/db` | Database abstraction (Kysely-based, driver-agnostic) | Raw Kysely |
+| `@cibule/db-d1` | Cloudflare D1 driver for @cibule/db | kysely-d1 |
+| `@cibule/db-sqlite` | SQLite driver for @cibule/db (better-sqlite3) | Direct better-sqlite3 |
+| `@cibule/db-migrate` | Migration orchestrator (Prisma + D1 PRAGMA fixes) | Manual migrations |
+| `@cibule/storage` | File storage abstraction (upload, download, presigned URLs) | Custom storage |
+| `@cibule/storage-r2` | Cloudflare R2 driver for @cibule/storage | Direct R2 API |
+| `@cibule/storage-s3` | AWS S3 driver for @cibule/storage | Direct AWS SDK |
+| `@cibule/image` | Image transformation abstraction | Custom image processing |
+| `@cibule/image-sharp` | Sharp-based driver with FileStorage caching (Node.js) | Direct Sharp |
+| `@cibule/image-cf` | Cloudflare Image Resizing driver | Direct CF API |
+| `@cibule/wiring` | Per-request DI middleware, AsyncLocalStorage helpers | Custom middleware |
+| `@cibule/devkit` | Nx generators for onion architecture scaffolding | Manual Nx setup |
+
+**DI core API** (`@cibule/di`):
+- `InjectionToken<T>` — typed token, `Injector.create({ providers, parent? })` — container
+- `inject<T>(token)` / `inject<T>(token, { optional: true })` — resolve from context
+- `runInInjectionContext(injector, fn)` — scoped execution
+- Provider types: `useValue`, `useClass`, `useFactory`, `multi: true`
+
+**Database pattern** (`@cibule/db` + driver):
+```typescript
+// Domain layer — driver-agnostic
+import type { Db } from '@cibule/db';
+import { DB_ACCESSOR, UNIT_OF_WORK_FACTORY } from '@cibule/db';
+
+// Infrastructure — pick driver per platform
+import { provideD1Db } from '@cibule/db-d1';       // Cloudflare Workers
+import { provideSqliteDb } from '@cibule/db-sqlite'; // Node.js local dev
+```
+
+**Workspace scaffolding** (`@cibule/devkit`):
+```bash
+nx g @cibule/devkit:preset myorg        # Initialize workspace with onion layers
+nx g @cibule/devkit:scope market --frontend  # Create domain scope
+```
+
+**Dependency bug handling**: If a bug is caused by a third-party dependency (not by project code), mark the task as `[~] BLOCKED` with the bug details and the package version. Continue with other tasks. The dependency freshness check at phase transitions will detect new versions — re-attempt blocked tasks after the package is updated.
+
+## Backend Patterns
+
+- Hono routes with validation (**TypeBox** — `typebox` for schema + type inference, `TypeCompiler` for runtime validation). **NEVER use `@sinclair/typebox`** — the correct package is `typebox`.
+- **OpenAPI-first**: Use `hono-openapi` with `openAPIRouteHandler` for all API routes — generates OpenAPI spec from TypeBox schemas automatically. API docs served via `@scalar/hono-api-reference` at `/reference`.
+- `@cibule/di` for dependency injection (see @cibule/* Ecosystem section above)
+- `@cibule/db` + driver for database access, UnitOfWork for atomic writes
+- `@cibule/storage` + driver for file storage, `@cibule/image` + driver for image processing
+- `@cibule/wiring` for per-request DI middleware
+
+## Platform-Agnostic Backend (STRICT)
+
+- Backend code MUST run on both Node.js and Cloudflare Workers without modification
+- NEVER use Node.js-specific APIs (`fs`, `path`, `process`, `Buffer`) in business/domain/api layers
+- NEVER use Cloudflare-specific APIs (`env.DB`, `ctx.waitUntil()`) in business/domain layers
+- Platform-specific code lives ONLY in `infrastructure/` layer behind abstract interfaces
+- Use Web Standard APIs where possible: `fetch`, `Request`, `Response`, `URL`, `crypto`, `TextEncoder`/`TextDecoder`, `Headers`, `FormData`, `ReadableStream`
+- **Platform-specific code MUST be in separate libraries (STRICT)** — NEVER mix Node.js and Cloudflare code in the same library. Barrel exports (`index.ts`) would pull both platforms into the bundle, causing compilation errors (e.g. `better-sqlite3` in Cloudflare, or D1 bindings in Node.js):
+  ```
+  libs/[domain]/
+    infrastructure-d1/     # Cloudflare D1 implementation ONLY
+    infrastructure-sqlite/  # Node.js SQLite implementation ONLY
+  libs/shared/
+    infrastructure-d1/     # shared D1 providers (provideD1Database)
+    infrastructure-sqlite/  # shared SQLite providers (provideSqliteDatabase)
+  ```
+  Each entry point imports ONLY its platform's library:
+  - Worker entry → `@myorg/shared-infrastructure-d1`
+  - Node entry → `@myorg/shared-infrastructure-sqlite`
+- Hono is inherently platform-agnostic — use its standard APIs, avoid `c.env` directly in routes (inject via DI)
+- Entry points handle platform wiring:
+  - `apps/api/src/main.ts` — Node.js entry (optional, for local dev)
+  - `apps/api/src/index.ts` — Cloudflare Worker entry (production)
+- Default deployment: **Cloudflare Workers** (production), **Node.js** (local development via `@nx/js:node` executor + Node.js entry point). Wrangler is deployment-only — NEVER used for local dev or in Nx targets.

package/dist/template/.claude/standards/coding-standards.md

@@ -0,0 +1,64 @@
+# Coding Standards
+
+Shared coding rules for all implementation agents and the code reviewer.
+
+## File Organization & Size Limits
+
+**Single-purpose files (STRICT):**
+- Each `.ts` file exports ONE class, ONE function, or ONE closely related set of helpers (e.g., a type + its factory)
+- Name files after their single export: `get-image.ts`, `parse-html.ts`, `price-calculator.ts`
+- NEVER bundle unrelated exports into a barrel file like `utils.ts` or `helpers.ts` — split into individual files
+- Index files (`index.ts`) are the ONLY exception — they re-export the public API of a library
+
+**File size limits:**
+- MAX 200 lines per TypeScript file — split into types, utils, sub-components if larger
+- MAX 200 lines per SCSS file — split into partials
+- MAX 100 lines per HTML template — decompose into child components
+
+**Co-located tests:**
+- Test files live next to the source file: `price-calculator.spec.ts` beside `price-calculator.ts`
+- NEVER create `__tests__/` directories — tests are always co-located
+- One test file per source file — do NOT bundle multiple files' tests together
+
+## TypeScript Config
+
+- `moduleResolution: "bundler"` in `tsconfig.base.json` — all code goes through a bundler, so use bundler-style resolution
+- NEVER add `.js` extensions to TypeScript imports — write `import { Foo } from './foo'`, not `'./foo.js'`
+- `module: "ESNext"` + `target: "ES2022"` (or as appropriate)
+- `strict: true`, `noUncheckedIndexedAccess: true`
+- Path aliases via `compilerOptions.paths` in `tsconfig.base.json` — managed by Nx generators, do not edit manually
+
+## Coding Style
+
+- No comments in code — write self-explanatory code
+- Explicit access modifiers: `public` for API, `protected` for template-used, `private` for internal
+- Import order enforced by `eslint-plugin-simple-import-sort` (automatic)
+- Use `type` imports for type-only imports (`import type { Foo }`)
+- DRY: 3+ repeats = extract to shared utility/component/directive
+- Prefer composition over inheritance
+- `readonly` on all fields that don't need reassignment
+- No `any` — use `unknown` + type narrowing
+- No non-null assertions (`!`) — handle nullability explicitly with narrowing, `??`, or early returns
+- No `as unknown as T` double-casting — if types don't align, fix the types or use proper type guards
+- No `eslint-disable` comments — NEVER suppress linter rules. If ESLint flags an error, fix the code instead of disabling the rule. This includes `eslint-disable-next-line`, `eslint-disable-line`, and block `eslint-disable` comments.
+
+## Code Cleanliness (STRICT — clean code enables high coverage)
+
+- **Pure functions first**: business logic and domain operations are pure — same input, same output, no side effects. This makes them trivially testable.
+- **Minimal branching**: avoid nested conditionals (max 2 levels). Prefer early returns, lookup maps/objects, `??`/`?.` chains, polymorphism. If a function has 4+ branches, split it.
+- **Side effects at boundaries**: I/O (HTTP, DB, logging, DOM) happens at the edges — infrastructure layer, entry points. Business and domain code stays pure.
+- **Data transformations over mutations**: prefer `map`/`filter`/spread/new objects over `push`/`splice`/`delete`/mutation. Immutable data is predictable and testable.
+- **Small focused functions**: each function does ONE thing. Max ~20 lines of logic. Extract complex expressions into named pure helpers.
+- **Declarative over imperative**: describe WHAT, not HOW. Prefer expressions over statement sequences.
+
+## Modern JavaScript Syntax (STRICT — enforced by ESLint)
+
+- `for...of` over `.forEach()` — clearer, supports `break`/`continue`/`await`
+- `const` by default — `let` only when reassignment is needed, NEVER `var`
+- Arrow functions in callbacks — `array.map(x => x.id)`, not `array.map(function(x) { ... })`
+- Template literals — `` `Hello ${name}` ``, not `'Hello ' + name`
+- Object shorthand — `{ name, age }`, not `{ name: name, age: age }`
+- Destructuring — `const { id, name } = user`, not `const id = user.id`
+- Nullish coalescing `??` over `||` for defaults (avoids falsy pitfalls)
+- Optional chaining `?.` over nested `if` checks
+- `Promise.all()` for parallel async, `for await...of` for async iteration

package/dist/template/.claude/standards/testing-standards.md

@@ -0,0 +1,94 @@
+# Testing Standards
+
+Testing, coverage, VRT, and code quality tooling standards. Consumed by `test-engineer`, `senior-code-reviewer`, and framework-specific engineers.
+
+## Test Coverage
+
+80% minimum for statements, branches, functions, lines (enforced in CI).
+
+- **Config template**: `.claude/templates/vitest.coverage.ts` — merge into each project's `vite.config.ts` or `vitest.config.ts` during scaffolding.
+- Reporters: `cobertura` (GitLab/GitHub MR coverage), `html` (browsable), `text-summary`
+- 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%), `threshold: 0.2` (per-pixel YIQ), animations disabled
+- **Cross-platform**: Baselines MUST be generated in Docker (Linux). Remove `{platform}` from `snapshotPathTemplate` when VRT runs exclusively in Docker
+- **Update baselines**: run inside Docker: `docker run --rm -v $(pwd):/work -w /work mcr.microsoft.com/playwright:v1.52.0-jammy npx playwright test --grep "Visual Regression" --update-snapshots`
+- **CI**: use Playwright Docker image (`mcr.microsoft.com/playwright`) — same version as baseline generation
+- **Font wait**: Always `await page.waitForFunction(() => document.fonts.ready)` before screenshot. Self-host fonts for deterministic rendering.
+- **No `networkidle`**: Banned by `playwright/no-networkidle` lint rule. Use font wait + element visibility + `toHaveScreenshot()` auto-retry instead.
+- **Auto-retry**: `toHaveScreenshot()` takes consecutive screenshots until two consecutive captures match, then compares against baseline. Handles most rendering settling automatically.
+
+### Shared Playwright VRT config
+
+```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,
+  // Remove {platform} — baselines generated in Docker (Linux-only)
+  snapshotPathTemplate: '{snapshotDir}/{testFileDir}/{testFileName}-snapshots/{arg}{-projectName}{ext}',
+  use: {
+    baseURL: 'http://localhost:<PORT>', // Framework-specific: Angular 4200, React/Next 3000, Vite 5173
+    trace: 'on-first-retry',
+  },
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixelRatio: 0.01,
+      threshold: 0.2,
+      animations: 'disabled',
+      scale: 'css',
+    },
+  },
+  webServer: {
+    command: 'nx serve [APP]',
+    url: 'http://localhost:<PORT>',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+### 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;
+```
+
+## Code Quality & Linting
+
+Config templates are in `.claude/templates/` — copy to project root during Phase 0 scaffolding:
+- **ESLint**: `.claude/templates/eslint.config.js` → `eslint.config.js` (flat config, `@typescript-eslint/strict-type-checked` + `@nx/eslint-plugin` + `eslint-plugin-simple-import-sort` + `eslint-plugin-prefer-arrow-functions`). Add framework-specific rules from `.claude/profiles/frontend.md`.
+- **Prettier**: `.claude/templates/.prettierrc` → `.prettierrc`, `.claude/templates/.prettierignore` → `.prettierignore`
+- **Stylelint**: `.claude/templates/.stylelintrc.json` → `.stylelintrc.json` (SCSS only, forces theme tokens over hardcoded colors)
+- **Pre-commit hooks**: `.claude/templates/.lefthook.yml` → `.lefthook.yml`
+
+Each library's `project.json` must declare tags: `"tags": ["type:domain", "scope:auth"]`
+
+Key rules enforced (do NOT weaken):
+- `prefer-arrow-functions/prefer-arrow-functions` — const arrow over function declarations
+- `max-classes-per-file: 1`, `max-depth: 4`
+- `@typescript-eslint/explicit-member-accessibility` — explicit public/private/protected
+- `@typescript-eslint/prefer-readonly` — readonly where possible
+- `@typescript-eslint/no-non-null-assertion`, `no-explicit-any`, `consistent-type-imports`, `strict-boolean-expressions`
+- `no-warning-comments: ['eslint-disable']` — no eslint-disable comments
+- `@nx/enforce-module-boundaries` — onion architecture layer constraints
+- `eslint-config-prettier` installed to disable conflicting rules. Do NOT use `eslint-plugin-prettier`.
+
+**Enforcement:**
+- All three tools run in CI pipeline (fail on violations)
+- `nx affected --target=lint` for incremental linting
+- Pre-commit hooks prevent committing violations