@quanticjs/create-app 0.1.1

package/templates/claude/skills/add-api-endpoint/SKILL.md

@@ -0,0 +1,59 @@
+# Add API Endpoint
+
+Wire a CQRS handler to an HTTP endpoint with DTO validation and a thin controller.
+
+## Usage
+```
+/add-api-endpoint POST /project/items
+/add-api-endpoint GET /identity/users/:id
+```
+
+## Steps
+1. **Create handler** — run `/add-handler` for the command/query + validator + handler
+2. **Create DTO** with class-validator decorators (controller-layer validation):
+   ```typescript
+   import { IsString, IsNotEmpty, MaxLength } from 'class-validator';
+   import { ApiProperty } from '@nestjs/swagger';
+
+   export class CreateItemDto {
+     @ApiProperty({ description: 'Item name', minLength: 1, maxLength: 100 })
+     @IsString()
+     @IsNotEmpty()
+     @MaxLength(100)
+     name: string;
+   }
+   ```
+3. **Create response DTO:**
+   ```typescript
+   export class ItemResponseDto {
+     @ApiProperty()
+     id: string;
+
+     @ApiProperty()
+     name: string;
+
+     @ApiProperty()
+     createdAt: Date;
+   }
+   ```
+4. **Add controller method** — THIN pattern:
+   ```typescript
+   @Post()
+   @ApiOperation({ summary: 'Create a new item' })
+   @ApiResponse({ status: 201, type: ItemResponseDto })
+   @ApiResponse({ status: 400, type: ErrorResponseDto })
+   async create(@Body() dto: CreateItemDto): Promise<ItemResponseDto> {
+     return this.commandBus.execute(new CreateItemCommand(dto.name, dto.description));
+   }
+   ```
+5. Register handler in module's `providers` array (if not done in step 1)
+6. **Add backend tests** — run `/write-backend-tests` for handler, validator, and controller
+7. `npm run build && npm run test`
+
+## Rules
+- Controller does NOTHING except parse request → commandBus/queryBus → return
+- DTO uses class-validator for shape validation; business rules stay in the Zod validator (created by `/add-handler`)
+- ALL repo access via `getTransactionalRepo()` — UnitOfWork is automatic
+- Every endpoint annotated with `@ApiOperation`, `@ApiResponse`, `@ApiBody`, `@ApiTags`
+- All API responses use typed response DTOs — never raw entity objects
+- Error responses use RFC 9457 problem-details shape

package/templates/claude/skills/add-auth-endpoint/SKILL.md

@@ -0,0 +1,68 @@
+# Add Authenticated Endpoint
+
+## Auth Flow (BFF Pattern)
+```
+Browser → httpOnly cookie → NestJS BFF middleware → injects Bearer header → JwtAuthGuard → RolesGuard → Handler
+```
+
+The frontend sends **no** Authorization header. The BFF middleware extracts the JWT from the httpOnly session cookie and injects it as a Bearer token before the request reaches the controller.
+
+## Steps
+1. **Add controller endpoint** with appropriate decorators:
+   ```typescript
+   @Controller('items')
+   export class ItemsController {
+     constructor(private readonly commandBus: CommandBus) {}
+
+     // Protected endpoint (default — JwtAuthGuard is global)
+     @Post()
+     async create(@Body() dto: CreateItemDto, @Req() req: any) {
+       return this.commandBus.execute(new CreateItemCommand(dto.name, req.user.keycloakId));
+     }
+
+     // Admin-only endpoint
+     @Roles('admin')
+     @Get('admin/stats')
+     async stats() { ... }
+
+     // Public endpoint (no auth required)
+     @Public()
+     @Get('health')
+     async health() { ... }
+   }
+   ```
+2. **Extract user from request** — `req.user` contains:
+   ```typescript
+   {
+     keycloakId: string;       // JWT sub
+     email: string;
+     roles: string[];          // from realm_access.roles
+     username?: string;        // from preferred_username
+   }
+   ```
+   Note: `organizationId` is NOT in the JWT (multi-tenancy/RLS deferred per ADR-005).
+
+## Decorators
+| Decorator | Effect |
+|-----------|--------|
+| *(none)* | JwtAuthGuard is global — endpoint is protected by default |
+| `@Public()` | Bypass JwtAuthGuard — endpoint is public |
+| `@Roles('admin')` | Require specific realm role(s) |
+| `@Roles('admin', 'super-admin')` | Require ANY of the listed roles |
+
+## BFF Auth Endpoints (in `src/bff/`)
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /auth/login` | Redirect to Keycloak (params: `provider`, `returnTo`) |
+| `GET /auth/callback` | OIDC code exchange → set httpOnly cookie → redirect to SPA |
+| `POST /auth/refresh` | Refresh access token server-side |
+| `POST /auth/logout` | Clear cookie + revoke Keycloak session |
+| `GET /auth/me` | Return current user info from session |
+
+## Rules
+- NEVER bypass auth for endpoints that mutate data
+- NEVER return raw tokens to the frontend — only user profile data via `/auth/me`
+- NEVER store tokens in `localStorage`, `sessionStorage`, or non-httpOnly cookies
+- Frontend sends requests with `credentials: 'include'` — cookies are sent automatically
+- NEVER set `Authorization` headers from frontend code
+- NEVER implement token refresh logic in the frontend — BFF middleware handles it

package/templates/claude/skills/add-entity/SKILL.md

@@ -0,0 +1,56 @@
+# Add Entity
+
+## Steps
+1. **Create entity file** in `src/<module>/entities/<EntityName>.entity.ts`
+2. **Choose base class:**
+   - `BaseEntity` — standard base class. Provides `id` (UUID), `createdAt`, `updatedAt`.
+   - `TenantBaseEntity` — **only when multi-tenancy is enabled** (currently deferred per ADR-005). Adds `organizationId` column + RLS. Do NOT use until multi-tenancy is re-activated.
+   ```typescript
+   import { BaseEntity } from '@quanticjs/core';
+   ```
+3. **Define columns:**
+   ```typescript
+   import { BaseEntity } from '@quanticjs/core';
+
+   @Entity('items')
+   export class Item extends BaseEntity {
+     @Column({ type: 'varchar', length: 200 })
+     name!: string;
+
+     @Column({ type: 'text', nullable: true })
+     description!: string | null;
+
+     @Column({ type: 'jsonb', default: {} })
+     metadata!: Record<string, unknown>;
+
+     @Column({ type: 'boolean', default: true })
+     isActive!: boolean;
+   }
+   ```
+4. **Register in module** — add to `TypeOrmModule.forFeature([...])` in the module
+5. **Generate migration:** `npx typeorm migration:generate src/migrations/<Name>`
+6. **Run migration:** `npx typeorm migration:run`
+
+## Column Type Reference
+| TypeScript | PostgreSQL | Notes |
+|------------|------------|-------|
+| `string` | `varchar(N)` | Always set length |
+| `string` | `text` | Unlimited length |
+| `number` | `int` | Integer |
+| `number` | `decimal(10,2)` | Money/precision |
+| `boolean` | `boolean` | |
+| `Date` | `timestamptz` | Always use timestamptz |
+| `Record<string,unknown>` | `jsonb` | Queryable JSON |
+| `string[]` | `varchar[]` | PostgreSQL array |
+| `enum` | `enum` | TypeORM enum type |
+
+## Rules
+- Use `BaseEntity` for all entities (multi-tenancy/RLS is deferred per ADR-005)
+- Do NOT use `TenantBaseEntity` or add `organizationId` until multi-tenancy is re-activated
+- `BaseEntity` provides: `id` (UUID v4), `createdAt`, `updatedAt` — never redefine these
+- Use `!` (definite assignment) on all columns — TypeORM sets them
+- Database columns are **camelCase** (TypeORM default naming strategy)
+- NEVER modify a migration that has been run — create a new one
+- Index columns used in WHERE clauses: `@Index(['columnName'])`
+- Import base classes from `@quanticjs/core`
+- Each module owns its own PostgreSQL schema

package/templates/claude/skills/add-event/SKILL.md

@@ -0,0 +1,127 @@
+# Add Domain Event
+
+## Event Flow
+```
+Handler → OutboxEvent (same DB transaction) → OutboxPublisherService (poll) → Redis Stream → Consumer
+```
+
+Events use the **outbox pattern** — the event record is written to the database in the same transaction as the entity mutation, guaranteeing atomicity. A background publisher polls the outbox and pushes to Redis Streams.
+
+## Steps
+1. **Create domain event in the handler** after successful mutation:
+   ```typescript
+   import { getTransactionalRepo, Result } from '@quanticjs/core';
+   import { OutboxEvent, DomainEvent } from '@quanticjs/core';
+
+   @CommandHandler(CreateItemCommand)
+   export class CreateItemHandler implements ICommandHandler<CreateItemCommand> {
+     constructor(
+       @InjectRepository(Item) private readonly itemRepo: Repository<Item>,
+       @InjectRepository(OutboxEvent) private readonly outboxRepo: Repository<OutboxEvent>,
+     ) {}
+
+     async execute(command: CreateItemCommand): Promise<Result<ItemDto>> {
+       const itemRepo = getTransactionalRepo(this.itemRepo);
+       const outboxRepo = getTransactionalRepo(this.outboxRepo);
+
+       const item = itemRepo.create({ name: command.name });
+       await itemRepo.save(item);
+
+       // Domain event — same transaction as the entity write
+       const event = new DomainEvent(
+         'item.created',        // eventType
+         item.id,               // aggregateId
+         { name: item.name },   // payload (minimal — IDs preferred)
+       );
+
+       await outboxRepo.save(outboxRepo.create({
+         eventType: event.eventType,
+         aggregateId: event.aggregateId,
+         streamKey: event.streamKey,
+         payload: event.payload,
+       }));
+
+       return Result.success(toDto(item));
+     }
+   }
+   ```
+
+2. **Stream key** is derived from eventType: `item.created` → `autoflux:events:items`
+
+3. **OutboxPublisherService** (from `@quanticjs/core`) polls pending events:
+   - Reads pending OutboxEvents
+   - Publishes to Redis Stream
+   - Marks as Published or Failed (max 5 retries with exponential backoff → DLQ)
+
+## Event Naming Convention
+| Event Type | Stream Key | When |
+|------------|------------|------|
+| `item.created` | `autoflux:events:items` | After entity creation |
+| `item.updated` | `autoflux:events:items` | After entity update |
+| `item.deleted` | `autoflux:events:items` | After soft delete |
+| `project.status.changed` | `autoflux:events:projects` | After status transition |
+
+## Consuming Events
+
+Extend `RedisStreamConsumer` from `@quanticjs/core`. The base class automatically creates a **dedicated Redis connection** for blocking `XREADGROUP BLOCK` calls, keeping the shared `REDIS_CLIENT` free for non-blocking ops.
+
+```typescript
+import { Injectable, Inject, Optional } from '@nestjs/common';
+import { REDIS_CLIENT, RedisStreamConsumer } from '@quanticjs/core';
+import type { Redis } from 'ioredis';
+import { hostname } from 'os';
+
+@Injectable()
+export class ItemEventConsumer extends RedisStreamConsumer {
+  readonly streamKey = 'autoflux:events:items';
+  readonly consumerGroup = 'project-planning';
+  readonly consumerName = `planner-${hostname()}-${process.pid}`;
+
+  constructor(@Optional() @Inject(REDIS_CLIENT) redis: Redis | undefined) {
+    super(redis);
+  }
+
+  protected shouldHandle(fields: Record<string, string>): boolean {
+    return fields.eventType === 'item.created';
+  }
+
+  async handleMessage(fields: Record<string, string>): Promise<void> {
+    const payload = JSON.parse(fields.payload || '{}');
+    // Handle idempotently — events may be delivered more than once
+  }
+}
+```
+
+## Lifecycle Hooks
+```typescript
+// Setup in onModuleInit, polling in onApplicationBootstrap
+async onModuleInit() {
+  await this.createConsumerGroup();  // XGROUP CREATE
+}
+
+async onApplicationBootstrap() {
+  this.startPolling();  // non-blocking — fires and forgets
+}
+```
+
+## Connection Layout
+| Client | Count | Purpose |
+|--------|-------|---------|
+| `REDIS_CLIENT` (shared) | 1 | Cache, locks, XADD, XGROUP CREATE, XACK |
+| Dedicated blocking client | 1 per consumer | `XREADGROUP BLOCK` only |
+
+## Retry & Dead-Letter Policy
+- Max retries: 5 with exponential backoff + jitter
+- Backoff: `min(1s × 2^attempt + random(0,1000ms), 30s)`
+- Dead-letter stream: `{stream}:dlq` with `MAXLEN ~ 100000`
+- Failed events are NEVER silently dropped
+
+## Rules
+- ALWAYS use outbox pattern — never publish directly to Redis (data loss on crash)
+- OutboxEvent is saved in the SAME transaction as the entity mutation
+- Event payloads should be minimal — include IDs, not full entities
+- Consumers must be idempotent — events may be delivered more than once
+- NEVER share Redis connection for blocking XREADGROUP reads
+- NEVER start polling in `onModuleInit()` — use `onApplicationBootstrap()`
+- NEVER publish events before the transaction commits
+- All repo access via `getTransactionalRepo()`

package/templates/claude/skills/add-feature/SKILL.md

@@ -0,0 +1,20 @@
+# Add Feature
+
+End-to-end feature implementation orchestrating all sub-skills.
+
+## Usage
+```
+/add-feature Create project items with priority and status
+/add-feature User profile editing with avatar upload
+```
+
+## Steps
+1. **Understand requirements** — read any specs, clarify with user if ambiguous
+2. **Create command/query + validator + handler** — run `/add-handler`
+3. **Create/update entity** — run `/add-entity`
+4. **Create migration** — run `/add-migration`
+5. **Add controller endpoint** — run `/add-api-endpoint` (handler already exists from step 2, so only DTO + controller)
+6. **Add frontend** — run `/add-frontend-page` (skip if purely backend)
+7. **Add backend tests** — run `/write-backend-tests`
+8. **Add UI tests** — run `/write-ui-tests` (skip if no frontend)
+9. **Verify** — `npm run build && npm test`

package/templates/claude/skills/add-frontend-page/SKILL.md

@@ -0,0 +1,75 @@
+# Add Frontend Page
+
+## Usage
+```
+/add-frontend-page /projects
+/add-frontend-page /settings/profile
+```
+
+## Steps
+1. Create route in React Router config
+2. Create page component in `client/src/pages/` — lazy-loaded with `React.lazy()` + `<Suspense>`
+3. Create data hooks using `@quanticjs/react-query`:
+   - `useApiQuery` for data fetching (NOT raw `useQuery`)
+   - `useApiMutation` for write operations with `invalidates` option (NOT raw `useMutation`)
+   - `usePaginatedQuery` for paginated lists
+4. Use shadcn/ui + `@quanticjs/react-ui` components (Spinner, Skeleton, EmptyState, ErrorBoundary, Dialog, ToastProvider)
+5. Add loading skeleton, empty state, and error boundary
+6. Forms use `useForm` from `@quanticjs/react-forms` + Zod (NOT raw React Hook Form) — auto-maps server validation errors
+7. Support dark mode via CSS variables: `hsl(var(--background))`, `hsl(var(--primary))`
+8. **Add tests** — run `/write-ui-tests` for the new page
+
+## Design Standards
+- All async content has loading skeletons (`Skeleton` from `@quanticjs/react-ui`)
+- All lists have empty states (`EmptyState` from `@quanticjs/react-ui`)
+- All forms use `useForm` from `@quanticjs/react-forms` + Zod (auto server-error mapping)
+- WCAG 2.1 AA accessible
+- No hardcoded hex colors or spacing — use design tokens/CSS variables
+- Components accept `className` for extension and forward refs
+
+## State Management (per ADR-003)
+| State type | Tool |
+|---|---|
+| Server/remote data | `useApiQuery` / `useApiMutation` from `@quanticjs/react-query` |
+| URL-derived state | `useSearchParams` |
+| Local UI state | `useState` |
+| Shared client state | Zustand store (with selectors) |
+| Form state | `useForm` from `@quanticjs/react-forms` + Zod |
+
+## Error Handling — Three Tiers
+
+| Tier | Handles | Pattern |
+|---|---|---|
+| **Forms** | Validation errors (400/422) | `useForm` auto-maps `ApiError.fieldErrors` to form fields. Non-field errors go to `errors._root`. |
+| **Toast** | Non-form mutations (delete, toggle, actions) | `toast.error(apiError)` — ApiError-aware, extracts title + detail automatically |
+| **ErrorBoundary** | Unhandled render errors | Already wired in app root provider stack. Prefer page-level boundary for granular recovery. |
+
+Non-form mutations **must** always provide `onError`:
+```typescript
+const mutation = useApiMutation(
+  (api, id: string) => api.delete(`/items/${id}`),
+  {
+    invalidates: [['items']],
+    onError: (error) => toast.error(error),
+  },
+);
+```
+
+**5xx errors:** Never show `error.detail` — may contain stack traces. Show generic "Something went wrong" message.
+Always include `error.correlationId` in error UI for support reporting.
+
+## Rules
+- NEVER use raw `useQuery`/`useMutation` — use `useApiQuery`/`useApiMutation` from `@quanticjs/react-query`
+- NEVER use raw React Hook Form — use `useForm` from `@quanticjs/react-forms` (auto server-error mapping)
+- NEVER fetch data with `useEffect` + `useState` — use `useApiQuery`
+- NEVER copy query data into `useState`
+- NEVER put server data in Zustand
+- NEVER manually map server validation errors to form fields — `@quanticjs/react-forms` handles this
+- NEVER omit `onError` on non-form mutations — every mutation failure must be visible to the user
+- NEVER show `error.detail` from 5xx responses — use generic message instead
+- NEVER write `catch (e) { console.log(e) }` on mutations — swallowing errors is a bug
+- NEVER use `any` — use `unknown` and narrow
+- NEVER hardcode hex colors or spacing values
+- NEVER use `NodeJS.Timeout` or other Node.js types in frontend code
+- API errors handled via `ApiError` from `@quanticjs/react-core` — use `.detail`, `.fieldErrors`, `.correlationId`
+- Auth refresh handled automatically by `createClient`'s `auth.refresh` — NEVER implement retry logic on 401

package/templates/claude/skills/add-handler/SKILL.md

@@ -0,0 +1,105 @@
+# Add Handler
+
+Create a CQRS command or query with validator and handler following the `@quanticjs/core` patterns.
+
+## Usage
+```
+/add-handler CreateItem in project
+/add-handler GetUserProfile in identity
+```
+
+## Steps
+
+1. **Create command or query class** in `src/<module>/commands/` or `src/<module>/queries/`
+   - Add `@Validate(XxxValidator)` decorator on the command class (MANDATORY)
+   - Add optional decorators as needed: `@Cache`, `@DistributedLock`, `@FeatureFlag`
+   ```typescript
+   import { Validate, DistributedLock } from '@quanticjs/core';
+
+   @Validate(CreateXxxValidator)
+   @DistributedLock('create-xxx:{name}')  // only if critical section needed
+   export class CreateXxxCommand {
+     constructor(public readonly name: string, public readonly userId: string) {}
+   }
+   ```
+
+2. **Create `.validator.ts`** co-located with the command — ALL validation logic lives here:
+   ```typescript
+   import { z } from 'zod';
+   import { ICommandValidator, validateCommand } from '@quanticjs/core';
+
+   export class CreateXxxValidator implements ICommandValidator<CreateXxxCommand> {
+     private schema = z.object({
+       name: z.string().min(1).max(100),
+       // Business rules go here as .refine() / .superRefine()
+     });
+     validate(command: CreateXxxCommand) { return validateCommand(this.schema, command); }
+   }
+   ```
+
+3. **Create handler class** implementing `ICommandHandler<T>` or `IQueryHandler<T>`:
+   ```typescript
+   import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+   import { InjectRepository } from '@nestjs/typeorm';
+   import { Repository } from 'typeorm';
+   import { getTransactionalRepo, Result } from '@quanticjs/core';
+
+   @CommandHandler(CreateXxxCommand)
+   export class CreateXxxHandler implements ICommandHandler<CreateXxxCommand> {
+     constructor(@InjectRepository(Xxx) private readonly xxxRepo: Repository<Xxx>) {}
+
+     async execute(command: CreateXxxCommand): Promise<Result<XxxDto>> {
+       const xxxRepo = getTransactionalRepo(this.xxxRepo);  // UnitOfWork
+       const entity = xxxRepo.create({ name: command.name });
+       await xxxRepo.save(entity);
+       return Result.success(toDto(entity));
+     }
+   }
+   ```
+
+4. **Register** handler and validator in module's `providers` array
+5. **Add tests** — run `/write-backend-tests` for the handler and validator
+
+## Pipeline Behavior Chain
+**Commands:** `Log (global) → FeatureFlag → Validate → Cache → DistributedLock → Transactional (auto) → Handler`
+**Queries:** `Log (global) → FeatureFlag → Validate → Cache → Handler`
+
+## Available Decorators
+| Decorator | When to Use |
+|-----------|-------------|
+| `@Validate(ValidatorClass)` | Every command with external input (MANDATORY) |
+| `@DistributedLock('key:{prop}')` | Commands with critical sections — race conditions, concurrent writes, resource contention |
+| `@Cache('key:{prop}', { ttlSeconds })` | Read-heavy queries |
+| `@FeatureFlag('release-module-feature')` | Feature-gated commands (see naming below) |
+| `@IsolatedTransaction()` | Audit/notification commands that must commit independently |
+
+## Feature Flag Naming & Lifecycle
+
+When adding `@FeatureFlag`, use the correct naming convention and fallback:
+
+| Category | Name format | Lifetime | Fallback |
+|---|---|---|---|
+| **Release** | `release-{module}-{feature}` | Remove within 30 days of full rollout | `throw` (default) |
+| **Kill switch** | `kill-{module}-{feature}` | Permanent | `throw` (default) |
+| **Experiment** | `experiment-{module}-{feature}` | Remove within 90 days | `default` (control variant) |
+
+```typescript
+@FeatureFlag('release-billing-invoices')                                    // blocks if disabled
+@FeatureFlag('kill-payments-processing')                                    // blocks if disabled
+@FeatureFlag('experiment-scoring-v2', { fallback: 'default', defaultValue: oldResult })
+@FeatureFlag('release-notifications-email', { fallback: 'skip' })           // silently skips
+```
+
+If `UNLEASH_URL` is not set, all flags pass — local dev and tests work without Unleash.
+
+## Rules
+- Command class MUST have `@Validate(XxxValidator)` — without it, the `.validator.ts` is dead code
+- ALL validation in `.validator.ts` using Zod — NEVER validate inline in handlers
+- Business rules (age >= 18, email unique, date range valid) → Zod `.refine()` / `.superRefine()` in validator
+- Handler uses `getTransactionalRepo()` for all repo access — UnitOfWork is automatic
+- Handlers NEVER contain validation logic — no `if (x < y) return Result.validationError()`
+- Handlers NEVER throw exceptions — return `Result.failure()` / `Result.notFound()` / `Result.conflict()` etc.
+- If handler has a critical section, add `@DistributedLock('key:{prop}')` on the **command class**
+- Return `Result<T>` from handlers — never throw for business errors
+- Feature flags: NEVER nest multiple `@FeatureFlag` on one handler — one handler, one flag
+- Feature flags: NEVER use on infrastructure code (migrations, middleware) — use env vars instead