create-rigel 0.1.0

package/templates/express/docker-compose.yml

@@ -0,0 +1,114 @@
+# The top-level `version:` key is obsolete in Compose v2 and emits a warning — omitted.
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - '3000:3000'
+    environment:
+      NODE_ENV: development
+      PORT: 3000
+      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/myapp
+      REDIS_URL: redis://redis:6379
+      # Dev-only placeholder (≥32 chars to satisfy env validation). NEVER use in prod.
+      JWT_SECRET: dev-only-secret-change-me-min-32-characters
+      CORS_ORIGINS: http://localhost:3000
+      LOG_LEVEL: debug
+      SERVICE_NAME: myapp
+      # Traces + metrics → otel-lgtm collector (OTLP/HTTP). Defaults to the lgtm service;
+      # export an empty OTEL_EXPORTER_OTLP_ENDPOINT to disable (e.g. CI runs the app without LGTM).
+      OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT-http://lgtm:4318}
+      OTEL_SERVICE_NAME: myapp
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      lgtm:
+        condition: service_started # don't block app boot; OTLP exporter retries until collector is up
+    networks:
+      - app-network
+    restart: unless-stopped
+
+  postgres:
+    image: postgres:16-alpine
+    ports:
+      - '5432:5432'
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: myapp
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - app-network
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - '6379:6379'
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 10s
+      timeout: 3s
+      retries: 5
+    networks:
+      - app-network
+    restart: unless-stopped
+
+  # All-in-one OpenTelemetry backend: Collector + Prometheus (metrics) + Tempo (traces)
+  # + Loki (logs) + Grafana UI. Receives OTLP on 4317 (gRPC) / 4318 (HTTP).
+  lgtm:
+    image: grafana/otel-lgtm:latest
+    ports:
+      - '3001:3000' # Grafana UI (remapped off 3000 to avoid clashing with the app)
+      - '4317:4317' # OTLP gRPC
+      - '4318:4318' # OTLP HTTP
+    volumes:
+      - lgtm-data:/data
+    healthcheck:
+      # otel-lgtm writes this readiness marker once all bundled services are up.
+      test: ['CMD-SHELL', 'test -f /tmp/ready || exit 1']
+      interval: 10s
+      timeout: 5s
+      retries: 12
+    networks:
+      - app-network
+    restart: unless-stopped
+
+  # Log shipper: tails container stdout JSON and pushes to Loki inside otel-lgtm.
+  # (Traces + metrics go straight to the collector via OTLP; only logs use Alloy.)
+  alloy:
+    image: grafana/alloy:latest
+    command:
+      - run
+      - /etc/alloy/config.alloy
+      - --storage.path=/var/lib/alloy/data
+    volumes:
+      - ./infra/monitoring/alloy/config.alloy:/etc/alloy/config.alloy:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    depends_on:
+      lgtm:
+        condition: service_healthy
+    networks:
+      - app-network
+    restart: unless-stopped
+
+volumes:
+  postgres-data:
+  redis-data:
+  lgtm-data:
+
+networks:
+  app-network:
+    driver: bridge

package/templates/express/docs/PLANS.md

@@ -0,0 +1,111 @@
+# PLANS.md — Execution Plan Format & Lifecycle
+
+---
+
+## Roadmap → Specs (the altitude above plans)
+
+`/write-roadmap` creates → `docs/product-specs/ROADMAP.md` (epics → dependency-ordered specs).
+The roadmap plans the SET of specs for a whole product; `/write-spec` then authors each one.
+A single spec may span MULTIPLE plans — slice a big spec into shippable milestones, each its own
+`PLAN-XXX`. The spec's `**Plan:**` field then lists them all (e.g. `PLAN-003, PLAN-007`).
+
+---
+
+## Lifecycle
+
+```
+/write-plan creates → docs/exec-plans/active/PLAN-XXX.md  [IN_PROGRESS]
+  → layers built one by one, checkboxes ticked
+  → /garbage-collect closes → docs/exec-plans/completed/  [COMPLETE]
+```
+
+Plans are **never deleted.** They are the project's memory.
+
+---
+
+## Plan Template
+
+```markdown
+# PLAN-XXX — {Feature Name}
+
+**Status:** IN_PROGRESS
+**Spec:** docs/product-specs/ready/SPEC-XXX-{slug}.md
+**Created:** YYYY-MM-DD
+**Completed:** —
+
+---
+
+## Goal
+One sentence.
+
+---
+
+## Layer Build Order
+
+| # | Layer | Files | Gate Focuses On |
+|---|---|---|---|
+| 1 | Types | `src/types/...` | Zero imports, zero logic |
+| 2 | Config | `src/config/...` | process.env only in env.ts |
+| 3 | Models | `src/models/...` | paranoid, UUIDv7, indexes |
+| 4 | Migrations | `db/migrations/...` | Runs clean, has down() |
+| 5 | Repo | `src/repo/...` | Zod parse, cursor, ownership, no N+1 |
+| 6 | Service | `src/services/...` | No express, ≥90% coverage |
+| 7 | Runtime | `src/runtime/routes/v1/...` | Auth first, envelope |
+| 8 | Workers | `src/runtime/workers/...` | Zod payload, retry, logs |
+| 9 | Tests | `tests/...` | Coverage gates |
+
+---
+
+## Acceptance Criteria
+- [ ] criterion (from spec)
+
+---
+
+## Progress Log
+
+### YYYY-MM-DD — Plan created
+- notes
+
+---
+
+## Decision Log
+
+### Decision: {title}
+**Date:** YYYY-MM-DD
+**Context:** why this decision was needed
+**Chosen:** what was decided
+**Alternatives:** what else was considered
+**Trade-offs:** what this costs
+```
+
+---
+
+## Small Task Alternative (< 2 hours)
+
+Use a PR description instead of a full plan:
+
+```markdown
+## What
+[1-2 sentences]
+
+## Why
+[1 sentence]
+
+## Checklist
+- [ ] Types updated
+- [ ] Tests pass
+- [ ] ESLint clean
+- [ ] QUALITY_SCORE.md updated
+```
+
+---
+
+## Escalation Rule
+
+Escalate to human only when judgment is required:
+- Ambiguous acceptance criteria
+- Conflicting requirements
+- Security decision with no established pattern
+- Performance budget impossible without architecture change
+
+Never escalate for: technical unknowns, linter failures, test failures — fix those.

package/templates/express/docs/QUALITY_SCORE.md

@@ -0,0 +1,66 @@
+# QUALITY_SCORE.md — Domain Health Grades
+
+Updated by `/garbage-collect` after every feature.
+
+---
+
+## Grading Rubric
+
+Coverage is judged **per layer** against the thresholds in `jest.config.ts`
+(utils 100% · services 90% · repo 80% · routes 75% · providers 70%), never as a single
+global number — that is what CI enforces.
+
+| Grade | Meaning |
+|---|---|
+| A | All invariants met, **every per-layer coverage threshold met**, zero known debt |
+| B | Minor issues, per-layer thresholds met with little margin, low-priority debt logged |
+| C | Layer violation OR any per-layer threshold breached OR unresolved medium debt |
+| D | Multiple violations, coverage well under thresholds, active bugs |
+| F | Blocking issues, data integrity risk, security concern |
+
+---
+
+## Architecture Health
+
+| Check | Status |
+|---|---|
+| No cross-layer imports (eslint boundaries) | — |
+| Cross-user isolation test per owned resource | — |
+| No circular imports (madge) | — |
+| No files > 400 lines | — |
+| No process.env outside Config | — |
+| No console.log in src/ | — |
+| OpenAPI contract in sync (openapi:export clean) | — |
+| Utils: 100% test coverage | — |
+
+Run `/layer-check` to update this table.
+
+---
+
+## Domain Grades
+
+| Domain | Grade | Coverage | Last Updated | Notes |
+|---|---|---|---|---|
+| *(no domains yet — add after first feature)* | — | — | — | — |
+
+---
+
+## Domain Grade Template
+
+Copy this block for each new domain:
+
+```
+### {Domain Name}
+**Grade:** —
+**Coverage:** —%
+**Last Updated:** YYYY-MM-DD (PLAN-XXX)
+
+Passing:
+- [ ] No layer violations
+- [ ] Zod parse on all repo boundaries
+- [ ] Structured logging on all service methods
+- [ ] OTel spans on all service boundaries
+
+Issues:
+- none
+```

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

@@ -0,0 +1,89 @@
+# Core Beliefs — The Engineering Constitution
+
+Rules without reasons get bent under pressure.
+This document explains the WHY behind every constraint in this harness.
+
+---
+
+## 1. The Repo Is Reality
+
+If a decision isn't written in this repository, it doesn't exist.
+Slack messages, verbal agreements, and meeting notes are invisible to agents and to future engineers.
+
+**Consequence:** Every architectural decision → ADR. Every product → `ROADMAP.md`. Every feature intent → spec. Every execution plan → PLAN-XXX.md.
+
+---
+
+## 2. Enforce Mechanically, Not Aspirationally
+
+A linter rule that blocks CI is worth ten documentation paragraphs.
+Agents respond to feedback in their context window — linter errors are that feedback.
+
+**Consequence:** Every constraint that matters is encoded as an ESLint rule, a structural test, or a hook. Not just a doc.
+
+---
+
+## 3. Agents Execute. Humans Steer.
+
+Human attention is the scarcest resource. Every minute spent writing boilerplate is a minute not spent on product quality.
+
+**Consequence:** The harness is optimised for maximum agent autonomy. Escalations happen only when judgment is required — not when tasks are hard.
+
+---
+
+## 4. Layers Protect Business Logic
+
+The layer architecture isn't aesthetic. It exists so business logic can be tested, ported, and reasoned about in isolation — without spinning up HTTP, a database, or any external dependency.
+
+**Consequence:** Service methods take domain types and return domain types. No `Request`, no `Response`, no HTTP concepts.
+
+---
+
+## 5. External Data Is Adversarial Until Proven Otherwise
+
+TypeScript's type system tells you what you expect — not what you got.
+APIs change. DB schemas get migrated. Payloads get spoofed.
+
+**Consequence:** `Schema.parse(raw.toJSON())` at every external data boundary. `as SomeType` is forbidden on external data.
+
+---
+
+## 6. Observability Is Not Optional
+
+When something breaks in production, structured logs + traces are the only way to reproduce it without live debugging. Agents can query logs to fix bugs autonomously — but only if the logs exist.
+
+**Consequence:** Structured JSON logging and OTel spans on every service boundary. No silent operations.
+
+---
+
+## 7. Gate Before Commit — Always
+
+Shipping code that violates the harness compounds over time. Every violation makes the next one cheaper to introduce.
+
+**Consequence:** The gate-checker runs after every layer. It must PASS before any commit is made. Auto-fix is enabled — there's no reason to leave violations unfixed.
+
+---
+
+## 8. Small, Boring, Legible
+
+Agents reason best about code they can fully read in a single context window.
+400 lines is the cognitive limit. Boring technology has more training data and fewer surprises.
+
+**Consequence:** 400-line hard limit. Prefer well-known libraries. No premature abstraction.
+
+---
+
+## 9. Technical Debt Is a High-Interest Loan
+
+Every shortcut taken today costs more to fix when built upon.
+Log debt immediately. Pay it in small amounts daily.
+
+**Consequence:** `tech-debt-tracker.md` is updated after every feature. Garbage collection runs after every plan completes.
+
+---
+
+## 10. The Fix Is Never "Try Harder"
+
+Repeated failures indicate a missing capability — a missing tool, constraint, or abstraction.
+
+**Consequence:** When the same problem recurs: diagnose the missing capability → build it → solve it permanently. Build the abstraction before writing the third hand-rolled copy.

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

@@ -0,0 +1,70 @@
+# ADR-000 — Infrastructure & Stack Choices
+
+**Status:** ACCEPTED
+**Date:** *(fill when /infra-setup is run)*
+**Plan:** Phase 0
+
+---
+
+## Context
+
+Starting a new TypeScript backend project. Need to select the foundational stack for the long term.
+Choices made here are expensive to change later.
+
+---
+
+## Decisions
+
+### Runtime: Node 24 LTS + TypeScript 5
+- Node 24 is the current LTS — stable, long support window
+- TypeScript 5 with `strict: true` — `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess` catch a class of bugs TypeScript 4 missed
+
+### Framework: Express 5
+- Express 5 is finally stable — async error propagation built-in (no need for `express-async-errors` wrapper in future)
+- Widest ecosystem, most agent training data, most Stack Overflow coverage
+- Alternatives considered: Fastify (better performance, less ecosystem), Hono (newer, less mature)
+
+### ORM: Sequelize 6 + sequelize-typescript
+- Team already familiar
+- `paranoid: true` soft deletes built-in
+- sequelize-cli provides robust migration tooling
+- Stable v6 release with proven production track record
+- Alternatives considered: Prisma (better DX, but generates its own runtime, less control), Drizzle (very new)
+
+### Auth: jose 5 (JWT)
+- Zero CVE history (unlike `jsonwebtoken`)
+- Web Crypto API — runs in any JS runtime
+- Alternatives rejected: `jsonwebtoken` — has had multiple CVEs
+
+### Password Hashing: argon2
+- Winner of the Password Hashing Competition (2015)
+- Resistant to GPU/ASIC attacks
+- Alternatives rejected: bcrypt — vulnerable to GPU attacks at high parallelism
+
+### Queue: BullMQ 5 + Redis
+- Most mature Redis-backed queue in Node ecosystem
+- Built-in retry, backoff, rate limiting, delayed jobs
+- Alternatives considered: `pg-boss` (Postgres-backed, fewer deps), SQS (infrastructure dependency)
+
+### Logging: pino 9
+- Fastest structured JSON logger in Node ecosystem (~5x faster than winston)
+- Built-in redaction
+- Alternatives rejected: winston — slow, complex config
+
+### Validation: Zod 3
+- TypeScript-first, infers types from schemas
+- Used at every external data boundary
+- Alternatives considered: Yup (less TypeScript-native), io-ts (too verbose)
+
+### Caching/Sessions: ioredis 5
+- Most stable Redis client for Node
+- Used for: rate limiting, token revocation, job queues, application cache
+
+---
+
+## Consequences
+
+- Express 5 async errors: built-in async error propagation to `errorHandler` middleware
+- Sequelize + `paranoid: true`: never hard-delete unless explicitly using `{ force: true }`
+- jose: tokens are stateless — revocation requires Redis check on every verify
+- argon2: slower than bcrypt on CPU (that's a feature, not a bug — harder to brute-force)

package/templates/express/docs/design-docs/decisions/ADR-001-observability.md

@@ -0,0 +1,82 @@
+# ADR-001 — Observability (Traces, Metrics, Logs)
+
+**Status:** ACCEPTED
+**Date:** *(fill when /infra-setup is run)*
+**Plan:** Phase 0
+**See also:** `docs/design-docs/observability.md` (the see-it/debug-it walkthrough)
+
+---
+
+## Context
+
+Core belief #6 ("observability is not optional") and `QUALITY_SCORE.md` require structured logging
+and OTel spans on every service boundary, so that production issues can be reproduced — and fixed by
+agents — from telemetry alone. We need a concrete, low-friction implementation that works in dev,
+no-ops cleanly in tests/CI, and respects the layered-architecture import rules. This ADR records the
+non-obvious choices; the mechanics live in `observability.md`.
+
+---
+
+## Decisions
+
+### Signals: OpenTelemetry SDK (`@opentelemetry/sdk-node`), one release line
+- Traces + metrics exported via OTLP/HTTP (`exporter-trace-otlp-http`, `exporter-metrics-otlp-http`)
+  with `getNodeAutoInstrumentations()` (http/express/pg/ioredis patched for free).
+- All `@opentelemetry/*` packages pinned to the same release line; `@opentelemetry/api` is kept
+  within the SDK's peer range. Version skew here is the most common source of silent breakage.
+
+### Local backend: `grafana/otel-lgtm` (all-in-one)
+- A single container bundles the OTel Collector + Prometheus (metrics) + Tempo (traces) + Loki
+  (logs) + Grafana. Zero config, OTLP defaults, one `docker compose up`.
+- Alternatives rejected: wiring discrete collector + Prometheus + Tempo + Loki + Grafana services —
+  far more YAML and moving parts for a template, with no dev-time benefit.
+- Grafana is published on host **3001** (its in-container default is 3000) to avoid clashing with
+  the app/frontend.
+- **Not for production** — prod points `OTEL_EXPORTER_OTLP_ENDPOINT` at a real collector / Grafana
+  Cloud; app code is unchanged.
+
+### Logs: pino JSON → Alloy → Loki (not OTLP from the app)
+- Under ESM, `@opentelemetry/instrumentation-pino`'s OTLP log-sending does not reliably emit, so we
+  do not depend on it. Instead:
+  1. **Correlation** is deterministic — a pino `mixin` reads `trace.getActiveSpan()` and stamps
+     `trace_id`/`span_id` on every line, independent of auto-instrumentation patching.
+  2. **Shipping** is decoupled — Grafana Alloy tails container stdout JSON and pushes to Loki.
+- Consequence: we **do not install** `@opentelemetry/exporter-logs-otlp-http` or
+  `@opentelemetry/sdk-logs`; the `NodeSDK` carries only `traceExporter` + `metricReaders`. Fewer
+  packages, no ESM log-export bug to fight.
+
+### Helpers live in Config, the SDK lives in Providers
+- The layer rules let every domain layer import `config/` but forbid Service/Repo from importing
+  `providers/` (enforced by madge). So `logger`, `withSpan` (tracing), and `metrics` live in
+  `src/config/` and use only the `@opentelemetry/api` global (a safe no-op until an SDK starts).
+- The `NodeSDK` itself lives only in `src/providers/telemetry.ts`, boot-only.
+
+### Boot order: start the SDK before importing the app (ESM)
+- Auto-instrumentation can only patch a library loaded *after* `sdk.start()`. `src/runtime/server.ts`
+  statically imports only telemetry, calls `await startTelemetry()`, then `await import('./app.js')`.
+- The instrumented libs (express/pg/ioredis) are CommonJS, so the SDK's require-hook patches them
+  with no ESM loader hook needed — provided the start runs before the first `require`. This pattern
+  is identical under `tsx` (dev) and `node dist/...` (prod), so there is no start-command divergence
+  and no `NODE_OPTIONS`/`--import` flag to maintain.
+
+### Off by default in tests/CI
+- Gate on `OTEL_EXPORTER_OTLP_ENDPOINT`: blank ⇒ `startTelemetry()` returns early and all helpers
+  no-op. `npm test`/CI run with it unset and never start the LGTM stack.
+- `providers/telemetry.ts` is boot-only and excluded from coverage (like `server.ts`); the `config/`
+  helpers are unit-tested against the no-op API.
+
+### Env booleans: `z.stringbool()`, never `z.coerce.boolean()`
+- `z.coerce.boolean('false')` is `true` (any non-empty string is truthy). Boolean `OTEL_*` flags use
+  zod 4's `z.stringbool()`.
+
+---
+
+## Consequences
+
+- One `docker compose up` gives a full local trace/metric/log stack with log↔trace correlation.
+- Services stay clean: `withSpan(...)` + the existing `logger.info({ event, durationMs })`, no
+  Provider imports, no manual trace-context threading.
+- Logging is resilient to OTel/ESM churn because correlation and shipping don't depend on the pino
+  auto-instrumentation.
+- Adding OTLP log export later (if the ESM gap closes) is additive: install `sdk-logs` +
+  `exporter-logs-otlp-http`, add `logRecordProcessors` to the SDK, drop Alloy. No app-code change.

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

@@ -0,0 +1,23 @@
+# Architectural Decision Records (ADRs)
+
+All significant decisions are recorded here. Never deleted — mark as SUPERSEDED if replaced.
+
+---
+
+## Index
+
+| ID | Title | Status | Date | Plan |
+|---|---|---|---|---|
+| ADR-000 | Infrastructure & Stack Choices | ACCEPTED | *(fill on /infra-setup)* | — |
+
+---
+
+## ADR Statuses
+
+| Status | Meaning |
+|---|---|
+| PROPOSED | Under discussion |
+| ACCEPTED | Adopted — in effect |
+| REJECTED | Considered but not adopted |
+| SUPERSEDED | Replaced by a newer ADR |
+| DEPRECATED | No longer relevant |

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

@@ -0,0 +1,11 @@
+# Design Docs Index
+
+| Document                              | Purpose                                              |
+| ------------------------------------- | ---------------------------------------------------- |
+| `core-beliefs.md`                     | The engineering constitution — WHY every rule exists |
+| `decisions/index.md`                  | ADR registry — all architectural decisions           |
+| `decisions/ADR-000-infrastructure.md` | Stack choices and rationale                          |
+
+---
+
+Add a row here when creating a new design doc or ADR.