create-rigel 0.1.0

package/templates/fastapi/docs/product-specs/ROADMAP.md

@@ -0,0 +1,49 @@
+# Product Roadmap
+
+**Product:** *(name)* · **Brief:** *(one-line, or link to the brief)* · **Last updated:** *(YYYY-MM-DD)*
+**Walking skeleton:** *(SPEC-001 — the thinnest end-to-end slice; build this first)*
+
+> LIVING document — the altitude ABOVE specs. `/write-roadmap` writes it from a product brief.
+> `/write-spec` reads it to pick the next spec and pre-fill epic + dependency context, and flips
+> a row's **Spec ID** and **Status** as specs are created. Update in place; never delete history.
+
+---
+
+## Bounded Contexts (Epics)
+
+| Epic | Bounded Context | Responsibility |
+|---|---|---|
+| *(none yet)* | — | — |
+
+---
+
+## Spec Roadmap (dependency-ordered)
+
+| Order | Spec ID | Name | Epic | Depends On | Skeleton | Status |
+|---|---|---|---|---|---|---|
+| *(none yet)* | — | — | — | — | — | — |
+
+> `Spec ID` is `—` until `/write-spec` creates the file and assigns the real number.
+> `Depends On` references other rows by Spec ID (or by Order if not yet numbered).
+> Exactly one row carries `✅ yes` in `Skeleton`. Every spec appears after its dependencies.
+
+---
+
+## Build Sequence Rationale
+
+1. *(walking skeleton — why this thin slice first: proves auth + one entity + one endpoint end-to-end)*
+2. *(next slice — what it unblocks)*
+
+---
+
+## Roadmap Statuses
+
+| Status | Meaning |
+|---|---|
+| NOT_STARTED | On the roadmap, no spec file yet |
+| DRAFT | `/write-spec` wrote a SPEC-XXX (in `draft/`) |
+| READY | Spec approved — plannable |
+| PLANNED | `/write-plan` created a plan |
+| IN_PROGRESS | Being built |
+| SHIPPED | Complete and live |
+| CANCELLED | Removed from the roadmap |

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

@@ -0,0 +1,18 @@
+# Product Specs Index
+
+> Whole-product decomposition (epics → dependency-ordered specs, walking skeleton) lives in
+> [`ROADMAP.md`](ROADMAP.md). `/write-spec` fills this index per spec as each is created.
+
+| ID | Name | Status | Plan | Created |
+|---|---|---|---|---|
+| *(no specs yet)* | — | — | — | — |
+
+## Spec Statuses
+| Status | Meaning |
+|---|---|
+| DRAFT | Written, not reviewed |
+| READY | Approved — plannable |
+| PLANNED | Plan created |
+| IN_PROGRESS | Being built |
+| SHIPPED | Complete and live |
+| CANCELLED | Not being built |

package/templates/fastapi/gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.class
+*.pyc
+.Python
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Build
+dist/
+build/
+*.egg-info/
+
+# Environment — NEVER commit
+.env
+.env.local
+.env.*.local
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Logs
+*.log
+logs/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Docker
+docker-compose.override.yml

package/templates/fastapi/scripts/gate.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# scripts/gate.sh — deterministic, runnable mirror of the gate-checker agent's
+# universal checks. Humans run `make gate`; pre-commit runs this; the agent runs
+# the same logic. Exits non-zero on any violation so it can block commits/CI.
+#
+# Layer-specific coverage thresholds (utils 100 / services 90 / repo 80 /
+# runtime 75 / providers 70) are enforced by the gate-checker agent and CI;
+# this script enforces the universal, always-on invariants.
+
+set -uo pipefail
+
+FAIL=0
+fail() { printf '%b\n' "❌ $1"; FAIL=1; }   # %b so embedded \n render as newlines
+pass() { printf '%b\n' "✓ $1"; }
+
+if [[ ! -d src ]]; then
+  echo "No src/ yet — run /infra-setup first. Nothing to gate."
+  exit 0
+fi
+
+# 1. File size — no file > 400 lines
+BIG=$(find src/ -name "*.py" -print0 | xargs -0 wc -l 2>/dev/null | awk '$1 > 400 && $2 != "total" { print $2" ("$1" lines)" }')
+[[ -n "$BIG" ]] && fail "files over 400 lines:\n$BIG" || pass "no file > 400 lines"
+
+# 2. print() in src/ (except logger.py and config/)
+PRINTS=$(grep -rn "^\s*print(" src/ --include="*.py" 2>/dev/null | grep -v "src/providers/logger" | grep -v "src/config/")
+[[ -n "$PRINTS" ]] && fail "print() in src/:\n$PRINTS" || pass "no print() in src/"
+
+# 3. os.environ outside settings.py
+ENVS=$(grep -rn "os\.environ" src/ --include="*.py" 2>/dev/null | grep -v "src/config/settings.py")
+[[ -n "$ENVS" ]] && fail "os.environ outside settings.py:\n$ENVS" || pass "no os.environ outside settings.py"
+
+# 4. HTTPException raised in a service
+SVC_HTTP=$(grep -rn "HTTPException" src/services/ --include="*.py" 2>/dev/null)
+[[ -n "$SVC_HTTP" ]] && fail "HTTPException in service layer:\n$SVC_HTTP" || pass "no HTTPException in services"
+
+# 5. Services must not import fastapi or ORM models
+SVC_IMP=$(grep -rn "from fastapi\|import fastapi\|from src.models\|import src.models" src/services/ --include="*.py" 2>/dev/null)
+[[ -n "$SVC_IMP" ]] && fail "service imports fastapi/models:\n$SVC_IMP" || pass "services free of fastapi/models imports"
+
+# 6. Unvalidated raw dict / ORM returns in repo
+RAW=$(grep -rn "return row\.__dict__\|return dict(row\|return rows\b" src/repo/ --include="*.py" 2>/dev/null)
+[[ -n "$RAW" ]] && fail "unvalidated returns in repo (use Schema.model_validate):\n$RAW" || pass "repo returns validated"
+
+# 7. Offset pagination in repo
+OFFSET=$(grep -rn "\.offset(" src/repo/ --include="*.py" 2>/dev/null)
+[[ -n "$OFFSET" ]] && fail "offset pagination in repo (use cursor):\n$OFFSET" || pass "no offset pagination"
+
+# 8. ruff
+echo "── ruff ──"; uv run ruff check src/ || FAIL=1
+
+# 9. mypy
+echo "── mypy ──"; uv run mypy src/ || FAIL=1
+
+# 10. bandit (full security scan)
+echo "── bandit ──"; uv run bandit -r src/ -ll -q || FAIL=1
+
+# 11. architecture structural tests
+if [[ -d tests/architecture ]]; then
+  echo "── architecture tests ──"; uv run pytest tests/architecture/ -q || FAIL=1
+fi
+
+echo "─────────────────────────────"
+if [[ $FAIL -ne 0 ]]; then
+  echo "GATE: ❌ FAIL"
+  exit 1
+fi
+echo "GATE: ✅ PASS"

package/templates/nestjs/.claude/CLAUDE.md

@@ -0,0 +1,121 @@
+# CLAUDE.md — Agent Entry Point
+
+Stack: NestJS 11 · TypeScript 5 strict · Sequelize 6 + sequelize-typescript · PostgreSQL · Redis · BullMQ
+
+---
+
+## Cardinal Rules
+
+1. **Read the active plan first** — `docs/exec-plans/active/`
+2. **No plan = no code** — run `/write-spec` then `/write-plan` first
+3. **Gate must PASS before commit** — auto-fix, re-run, then commit
+4. **One layer at a time** — complete + gate + commit before next
+5. **No `process.env`** — use `ConfigService` injected via NestJS DI
+6. **No `HttpException` in services** — use `NotFoundException`, `ConflictException` etc.
+7. **No `@InjectModel()` in services** — inject the repository, not the model
+8. **Zod parse every `.toJSON()`** — in repository only, every time
+
+---
+
+## Session Start Checklist
+
+```
+1. ls docs/exec-plans/active/    → active plan?
+2. If yes  → read it → find first [ ] layer → /build-layer
+3. If no   → ask human what to build → /write-spec
+```
+
+---
+
+## NestJS-Specific Patterns
+
+### Config — always ConfigService, never process.env
+```typescript
+// ✅ Inject ConfigService
+constructor(private config: ConfigService) {}
+const secret = this.config.get<string>('JWT_SECRET')
+
+// ❌ Never
+const secret = process.env.JWT_SECRET
+```
+
+### Auth — global guard, opt-out with @Public()
+```typescript
+// ✅ Public route
+@Public()
+@Post('register')
+register(@Body() dto: RegisterDto) { ... }
+
+// ✅ Protected (no decoration needed — global guard handles it)
+@Get('me')
+getProfile(@CurrentUser() user: JwtPayload) { ... }
+```
+
+### Service exceptions — NestJS built-ins only
+```typescript
+// ✅
+throw new NotFoundException(`Application ${id} not found`)
+throw new ConflictException('Invalid stage transition')
+
+// ❌
+throw new HttpException('not found', 404)
+```
+
+### Repository — Zod on every output
+```typescript
+// ✅
+const raw = await this.appModel.findOne({ where: { id, userId } })
+if (!raw) throw new NotFoundException(`Application ${id} not found`)
+return ApplicationSchema.parse(raw.toJSON())
+
+// ❌
+return raw                    // raw Sequelize instance
+return raw.toJSON() as App    // cast without validation
+```
+
+### Controller — one-liners only
+```typescript
+// ✅
+@Get(':id')
+@ApiOperation({ summary: 'Get application by ID' })
+@ApiOkResponse({ type: ApplicationResponseDto })
+findOne(@Param('id') id: string, @CurrentUser() user: JwtPayload) {
+  return this.applicationService.findOne(user.sub, id)
+}
+
+// ❌ Business logic in controller
+@Get(':id')
+async findOne(@Param('id') id: string) {
+  const app = await this.service.findOne(id)
+  if (app.stage === 'CANCELLED') { ... }  // logic belongs in service
+}
+```
+
+### Logging — Logger, not console
+```typescript
+// ✅
+private readonly logger = new Logger(ApplicationService.name)
+this.logger.log({ event: 'application.created', id: app.id })
+
+// ❌
+console.log('created', app.id)
+```
+
+---
+
+## Stack Reference
+
+```
+Framework:  NestJS 11, Node 22, TypeScript 5 strict
+ORM:        Sequelize 6 + sequelize-typescript + sequelize-cli
+Auth:       @nestjs/passport + passport-jwt + @nestjs/jwt
+Password:   argon2
+Config:     @nestjs/config + joi
+Logging:    nestjs-pino + pino
+Queue:      @nestjs/bullmq + bullmq + ioredis
+Rate limit: @nestjs/throttler
+API docs:   @nestjs/swagger (live at /api/docs)
+Health:     @nestjs/terminus (/health + /ready)
+Validation: class-validator + class-transformer (input) + zod (output)
+Testing:    Jest + Supertest (NestJS default)
+```

package/templates/nestjs/.claude/agents/db-optimizer.md

@@ -0,0 +1,51 @@
+---
+name: db-optimizer
+description: Audits repository layer for N+1, missing indexes, offset pagination. Run before shipping any DB queries.
+model: claude-sonnet-4-5
+tools: [Read, Bash]
+color: orange
+---
+
+## Checks
+
+### N+1 Detection
+```bash
+# Flag model calls inside loops
+grep -rn "for\|forEach\|\.map" src/ --include="*.repository.ts" -A5 | grep "await this\."
+```
+For each N+1: provide the `include: [{ model: X }]` fix.
+
+### Pagination Audit
+```bash
+grep -rn "findAll\|list\|getAll" src/ --include="*.repository.ts"
+grep -rn "offset:\|\.offset(" src/ --include="*.repository.ts"
+```
+
+### Zod Parse Audit
+```bash
+grep -rn "\.toJSON()" src/ --include="*.repository.ts" -A2 | grep -v "Schema\.parse"
+```
+
+### Index Audit
+Check every `where:` in repository files — verify matching index in `@Table({ indexes })`.
+
+### Soft Delete Audit
+```bash
+grep -rn "findAll\|findOne" src/ --include="*.repository.ts" -A10 | grep -v "userId\|user_id"
+```
+
+## Output
+```
+APPROVED — all repo patterns correct.
+
+OR
+
+CRITICAL:
+1. N+1 in applications.repository.ts:45
+   Fix: add include: [{ model: Note }] to findAll
+
+HIGH:
+2. Missing index — applications filtered by (userId, stage) with no composite index
+   Fix: add to @Table indexes: [{ fields: ['user_id', 'stage'] }]
+   Migration: CREATE INDEX CONCURRENTLY idx_applications_user_stage ON applications(user_id, stage)
+```

package/templates/nestjs/.claude/agents/doc-gardener.md

@@ -0,0 +1,45 @@
+---
+name: doc-gardener
+description: Scans documentation for staleness and fixes it. Called by /doc-garden skill.
+model: claude-sonnet-4-5
+tools: [Read, Write, Bash]
+color: green
+---
+
+## Checks
+
+### AGENTS.md
+- Agents table matches `.claude/agents/` directory?
+- Slash commands match `.claude/skills/` directory?
+
+### ARCHITECTURE.md
+- Module list matches actual `src/` structure?
+- Layer definitions still accurate?
+
+### docs/product-specs/index.md
+- Every spec in `draft/` and `ready/` has a row?
+- Status matches `Status:` field inside the file?
+
+### .env.example
+```bash
+grep -o "[A-Z_]*:" src/config/configuration.ts | sort
+grep "^[A-Z]" .env.example | cut -d= -f1 | sort
+```
+Every config key documented?
+
+### docs/design-docs/decisions/index.md
+Every `.md` file in `decisions/` listed?
+
+## Output + Commit
+```
+DOC GARDEN — {timestamp}
+Updated: [file] — [what]
+No changes: [file] ✓
+```
+
+If changed:
+```bash
+git add docs/ AGENTS.md ARCHITECTURE.md .env.example
+git commit -m "docs: doc garden — sync stale documentation"
+git push origin main
+```

package/templates/nestjs/.claude/agents/garbage-collector.md

@@ -0,0 +1,50 @@
+---
+name: garbage-collector
+description: End-of-feature cleanup. Called by /garbage-collect after all layers complete.
+model: claude-sonnet-4-5
+tools: [Read, Write, Bash]
+color: green
+---
+
+## Steps (auto-fix everything)
+
+### 1. File Size
+```bash
+find src/ -name "*.ts" | xargs wc -l | awk '$1 > 400 { print $2, $1 }' | sort -rn
+```
+Split any file over 400 lines.
+
+### 2. TypeScript + ESLint
+```bash
+npx tsc --noEmit
+npx eslint src/ --fix --max-warnings=0
+```
+
+### 3. Stale Docs
+- `AGENTS.md` — matches current modules?
+- `ARCHITECTURE.md` — matches current `src/` structure?
+- `docs/design-docs/decisions/index.md` — all ADRs listed?
+- `.env.example` — all vars from `src/config/configuration.ts` documented?
+
+### 4. Update QUALITY_SCORE.md
+```bash
+npx jest --coverage 2>&1 | grep -A5 "Coverage summary"
+```
+
+### 5. Log Tech Debt → `docs/exec-plans/tech-debt-tracker.md`
+
+### 6. Close Plan
+- All `[x]` confirmed
+- `Status: COMPLETE`, `Completed: YYYY-MM-DD`
+- Move: `docs/exec-plans/active/PLAN-XXX.md` → `docs/exec-plans/completed/`
+
+### 7. Mark Spec SHIPPED
+- `docs/product-specs/ready/SPEC-XXX.md` → `Status: SHIPPED`
+- Update `docs/product-specs/index.md`
+
+### 8. Final Commit
+```bash
+git add -A
+git commit -m "chore: garbage collect — close PLAN-XXX"
+git push origin main
+```

package/templates/nestjs/.claude/agents/gate-checker.md

@@ -0,0 +1,127 @@
+---
+name: gate-checker
+description: Runs the layer gate after every /build-layer. Outputs PASS or FAIL with exact items. Called automatically — not by human.
+model: claude-sonnet-4-5
+tools: [Bash, Read]
+color: red
+---
+
+You are the gate enforcement agent. Check current layer against all harness standards.
+Output precise PASS or FAIL verdict. Never build code — only check it.
+
+## Universal Checks (every layer)
+
+```bash
+# 1. TypeScript
+npx tsc --noEmit 2>&1
+
+# 2. ESLint
+npx eslint src/ --max-warnings=0 2>&1
+
+# 3. File size
+find src/ -name "*.ts" | xargs wc -l | sort -rn | awk '$1 > 400 { print "FAIL:", $2, $1, "lines" }'
+
+# 4. console.log
+grep -rn "console\.\(log\|error\|warn\|info\)" src/ --include="*.ts"
+
+# 5. process.env outside config/
+grep -rn "process\.env" src/ --include="*.ts" | grep -v "src/config/"
+
+# 6. HttpException in services
+grep -rn "HttpException" src/ --include="*.service.ts"
+
+# 7. @InjectModel in services
+grep -rn "@InjectModel" src/ --include="*.service.ts"
+
+# 8. Architecture tests
+npx jest src/ --testPathPattern="spec" --no-coverage 2>&1 | tail -5
+```
+
+## Layer-Specific Checks
+
+### Model layer
+```bash
+# paranoid: true on all models
+grep -rL "paranoid.*true" src/**/*.model.ts 2>/dev/null
+
+# UUIDv7 default on id
+grep -rn "@Column.*primaryKey" src/ --include="*.model.ts" -A2 | grep -v "newId"
+```
+
+### DTO layer
+```bash
+# @ApiProperty on all properties
+grep -rn "^\s*readonly\s\+" src/ --include="*.dto.ts" | while read line; do
+  file=$(echo $line | cut -d: -f1)
+  grep -c "@ApiProperty" $file 2>/dev/null || echo "MISSING @ApiProperty in $file"
+done
+
+# class-validator on all input fields
+grep -rn "^\s*readonly\s\+" src/ --include="*create*.dto.ts" -c
+```
+
+### Repository layer
+```bash
+# Zod parse on all returns
+grep -rn "\.toJSON()" src/ --include="*.repository.ts" -A2 | grep -v "Schema\.parse\|\.parse("
+# No offset pagination
+grep -rn "offset:\|\.offset(" src/ --include="*.repository.ts"
+# Ownership check (userId in WHERE)
+grep -rn "findByPk\|findOne\|findAll" src/ --include="*.repository.ts" | grep -v "userId\|user_id"
+```
+
+### Service layer
+```bash
+# No @InjectModel (should use repository)
+grep -rn "@InjectModel" src/ --include="*.service.ts"
+# No HTTP imports
+grep -rn "from 'express'\|HttpException\b" src/ --include="*.service.ts"
+# Coverage
+npx jest --testPathPattern="service.spec" --coverage --coverageThreshold='{"global":{"lines":90}}' 2>&1 | tail -3
+```
+
+### Controller layer
+```bash
+# @ApiTags on every controller
+grep -rn "@Controller" src/ --include="*.controller.ts" -B5 | grep -v "@ApiTags"
+# @ApiOperation on every route
+grep -rn "@Get\|@Post\|@Put\|@Patch\|@Delete" src/ --include="*.controller.ts" -B3 | grep -v "@ApiOperation"
+# No business logic
+grep -rn "^\s\+if\|^\s\+else\|^\s\+switch" src/ --include="*.controller.ts"
+# E2E coverage
+npx jest --testPathPattern="e2e" --no-coverage 2>&1 | tail -5
+```
+
+### Module layer
+```bash
+# SequelizeModule.forFeature in imports
+grep -rn "SequelizeModule.forFeature" src/ --include="*.module.ts"
+# Repository in providers
+grep -rn "Repository\b" src/ --include="*.module.ts"
+```
+
+## Output Format
+```
+─────────────────────────────────────────
+GATE CHECK — Layer: [name]  [Attempt N]
+─────────────────────────────────────────
+Universal
+  ✓/✗ TypeScript: 0 errors
+  ✓/✗ ESLint: 0 errors
+  ✓/✗ No file > 400 lines
+  ✓/✗ No console.log
+  ✓/✗ No process.env outside config/
+  ✓/✗ No HttpException in services
+  ✓/✗ No @InjectModel in services
+
+Layer-Specific ([name])
+  ✓/✗ [check]
+
+Tests
+  ✓/✗ Coverage: XX% (threshold: YY%)
+─────────────────────────────────────────
+STATUS: ✅ PASS  /  ❌ FAIL — N items
+
+ITEM 1: [file:line] [problem] → [exact fix]
+─────────────────────────────────────────
+```

package/templates/nestjs/.claude/agents/reviewer.md

@@ -0,0 +1,68 @@
+---
+name: reviewer
+description: Full harness review before opening a PR. Run with "Use the reviewer agent to review current changes."
+model: claude-sonnet-4-5
+tools: [Read, Bash]
+color: blue
+---
+
+Run `git diff main --name-only` then read all changed files.
+
+## Checklist
+
+### Architecture
+- [ ] No cross-layer violations (service doesn't touch HTTP, controller has no logic)
+- [ ] No file > 400 lines
+- [ ] TypeScript: 0 errors
+- [ ] ESLint: 0 errors
+
+### Code Quality
+- [ ] No `console.log` (use `Logger`)
+- [ ] No `process.env` (use `ConfigService`)
+- [ ] No `HttpException` in services
+- [ ] No `@InjectModel` in services (inject repository)
+
+### Database (if repository/model changed)
+- [ ] All `.toJSON()` results: `ZodSchema.parse()`
+- [ ] All list methods: cursor pagination (no offset)
+- [ ] No N+1 (no model calls in loops — use `include`)
+- [ ] Multi-table writes: `sequelize.transaction()`
+- [ ] New models: `paranoid: true`, `newId()`, indexes in `@Table`
+- [ ] Ownership: `userId` in every WHERE clause
+
+### API (if controller changed)
+- [ ] `@ApiTags()` on controller class
+- [ ] `@ApiOperation()` on every route
+- [ ] `@ApiBearerAuth()` on class (if protected)
+- [ ] `@ApiResponse()` on every route
+- [ ] All routes under `/v1/` prefix
+- [ ] Rate limiting tier applied
+
+### Security
+- [ ] Public routes have `@Public()`
+- [ ] No `@UseGuards(JwtAuthGuard)` manually (it's global)
+- [ ] Admin routes have `@Roles('ADMIN')`
+- [ ] Input validation via DTO + `@ApiProperty()`
+
+### Tests
+- [ ] Service: 90%+ coverage, error paths tested
+- [ ] E2E: 201, 401, 422, 404 all covered
+- [ ] Mock uses `Test.createTestingModule` pattern
+
+### Docs
+- [ ] ADR for non-obvious decisions
+- [ ] `QUALITY_SCORE.md` updated
+
+## Verdict
+```
+APPROVED — ready to merge.
+
+OR
+
+CHANGES REQUIRED:
+BLOCKING:
+1. [file:line] [problem] → [fix]
+
+NON-BLOCKING:
+2. [description]
+```