create-rigel 0.1.0

package/templates/fastapi/.claude/skills/02-write-spec/SKILL.md

@@ -0,0 +1,82 @@
+# /write-spec — Write a Product Spec
+
+**Verified:** 2026-06-19 · **Staleness threshold:** 60 days  
+**Libraries:** harness toolchain (uv, ruff, mypy, pytest) — process skill, no external library pins  
+
+Triggered by: `/write-spec`
+
+## Step 1 — Consult the Roadmap (if present)
+```bash
+ls docs/product-specs/ROADMAP.md 2>/dev/null
+```
+If it exists, read it. Pick the first row with Status `NOT_STARTED` — the **walking skeleton**
+if nothing is created yet, otherwise the next dependency-unblocked row. Use that row's Name,
+Epic, and Depends-On to pre-fill the spec's title and the `**Epic:**` / `**Depends on:**` fields.
+If no roadmap exists, proceed ad hoc (a single standalone spec).
+
+## Step 2 — Get Next Spec Number
+```bash
+ls docs/product-specs/{draft,ready}/ 2>/dev/null | grep "SPEC-" | sort | tail -1
+```
+Increment by 1. Start at SPEC-001 if none. (`ROADMAP.md` is CAPS, so the `grep SPEC-` is unaffected.)
+
+## Step 3 — Write the Spec
+Save to: `docs/product-specs/draft/SPEC-XXX-{slug}.md`
+
+```markdown
+# SPEC-XXX — {Feature Name}
+
+**Status:** DRAFT
+**Created:** YYYY-MM-DD
+**Plan:** —
+**Epic:** —          <!-- from ROADMAP.md row, if roadmap-driven -->
+**Depends on:** —    <!-- from ROADMAP.md row, if roadmap-driven -->
+
+---
+
+## Problem Statement
+{what problem, who has it, why it matters}
+
+## What We're Building
+{the solution at high level}
+
+## Core Entities
+| Entity | Purpose |
+|---|---|
+
+## API Endpoints
+{METHOD /path — description}
+
+## Business Rules
+{numbered list}
+
+## State Machine (if applicable)
+{ASCII diagram + transition rules}
+
+## Non-Functional Requirements
+{performance, rate limits, auth, coverage targets}
+
+## Out of Scope (v1)
+{what is NOT being built}
+
+## Acceptance Criteria
+- [ ] {testable, specific}
+```
+
+## Step 4 — Update Index + Roadmap
+Add row to `docs/product-specs/index.md`: `| SPEC-XXX | {Name} | DRAFT | — | YYYY-MM-DD |`
+If this spec came from a `ROADMAP.md` row, flip that row: `Spec ID: — → SPEC-XXX` and
+`Status: NOT_STARTED → DRAFT` (mirrors how `/write-plan` updates the spec + index together).
+
+## Step 5 — Tell the Human
+```
+Spec written: docs/product-specs/draft/SPEC-XXX-{slug}.md
+Status: DRAFT
+
+Review it. When satisfied:
+  1. Move to: docs/product-specs/ready/SPEC-XXX-{slug}.md
+  2. Change Status: DRAFT → READY
+  3. Run /write-plan
+
+Claude will not create a plan until the spec is in ready/.
+```

package/templates/fastapi/.claude/skills/03-write-plan/SKILL.md

@@ -0,0 +1,83 @@
+# /write-plan — Write an Execution Plan
+
+**Verified:** 2026-06-19 · **Staleness threshold:** 60 days  
+**Libraries:** harness toolchain (uv, ruff, mypy, pytest) — process skill, no external library pins  
+
+Triggered by: `/write-plan`
+
+## Step 1 — Find Ready Spec
+```bash
+ls docs/product-specs/ready/
+```
+If none → tell human to mark a spec READY first. Stop.
+
+> A large spec may span MULTIPLE plans — slice it into shippable milestones, each its own
+> `PLAN-XXX` that ends green (e.g. data model + CRUD; then an external integration; then
+> reporting). Plans are numbered independently, so just create the next plan for the same spec.
+
+## Step 2 — Get Next Plan Number
+```bash
+ls docs/exec-plans/{active,completed}/ 2>/dev/null | grep "PLAN-" | sort | tail -1
+```
+
+## Step 3 — Read the Spec
+Identify all entities → models + migrations + repos + services.
+Identify all endpoints → routers. Background jobs → workers.
+
+## Step 4 — Write the Plan
+Save to: `docs/exec-plans/active/PLAN-XXX-{slug}.md`
+
+```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/{entity}_schema.py`, `exceptions.py` | Zero imports, zero logic |
+| 2 | Config | `src/config/settings.py` update, `constants.py` | No os.environ elsewhere |
+| 3 | Models | `src/models/{entity}.py` × N | deleted_at, uuid7, indexes |
+| 4 | Migrations | `alembic/versions/...` × N | Runs clean, has downgrade() |
+| 5 | Repo | `src/repo/{entity}_repo.py` × N | model_validate, cursor, ownership, no N+1 |
+| 6 | Service | `src/services/{domain}_service.py` × N | No fastapi, ≥90% coverage |
+| 7 | Runtime | `src/runtime/routers/v1/{resource}.py` × N | Depends(require_auth), typed return |
+| 8 | Workers | `src/runtime/workers/{name}_worker.py` × N | model_validate payload, retry, logs |
+| 9 | Tests | `tests/unit/`, `tests/integration/` | Coverage gates |
+
+---
+
+## Acceptance Criteria
+- [ ] {from spec}
+
+---
+
+## Progress Log
+### {date} — Plan created
+
+---
+
+## Decision Log
+*(filled during build)*
+```
+
+## Step 5 — Update Spec + Index
+APPEND `PLAN-XXX` to the spec's `**Plan:**` field (do not overwrite) — a spec split across
+several plans lists them all, e.g. `**Plan:** PLAN-003, PLAN-007`. Update index status to `PLANNED`.
+
+## Step 6 — Tell the Human
+```
+Plan written: docs/exec-plans/active/PLAN-XXX-{slug}.md
+{N} layers planned. Run /build-layer to start Layer 1.
+```

package/templates/fastapi/.claude/skills/04-build-layer/SKILL.md

@@ -0,0 +1,170 @@
+# /build-layer — Build Next Layer from Active Plan
+
+**Verified:** 2026-06-18 · **Staleness threshold:** 60 days  
+**Libraries:** FastAPI 0.115, SQLAlchemy 2.0, pydantic 2, pytest 8 — see .claude/rules/*.md for layer specifics  
+
+Triggered by: `/build-layer` (no argument — reads active plan automatically)
+
+---
+
+## Step 1 — Find Active Plan and Next Layer
+
+```bash
+PLAN=$(ls docs/exec-plans/active/*.md 2>/dev/null | head -1)
+[[ -z "$PLAN" ]] && echo "No active plan. Run /write-plan first." && exit 1
+cat "$PLAN"
+```
+
+Parse the Build Order table. Find first row with `[ ]`. If all `[x]` → run `/garbage-collect`.
+
+---
+
+## Step 2 — Load Context
+
+Read: active plan, linked spec, `ARCHITECTURE.md`, and the path-scoped rule:
+
+- Types → `.claude/rules/architecture.md`
+- Config → `.claude/rules/architecture.md`
+- Models → `.claude/rules/database.md`
+- Repo → `.claude/rules/database.md` + `.claude/rules/security.md`
+- Service → `.claude/rules/architecture.md` + `.claude/rules/security.md`
+- Runtime → `.claude/rules/api.md` + `.claude/rules/security.md`
+- Workers → `.claude/rules/jobs.md`
+- Tests → `.claude/rules/testing.md`
+
+---
+
+## Step 3 — Build the Layer
+
+### Types (`src/types/`)
+
+- One file per domain entity: `{entity}_schema.py`
+- Pydantic `BaseModel` — input schemas, response schemas, enums
+- `exceptions.py` — `DomainError` subclasses: `ApplicationNotFoundError`, `StageTransitionError` etc.
+- `common.py` — `PageResult[T]`, cursor types
+- Zero imports from other src layers. Zero logic.
+
+### Config (`src/config/`)
+
+- Update `settings.py` if new env vars needed (add to `Settings` + `.env.example`)
+- Add domain constants to `constants.py`
+
+### Models (`src/models/`)
+
+- One file per entity: `{entity}.py`
+- SQLAlchemy 2 declarative `MappedColumn` style
+- `deleted_at: Mapped[datetime | None] = mapped_column(default=None)`
+- `id: Mapped[UUID] = mapped_column(default=uuid_utils.uuid7)`
+- `__table_args__` with indexes (FK cols + ORDER BY cols + partial on deleted_at)
+- Export all from `src/models/__init__.py`
+
+### Migrations (`alembic/versions/`)
+
+```bash
+uv run alembic revision --autogenerate -m "create_{table}"
+# Review generated file — fix any issues
+uv run alembic upgrade head
+# Verify it ran clean
+```
+
+### Repo (`src/repo/`)
+
+- One file per entity: `{entity}_repo.py`
+- Every result: `Schema.model_validate(row.__dict__)`
+- List methods: cursor pagination (Op.lt on created_at + id)
+- Ownership: `WHERE id = :id AND user_id = :user_id`
+- No N+1: use `selectinload()` / `joinedload()` for related data
+- Soft delete: `WHERE deleted_at IS NULL` on every query
+
+### Service (`src/services/`)
+
+- One file per domain: `{domain}_service.py`
+- Receives: `AsyncSession` + typed Pydantic inputs
+- Returns: typed Pydantic outputs
+- Raises: `DomainError` subclasses — NEVER `HTTPException`
+- NO `from fastapi import ...`
+- State machines, business rules, orchestration live here
+- Multi-table writes: `async with session.begin():`
+
+### Runtime (`src/runtime/routers/v1/`)
+
+- One file per resource: `{resource}.py`
+- All routes: `Depends(require_auth)` as first dependency
+- Handler body: service call only — no business logic
+- Exception mapping: handled by global handlers in `exception_handlers.py`
+- All under `/api/v1/` prefix
+
+### Workers (`src/runtime/workers/`)
+
+- One file per queue: `{name}_worker.py`
+- First line: `data = PayloadSchema.model_validate(payload)`
+- Log: start, complete, failed with structlog
+- Re-raise on error (Celery handles retry per task config)
+
+### Tests (`tests/`)
+
+- `tests/unit/services/{service}_test.py` — service layer, mock repos
+- `tests/unit/utils/{util}_test.py` — utils
+- `tests/integration/test_{feature}.py` — full HTTP via AsyncClient
+- Meet coverage thresholds from `.claude/rules/testing.md`
+
+---
+
+## Step 4 — Run Gate
+
+Call `gate-checker` agent.
+
+**If FAIL:**
+
+- Read each ITEM → fix automatically → log fix
+- Re-run gate (max 3 attempts)
+- If still failing after 3: present to human with exact blocker
+
+**If PASS:**
+
+- Tick checkbox in plan: `- [ ] Layer N` → `- [x] Layer N`
+- Write ADR if non-obvious decision was made
+
+---
+
+## Step 5 — ADR (if needed)
+
+Save to `docs/design-docs/decisions/ADR-XXX-{slug}.md`.
+Update `docs/design-docs/decisions/index.md`.
+
+---
+
+## Step 6 — Commit and Push
+
+```bash
+git add -A
+git commit -m "{feat|chore|test}({layer}): {description}
+
+{bullet points}
+
+PLAN-XXX Layer N/Total"
+git push origin main
+```
+
+---
+
+## Step 7 — Report to Human
+
+```
+═══════════════════════════════════════════
+✅ Layer N ({layer-name}) — COMPLETE
+═══════════════════════════════════════════
+Files created: [list]
+Gate attempts: N
+Auto-fixed:    [list of fixes]
+ADR written:   ADR-XXX / None needed
+Committed:     [hash]
+
+Progress: [x] Layer 1  [x] Layer 2  [ ] Layer 3 ...
+
+Ready for Layer N+1: {next-layer-name}
+Confirm to continue? [human must respond]
+═══════════════════════════════════════════
+```
+
+**Wait for human confirmation before next layer.**

package/templates/fastapi/.claude/skills/05-validate-layer/SKILL.md

@@ -0,0 +1,20 @@
+# /validate-layer — Run Gate Without Building
+
+**Verified:** 2026-06-18 · **Staleness threshold:** 60 days  
+**Libraries:** harness toolchain (uv, ruff, mypy, pytest) — process skill, no external library pins  
+
+Triggered by: `/validate-layer`
+
+Calls `gate-checker` agent on current state of `src/`. Read-only — no auto-fix.
+
+## Steps
+1. Find most recently checked layer from active plan
+2. Call `gate-checker` agent with that layer name
+3. Present full PASS/FAIL report
+
+```
+VALIDATION REPORT — Layer: {name}
+{full gate output}
+
+Read-only validation. To auto-fix: run /build-layer
+```

package/templates/fastapi/.claude/skills/06-push-layer/SKILL.md

@@ -0,0 +1,31 @@
+# /push-layer — Commit and Push Current Layer
+
+**Verified:** 2026-06-18 · **Staleness threshold:** 60 days  
+**Libraries:** harness toolchain (uv, ruff, mypy, pytest) — process skill, no external library pins  
+
+Triggered by: `/push-layer`
+
+## Steps
+
+1. Quick gate check before push:
+```bash
+uv run ruff check src/ && uv run mypy src/
+```
+If fails → abort, tell human to fix or run `/build-layer`.
+
+2. Stage + commit:
+```bash
+git add -A
+git status
+git commit -m "{conventional commit message from active plan}"
+```
+
+3. Push:
+```bash
+git push origin $(git branch --show-current)
+```
+
+4. Report: `Pushed: {hash} — {message}`
+
+## Conventional Commit Types
+`feat` · `chore` · `test` · `refactor` · `fix` · `docs`

package/templates/fastapi/.claude/skills/07-layer-check/SKILL.md

@@ -0,0 +1,51 @@
+# /layer-check — Ad-hoc Architecture Violation Scan
+
+**Verified:** 2026-06-18 · **Staleness threshold:** 60 days  
+**Libraries:** harness toolchain (uv, ruff, mypy, pytest) — process skill, no external library pins  
+
+Triggered by: `/layer-check`
+
+```bash
+echo "=== ruff ==="
+uv run ruff check src/ 2>&1
+
+echo "=== mypy ==="
+uv run mypy src/ 2>&1
+
+echo "=== print() in src/ ==="
+grep -rn "^\s*print(" src/ --include="*.py" | grep -v "src/providers/logger" | grep -v "src/config"
+
+echo "=== os.environ outside settings ==="
+grep -rn "os\.environ" src/ --include="*.py" | grep -v "src/config/settings.py"
+
+echo "=== HTTPException in services ==="
+grep -rn "HTTPException" src/services/ --include="*.py" 2>/dev/null
+
+echo "=== raw dict returns in repo ==="
+grep -rn "return row\.__dict__\|return dict(row" src/repo/ --include="*.py" 2>/dev/null
+
+echo "=== offset pagination ==="
+grep -rn "\.offset(\|OFFSET" src/repo/ --include="*.py" 2>/dev/null
+
+echo "=== file sizes ==="
+find src/ -name "*.py" | xargs wc -l | sort -rn | awk '$1 > 400 { print "VIOLATION:", $2, $1, "lines" }'
+
+echo "=== architecture tests ==="
+uv run pytest tests/architecture/ -v --no-header 2>&1
+```
+
+Output:
+```
+LAYER CHECK — {timestamp}
+ruff:           CLEAN / {N} errors
+mypy:           CLEAN / {N} errors
+print():        NONE / {list}
+os.environ:     NONE / {list}
+HTTPException:  NONE / {list}
+Raw returns:    NONE / {list}
+Offset:         NONE / {list}
+File sizes:     NONE / {list}
+Arch tests:     PASS / FAIL
+
+OVERALL: ✅ CLEAN / ❌ {N} violations
+```

package/templates/fastapi/.claude/skills/08-garbage-collect/SKILL.md

@@ -0,0 +1,47 @@
+# /garbage-collect — End-of-Feature Cleanup
+
+**Verified:** 2026-06-18 · **Staleness threshold:** 60 days  
+**Libraries:** harness toolchain (uv, ruff, mypy, pytest) — process skill, no external library pins  
+
+Triggered by: `/garbage-collect`
+
+## Steps
+
+### 1. File Size
+```bash
+find src/ -name "*.py" | xargs wc -l | awk '$1 > 400 { print $2, $1 }' | sort -rn
+```
+Split any file over 400 lines.
+
+### 2. ruff + mypy
+```bash
+uv run ruff check src/ --fix
+uv run mypy src/
+```
+
+### 3. Stale Docs
+Check AGENTS.md, ARCHITECTURE.md, decisions/index.md, .env.example.
+
+### 4. QUALITY_SCORE.md
+```bash
+uv run pytest --cov=src --cov-report=term-missing 2>&1 | tail -20
+```
+Update domain grades.
+
+### 5. Log Debt → `docs/exec-plans/tech-debt-tracker.md`
+
+### 6. Close Plan
+- All `[x]` confirmed
+- `Status: COMPLETE`, `Completed: YYYY-MM-DD`
+- Move `active/PLAN-XXX.md` → `completed/`
+
+### 7. Mark Spec Shipped
+- `Status: SHIPPED` in spec file
+- 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/fastapi/.claude/skills/09-doc-garden/SKILL.md

@@ -0,0 +1,9 @@
+# /doc-garden — Scan and Fix Stale Docs
+
+**Verified:** 2026-06-18 · **Staleness threshold:** 60 days  
+**Libraries:** harness toolchain (uv, ruff, mypy, pytest) — process skill, no external library pins  
+
+Triggered by: `/doc-garden`
+
+Calls `doc-gardener` agent. Checks AGENTS.md, ARCHITECTURE.md, specs index,
+.env.example vs settings.py, decisions index. Updates what's stale. Commits if changed.

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

@@ -0,0 +1,53 @@
+# /db-optimize — Query Optimization
+
+**Verified:** 2026-06-18 · **Staleness threshold:** 60 days  
+**Libraries:** SQLAlchemy 2.0, asyncpg 0.30, PostgreSQL EXPLAIN ANALYZE  
+
+Triggered by: `/db-optimize [method-name]`
+
+## Step 1 — Find Slow Query
+```bash
+# From structlog output or 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 — EXPLAIN ANALYZE
+```bash
+psql $DATABASE_URL << 'SQL'
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+  SELECT a.* FROM applications a
+  WHERE a.user_id = 'uuid' AND a.deleted_at IS NULL
+  ORDER BY a.created_at DESC LIMIT 21;
+SQL
+```
+
+## Step 3 — Add Index via Alembic
+Add to model `__table_args__`:
+```python
+Index(
+    "idx_applications_user_created",
+    "user_id", "created_at",
+    postgresql_where=text("deleted_at IS NULL"),
+)
+```
+
+Generate + run:
+```bash
+uv run alembic revision --autogenerate -m "add_idx_applications_user_created"
+uv run alembic upgrade head
+```
+
+## Step 4 — Verify
+Re-run EXPLAIN ANALYZE — confirm `Index Scan` used, time < 200ms.
+
+## Step 5 — Commit
+```bash
+git add alembic/ src/models/
+git commit -m "perf(db): add idx_applications_user_created
+
+EXPLAIN before: {N}ms → after: {M}ms"
+```

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

@@ -0,0 +1,81 @@
+# /load-test — k6 Performance Testing
+
+**Verified:** 2026-06-18 · **Staleness threshold:** 60 days  
+**Libraries:** k6 0.54  
+**Source:** [k6 documentation](https://k6.io/docs/)
+
+Triggered by: `/load-test [smoke|stress|soak]`
+
+## Smoke (CI default)
+```bash
+k6 run --env BASE_URL=${BASE_URL:-http://localhost:8000} --env AUTH_TOKEN=${AUTH_TOKEN:-} tests/load/smoke.js
+```
+Thresholds: P95 < 500ms, error rate < 1%
+
+## Stress (pre-release)
+```bash
+k6 run --env BASE_URL=$STAGING_URL tests/load/stress.js
+```
+Thresholds: P95 < 1000ms, P99 < 2000ms, errors < 5%
+
+## stress.js scaffold
+```javascript
+import http from 'k6/http'
+import { check, sleep } from 'k6'
+
+export const options = {
+  stages: [
+    { duration: '2m', target: 50 },   // ramp up
+    { duration: '5m', target: 50 },   // sustained load
+    { duration: '2m', target: 100 },  // spike
+    { duration: '5m', target: 100 },  // sustained spike
+    { duration: '2m', target: 0 },    // ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<1000', 'p(99)<2000'],
+    http_req_failed: ['rate<0.05'],
+  },
+}
+
+export default function () {
+  const BASE_URL = __ENV.BASE_URL
+  const TOKEN    = __ENV.AUTH_TOKEN
+  const headers  = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' }
+
+  const health = http.get(`${BASE_URL}/v1/health`)
+  check(health, { 'health 200': (r) => r.status === 200 })
+
+  // Add feature-specific tests here (list, create, update operations)
+  sleep(1)
+}
+```
+
+## smoke.js scaffold
+```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 BASE_URL = __ENV.BASE_URL
+  const TOKEN    = __ENV.AUTH_TOKEN
+  const headers  = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' }
+
+  const health = http.get(`${BASE_URL}/v1/health`)
+  check(health, { 'health 200': (r) => r.status === 200 })
+
+  // Add feature-specific tests here
+  sleep(1)
+}
+```
+
+## Results format for PR
+```
+Load Test (smoke — 10 VUs, 30s):
+  P95: {N}ms  ✅/❌
+  Errors: {N}%  ✅/❌
+```

package/templates/fastapi/.dockerignore

@@ -0,0 +1,30 @@
+# Keep the Docker build context small and free of secrets.
+.git
+.github
+.gitignore
+.venv
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Secrets / local env — NEVER ship into an image
+.env
+.env.*
+!.env.example
+
+# Docs, tests, tooling — not needed at runtime
+docs/
+tests/
+infra/
+scripts/
+*.md
+Makefile
+.pre-commit-config.yaml
+.claude/

package/templates/fastapi/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  # Python deps — the "uv" ecosystem reads pyproject.toml AND updates uv.lock.
+  # (The "pip" ecosystem does NOT understand uv.lock, so updates would skip the lockfile.)
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    groups:
+      python-minor-patch:
+        update-types: ["minor", "patch"]
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  # Dockerfile base images
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"