@quanticjs/create-app 0.1.1

package/templates/claude/skills/implement-spec/SKILL.md

@@ -0,0 +1,98 @@
+# Implement Spec
+
+Implement a feature from an existing spec file, dynamically selecting only the sub-skills required by the spec's technical design.
+
+## Usage
+```
+/implement-spec SPEC-brd-analyzer.md
+/implement-spec SPEC-project-items.md
+```
+
+## Steps
+
+### Step 1: Load and Parse Spec
+1. Read the spec file from `docs/specs/<argument>` (or the full path if provided)
+2. If the argument is ambiguous or missing, list all files in `docs/specs/` and ask the user to pick one using AskUserQuestion
+3. Extract these sections:
+   - **Acceptance Criteria** — what "done" looks like
+   - **Technical Design** — modules, data model, API, events
+   - **Edge Cases** — error handling requirements
+   - **Test Plan** — what tests are needed
+
+### Step 2: Plan Implementation
+
+**Architecture check (MANDATORY first step):** This is a modular monolith. Before planning anything else, answer: does this spec introduce new domain areas that need their own NestJS module? Each distinct bounded context (e.g., "definition storage", "role registry", "billing", "notifications") must be its own module with its own directory, its own NestJS `@Module()`, and communication via `CommandBus`/`QueryBus`. Do NOT dump new domain logic into an existing module as subdirectories with loose services. If the spec introduces new domain areas, `/add-module` is the FIRST sub-skill to invoke.
+
+Based on the spec's Technical Design section, determine which sub-skills are needed. Only include what the spec calls for:
+
+| Spec mentions... | Run |
+|---|---|
+| New bounded context / module | `/add-module` |
+| New entities or data model changes | `/add-entity` |
+| Database schema changes | `/add-migration` |
+| Commands or queries | `/add-handler` |
+| REST endpoints | `/add-api-endpoint` |
+| Authenticated/role-gated endpoints | `/add-auth-endpoint` |
+| Frontend pages or components | `/add-frontend-page` |
+| External API integration (AI, payment, etc.) | `/add-integration` |
+| Domain events / async messaging | `/add-event` |
+| WebSocket / real-time updates | `/add-realtime` |
+| Backend tests | `/write-backend-tests` |
+| E2E / UI tests | `/write-ui-tests` |
+
+Present the plan to the user: which sub-skills will run, in what order, and why. Wait for confirmation before proceeding.
+
+### Step 3: Execute Implementation
+**Invoke each selected sub-skill via the Skill tool** in dependency order. Each sub-skill enforces the project's architectural rules (CQRS, validators, thin controllers, etc.) — those rules are the reason sub-skills exist. Writing code directly instead of invoking the skill bypasses every guardrail.
+
+Execution order:
+1. Module structure → invoke `/add-module`
+2. Entities → invoke `/add-entity` for each entity
+3. Migrations → invoke `/add-migration`
+4. Handlers → invoke `/add-handler` for each command/query (this creates the Command class, Handler, `.validator.ts` with Zod, and wires `@Validate`)
+5. API endpoints → invoke `/add-api-endpoint` or `/add-auth-endpoint` (this creates thin controllers that only dispatch to CommandBus/QueryBus)
+6. Frontend pages → invoke `/add-frontend-page`
+7. Integrations / events / realtime → invoke `/add-integration`, `/add-event`, `/add-realtime`
+8. Tests → invoke `/write-backend-tests` then `/write-ui-tests`
+
+Pass context from the spec into each sub-skill invocation — entity names, field types, endpoint paths, role requirements, etc. come from the spec, not guesswork.
+
+**Between sub-skill invocations**, you may write glue code that no sub-skill covers (e.g., a shared service, a converter utility, a parser). But any code that a sub-skill is responsible for (entities, commands, handlers, validators, controllers, tests) MUST be generated by invoking that sub-skill.
+
+### Step 4: Verify Against Acceptance Criteria
+1. Run `npm run build && npm test`
+2. Walk through each acceptance criterion from the spec
+3. For any criterion that isn't covered by the implementation, flag it to the user
+4. If E2E tests are in the test plan, run `/write-ui-tests`
+
+### Step 5: Create Implementation PR
+1. Create branch: `git checkout -b feat/<feature-slug>`
+2. Stage all implementation files (NOT the spec file — it's already merged)
+3. Commit with a message referencing the spec: `feat(<module>): implement <feature-name>`
+4. Push and open PR:
+   ```bash
+   gh pr create \
+     --title "feat(<module>): <feature-name>" \
+     --body "## Summary
+   Implements \`docs/specs/SPEC-<feature-slug>.md\`
+
+   ## Changes
+   <bullet list of what was added>
+
+   ## Acceptance Criteria
+   <checklist copied from spec>
+
+   ## Test Coverage
+   - [ ] Unit tests pass
+   - [ ] E2E tests pass (if applicable)
+   - [ ] All acceptance criteria verified"
+   ```
+
+## Rules
+- NEVER guess what to build — every decision comes from the spec
+- NEVER skip sub-skills that the spec's Technical Design requires
+- NEVER run sub-skills the spec doesn't call for
+- NEVER write code directly that a sub-skill is responsible for — always invoke the sub-skill via the Skill tool. Sub-skills enforce architectural rules (CQRS pipeline, `@Validate` + `.validator.ts`, thin controllers dispatching to CommandBus/QueryBus, `Result<T>`, `getTransactionalRepo`). Writing the code yourself bypasses all of these guardrails. If you find yourself writing a Command class, a Handler, a `.validator.ts`, a Controller, an Entity, or a test file without having invoked the corresponding sub-skill, STOP — you are doing it wrong.
+- If the spec is incomplete or ambiguous, ask the user BEFORE implementing
+- Always present the implementation plan and get confirmation before step 3
+- The spec file itself is never modified or committed by this skill

package/templates/claude/skills/review-code/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: review-code
+description: Multi-dimensional code review (quality, security, app logic) grounded in .claude/rules/. Classifies findings as Blocker, Suggestion, or Nit.
+---
+
+# Review Code — Quality, Security, Logic
+
+Senior-engineer review across three dimensions, grounded in the project's rules in `.claude/rules/`. Every finding must cite a rule or a concrete reason, reference `file:line`, and carry a severity.
+
+## Usage
+```
+/review-code                    # review all uncommitted + unpushed changes
+/review-code <path>             # review a file or directory
+/review-code main...HEAD        # review a branch vs main
+```
+
+## Process
+
+### Step 1: Scope
+- Default: `git diff --name-only HEAD` + `git diff --name-only main...HEAD`
+- If a path/range is provided, scope the review to that
+- Read every changed file in full — do NOT rely on the diff alone
+
+### Step 2: Load Applicable Rules
+Only load the rules that match the changed surface area:
+
+| Changed area | Rules to apply |
+|---|---|
+| `src/**/*.ts` | `backend-patterns.md`, `database-patterns.md` (if entity/migration) |
+| `client/src/**/*.{ts,tsx}` | `frontend-patterns.md` |
+| `*.spec.ts` / `*.test.tsx` | `testing-patterns.md` |
+| `Dockerfile*`, `docker-compose*.yml` | `docker-patterns.md` |
+| Auth-related | `auth-patterns.md` |
+
+### Step 3: Three Review Passes
+
+#### Pass A — Code Quality
+- Controllers thin? `@Validate` present? `getTransactionalRepo` used? `Result<T>` returned?
+- Validation logic misplaced in handlers?
+- Entity inheritance correct? camelCase columns? no duplicate `@Index`?
+- `.forRoot()` modules only in `app.module.ts`?
+- Frontend: React Query for server state? No tokens in localStorage? No `NodeJS.*` types?
+- Dead code, `console.log`, unused imports, missing error/empty/loading states
+
+#### Pass B — Security
+- Auth: JWT guard on every non-`@Public()` route? No token returned to browser?
+- Input: DTO class-validator decorators? Zod in `.validator.ts`? No raw SQL concatenation?
+- Secrets: no hardcoded keys, tokens, passwords?
+- Frontend XSS: no `dangerouslySetInnerHTML`? No tokens in URL params?
+- Logging: no PII, tokens, or secrets in logs?
+
+#### Pass C — Application Logic
+- Does the implementation satisfy the intent?
+- Transaction boundaries: multi-step writes in one UoW?
+- Concurrency: race windows protected with `@DistributedLock`?
+- Edge cases: empty input, pagination, null vs undefined
+- Frontend: loading/empty/error states rendered? optimistic update reverts on failure?
+
+### Step 4: Classify Every Finding
+
+| Severity | Definition |
+|---|---|
+| **Blocker** | Must fix before merge. Breaks a mandatory rule, security hole, or corrupts data. |
+| **Suggestion** | Should fix. Correct but suboptimal — missed caching, weak test coverage, unclear naming. |
+| **Nit** | Optional polish. Style, wording, micro-refactor. |
+
+Rules of thumb:
+- If a `.claude/rules/` file says **NEVER** or **MANDATORY** → Blocker
+- If it is a **security** or **data-integrity** concern → Blocker
+- If behavior is correct but surprising to a future reader → Suggestion
+- If removing the finding wouldn't change approval → Nit
+
+### Step 5: Output
+
+```
+## Code Review — <scope>
+
+**Files reviewed:** N   **Passes:** Quality · Security · Logic
+
+---
+
+### BLOCKERS (must fix) — <count>
+
+1. `file:line` · Dimension · rule reference
+   One-line description and fix.
+
+### SUGGESTIONS (should fix) — <count>
+
+2. `file:line` · Dimension
+   One-line description.
+
+### NITS (optional) — <count>
+
+3. `file:line` · Dimension
+   One-line description.
+
+---
+
+### Verdict
+- **N Blockers** — do not merge until resolved
+- **M Suggestions** — address in this PR if cheap
+- **K Nits** — author's discretion
+```
+
+## Rules
+- NEVER invent a rule — every Blocker cites `.claude/rules/` or a concrete security reason
+- NEVER mark a style preference as Blocker
+- NEVER review files you haven't read in full
+- Keep each finding to 1-2 sentences

package/templates/claude/skills/review-spec/SKILL.md

@@ -0,0 +1,216 @@
+# Review Spec
+
+Review an existing spec against `.claude/rules/` and the `/implement-spec` contract. Produces a gap report, then writes a corrected copy that a developer can implement without surprises.
+
+## Usage
+```
+/review-spec SPEC-brd-analyzer.md
+/review-spec --all                  # batch — review every spec in docs/specs/
+```
+
+## Process
+
+### Step 1: Load Spec(s)
+
+1. Read the spec file from `docs/specs/<argument>` (or the full path if provided)
+2. If `--all`, list every `SPEC-*.md` in `docs/specs/` and process each one sequentially
+3. If the argument is ambiguous or missing, list all files in `docs/specs/` and ask the user to pick one using AskUserQuestion
+
+### Step 2: Load Rules
+
+Read **all** rule files from `.claude/rules/` in parallel:
+
+| File | Covers |
+|---|---|
+| `backend-patterns.md` | CQRS, validators, thin controllers, Result\<T\>, UoW, module boundaries, Redis Streams, feature flags |
+| `frontend-patterns.md` | State management, TanStack Query, Zustand, error handling, provider stack, shadcn/ui, TypeScript strict |
+| `auth-patterns.md` | BFF flow, cookie config, token storage, permission model, Socket.IO auth |
+| `database-patterns.md` | TypeORM code-first, camelCase columns, schema-per-module, migration rules |
+| `api-patterns.md` | OpenAPI decorators, DTO patterns, Result→HTTP mapping, RFC 9457 |
+| `testing-patterns.md` | Three backend layers, three frontend layers, CI pipeline |
+| `testing-e2e-ui.md` | Playwright 4-state coverage, auth mocking, semantic locators |
+| `docker-patterns.md` | Compose architecture, Vite proxy, port mapping, E2E isolation |
+| `observability-backend.md` | Pino structured logging, LogBehavior, PII masking, metrics, alerts |
+| `observability-frontend.md` | Sentry, web vitals, correlation IDs |
+| `resilience-ops.md` | Health probes, graceful shutdown, circuit breaker |
+| `playwright-mcp.md` | MCP browser control, snapshot vs screenshot, auth state |
+
+Also read the `/specify` skill (`SKILL.md`) and `/implement-spec` skill (`SKILL.md`) to know the spec format contract.
+
+### Step 3: Four Review Passes
+
+Run each pass against the loaded spec. Track every finding with a severity.
+
+#### Pass 1 — Structural Completeness (vs. `/implement-spec` contract)
+
+`/implement-spec` expects these sections. Flag any that are missing or empty:
+
+| Required Section | What `/implement-spec` extracts from it |
+|---|---|
+| `## Problem` | Context for the implementer |
+| `## Solution` | What to build |
+| `## Acceptance Criteria` | Checklist items — each becomes a verification step |
+| `## Technical Design` | Drives sub-skill selection |
+| `### Affected Modules` | Determines if `/add-module` is needed |
+| `### Data Model Changes` | Drives `/add-entity` + `/add-migration` |
+| `### API Changes` | Drives `/add-api-endpoint` or `/add-auth-endpoint` |
+| `### Events` | Drives `/add-event` |
+| `## Edge Cases` | Error handling requirements |
+| `## Test Plan` | Drives `/write-backend-tests` + `/write-ui-tests` |
+
+Also check:
+- Does `### Affected Modules` name specific existing modules or propose new bounded contexts? Vague references like "the backend" are not actionable.
+- Does `### Data Model Changes` list entity names, fields, and types? `/add-entity` needs these.
+- Does `### API Changes` specify HTTP method, path, request/response shape, and auth requirements?
+- Does `## Test Plan` distinguish unit, integration, and E2E tests?
+
+#### Pass 2 — Rule Violations
+
+Check the spec's technical design against every NEVER and MANDATORY rule. Common violations:
+
+**Backend (`backend-patterns.md`):**
+- Proposes injecting services/repositories into controllers (must use CommandBus/QueryBus only)
+- Describes validation logic in handlers (must use `@Validate` + `.validator.ts`)
+- Uses Joi/Yup instead of Zod
+- Proposes throwing HttpException from handlers (must return `Result<T>`)
+- Puts business logic in controllers
+- Imports `.forRoot()` modules in feature modules
+- Proposes direct module-to-module service imports (must use CommandBus/QueryBus)
+
+**Auth (`auth-patterns.md`):**
+- Stores tokens in localStorage/sessionStorage
+- Sets Authorization headers from frontend code
+- Reads token claims in frontend JS (must call `/auth/me`)
+- Implements token refresh in frontend (BFF handles it)
+- Adds 401 retry/intercept logic in frontend API client
+
+**Database (`database-patterns.md`):**
+- Uses snake_case column names (must be camelCase)
+- Writes manual CREATE TABLE for entities with TypeORM (must use migration:generate)
+- Uses `synchronize: true`
+- Accesses another module's tables directly
+
+**Frontend (`frontend-patterns.md`):**
+- Fetches data with useEffect + useState (must use TanStack Query)
+- Copies query data into useState
+- Puts server data in Zustand
+- Uses console.log instead of Sentry
+- Uses `any` type
+- Omits `onError` on mutations
+- Uses react-hook-form directly instead of `@quanticjs/react-forms`
+
+**Testing (`testing-patterns.md`, `testing-e2e-ui.md`):**
+- Happy-path-only test plan (must cover error, empty, loading states)
+- Mocks database in integration tests (must use real DB)
+- Uses localStorage for auth in tests (must mock `/auth/me`)
+- Uses CSS selectors in E2E (must use semantic locators)
+
+**Resilience (`resilience-ops.md`):**
+- External HTTP calls without circuit breaker
+- Missing health probes
+- Missing graceful shutdown for custom resources
+
+**Observability (`observability-backend.md`):**
+- Uses console.log (must use Pino)
+- Logs sensitive data without `logExclude` or `@Log({ logPayload: false })`
+
+#### Pass 3 — Missing Edge Cases
+
+Check the `## Edge Cases` section against what the rules require:
+
+- **Auth edge cases:** unauthenticated access, expired session, insufficient permissions, role escalation
+- **API edge cases:** invalid input (400), not found (404), conflict (409), server error (500)
+- **Frontend edge cases:** loading state, empty state, error state (mandatory per `testing-e2e-ui.md`)
+- **Concurrency:** race conditions on write operations — does the spec mention `@DistributedLock` where needed?
+- **Transaction boundaries:** multi-step writes — does the spec clarify what should be atomic?
+- **Partial failures:** what happens if step 2 of a 3-step operation fails?
+- **Data boundaries:** empty arrays, null values, max-length strings, pagination edge cases
+- **Inter-module:** what if a cross-module command fails? How does the caller handle `Result.failure`?
+
+#### Pass 4 — Acceptance Criteria Quality
+
+Each criterion must be:
+- **Specific** — names the exact behavior, not vague ("it works")
+- **Testable** — can be turned into an automated test assertion
+- **Complete** — covers the happy path AND at least one failure mode
+- **Measurable** — includes concrete values where applicable (response time, field limits, etc.)
+
+Flag criteria that:
+- Use vague language: "should work correctly", "handles errors", "is secure"
+- Are duplicates of other criteria
+- Cannot be verified without manual testing (rephrase so they can be automated)
+- Miss the error/empty/loading states that `testing-e2e-ui.md` mandates for every UI feature
+
+### Step 4: Report
+
+Output a structured report:
+
+```
+## Spec Review — SPEC-<name>.md
+
+### Pass 1: Structural Completeness
+- [ ] or [x] for each required section
+- Details on what's missing or incomplete
+
+### Pass 2: Rule Violations — <count>
+For each violation:
+- **Rule:** <rule-file.md> — <quoted NEVER/MANDATORY>
+- **Spec says:** <what the spec proposes>
+- **Should say:** <what it should propose instead>
+
+### Pass 3: Missing Edge Cases — <count>
+For each missing case:
+- **Category:** auth / API / frontend / concurrency / transaction / data
+- **Missing:** <what's not covered>
+- **Required by:** <rule-file.md> or <general best practice>
+
+### Pass 4: Acceptance Criteria — <count> issues
+For each issue:
+- **Criterion:** <the problematic criterion>
+- **Problem:** vague / untestable / incomplete / missing failure mode
+- **Suggested rewrite:** <improved criterion>
+
+### Summary
+- Structural: X/10 sections present
+- Rule violations: X found
+- Missing edge cases: X found
+- Criteria issues: X found
+```
+
+### Step 5: Write Corrected Spec
+
+After presenting the report:
+
+1. Write the corrected spec to `docs/specs/SPEC-<slug>-v2.md`
+2. The corrected spec:
+   - Fills in all missing sections with actionable content derived from the rules
+   - Fixes every rule violation (replaces the violating design with the rule-compliant pattern)
+   - Adds missing edge cases with handling strategies
+   - Rewrites weak acceptance criteria to be specific and testable
+   - Preserves the original spec's intent — only fix what's wrong, don't redesign the feature
+   - Adds a comment at the top: `<!-- Reviewed version of SPEC-<slug>.md — see review report for changes -->`
+3. Tell the user: "Corrected spec written to `docs/specs/SPEC-<slug>-v2.md`. Review the changes — if it looks good, replace the original."
+
+### Step 6 (batch mode only): Summary Table
+
+If `--all` was used, after processing all specs output a summary:
+
+```
+## Batch Review Summary
+
+| Spec | Structural | Violations | Edge Cases | Criteria | Output |
+|---|---|---|---|---|---|
+| SPEC-foo.md | 8/10 | 3 | 2 | 1 | SPEC-foo-v2.md |
+| SPEC-bar.md | 10/10 | 0 | 1 | 0 | SPEC-bar-v2.md |
+```
+
+## Rules
+
+- NEVER modify the original spec file — always write to `-v2.md`
+- NEVER invent features or requirements — only fix what violates rules or is structurally incomplete
+- NEVER remove content from the original spec unless it directly contradicts a rule
+- Every rule violation finding MUST cite the specific rule file and the NEVER/MANDATORY clause
+- When filling missing sections, use information from the existing spec — don't fabricate business requirements
+- If a section cannot be filled without domain knowledge (e.g., "what should the empty state say?"), write a `TODO:` placeholder and flag it in the report
+- Preserve the original spec's formatting style and voice
+- If the original spec is already compliant, say so — don't create a `-v2.md` that's identical to the original

package/templates/claude/skills/run-tests/SKILL.md

@@ -0,0 +1,37 @@
+# Run Tests
+
+## Commands
+- All backend tests: `npm test`
+- Specific file: `npx jest --testPathPattern=<pattern>`
+- Watch mode: `npx jest --watch`
+- Coverage: `npm run test:cov`
+- Frontend unit tests: `cd client && npx vitest run`
+- Frontend E2E tests: `cd client && npx playwright test`
+
+## Prerequisites (E2E tests)
+E2E tests run against the Docker stack. Start it before running:
+```bash
+docker compose up -d
+# Wait for healthy
+docker compose ps
+```
+
+## Test Conventions
+| Type | Pattern | Location |
+|------|---------|----------|
+| Backend unit | `*.spec.ts` | Next to the file they test |
+| Backend integration | `test/*.e2e-spec.ts` | `test/` directory |
+| Frontend unit | `*.test.tsx` | `client/src/<path>/__tests__/` |
+| Frontend E2E | `*.spec.ts` | `client/e2e/` |
+
+## Test Order
+1. `npm run build` — ensure compilation succeeds
+2. `npm test` — backend unit + integration
+3. `cd client && npx vitest run` — frontend unit
+4. `cd client && npx playwright test` — E2E (requires Docker stack)
+
+## Rules
+- Fix test failures before moving on — never skip broken tests
+- Every new handler needs a spec (happy path + failure paths)
+- Frontend tests mock APIs — never depend on running backend
+- E2E tests cover: happy, error, empty, loading states

package/templates/claude/skills/specify/SKILL.md

@@ -0,0 +1,87 @@
+# Specify Feature
+
+## Usage
+`/specify <brief-feature-description>`
+
+## Process
+
+### Step 1: Interview
+Interview the user about the feature using AskUserQuestion. Cover:
+- **What** — exact behavior, inputs, outputs, edge cases
+- **Why** — business value, who benefits, what problem it solves
+- **Constraints** — performance, security, compatibility, deadlines
+- **UX** — user flow, error states, empty states, loading states
+- **Technical** — which modules are affected, data model changes, API surface
+- **Edge cases** — what happens when things go wrong, concurrent access, partial failures
+- **Testing** — how do we verify this works, what are the acceptance criteria
+
+Do not ask obvious questions. Dig into the hard parts the user might not have considered.
+Keep interviewing until all ambiguity is resolved.
+
+### Step 2: Write Spec
+Write the complete spec to `docs/specs/SPEC-<feature-slug>.md`:
+
+```markdown
+# Feature: <name>
+
+## Problem
+<why this feature is needed>
+
+## Solution
+<what we are building>
+
+## Acceptance Criteria
+- [ ] <measurable criterion>
+- [ ] ...
+
+## Technical Design
+### Affected Modules
+### Data Model Changes
+### API Changes
+### Events
+
+## Edge Cases
+<each edge case and how it is handled>
+
+## Test Plan
+- Unit tests: <what to test>
+- Integration tests: <what to test>
+- E2E tests: <what to test>
+```
+
+### Step 3: Create Spec PR
+After the user confirms the spec:
+
+1. Create a feature slug from the spec name (lowercase, hyphenated)
+2. Create branch: `git checkout -b spec/<feature-slug>`
+3. Add only the spec file: `git add docs/specs/SPEC-<feature-slug>.md`
+4. Commit: `git commit -m "spec: <feature-name>"`
+5. Push: `git push -u origin spec/<feature-slug>`
+6. Open PR:
+   ```bash
+   gh pr create \
+     --title "Spec: <feature-name>" \
+     --body "## Feature Spec: <feature-name>
+
+   <1-2 sentence summary>
+
+   **Spec file:** \`docs/specs/SPEC-<feature-slug>.md\`
+
+   ## Review Checklist
+   - [ ] Acceptance criteria are clear and testable
+   - [ ] Technical design covers all affected modules
+   - [ ] Edge cases are addressed
+   - [ ] Test plan is complete
+
+   ---
+   Once this PR is merged, implementation can begin." \
+     --base main \
+     --head "spec/<feature-slug>"
+   ```
+7. Tell the user: "Spec PR created. Once approved and merged, implementation starts."
+
+## Rules
+- NEVER start implementing before the spec PR is merged
+- The spec must be detailed enough that someone with no project context can implement it correctly
+- Include acceptance criteria that can be turned into tests
+- Only the spec file goes in the spec/ branch — no code changes