@quanticjs/create-app 0.1.1

package/templates/claude/rules/playwright-mcp.md

@@ -0,0 +1,80 @@
+# Playwright MCP — Browser Control for Claude Code
+
+You have a Playwright MCP server configured (`.claude/mcp.json`). This gives you **real-time browser control** — navigate pages, click elements, fill forms, and take screenshots without writing test files.
+
+**State "using Playwright MCP" in your first message of an MCP session** — otherwise Claude may default to Bash-driven Playwright commands instead of the MCP tools.
+
+## Setup & Version Pinning
+
+- **Package:** Microsoft's `@playwright/mcp` — **NOT** the community `@executeautomation/playwright-mcp-server`. Do not confuse them.
+- **Pin the version** in `.claude/mcp.json`. Never use `@latest` in shared configs — beta releases silently break tool schemas mid-session.
+- **Node 18+ required.** Older versions throw `performance is not defined`. Verify with `node --version` before any MCP run.
+- **Install browser binaries** after any version bump: `npx playwright install` (and `npx playwright install-deps` on Linux/CI).
+- **Smoke test** after setup: `browser_navigate` to `http://localhost:5173/` and confirm the a11y tree returns.
+
+## CI / Headless
+
+- Pass `--headless` to the MCP server args when running in CI or Docker — default is headed.
+- For repeatable CI runs, prefer coded specs (`client/e2e/`) over MCP. Use MCP for exploration and debugging, not pipeline execution.
+
+## Two Uses
+
+### 1. Visual Self-QA (during implementation)
+After implementing UI changes, open the page and verify it renders correctly:
+- `browser_navigate` to the page → `browser_snapshot` (content) or `browser_screenshot` (visual layout) → check it looks right
+- Use during any issue that touches `.tsx` files
+
+### 2. E2E Journey Verification (via `/e2e-verify`)
+Walk through full user journeys by browsing the app interactively. This replaces hardcoded Playwright spec files for UI verification. See `.claude/skills/e2e-verify/SKILL.md` for the journey definitions.
+
+## MCP Tools
+
+- `browser_navigate` — open a URL
+- `browser_click` — click an element
+- `browser_fill` — type into an input
+- `browser_snapshot` — return the accessibility tree (~120 tokens, stable selectors)
+- `browser_screenshot` — capture a visual screenshot (~1,500 tokens)
+- `browser_select_option`, `browser_hover`, `browser_drag`, etc.
+
+## Snapshot vs Screenshot
+
+Prefer `browser_snapshot` for element discovery, interaction, and content verification — it returns the accessibility tree, costs ~12x fewer tokens than a screenshot, and provides more stable element references.
+
+Use `browser_take_screenshot` only when verifying **visual appearance** (colors, layout, spacing, images).
+
+## Authenticated Pages
+
+Most pages require login. The app uses BFF httpOnly cookies — not sessionStorage tokens.
+
+Run `cd client && npx tsx ../scripts/save-auth-state.ts` first (requires Docker stack up). This completes the BFF OIDC login flow through Keycloak and saves the resulting httpOnly session cookie to `client/e2e/auth/storage-state.json`.
+
+If pages redirect to the login page, the storage state is expired — re-run the save script.
+
+## Ports
+
+### Dev Stack (visual self-QA during development)
+
+| Service | URL | When |
+|---------|-----|------|
+| Vite dev server | `http://localhost:5173` | `cd client && npm run dev` |
+| Backend API | `http://localhost:3000` | `docker compose up` |
+| Keycloak | `http://localhost:8080` | `docker compose up` |
+
+### Test Stack (E2E skills: `/e2e-full`, `/e2e-verify`, `/e2e-audit`)
+
+| Service | URL | When |
+|---------|-----|------|
+| Vite (test) | `http://localhost:5199` | `cd client && VITE_API_URL=http://localhost:3099 npm run dev -- --port 5199` |
+| Backend API (test) | `http://localhost:3099` | `docker compose -f docker-compose.test.yml up` |
+| Keycloak (test) | `http://localhost:8099` | `docker compose -f docker-compose.test.yml up` |
+
+**E2E tests MUST use the test stack** — never the dev stack.
+
+## Do NOT
+
+- Do not commit `client/e2e/auth/storage-state.json` — it contains httpOnly session cookies
+- Do not use MCP for API contract assertions (status codes, JSON payloads) — use coded tests for those
+- Do not use MCP as a replacement for the mocked UI E2E suite (`client/e2e/`) — MCP is for exploratory/visual verification only
+- Do not point MCP at environments with real user data. Every page's DOM, console output, and form values get transmitted to Anthropic's API — keep MCP restricted to the local dev stack
+- Do not use `@playwright/mcp@latest` in `.claude/mcp.json` — pin a specific version
+- Do not install `@executeautomation/playwright-mcp-server` thinking it's the same package — it isn't

package/templates/claude/rules/resilience-ops.md

@@ -0,0 +1,103 @@
+---
+globs: "src/**/*.ts"
+---
+
+# Resilience & Operations Patterns
+
+## Health Probes
+
+Every service imports `QuanticHealthModule.forRoot()` in `app.module.ts`. It provides three Kubernetes probes:
+
+| Probe | Path | Checks | Purpose |
+|---|---|---|---|
+| Liveness | `/health/live` | Event loop only | Is the process alive? Restart if not. |
+| Readiness | `/health/ready` | DB + Redis (auto-detected) + custom | Can it serve traffic? Remove from LB if not. |
+| Startup | `/health/startup` | User-configured | Has initialization completed? |
+
+**Auto-detection:** If `DataSource` or `REDIS_CLIENT` is in the DI container, readiness checks are registered automatically. Disable with `autoDetect: false`.
+
+**Transport modes:**
+- `controller` (default) — mounts on existing NestJS server, routes are `@Public()`
+- `standalone` — separate `http.createServer` on dedicated port (for workers/queue consumers)
+- `file` — writes to `/tmp/.healthy` on interval (for cron jobs)
+- `none` — programmatic access only via `HealthRegistry`
+
+**Custom checks:**
+```typescript
+QuanticHealthModule.forRoot({
+  readiness: [
+    { name: 'minio', check: () => minioClient.bucketExists('uploads'), timeoutMs: 5000 },
+    { name: 'payments', url: 'http://payments:3000/health/live', timeoutMs: 3000 },
+  ],
+})
+```
+
+**Shutdown-aware:** On SIGTERM, readiness flips to 503 immediately, waits `shutdownDelayMs` (default 5s) for LB to stop routing, then `GracefulShutdownService` drains resources.
+
+## Graceful Shutdown
+
+On SIGTERM, shutdown runs in two phases:
+
+```
+SIGTERM → Phase 1: readiness → 503, wait 5s (LB stops routing)
+        → Phase 2: drainWork() → close DB → close Redis → exit
+```
+
+Services with custom resources (queues, websockets, outbox publisher) override `drainWork()`:
+
+```typescript
+@Injectable()
+export class AppShutdownService extends GracefulShutdownService {
+  constructor(
+    @Optional() dataSource: DataSource,
+    @Optional() @Inject('REDIS_CLIENT') redis: Redis,
+    private readonly queueWorker: Worker,
+  ) {
+    super(dataSource, redis);
+  }
+
+  protected async drainWork(): Promise<void> {
+    await this.queueWorker.close(); // stop accepting jobs, wait for in-progress
+  }
+}
+```
+
+**Kubernetes alignment:** `terminationGracePeriodSeconds` must exceed `shutdownDelayMs + drainTimeout + buffer` (default: 45s in Helm chart).
+
+## Circuit Breaker
+
+All outbound HTTP calls to external services must use `createCircuitBreaker()`:
+
+```typescript
+import { createCircuitBreaker } from '@quanticjs/core';
+
+const policy = createCircuitBreaker({
+  maxRetries: 2,              // 3 total attempts, exponential backoff
+  consecutiveFailures: 5,     // open circuit after 5 consecutive failures
+  halfOpenAfterMs: 30_000,    // test one request after 30s
+});
+
+const result = await policy.execute(() => httpClient.get('/external-api'));
+```
+
+**States:** Closed (normal) → Open (fast-fail, no outbound calls) → Half-open (test one request) → Closed on success.
+
+**Where to apply:**
+
+| Integration | Circuit breaker? |
+|---|---|
+| Keycloak JWKS | Yes |
+| Kogito workflow | Yes |
+| Third-party APIs | Yes |
+| Redis | No — ioredis has built-in retry |
+| TypeORM / DB | No — connection pool retries internally |
+
+## NEVER
+
+- **NEVER** make liveness depend on external services (DB, Redis) — liveness checks the process only; dependency failures go in readiness
+- **NEVER** skip `QuanticHealthModule.forRoot()` in `app.module.ts` — every service needs health probes
+- **NEVER** exit on SIGTERM without draining — extend `GracefulShutdownService` and close custom resources in `drainWork()`
+- **NEVER** make outbound HTTP calls to external services without a circuit breaker
+- **NEVER** retry 4xx responses — they are deterministic client errors
+- **NEVER** share a circuit breaker across integrations — one failing service must not trip the circuit for healthy ones
+- **NEVER** wrap Redis or TypeORM calls in a circuit breaker — they have built-in retry/reconnect

package/templates/claude/rules/testing-e2e-ui.md

@@ -0,0 +1,190 @@
+---
+globs: "client/e2e/**/*.ts, client/playwright.config.ts"
+---
+
+# Testing — E2E UI (Playwright, Mocked APIs)
+
+All API calls are mocked with `page.route()`. Tests verify the UI renders correctly and user interactions work.
+
+## Coverage Requirements (MANDATORY)
+
+**Every spec file MUST test all four states:**
+
+| State | What to test | How to mock |
+|-------|-------------|-------------|
+| **Happy path** | Feature works as expected | Mock API returns 200 with valid data |
+| **Error state** | API failure shows error UI | Mock API returns 500, verify error message shown |
+| **Empty state** | No data shows empty UI | Mock API returns 200 with empty array |
+| **Loading state** | Skeleton/spinner shown while loading | Delay API response, verify skeleton visible |
+
+```typescript
+test.describe('Projects List', () => {
+  test('shows project cards on success', async ({ page }) => {
+    await page.route('**/api/projects*', route => route.fulfill({
+      status: 200, json: { value: mockProjects },
+    }));
+    await page.goto('/projects');
+    await expect(page.getByText('My Project')).toBeVisible();
+  });
+
+  test('shows error message on API failure', async ({ page }) => {
+    await page.route('**/api/projects*', route => route.fulfill({ status: 500 }));
+    await page.goto('/projects');
+    await expect(page.getByText(/something went wrong|error|try again/i)).toBeVisible();
+  });
+
+  test('shows empty state when no projects', async ({ page }) => {
+    await page.route('**/api/projects*', route => route.fulfill({
+      status: 200, json: { value: [] },
+    }));
+    await page.goto('/projects');
+    await expect(page.getByText(/no projects/i)).toBeVisible();
+  });
+
+  test('shows loading while fetching', async ({ page }) => {
+    await page.route('**/api/projects*', async route => {
+      await new Promise(r => setTimeout(r, 2000));
+      await route.fulfill({ status: 200, json: { value: [] } });
+    });
+    await page.goto('/projects');
+    await expect(page.locator('[role="status"]')).toBeVisible();
+  });
+});
+```
+
+## Auth Mocking (MANDATORY)
+
+Auth uses BFF httpOnly cookies — **not** localStorage/sessionStorage tokens.
+
+Mock the BFF `/auth/me` endpoint in `beforeEach`:
+
+```typescript
+test.beforeEach(async ({ page }) => {
+  await page.route('**/auth/me', route => route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      id: 'user-1',
+      keycloakId: 'kc-1',
+      email: 'test@test.com',
+      displayName: 'Test User',
+      role: 'user',
+      roles: ['user'],
+      permissions: ['project.read', 'project.create'],
+    }),
+  }));
+});
+
+test('unauthenticated user redirected to login', async ({ page }) => {
+  await page.route('**/auth/me', route => route.fulfill({ status: 401 }));
+  await page.goto('/projects');
+  await expect(page).toHaveURL(/\/login/);
+});
+
+test('non-admin cannot access admin pages', async ({ page }) => {
+  // Default mock has role: 'user' — admin routes should redirect
+  await page.goto('/admin/prompt-templates');
+  await expect(page).not.toHaveURL('/admin/prompt-templates');
+});
+```
+
+**NEVER** mock auth by injecting tokens into `localStorage` or `sessionStorage` — the app uses BFF httpOnly cookies and checks auth via `/auth/me`.
+
+## Locators — Semantic ONLY
+
+```typescript
+// ❌ WRONG
+page.locator('.btn-primary');
+page.locator('[data-testid="submit"]');
+page.locator('.fixed.inset-0');
+page.locator('[class*="animate-pulse"]');
+
+// ✅ CORRECT
+page.getByRole('button', { name: 'Submit' });
+page.getByRole('heading', { name: 'Projects' });
+page.getByLabel('Email address');
+page.getByText('Welcome back');
+page.getByPlaceholder('Search...');
+```
+
+**Priority:** `getByRole` > `getByLabel` > `getByText` > `getByPlaceholder` > `getByTestId` (last resort)
+
+Chain and filter to narrow scope:
+```typescript
+const card = page.getByRole('listitem').filter({ hasText: 'My Project' });
+await card.getByRole('link', { name: 'View' }).click();
+```
+
+## Assertions — Web-First Only
+
+```typescript
+// ❌ WRONG — checks once, no retry, FLAKY
+expect(await page.getByText('welcome').isVisible()).toBe(true);
+
+// ✅ CORRECT — retries until visible or timeout
+await expect(page.getByText('welcome')).toBeVisible();
+await expect(page.getByRole('heading')).toHaveText('Dashboard');
+await expect(page).toHaveURL('/projects');
+```
+
+## Waiting — Correct Alternatives
+
+```typescript
+// ❌ WRONG
+await page.waitForTimeout(500);
+
+// ✅ CORRECT
+await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible();
+await page.waitForURL('/projects');
+await page.waitForResponse('**/api/projects');
+await expect(page.getByRole('heading')).toHaveText('Success');
+```
+
+## Responsive Viewport Testing
+
+```typescript
+test.describe('tablet', () => {
+  test.use({ viewport: { width: 768, height: 1024 } });
+  test('sidebar collapses on tablet', async ({ page }) => {
+    await page.goto('/');
+    // verify collapsed sidebar behavior
+  });
+});
+
+test.describe('desktop', () => {
+  test.use({ viewport: { width: 1440, height: 900 } });
+  test('shows expanded sidebar', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.getByRole('navigation')).toBeVisible();
+  });
+});
+```
+
+## Test File Structure
+
+```
+client/e2e/
+├── auth/
+│   └── storage-state.json   # gitignored — MCP session cookies
+├── login.spec.ts
+├── dashboard.spec.ts
+├── projects-list.spec.ts
+├── create-project.spec.ts
+├── project-detail.spec.ts
+├── prompt-templates.spec.ts
+├── profile.spec.ts
+├── settings.spec.ts
+└── users.spec.ts
+```
+
+## NEVER
+
+- **NEVER** use CSS selectors (`.class`, `#id`, `div > span`, `[class*="..."]`)
+- **NEVER** use `expect(await el.isVisible()).toBe(true)` — use `await expect(el).toBeVisible()`
+- **NEVER** use `page.waitForTimeout()`
+- **NEVER** use XPath selectors
+- **NEVER** test third-party services directly — mock with `page.route()`
+- **NEVER** use `localStorage`/`sessionStorage` to mock auth — mock `/auth/me` via `page.route()`
+- **NEVER** use `fireEvent` — use Playwright's built-in actions (`click`, `fill`, `press`)
+- **NEVER** write happy-path-only tests — all 4 states are mandatory
+- **NEVER** use `.animate-spin` or other CSS class selectors for loading states — use `[role="status"]` or semantic text

package/templates/claude/rules/testing-patterns.md

@@ -0,0 +1,94 @@
+---
+globs: "src/**/*.spec.ts, src/**/*.test.ts, client/src/**/*.test.{ts,tsx}, client/e2e/**"
+---
+
+# Testing Patterns
+
+## Backend — Three Layers
+
+### Unit Tests (Jest)
+
+Test handlers, validators, and utilities in isolation.
+
+Every handler test must cover: happy path, validation failure, not found, conflict, permission check.
+
+Validator tests are mandatory and separate.
+
+### Integration Tests (Jest + Supertest)
+
+Full HTTP → Controller → Pipeline → Handler → Database round trips.
+
+**Real database, not mocks.** Run against PostgreSQL via `docker-compose.test.yml`.
+
+### E2E Tests
+
+Isolated test stack: `docker-compose.test.yml` with separate ports (API 3099, Keycloak 8099).
+
+## Frontend — Three Layers
+
+### Component Tests (Vitest + React Testing Library)
+
+Test user-visible behavior, not implementation details.
+
+**Query priority:** `getByRole` > `getByLabelText` > `getByText` > `getByTestId` (last resort).
+
+**Every component test must cover:** happy path, loading state, error state, empty state, user interactions.
+
+```typescript
+it('renders item name', () => {
+  render(<ItemCard item={{ id: '1', name: 'Test' }} />);
+  expect(screen.getByRole('heading', { name: 'Test' })).toBeInTheDocument();
+});
+```
+
+### Hook Tests (Vitest + TanStack Query)
+
+Test custom hooks with a real QueryClient. Use MSW for API mocking.
+
+**Auth mocking:**
+```typescript
+// ✅ CORRECT
+queryClient.setQueryData(['auth', 'session'], { keycloakId: 'test-id', roles: ['user'] });
+
+// ❌ WRONG
+localStorage.setItem('access_token', 'fake-jwt');
+```
+
+### E2E Tests (Playwright)
+
+Mock APIs via `page.route()`. Every spec covers 4 states:
+
+| State | Mock |
+|-------|------|
+| Happy path | API returns 200 |
+| Error | API returns 500 |
+| Empty | API returns 200 + empty array |
+| Loading | Delay API response |
+
+**Auth in E2E:**
+```typescript
+await page.route('**/auth/me', route => route.fulfill({
+  status: 200,
+  body: JSON.stringify({ keycloakId: 'kc-1', roles: ['user'] }),
+}));
+```
+
+**Responsive testing:** Test at mobile viewport (375×812) and desktop.
+
+## CI Pipeline
+
+```
+PR → lint → type-check → unit tests → integration tests → UI E2E → merge
+Nightly → system E2E (full stack)
+```
+
+## NEVER
+
+- **NEVER** test implementation details (internal state, private methods, CSS classes)
+- **NEVER** use CSS selectors in E2E tests — use semantic locators
+- **NEVER** use `page.waitForTimeout()` — use web-first assertions
+- **NEVER** use `fireEvent` — use `userEvent`
+- **NEVER** mock the database in integration tests
+- **NEVER** use `localStorage`/`sessionStorage` for auth in tests
+- **NEVER** write happy-path-only tests
+- **NEVER** use `setTimeout`/`waitForTimeout` for timing in tests

package/templates/claude/rules/workflow-backend.md

@@ -0,0 +1,64 @@
+# Workflow Backend — Use the Workflow Engine, Don't Rebuild It
+
+The workflow engine handles process orchestration, task routing, and state management. **Application code defines workflow configurations and domain-specific handlers — never reimplements the engine.**
+
+## Workflow Module (`src/workflow/`)
+
+This module owns all workflow engine interaction. Other modules (change-request, notification, etc.) consume workflow events and provide domain-specific handlers — they never access workflow internals directly.
+
+## Engine Responsibilities
+
+| Concern | Handled by |
+|---|---|
+| Process instance lifecycle (start, signal, abort) | Workflow module commands |
+| Task assignment and routing | Workflow engine based on process definitions |
+| Task claim/unclaim/complete | Workflow module commands dispatched from controllers |
+| Process variable management | Workflow engine context — read via workflow queries |
+| Workflow state transitions | Process definitions — not application code |
+
+## What Goes in Application Code vs. Workflow Engine
+
+| Belongs in **application code** | Belongs in **workflow engine** (already built) |
+|---|---|
+| Workflow definition configs (which roles, which steps) | Process execution and state machine logic |
+| Domain-specific task completion handlers | Task routing and assignment rules |
+| Commands to start/signal/complete workflow steps | Process instance lifecycle management |
+| Validators for task completion payloads | State transition persistence |
+| Event consumers reacting to workflow state changes | Process evaluation and branching |
+| Role and permission definitions for workflow steps | Task inbox queries and filtering |
+
+## Inter-Module Communication
+
+Other modules interact with workflows through the bus — never by importing workflow services directly:
+
+```typescript
+// ✅ CORRECT — dispatch via CommandBus
+this.commandBus.execute(new StartWorkflowCommand(processId, variables));
+this.commandBus.execute(new CompleteTaskCommand(taskId, payload));
+this.queryBus.execute(new GetProcessTimelineQuery(processInstanceId));
+
+// ❌ WRONG — direct service import from another module
+await this.workflowService.startProcess('cr-approval', variables);
+```
+
+## Workflow Events via Redis Streams
+
+Workflow state changes are published to Redis Streams. Domain modules subscribe to react:
+
+| Event | Published when |
+|---|---|
+| `workflow.process.started` | New process instance created |
+| `workflow.task.assigned` | Task routed to a user/role |
+| `workflow.task.completed` | Task action submitted |
+| `workflow.process.completed` | Process reaches end state |
+| `workflow.process.error` | Process hits an error boundary |
+
+## NEVER
+
+- **NEVER** access workflow internals from outside the workflow module — dispatch commands via the bus
+- **NEVER** write your own process state machine — use the workflow engine
+- **NEVER** write your own task assignment/routing logic — configure it in process definitions
+- **NEVER** write your own task inbox query — use workflow module queries
+- **NEVER** manage process variables outside the workflow module — read them via workflow queries
+- **NEVER** poll for workflow state changes — subscribe to workflow Redis Stream events
+- **NEVER** import workflow module services into other modules — use CommandBus/QueryBus

package/templates/claude/rules/workflow-frontend.md

@@ -0,0 +1,60 @@
+# Workflow UI — Use `@quanticjs/workflow-ui`, Don't Rebuild It
+
+`@quanticjs/workflow-ui` provides the **complete workflow UI layer** for task management. Every component and hook below is already implemented. Import and use it — never write your own version.
+
+## Provider
+
+| Export | Purpose |
+|---|---|
+| `WorkflowProvider` | Context provider for workflow hooks — wraps pages that use workflow features |
+
+## Hooks
+
+| Hook | Purpose |
+|---|---|
+| `useTaskList(filters?)` | Fetches task inbox — filterable by status, role, assignee |
+| `useTask(taskId)` | Fetches single task with full context (process variables, form schema) |
+| `useTaskClaim(taskId)` | Claim/unclaim a task for the current user |
+| `useTaskAction(taskId)` | Complete, delegate, or skip a task with payload |
+| `useProcessTimeline(processInstanceId)` | Fetches workflow state history — completed/pending/active nodes |
+
+## Components
+
+| Component | Purpose |
+|---|---|
+| `TaskInbox` | Full task list with filtering, sorting, pagination — renders role-based task assignments |
+| `WorkflowForm` | Dynamic form rendered from task form schema — integrates with `useTaskAction` |
+| `TaskDetail` | Task context view — process variables, form, history, actions |
+| `TaskActions` | Approve/reject/claim/delegate action buttons — wired to `useTaskAction` |
+| `ProcessTimeline` | Visual workflow state diagram — completed (green), active (yellow), blocked (red) |
+
+## When to Use
+
+| Feature need | Use |
+|---|---|
+| Dashboard task list | `TaskInbox` |
+| Approval interfaces | `TaskDetail` + `TaskActions` |
+| Workflow visualization | `ProcessTimeline` |
+| Dynamic task forms | `WorkflowForm` |
+| Claiming tasks | `useTaskClaim` |
+| Completing workflow steps | `useTaskAction` |
+
+## What Goes in Application Code vs. workflow-ui
+
+| Belongs in **application code** | Belongs in **workflow-ui** (already built) |
+|---|---|
+| CR-specific approval pages | Task inbox with filtering/sorting/pagination (`TaskInbox`) |
+| Custom approval form layouts composing `TaskDetail` | Task context view + form rendering (`TaskDetail`, `WorkflowForm`) |
+| Page routing to task views | Approve/reject/claim/delegate buttons (`TaskActions`) |
+| Workflow page wrappers with `WorkflowProvider` | Process state visualization (`ProcessTimeline`) |
+| Domain-specific task filters | Task fetching, claiming, action hooks |
+
+## NEVER
+
+- **NEVER** write your own task inbox component — use `TaskInbox` from `@quanticjs/workflow-ui`
+- **NEVER** write your own task detail/actions UI — use `TaskDetail` + `TaskActions` from `@quanticjs/workflow-ui`
+- **NEVER** write your own workflow visualization — use `ProcessTimeline` from `@quanticjs/workflow-ui`
+- **NEVER** write your own dynamic form renderer for workflow tasks — use `WorkflowForm` from `@quanticjs/workflow-ui`
+- **NEVER** write your own task list/claim/complete hooks — use `useTaskList` / `useTaskClaim` / `useTaskAction` from `@quanticjs/workflow-ui`
+- **NEVER** write your own process timeline hook — use `useProcessTimeline` from `@quanticjs/workflow-ui`
+- **NEVER** use workflow hooks outside a `WorkflowProvider` — wrap workflow pages with it

package/templates/claude/settings.json

@@ -0,0 +1,68 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm install *)",
+      "Bash(npm ci)",
+      "Bash(npm run *)",
+      "Bash(npm test *)",
+      "Bash(npm init *)",
+      "Bash(npx *)",
+      "Bash(node *)",
+      "Bash(ls *)",
+      "Bash(find *)",
+      "Bash(grep *)",
+      "Bash(cat *)",
+      "Bash(mkdir *)",
+      "Bash(cp *)",
+      "Bash(mv *)",
+      "Bash(git status*)",
+      "Bash(git log*)",
+      "Bash(git diff*)",
+      "Bash(git branch*)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(docker compose *)",
+      "Bash(docker build *)",
+      "Bash(docker ps*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-destructive.sh\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-secrets.sh\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-format.sh\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/on-compaction.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
+  "enabledPlugins": {
+    "frontend-design@claude-plugins-official": true
+  }
+}