create-rigel 0.1.0

package/templates/express/.claude/skills/10-db-optimize/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: 10-db-optimize
+description: /db-optimize — Query Optimization Workflow
+verified: 2026-06-04
+libraries: [sequelize, pg]
+source: https://sequelize.org/docs/v6/
+staleness-threshold-days: 60
+---
+
+# /db-optimize — Query Optimization Workflow
+
+Triggered by: `/db-optimize [method-name or file]`
+
+---
+
+## Step 1 — Find the Slow Query
+```bash
+# From logs (pino + your log aggregator)
+# Or from pg_stat_statements:
+psql $DATABASE_URL -c "
+  SELECT query, mean_exec_time::int, calls
+  FROM pg_stat_statements
+  WHERE mean_exec_time > 200
+  ORDER BY mean_exec_time DESC LIMIT 10;
+"
+```
+
+## Step 2 — Run EXPLAIN ANALYZE
+```bash
+# Replace with the actual query being executed
+psql $DATABASE_URL << 'SQL'
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+  SELECT a.*, n.id as note_id, n.content
+  FROM applications a
+  LEFT JOIN notes n ON n.application_id = a.id
+  WHERE a.user_id = 'uuid-here' AND a.deleted_at IS NULL
+  ORDER BY a.created_at DESC LIMIT 21;
+SQL
+```
+
+## Step 3 — Read the Output
+| Output | Problem | Fix |
+|---|---|---|
+| `Seq Scan` on large table | Missing index | Add B-tree index on filter column |
+| `Rows Removed >> returned` | Index too broad | Add partial index |
+| `Nested Loop` with large outer | N+1 at DB level | Add composite index or use Hash Join |
+| `Sort` without `Index Scan` | ORDER BY without index | Add index on sort column |
+
+## Step 4 — Add Index via Migration
+```bash
+npx sequelize-cli migration:generate --name add-idx-{table}-{columns}
+```
+
+```javascript
+// In the generated migration file:
+module.exports = {
+  up: async (queryInterface) => {
+    await queryInterface.sequelize.query(
+      'CREATE INDEX CONCURRENTLY idx_{table}_{col} ON {table}({col}) WHERE deleted_at IS NULL'
+    )
+  },
+  down: async (queryInterface) => {
+    await queryInterface.sequelize.query('DROP INDEX IF EXISTS idx_{table}_{col}')
+  },
+}
+```
+
+```bash
+npx sequelize-cli db:migrate
+```
+
+## Step 5 — Also Add to Model
+```typescript
+// src/models/{Entity}.model.ts
+@Table({
+  tableName: '{table}',
+  paranoid: true,
+  indexes: [
+    { fields: ['{col}'], where: { deleted_at: null }, name: 'idx_{table}_{col}' },
+  ],
+})
+```
+
+## Step 6 — Verify
+Re-run EXPLAIN ANALYZE — confirm `Index Scan` is used and execution time < 200ms.
+
+## Step 7 — Attach to Commit
+```bash
+git add db/migrations/ src/models/
+git commit -m "perf(db): add index idx_{table}_{col}
+
+EXPLAIN ANALYZE before: {N}ms
+EXPLAIN ANALYZE after:  {M}ms
+
+Query: [description]"
+```

package/templates/express/.claude/skills/11-load-test/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: 11-load-test
+description: /load-test — k6 Performance Testing
+verified: 2026-06-04
+libraries: [k6]
+source: https://grafana.com/docs/k6/latest/
+staleness-threshold-days: 60
+---
+
+# /load-test — k6 Performance Testing
+
+Triggered by: `/load-test [smoke|stress|soak]`
+Default: `smoke`
+
+**The scripts already ship in the template** at `tests/load/{smoke,stress,soak}.js`
+and run out of the box against `/health` (no feature needed). npm scripts wrap them.
+k6 is a separate binary — install it first: `choco install k6` (Windows) / `brew install k6` (macOS).
+
+---
+
+## Run it
+
+```bash
+# Local (server running on :3000)
+npm run load:smoke
+npm run load:stress
+npm run load:soak
+
+# Against a remote target (+ auth)
+k6 run --env BASE_URL=https://staging.example.com --env AUTH_TOKEN=$TOKEN tests/load/smoke.js
+```
+
+## In CI (manual)
+
+`.github/workflows/load-test.yml` runs **only** via `workflow_dispatch` — never on
+push or PR. Trigger it from **GitHub → Actions → Load Test → Run workflow** and pass
+`base_url`, `test` (smoke/stress/soak), and optional `auth_token`.
+
+## Profiles & thresholds
+
+| Profile | Load | Thresholds |
+|---|---|---|
+| Smoke  | 10 VUs / 30s | P95 < 500ms · err < 1% |
+| Stress | ramp → 100 VUs | P95 < 1000ms · P99 < 2000ms · err < 5% |
+| Soak   | 20 VUs, sustained (`--env DURATION=2h`) | P95 < 800ms · err < 2% |
+
+---
+
+## Adapting a script to a real endpoint
+
+Each shipped script hits `/health` and includes a **commented** authenticated
+example. Uncomment and point it at your feature:
+
+```javascript
+const headers = { Authorization: `Bearer ${__ENV.AUTH_TOKEN}`, 'Content-Type': 'application/json' }
+const res = http.get(`${__ENV.BASE_URL}/api/v1/applications`, { headers })
+check(res, {
+  'status 200':     (r) => r.status === 200,
+  'has data field': (r) => r.json('data') !== undefined,
+})
+```
+
+## Interpreting Results
+| Metric | Healthy | Investigate |
+|---|---|---|
+| P95 latency | < 500ms | > 500ms |
+| P99 latency | < 1000ms | > 1000ms |
+| Error rate | < 1% | > 1% |
+| Checks passed | > 99% | < 99% |
+
+## Attach Results to PR
+```
+Load Test Results (smoke — 10 VUs, 30s):
+  P95: {N}ms  ✅/❌
+  P99: {N}ms  ✅/❌
+  Errors: {N}%  ✅/❌
+```

package/templates/express/.dockerignore

@@ -0,0 +1,43 @@
+# Build context hygiene — keep the Docker context small and free of secrets.
+# Without this, `COPY . .` in the builder stage ships node_modules, .git, the
+# .claude harness, docs, and tests into the image layers.
+
+# Dependencies (reinstalled inside the image via npm ci)
+node_modules/
+npm-debug.log*
+
+# Build output (rebuilt inside the image)
+dist/
+coverage/
+
+# Version control + CI
+.git/
+.gitignore
+.github/
+
+# Agent harness (never needed at runtime)
+.claude/
+
+# Docs, specs, plans
+docs/
+*.md
+
+# Local env + secrets — NEVER bake these into an image
+.env
+.env.*
+!.env.example
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+*.swp
+
+# Tests + load scripts
+tests/
+infra/
+
+# Local compose overrides + k6 output
+docker-compose.override.yml
+k6-results/

package/templates/express/.env.example

@@ -0,0 +1,42 @@
+# Environment
+NODE_ENV=development
+
+# Server
+PORT=3000
+
+# Database (PostgreSQL)
+DATABASE_URL=postgresql://user:pass@localhost:5432/dbname
+DATABASE_POOL_MAX=10
+DATABASE_POOL_MIN=2
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# JWT
+JWT_SECRET=
+JWT_ACCESS_EXPIRY_SECONDS=900
+JWT_REFRESH_EXPIRY_SECONDS=604800
+
+# CORS
+CORS_ORIGINS=http://localhost:3000
+
+# Logging
+LOG_LEVEL=info
+SERVICE_NAME=your-service-name
+APP_VERSION=0.0.1
+
+# Observability (OpenTelemetry)
+# OTLP/HTTP collector base URL for traces + metrics. The exporters append /v1/traces and
+# /v1/metrics.
+# IMPORTANT: BLANK by default ⇒ the SDK fully no-ops (the config/ helpers — logger, withSpan,
+# metrics — still work). This is the correct default for tests, CI, and local-without-backend.
+# To see signals in Grafana: start the LGTM stack and set this to http://localhost:4318
+# (see docs/design-docs/observability.md).
+OTEL_EXPORTER_OTLP_ENDPOINT=
+OTEL_SERVICE_NAME=your-service-name
+# Optional extra resource attributes (e.g. version, deployment env) — standard OTel var.
+# OTEL_RESOURCE_ATTRIBUTES=service.version=0.0.1,deployment.environment=development
+# How often metrics are flushed to the collector (ms).
+OTEL_METRIC_EXPORT_INTERVAL_MS=10000
+# Logs are NOT sent over OTLP — pino writes correlated JSON to stdout and Grafana Alloy ships
+# it to Loki. See docs/design-docs/observability.md.

package/templates/express/.github/CODEOWNERS

@@ -0,0 +1,22 @@
+# CODEOWNERS — GitHub auto-requests these reviewers based on which files changed.
+# Order matters: the LAST matching pattern wins.
+#
+# Replace the placeholder team slugs with your real GitHub teams/usernames, then
+# enable "Require review from Code Owners" in branch protection
+# (see docs/design-docs/team-workflow.md). Until then these are inert placeholders.
+
+# Default — any engineer on the team can review
+*                               @your-team/engineers
+
+# Security-sensitive — leads must review
+/.claude/hooks/                 @your-team/leads
+/src/providers/auth/            @your-team/leads
+/src/config/                    @your-team/leads
+
+# Platform / infra — platform team owns build, containers, and CI
+/Dockerfile                     @your-team/platform
+/docker-compose.yml             @your-team/platform
+/.github/workflows/             @your-team/platform
+
+# Database changes are irreversible in prod — leads must review
+/db/migrations/                 @your-team/leads

package/templates/express/.github/dependabot.yml

@@ -0,0 +1,48 @@
+# Dependabot keeps the (deliberately unpinned) dependency tree from drifting
+# silently. Because /infra-setup installs "latest LTS" with no lockfile in the
+# template, every product needs an automated way to surface updates + CVEs once
+# its lockfile exists. Grouped to keep PR noise low.
+version: 2
+updates:
+  # Application dependencies (npm). Active once a product's package-lock.json exists.
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 10
+    versioning-strategy: increase
+    groups:
+      # Peer-coupled set — must move together or the decorator layer breaks.
+      sequelize:
+        patterns:
+          - sequelize
+          - sequelize-typescript
+          - sequelize-cli
+      # OpenTelemetry shares a release line; bump as one unit.
+      opentelemetry:
+        patterns:
+          - '@opentelemetry/*'
+      types:
+        patterns:
+          - '@types/*'
+        update-types:
+          - minor
+          - patch
+      dev-minor-patch:
+        dependency-type: development
+        update-types:
+          - minor
+          - patch
+    labels:
+      - dependencies
+
+  # GitHub Actions — keep pinned action versions current (security-relevant).
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    labels:
+      - dependencies
+      - ci

package/templates/express/.github/pull_request_template.md

@@ -0,0 +1,58 @@
+<!--
+  PR title format: <type>(<scope>): <summary>
+  type ∈ feat | fix | chore | refactor | docs | test | perf
+  Example: feat(applications): add stage-transition endpoint
+-->
+
+## What does this PR do?
+
+<!-- One sentence. Link the spec it came from. -->
+
+- Spec: `docs/product-specs/ready/SPEC-XXX.md`
+
+## Execution plan reference
+
+<!-- Link the plan that drove this work. -->
+
+- Plan: `docs/exec-plans/active/PLAN-XXX.md` (or completed/)
+- Closes #
+
+## Layers touched (check each, confirm its rule holds)
+
+- [ ] **Types** — zero imports from other layers; no logic
+- [ ] **Config** — imports only from types/zod; `env.ts` Zod-validated
+- [ ] **Models** — `paranoid: true`; UUIDv7 ids
+- [ ] **Repo** — `Schema.parse(raw.toJSON())` on every result; ownership (`findByIdAndUser`); cursor pagination
+- [ ] **Service** — no `express`/`Request`/`Response` imports; business logic only
+- [ ] **Runtime** — order is auth → validate → service → respond; canonical envelope via `ok()`/`errorHandler`
+- [ ] **Providers** — entered via explicit interface only
+- [ ] **Utils** — zero domain imports; **100% test coverage**
+
+## Gate check (all green)
+
+- [ ] `tsc --noEmit` — type-check passes
+- [ ] `eslint src/ --max-warnings=0` — lint clean
+- [ ] `jest` — all tests pass
+- [ ] Coverage meets per-layer thresholds (utils 100 · services 90 · repo 80 · routes 75 · providers 70)
+- [ ] Architecture tests pass (`jest tests/architecture/`)
+- [ ] No file exceeds 400 lines
+
+## Security checklist
+
+- [ ] No `console.*` in `src/` (use `logger`)
+- [ ] No raw `process.env` outside `src/config/env.ts`
+- [ ] Auth required on every protected endpoint (`requireAuth` first)
+- [ ] `userId` scoped into every query (no cross-tenant leakage)
+- [ ] Cross-user isolation test exists (User B → 404 on User A's resource)
+
+## ADR
+
+- [ ] A non-obvious architectural decision was made → ADR written in `docs/design-docs/decisions/`
+- [ ] No ADR needed (nothing non-obvious)
+
+## Breaking changes
+
+- [ ] None
+- [ ] Yes — documented below (API contract, DB migration, env var, or config change)
+
+<!-- If breaking: describe the change, the migration path, and rollback steps. -->

package/templates/express/.github/workflows/ci.yml

@@ -0,0 +1,278 @@
+name: CI
+
+# The PR gate. Runs the same deterministic checks as `npm run gate`, plus
+# security scanning, image build/scan, SBOM, and a performance-budget gate.
+#
+# Template-aware: a freshly-cloned template has no `src/` yet (it is generated by
+# /infra-setup). The `guard` job detects that and lets source-dependent jobs skip
+# cleanly, so the template's own pushes stay green while every product built from
+# it inherits the full pipeline. Action versions are pinned; Dependabot keeps them
+# current (see .github/dependabot.yml).
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel superseded runs on the same ref to save minutes.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  security-events: write # upload Trivy SARIF to GitHub code scanning
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Detect whether application code exists yet. All source-dependent jobs gate
+  # on `has_src` so the bare template doesn't fail CI before /infra-setup runs.
+  # ---------------------------------------------------------------------------
+  guard:
+    name: Detect project state
+    runs-on: ubuntu-latest
+    outputs:
+      has_src: ${{ steps.detect.outputs.has_src }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: detect
+        run: |
+          if [ -n "$(find src -name '*.ts' 2>/dev/null | head -1)" ]; then
+            echo "has_src=true" >> "$GITHUB_OUTPUT"
+            echo "Application code detected — running the full pipeline."
+          else
+            echo "has_src=false" >> "$GITHUB_OUTPUT"
+            echo "No src/ yet (template state) — source-dependent jobs will skip."
+          fi
+
+  # ---------------------------------------------------------------------------
+  # Deterministic quality gate — mirrors `npm run gate` + coverage-enforced tests.
+  # ---------------------------------------------------------------------------
+  quality:
+    name: Lint · Typecheck · Test · Build
+    needs: guard
+    if: needs.guard.outputs.has_src == 'true'
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: myapp_test
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s --health-timeout 5s --health-retries 5
+      redis:
+        image: redis:7-alpine
+        ports: ["6379:6379"]
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s --health-timeout 3s --health-retries 5
+    env:
+      NODE_ENV: test
+      DATABASE_URL: postgresql://postgres:postgres@localhost:5432/myapp_test
+      REDIS_URL: redis://localhost:6379
+      JWT_SECRET: ci-test-secret-not-a-real-key-min-32-chars
+      CORS_ORIGINS: http://localhost:3000
+      # Blank endpoint ⇒ OTel SDK is a clean no-op. Never start LGTM in CI.
+      OTEL_EXPORTER_OTLP_ENDPOINT: ""
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then npm ci; else npm install; fi
+      - name: Typecheck
+        run: npm run typecheck
+      - name: Lint (0 warnings)
+        run: npm run lint
+      - name: Circular import check
+        run: npm run check:circular
+      - name: Test with coverage (thresholds enforced in jest.config.ts)
+        run: npm run test:coverage
+      - name: Build
+        run: npm run build
+      - name: OpenAPI contract is up to date
+        run: |
+          npm run openapi:export
+          # -N (intent-to-add) makes a never-committed contract count as a diff too, so this
+          # catches both drift AND "forgot to commit the generated contract" (plain `git diff`
+          # ignores untracked files and would pass silently).
+          git add -N docs/generated/openapi.json docs/generated/openapi.yaml 2>/dev/null || true
+          if ! git diff --exit-code -- docs/generated/openapi.json docs/generated/openapi.yaml; then
+            echo "::error::OpenAPI contract drifted or was never committed. Run 'npm run openapi:export' and commit docs/generated/openapi.*"
+            exit 1
+          fi
+      - name: Upload coverage
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage/
+          if-no-files-found: ignore
+
+  # ---------------------------------------------------------------------------
+  # Secret scanning — runs ALWAYS (even on the bare template; secrets can land in
+  # any file, not just src/).
+  # ---------------------------------------------------------------------------
+  secret-scan:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history so gitleaks can scan every commit
+      # Run the gitleaks CLI from its official image rather than the marketplace
+      # action. The action calls the GitHub API (job summaries / usage checks) and
+      # crashes with an unhandled RequestError on any non-2xx response; the binary
+      # just scans git history and exits non-zero on findings — no token, no API,
+      # no action version to resolve. `git` subcommand needs the full history above.
+      - name: gitleaks
+        run: |
+          docker run --rm -v "$PWD:/repo" -w /repo \
+            ghcr.io/gitleaks/gitleaks:latest git \
+            --config .gitleaks.toml --redact --exit-code 1 .
+
+  # ---------------------------------------------------------------------------
+  # Dependency vulnerability audit (needs a lockfile to be meaningful).
+  # ---------------------------------------------------------------------------
+  audit:
+    name: Dependency audit
+    needs: guard
+    if: needs.guard.outputs.has_src == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then npm ci; else npm install; fi
+      - name: npm audit (fail on high+)
+        run: npm run audit
+
+  # ---------------------------------------------------------------------------
+  # Static analysis (CodeQL) — scans the app source for security issues and
+  # uploads findings to GitHub code scanning. JS/TS needs no build step.
+  # ---------------------------------------------------------------------------
+  codeql:
+    name: CodeQL (JS/TS)
+    needs: guard
+    if: needs.guard.outputs.has_src == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: javascript-typescript
+      - uses: github/codeql-action/analyze@v3
+
+  # ---------------------------------------------------------------------------
+  # Dependency review — blocks PRs that introduce vulnerable or disallowed-license
+  # dependencies. PR-only (it diffs the base vs head dependency manifests).
+  # ---------------------------------------------------------------------------
+  dependency-review:
+    name: Dependency review
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high
+
+  # ---------------------------------------------------------------------------
+  # Container build + image vulnerability scan + SBOM.
+  # ---------------------------------------------------------------------------
+  container:
+    name: Image build · Trivy scan · SBOM
+    needs: [guard, quality]
+    if: needs.guard.outputs.has_src == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image
+        run: docker build -t harness-app:ci .
+      # Scanners run from their official Docker images (not marketplace actions) so there is
+      # no action-version to resolve/pin. `:latest` is intentional — you want the freshest
+      # vuln DB; a team that needs reproducibility can pin an image digest here.
+      - name: Trivy image scan (fail on CRITICAL/HIGH)
+        run: |
+          docker run --rm \
+            -v /var/run/docker.sock:/var/run/docker.sock \
+            -v "$PWD:/out" \
+            aquasec/trivy:latest image \
+            --severity CRITICAL,HIGH --ignore-unfixed \
+            --format sarif --output /out/trivy-results.sarif \
+            --exit-code 1 \
+            harness-app:ci
+      - name: Upload Trivy SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: trivy-results.sarif
+      - name: Generate SBOM (SPDX) with Syft
+        if: always()
+        run: |
+          docker run --rm \
+            -v /var/run/docker.sock:/var/run/docker.sock \
+            -v "$PWD:/out" \
+            anchore/syft:latest \
+            scan harness-app:ci -o spdx-json=/out/sbom.spdx.json
+      - name: Upload SBOM
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: sbom
+          path: sbom.spdx.json
+          if-no-files-found: ignore
+
+  # ---------------------------------------------------------------------------
+  # Performance budget gate — boots the app + Postgres + Redis via compose and
+  # runs the k6 smoke test (p95 < 500ms, error rate < 1%; see tests/load/smoke.js).
+  # Push-only (post-merge) to keep PRs fast; the manual load-test.yml covers
+  # stress/soak against deployed environments.
+  # ---------------------------------------------------------------------------
+  perf-smoke:
+    name: Perf budget (k6 smoke)
+    needs: [guard, quality]
+    if: needs.guard.outputs.has_src == 'true' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Boot the stack
+        env:
+          # Blank ⇒ OTel SDK no-ops. Honors "never start the LGTM backend in CI".
+          OTEL_EXPORTER_OTLP_ENDPOINT: ""
+        run: |
+          # --wait blocks until postgres/redis are healthy so the app doesn't race the DB on boot.
+          docker compose up -d --wait postgres redis
+          # --no-deps so the lgtm/alloy observability backend is NOT started in CI.
+          docker compose up -d --no-deps --build app
+          # Wait for the app health endpoint.
+          for i in $(seq 1 30); do
+            if curl -fsS http://localhost:3000/health >/dev/null 2>&1; then echo "app up"; break; fi
+            sleep 2
+          done
+      - uses: grafana/setup-k6-action@v1
+      - name: k6 smoke (enforces thresholds)
+        env:
+          BASE_URL: http://localhost:3000
+        run: k6 run tests/load/smoke.js
+      - name: Dump app logs on failure
+        if: failure()
+        run: docker compose logs app
+      - name: Tear down
+        if: always()
+        run: docker compose down -v