create-rigel 0.1.0

package/templates/nestjs/.claude/skills/06-layer-check/SKILL.md

@@ -0,0 +1,12 @@
+# /layer-check
+```bash
+npx tsc --noEmit 2>&1 | head -20
+npx eslint src/ --max-warnings=0 2>&1 | head -20
+grep -rn "console\." src/ --include="*.ts"
+grep -rn "process\.env" src/ --include="*.ts" | grep -v "src/config/"
+grep -rn "HttpException\b" src/ --include="*.service.ts"
+grep -rn "@InjectModel" src/ --include="*.service.ts"
+find src/ -name "*.ts" | xargs wc -l | sort -rn | awk '$1 > 400 { print "VIOLATION:", $2, $1 }'
+npx jest --no-coverage 2>&1 | tail -5
+```
+Output: CLEAN or {N} violations.

package/templates/nestjs/.claude/skills/07-garbage-collect/SKILL.md

@@ -0,0 +1,2 @@
+# /garbage-collect
+Calls garbage-collector agent.

package/templates/nestjs/.claude/skills/08-doc-garden/SKILL.md

@@ -0,0 +1,4 @@
+# /doc-garden
+Calls doc-gardener agent.
+Checks: AGENTS.md, ARCHITECTURE.md, spec index, .env.example vs config, ADR index.
+Updates stale content. Commits if changed.

package/templates/nestjs/.claude/skills/09-api-sync/SKILL.md

@@ -0,0 +1,36 @@
+# /api-sync — Export Live OpenAPI Spec
+
+NestJS generates OpenAPI automatically from @ApiProperty decorators.
+No static file needed. Export when backend is running:
+
+```bash
+# Backend must be running on port 3000
+curl http://localhost:3000/api/docs-json -o openapi.json
+
+# Or use the NestJS CLI plugin to generate at build time:
+# Add to nest-cli.json:
+# { "compilerOptions": { "plugins": ["@nestjs/swagger"] } }
+# Then:
+npx ts-node -e "
+const { NestFactory } = require('@nestjs/core');
+const { SwaggerModule, DocumentBuilder } = require('@nestjs/swagger');
+const { AppModule } = require('./src/app.module');
+async function generate() {
+  const app = await NestFactory.create(AppModule, { logger: false });
+  const config = new DocumentBuilder().setTitle('API').addBearerAuth().build();
+  const doc = SwaggerModule.createDocument(app, config);
+  require('fs').writeFileSync('openapi.json', JSON.stringify(doc, null, 2));
+  await app.close();
+}
+generate();
+"
+```
+
+Then:
+```bash
+git add openapi.json
+git commit -m "chore(api): export openapi spec"
+git push origin main
+```
+
+Frontend can now run /api-sync from their project using this file.

package/templates/nestjs/.claude/skills/10-load-test/SKILL.md

@@ -0,0 +1,29 @@
+# /load-test [smoke|stress|soak]
+
+```bash
+k6 run --env BASE_URL=${BASE_URL:-http://localhost:3000} tests/load/smoke.js
+```
+
+Create tests/load/smoke.js:
+```javascript
+import http from 'k6/http'
+import { check, sleep } from 'k6'
+
+export const options = {
+  vus: 10, duration: '30s',
+  thresholds: { http_req_duration: ['p(95)<500'], http_req_failed: ['rate<0.01'] },
+}
+
+export default function () {
+  const res = http.get(`${__ENV.BASE_URL}/health`)
+  check(res, { 'health 200': (r) => r.status === 200 })
+  sleep(1)
+}
+```
+
+Results format for PR:
+```
+Load Test (smoke — 10 VUs, 30s):
+  P95: {N}ms ✅/❌ (target < 500ms)
+  Errors: {N}% ✅/❌ (target < 1%)
+```

package/templates/nestjs/.env.example

@@ -0,0 +1,11 @@
+NODE_ENV=development
+PORT=3000
+DATABASE_URL=postgresql://app:app@localhost:5432/appdb
+DATABASE_POOL_MAX=10
+DATABASE_POOL_MIN=2
+REDIS_URL=redis://localhost:6379
+JWT_SECRET=
+JWT_ACCESS_EXPIRY=15m
+JWT_REFRESH_EXPIRY=7d
+CORS_ORIGINS=http://localhost:3001
+LOG_LEVEL=info

package/templates/nestjs/AGENTS.md

@@ -0,0 +1,88 @@
+# AGENTS.md — Navigation Map
+
+Stack: NestJS 11 · Node 22 · TypeScript 5 strict · Sequelize 6 + sequelize-typescript · PostgreSQL · Redis · BullMQ · argon2 · @nestjs/swagger · nestjs-pino
+
+---
+
+## 🗺️ Where Everything Lives
+
+| What you need | Where |
+|---|---|
+| Layer rules + dependency diagram | `ARCHITECTURE.md` |
+| Engineering constitution | `docs/design-docs/core-beliefs.md` |
+| Active execution plan | `docs/exec-plans/active/` |
+| Completed plans | `docs/exec-plans/completed/` |
+| Product specs (draft) | `docs/product-specs/draft/` |
+| Product specs (approved) | `docs/product-specs/ready/` |
+| Architectural decisions | `docs/design-docs/decisions/` |
+| Tech debt | `docs/exec-plans/tech-debt-tracker.md` |
+| Domain health grades | `docs/QUALITY_SCORE.md` |
+| Plan format | `docs/PLANS.md` |
+
+---
+
+## ⚡ Slash Commands
+
+| Command | What it does |
+|---|---|
+| `/infra-setup` | Phase 0 — full NestJS scaffold (run once) |
+| `/write-spec` | Write product spec → `docs/product-specs/draft/` |
+| `/write-plan` | Turn READY spec into execution plan |
+| `/build-layer` | Build next unchecked layer + run gate |
+| `/validate-layer` | Gate check without building |
+| `/push-layer` | Commit + push with conventional message |
+| `/layer-check` | Ad-hoc architecture violation scan |
+| `/garbage-collect` | End-of-feature cleanup |
+| `/doc-garden` | Fix stale documentation |
+| `/api-sync` | Export live OpenAPI spec from running server |
+| `/load-test` | Run k6 smoke / stress / soak |
+
+---
+
+## 🤖 Agents
+
+| Agent | When |
+|---|---|
+| `gate-checker` | Auto-called by `/build-layer` — PASS/FAIL per layer |
+| `reviewer` | Before opening a PR |
+| `arch-validator` | Deep layer compliance scan |
+| `db-optimizer` | N+1, missing index, pagination audit |
+| `security-auditor` | OWASP review — run before any auth PR |
+| `doc-gardener` | Fix stale docs |
+| `garbage-collector` | End-of-feature cleanup |
+
+---
+
+## ✅ Non-Negotiable Invariants
+
+- No `console.log` → use `Logger` from `@nestjs/common` or `nestjs-pino`
+- No `process.env` → use `ConfigService` injected via NestJS DI
+- No `HttpException` in services → use NestJS built-in exceptions (`NotFoundException` etc.)
+- No business logic in controllers → delegate to service only
+- No `@InjectModel()` in services → inject the repository class, not the model
+- Every Sequelize `.toJSON()` result → `ZodSchema.parse()`
+- Every list endpoint → cursor-based pagination
+- Every `@Column` DTO field → has `@ApiProperty()` decorator
+- No file > 400 lines
+
+---
+
+## 🔑 The NestJS Difference
+
+**Auth is opt-out, not opt-in.** Global `JwtAuthGuard` protects all routes. Use `@Public()` to expose a route without auth. Never add auth guards per-route.
+
+**Input validation is automatic.** Global `ValidationPipe` with `whitelist: true` runs `class-validator` on every DTO. No Zod on input.
+
+**Output validation is Zod.** Sequelize `.toJSON()` is not guaranteed — Zod parse it in the repository.
+
+**Swagger is live.** OpenAPI spec auto-generated at `/api/docs-json`. No separate file sync needed.
+
+---
+
+## 🔁 The Flow
+
+```
+/write-spec → human marks READY → /write-plan
+  → /build-layer (repeats per layer, gate-enforced)
+  → /garbage-collect → plan closed
+```

package/templates/nestjs/ARCHITECTURE.md

@@ -0,0 +1,192 @@
+# ARCHITECTURE.md — NestJS Layered Architecture
+
+Stack: NestJS 11 · TypeScript 5 · Sequelize 6 + sequelize-typescript · PostgreSQL
+
+---
+
+## Module Dependency Diagram
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Common (src/common/)                                             │
+│  ├─ Guards:       JwtAuthGuard (global), RolesGuard              │
+│  ├─ Decorators:   @CurrentUser(), @Public(), @Roles()            │
+│  ├─ Filters:      AllExceptionsFilter (global)                   │
+│  ├─ Interceptors: LoggingInterceptor (global)                    │
+│  └─ DTOs:         PaginationDto (shared cursor params)           │
+│                                                                   │
+│  Config (src/config/)                                             │
+│  └─ ConfigModule with Joi validation — ConfigService everywhere  │
+│                                                                   │
+│  Database (src/database/)                                         │
+│  └─ SequelizeModule.forRoot() — connection + pool config         │
+│                                                                   │
+│  [Feature] Module (src/[feature]/)                               │
+│  ├─ models/[feature].model.ts   ← Sequelize model (schema)      │
+│  ├─ dto/                        ← class-validator + @ApiProperty │
+│  ├─ [feature].repository.ts     ← @InjectModel + Zod parse      │
+│  ├─ [feature].service.ts        ← business logic only            │
+│  ├─ [feature].controller.ts     ← thin, Swagger decorators       │
+│  └─ [feature].module.ts         ← wires everything               │
+│                                                                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Layer Definitions
+
+### Model (`src/[feature]/models/`)
+
+- Sequelize-typescript class with `@Table`, `@Column` decorators
+- Schema definition only — **no logic, no methods**
+- `@Table({ paranoid: true })` on every model (soft delete)
+- `@Default(() => newId())` on every `id` column (UUIDv7)
+- Indexes defined in `@Table({ indexes: [] })`
+- Imports: Types only
+
+### DTOs (`src/[feature]/dto/`)
+
+- `class-validator` + `class-transformer` decorated classes
+- Every field has `@ApiProperty()` for Swagger
+- Input DTOs: `Create*Dto`, `Update*Dto`
+- Response DTOs: `*ResponseDto` (controls what is serialised)
+- **No logic** — only property definitions and validation decorators
+
+### Repository (`src/[feature]/[feature].repository.ts`)
+
+- `@Injectable()` class with `@InjectModel(Model)` in constructor
+- **Only place DB queries happen**
+- Every `.toJSON()` result passed through `ZodSchema.parse()`
+- Cursor-based pagination on all list methods
+- Ownership enforced in every `WHERE` clause (`userId` filter)
+- Exports only typed domain objects — never raw Sequelize instances
+
+### Service (`src/[feature]/[feature].service.ts`)
+
+- `@Injectable()` class — business logic only
+- Injects repository class (not the model directly)
+- **No HTTP types** — no `Request`, `Response`, `@nestjs/common` HTTP imports
+- **No `HttpException`** — uses NestJS built-in semantic exceptions:
+  - `NotFoundException`, `ConflictException`, `UnauthorizedException`, `ForbiddenException`, `BadRequestException`
+- Multi-step operations wrapped in `sequelize.transaction()`
+
+### Controller (`src/[feature]/[feature].controller.ts`)
+
+- `@Controller()` class — routing and serialisation only
+- **Zero business logic** — each handler is a one-liner delegating to service
+- Required Swagger decorators on every class and route:
+  - `@ApiTags()`, `@ApiBearerAuth()`, `@ApiOperation()`, `@ApiResponse()`
+- `@UseGuards()` only if route-level guard needed (not for JWT — that's global)
+- `@Roles('ADMIN')` for admin-only routes
+
+### Module (`src/[feature]/[feature].module.ts`)
+
+- Wires: `SequelizeModule.forFeature([Model])`, repository, service, controller
+- Exports services that other modules need
+- Imported in `AppModule` (or parent module)
+
+---
+
+## Import Rules (ESLint enforces)
+
+```
+Model         →  Types only
+DTOs          →  Types only (class-validator, swagger decorators)
+Repository    →  Model, Config, Types, Zod
+Service       →  Repository, Config, Types — NO HTTP imports
+Controller    →  Service, DTOs, Common decorators
+Module        →  All of the above
+Common        →  Config, Types only
+```
+
+**Forbidden:**
+
+- `process.env` anywhere (use `ConfigService`)
+- `console.log` anywhere (use `Logger` or `nestjs-pino`)
+- `HttpException` in services (use built-in semantic exceptions)
+- Business logic in controllers
+- `@InjectModel()` in services (inject repository instead)
+- Raw Sequelize instance returned from repository (always `.toJSON()` + Zod)
+
+---
+
+## Auth Model — Opt-Out, Not Opt-In
+
+```typescript
+// main.ts — JWT guard applied GLOBALLY
+app.useGlobalGuards(new JwtAuthGuard(reflector))
+
+// Public routes use @Public() decorator
+@Public()
+@Post('login')
+login(@Body() dto: LoginDto) { ... }
+
+// Protected routes need NO guard decoration — they're protected by default
+@Get('profile')
+getProfile(@CurrentUser() user: JwtPayload) { ... }
+
+// Admin routes add @Roles()
+@Roles('ADMIN')
+@Delete(':id')
+delete(@Param('id') id: string) { ... }
+```
+
+---
+
+## Validation Model
+
+```
+HTTP Request
+    │
+    ▼ Global ValidationPipe (whitelist: true, transform: true)
+    │   → class-validator validates DTO
+    │   → strips unknown fields
+    │   → transforms types (string → number etc.)
+    ▼
+Controller → Service → Repository
+                           │
+                           ▼ Sequelize query
+                           │
+                           ▼ .toJSON()
+                           │
+                           ▼ ZodSchema.parse() ← output validation boundary
+                           │
+                        TypedResult
+```
+
+---
+
+## NestJS Exception Map
+
+| NestJS Exception               | HTTP Status | When to use                                             |
+| ------------------------------ | ----------- | ------------------------------------------------------- |
+| `NotFoundException`            | 404         | Resource not found                                      |
+| `ConflictException`            | 409         | Duplicate, invalid state transition                     |
+| `UnauthorizedException`        | 401         | Invalid credentials, expired token                      |
+| `ForbiddenException`           | 403         | Insufficient permissions                                |
+| `BadRequestException`          | 400         | Invalid input (caught before service by ValidationPipe) |
+| `InternalServerErrorException` | 500         | Unexpected failure                                      |
+
+---
+
+## File Size Limit
+
+**400 lines maximum** per file. Enforced by PostToolUse hook + gate-checker.
+
+---
+
+## Naming Conventions
+
+| Thing        | Pattern               | Example                           |
+| ------------ | --------------------- | --------------------------------- |
+| Model        | `*.model.ts`          | `application.model.ts`            |
+| Repository   | `*.repository.ts`     | `application.repository.ts`       |
+| Service      | `*.service.ts`        | `application.service.ts`          |
+| Controller   | `*.controller.ts`     | `application.controller.ts`       |
+| Module       | `*.module.ts`         | `application.module.ts`           |
+| Create DTO   | `create-*.dto.ts`     | `create-application.dto.ts`       |
+| Update DTO   | `update-*.dto.ts`     | `update-application.dto.ts`       |
+| Response DTO | `*-response.dto.ts`   | `application-response.dto.ts`     |
+| Zod schemas  | `*Schema`             | `ApplicationSchema`               |
+| Migration    | `YYYYMMDDHHMMSS-*.js` | `20260508-create-applications.js` |

package/templates/nestjs/docs/PLANS.md

@@ -0,0 +1,22 @@
+# PLANS.md — Execution Plan Format
+
+## Lifecycle
+/write-plan → docs/exec-plans/active/PLAN-XXX.md
+  → /build-layer (each NestJS layer: Model → Migration → DTOs → Repository → Service → Controller → Module → Tests)
+  → /garbage-collect → docs/exec-plans/completed/
+
+Plans are NEVER deleted.
+
+## NestJS Layer Order (per feature)
+1. Model (sequelize-typescript class)
+2. Migration (sequelize-cli)
+3. DTOs (class-validator + @ApiProperty)
+4. Repository (@InjectModel + Zod parse)
+5. Service (@Injectable, NestJS exceptions)
+6. Controller (@Controller, Swagger decorators)
+7. Module (SequelizeModule.forFeature, wire everything)
+8. Tests (jest unit + supertest e2e)
+
+## Escalation Rule
+Escalate only for: ambiguous requirements, security decisions with no pattern, architecture change needed.
+Never escalate for: TypeScript errors, linter failures, test failures.

package/templates/nestjs/docs/QUALITY_SCORE.md

@@ -0,0 +1,27 @@
+# QUALITY_SCORE.md — Domain Health Grades
+
+Updated by /garbage-collect after every feature.
+
+## Grading
+| Grade | Meaning |
+|---|---|
+| A | All invariants met, ≥ 90% service coverage, zero debt |
+| B | Minor issues, ≥ 80% coverage, low-priority debt logged |
+| C | Layer violation OR < 80% OR unresolved medium debt |
+| D | Multiple violations, active bugs |
+
+## Architecture Health
+| Check | Status |
+|---|---|
+| No cross-layer imports | — |
+| No files > 400 lines | — |
+| No process.env outside config | — |
+| No console.log in src | — |
+| No HttpException in services | — |
+| No @InjectModel in services | — |
+| Zod parse on all .toJSON() in repos | — |
+
+## Domain Grades
+| Domain | Grade | Coverage | Last Updated |
+|---|---|---|---|
+| *(none yet)* | — | — | — |

package/templates/nestjs/docs/design-docs/core-beliefs.md

@@ -0,0 +1,18 @@
+# Core Beliefs — The Engineering Constitution
+
+1. **The Repo Is Reality** — if not committed, it doesn't exist
+2. **Enforce Mechanically** — linter rules + hooks > documentation
+3. **Agents Execute, Humans Steer** — escalate only when judgment is needed
+4. **Layers Protect Concerns** — controllers delegate, services have no HTTP, repos have no logic
+5. **External Data Is Adversarial** — Zod parse every .toJSON() at the repo boundary
+6. **Gate Before Commit** — TypeScript + ESLint + tests before every push
+7. **Observability Is Not Optional** — structured logs on every service boundary
+8. **Small, Boring, Legible** — 400-line limit, NestJS idioms, no premature abstraction
+9. **Technical Debt Is a High-Interest Loan** — log it immediately, pay daily
+10. **The Fix Is Never Try Harder** — repeated failure = missing rule, tool, or abstraction
+
+## NestJS-Specific Beliefs
+- Auth is opt-out (global guard) — not opt-in
+- ValidationPipe is the input contract — not manual Zod on inputs
+- Swagger is auto-generated — no separate file sync needed
+- Inject repositories into services — not models directly

package/templates/nestjs/docs/design-docs/decisions/ADR-000-infrastructure.md

@@ -0,0 +1,58 @@
+# ADR-000 — Infrastructure & Stack Choices
+
+**Status:** ACCEPTED
+**Date:** *(fill when /infra-setup is run)*
+**Plan:** Phase 0
+
+---
+
+## Decisions
+
+### Framework: NestJS 11
+- Modular architecture with IoC container built-in
+- TypeScript-first with full decorator support
+- Global guards, pipes, filters, interceptors
+- v11 stable — v12 (ESM + Vitest) targeting Q3 2026, not stable yet
+
+### ORM: Sequelize 6 + sequelize-typescript + @nestjs/sequelize
+- Team standard across projects
+- @nestjs/sequelize provides SequelizeModule.forRoot + @InjectModel DI
+- sequelize-typescript provides TypeScript decorator model definitions
+- sequelize-cli for migrations
+- Alternatives considered: Prisma (better DX), TypeORM (NestJS native) — Sequelize chosen for consistency
+
+### Auth: @nestjs/passport + passport-jwt + @nestjs/jwt
+- NestJS official pattern — JwtStrategy + JwtAuthGuard
+- Global guard (APP_GUARD) — every route protected by default
+- @Public() decorator for opt-out
+- argon2 for password hashing (GPU-resistant, beats bcrypt)
+
+### Validation: class-validator + class-transformer (input), Zod (output)
+- class-validator: NestJS native, integrates with ValidationPipe and Swagger
+- Zod: output validation on Sequelize .toJSON() at repository boundary
+- Two-layer approach: structured validation in, typed safety out
+
+### Config: @nestjs/config + Joi
+- ConfigModule with Joi schema — process.exit on invalid config at startup
+- ConfigService injected everywhere — no process.env in application code
+
+### Logging: nestjs-pino
+- Structured JSON logging via pino
+- NestJS lifecycle integration
+- Replaces default NestJS logger
+
+### API Docs: @nestjs/swagger
+- Auto-generated OpenAPI spec from DTOs and decorators
+- Live at /api/docs — no static file sync needed
+- Frontend exports via: curl http://localhost:3000/api/docs-json -o openapi.json
+
+### Queue: @nestjs/bullmq
+- Official NestJS BullMQ integration
+- Redis-backed, most mature queue in Node ecosystem
+
+### Rate Limiting: @nestjs/throttler
+- Official NestJS rate limiting
+- Applied per-controller or per-route with @Throttle()
+
+### Health: @nestjs/terminus
+- Official health checks — /health (liveness) + /ready (DB + Redis)

package/templates/nestjs/docs/design-docs/decisions/index.md

@@ -0,0 +1,7 @@
+# ADR Index
+
+| ID | Title | Status | Date | Plan |
+|---|---|---|---|---|
+| ADR-000 | Infrastructure & Stack Choices | ACCEPTED | *(fill)* | — |
+
+Add a row after every new ADR.

package/templates/nestjs/docs/design-docs/index.md

@@ -0,0 +1,7 @@
+# Design Docs Index
+
+| Document | Purpose |
+|---|---|
+| core-beliefs.md | Engineering constitution |
+| decisions/index.md | ADR registry |
+| decisions/ADR-000-infrastructure.md | Stack choices |

package/templates/nestjs/docs/exec-plans/tech-debt-tracker.md

@@ -0,0 +1,16 @@
+# Technical Debt Tracker
+
+## Severity
+| P0 | Security/data integrity — fix immediately |
+| P1 | Blocks features — within 2 sprints |
+| P2 | Degrades quality — within quarter |
+| P3 | Code smell — when in area |
+
+## Open Debt
+| ID | Severity | Area | Description | Created By | Date |
+|---|---|---|---|---|---|
+| *(none yet)* | — | — | — | — | — |
+
+## Resolved Debt
+| ID | Description | Resolved By | Date |
+|---|---|---|---|

package/templates/nestjs/docs/product-specs/index.md

@@ -0,0 +1,7 @@
+# Product Specs Index
+
+| ID | Name | Status | Plan | Created |
+|---|---|---|---|---|
+| *(none yet)* | — | — | — | — |
+
+## Statuses: DRAFT → READY → PLANNED → IN_PROGRESS → SHIPPED → CANCELLED

package/templates/nestjs/gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.env
+.env.local
+coverage/
+*.log
+.DS_Store
+.vscode/