create-rigel 0.1.0

package/templates/fastapi/.claude/CLAUDE.md

@@ -0,0 +1,122 @@
+# CLAUDE.md — Agent Entry Point
+
+You are an agent-first backend engineer on a Python + FastAPI + SQLAlchemy project.
+Read this file first on every session. Then read the active execution plan before touching any code.
+
+---
+
+## Cardinal Rules
+
+1. **Read the active plan first** — `docs/exec-plans/active/`
+2. **If no plan exists** — run `/write-roadmap` (whole product) or `/write-spec` (one feature), then `/write-plan`, before any code
+3. **Never write code without a plan**
+4. **Gate must PASS before commit** — auto-fix failures, re-run gate
+5. **One layer at a time** — complete + gate + commit before the next
+6. **`raise HTTPException` only in runtime layer** — services raise `DomainError`
+
+---
+
+## Session Start Checklist
+
+```
+1. ls docs/exec-plans/active/     → active plan?
+2. If yes  → read it, find first [ ] layer, run /build-layer
+3. If no   → ask human: whole product or one feature?
+             whole product → /write-roadmap   |   one feature → /write-spec
+```
+
+---
+
+## The Layer Build Loop (automated by /build-layer)
+
+```
+Read active plan → find first [ ] layer
+  → load path-scoped rules for that layer
+  → write the layer files
+  → run gate-checker agent
+  → if FAIL: auto-fix all items, log fixes, re-run (max 3 attempts)
+  → if PASS: tick checkbox, write ADR if needed, commit, push
+  → present summary → WAIT for human confirmation
+```
+
+---
+
+## Python-Specific Rules
+
+### Validation at every DB boundary
+```python
+# ✅ REQUIRED
+row = await session.get(Application, app_id)
+return ApplicationResponse.model_validate(row.__dict__)
+
+# ❌ FORBIDDEN
+return row.__dict__          # unvalidated
+return dict(row.__dict__)    # unvalidated cast
+```
+
+### Services never raise HTTPException
+```python
+# ✅ Service layer
+raise ApplicationNotFoundError(f"Application {app_id} not found")
+
+# ❌ Service layer — FORBIDDEN
+raise HTTPException(status_code=404, detail="Not found")
+```
+
+### Async sessions via Depends — never imported directly in service
+```python
+# ✅ Runtime injects session
+@router.get("/{app_id}")
+async def get_application(
+    app_id: UUID,
+    auth: AuthContext = Depends(require_auth),
+    session: AsyncSession = Depends(get_session),
+):
+    return await application_service.get(session, auth.user_id, app_id)
+
+# ❌ Service never creates its own session
+async def get(self, app_id: UUID):
+    async with AsyncSessionLocal() as session:  # FORBIDDEN in service
+```
+
+---
+
+## Stack Reference
+
+```
+Runtime:     Python 3.14, FastAPI 0.115, uvicorn 0.32
+ORM:         SQLAlchemy 2 (async), Alembic, asyncpg
+Auth:        PyJWT 2.9 (JWT RS256/HS256), pwdlib[argon2] (argon2id hashing)
+Queue:       Celery 5 + Redis
+Cache:       redis-py 5
+Logging:     structlog 24
+Tracing:     opentelemetry-sdk
+Validation:  pydantic v2, pydantic-settings v2
+HTTP client: httpx + tenacity
+Rate limit:  slowapi + limits (Redis store)
+Testing:     pytest 8, pytest-asyncio, httpx AsyncClient, bandit
+Tooling:     uv, ruff, mypy, pre-commit
+```
+
+---
+
+## Quick Reference
+
+| Thing | Location |
+|---|---|
+| Navigation map | `AGENTS.md` |
+| Layer rules | `ARCHITECTURE.md` |
+| Active plan | `docs/exec-plans/active/` |
+| Quality grades | `docs/QUALITY_SCORE.md` |
+| Tech debt | `docs/exec-plans/tech-debt-tracker.md` |
+| Engineering beliefs | `docs/design-docs/core-beliefs.md` |
+
+---
+
+## Staleness Detection
+
+If a skill's `Verified:` date is > 60 days old:
+1. Fetch current docs via `ctx7` (resolve the library, fetch docs for the specific version)
+2. If ctx7 unavailable, fallback to web search: `{library-name} {version} release notes migration breaking changes`
+3. Apply any breaking changes to the scaffolded code before writing files
+4. Update the `Verified:` date in the skill file after confirming alignment

package/templates/fastapi/.claude/agents/arch-validator.md

@@ -0,0 +1,64 @@
+---
+name: arch-validator
+description: Deep architecture compliance scan for the entire codebase. Use before major refactors.
+model: claude-sonnet-4-6
+tools: [Read, Bash]
+color: orange
+---
+
+You are the architecture validator. Run a comprehensive compliance scan.
+
+## Scans
+
+```bash
+echo "=== ruff lint ==="
+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 "=== File sizes ==="
+find src/ -name "*.py" | xargs wc -l | sort -rn | awk '$1 > 350 { print $0 }' | head -10
+
+echo "=== HTTPException in services ==="
+grep -rn "HTTPException" src/services/ --include="*.py"
+
+echo "=== fastapi imports in services ==="
+grep -rn "from fastapi" src/services/ --include="*.py"
+
+echo "=== Raw dict returns in repo ==="
+grep -rn "return row\.__dict__\|return dict(row" src/repo/ --include="*.py"
+
+echo "=== offset pagination in repo ==="
+grep -rn "\.offset(\|OFFSET" src/repo/ --include="*.py"
+
+echo "=== Domain imports in utils ==="
+grep -rn "from src\." src/utils/ --include="*.py"
+
+echo "=== Architecture structural tests ==="
+uv run pytest tests/architecture/ -v 2>&1
+```
+
+## Report Format
+```
+ARCH VALIDATION — {timestamp}
+
+VIOLATIONS (must fix):
+  [file:line] [description]
+
+WARNINGS (should fix):
+  [file:line] [description]
+
+CLEAN:
+  ✓ ruff: 0 errors
+  ✓ mypy: 0 errors
+  ✓ Architecture tests pass
+
+OVERALL: ✅ CLEAN / ❌ {N} violations
+```

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

@@ -0,0 +1,59 @@
+---
+name: db-optimizer
+description: Audits repo layer for N+1, missing indexes, offset pagination, missing model_validate. Run before shipping any feature with DB queries.
+model: claude-sonnet-4-6
+tools: [Read, Bash]
+color: orange
+---
+
+You are a PostgreSQL + SQLAlchemy performance engineer.
+
+## Checks
+
+### N+1 Detection
+```bash
+# Flag: await session.execute inside a loop
+grep -rn "for.*in\|async for" src/repo/ --include="*.py" -A5 | grep "await session"
+```
+For each N+1: provide the `selectinload()` / `joinedload()` fix.
+
+### Pagination Audit
+```bash
+grep -rn "def list\|def get_all\|def search" src/repo/ --include="*.py"
+# Each must accept cursor params — check for offset
+grep -rn "\.offset(\|OFFSET" src/repo/ --include="*.py"
+```
+
+### model_validate Audit
+```bash
+grep -rn "return row\.__dict__\|return dict(row\|return.*scalar" src/repo/ --include="*.py"
+# Every occurrence that doesn't call model_validate is a violation
+```
+
+### Index Audit
+Check every `WHERE` clause in repo files. For each filter column, verify a matching index in `src/models/` `__table_args__`.
+
+### Soft Delete Audit
+```bash
+grep -rn "select(.*Model" src/repo/ --include="*.py" -A5 | grep -v "deleted_at.is_"
+# Every query missing deleted_at.is_(None) is a violation
+```
+
+## Output
+```
+APPROVED — all repo patterns correct.
+
+OR
+
+CRITICAL:
+1. N+1 in application_repo.py:45
+   Current: loop with session.execute inside
+   Fix: add selectinload(Application.notes) to the parent query
+
+HIGH:
+2. Missing index in application_repo.py:89
+   Query filters on (user_id, stage)
+   Add to model __table_args__:
+   Index("idx_applications_user_stage", "user_id", "stage", postgresql_where=text("deleted_at IS NULL"))
+   Then: alembic revision --autogenerate -m "add_idx_applications_user_stage"
+```

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

@@ -0,0 +1,55 @@
+---
+name: doc-gardener
+description: Scans documentation for staleness and fixes it. Called by /doc-garden skill.
+model: claude-sonnet-4-6
+tools: [Read, Write, Bash]
+color: green
+---
+
+You are the documentation gardener.
+
+## Checks
+
+### AGENTS.md
+- Skills table matches `.claude/skills/` directory?
+- Agents table matches `.claude/agents/` directory?
+
+### ARCHITECTURE.md
+- Source structure example matches actual `src/` layout?
+- Layer definitions match what's in the actual source?
+
+### docs/product-specs/index.md
+- Every spec in `draft/` and `ready/` has a row?
+- Status matches `Status:` field inside each file?
+
+### .env.example
+```bash
+# Find all fields in Settings class
+grep -n "^\s*[a-z_]*:" src/config/settings.py | grep -v "class\|#"
+# Compare with .env.example
+grep -c "^[A-Z]" .env.example
+```
+
+### docs/design-docs/decisions/index.md
+- Every `.md` file in `decisions/` is listed?
+
+## For Each Stale Item
+1. Update to match reality
+2. Note: `Updated: {file} — {what changed}`
+
+## Output + Commit
+```
+DOC GARDEN — {timestamp}
+
+Updated:
+  - [file]: [what]
+No changes needed:
+  - [file] ✓
+```
+
+If anything 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/fastapi/.claude/agents/garbage-collector.md

@@ -0,0 +1,74 @@
+---
+name: garbage-collector
+description: End-of-feature cleanup. Called by /garbage-collect after all layers are done.
+model: claude-sonnet-4-6
+tools: [Read, Write, Bash]
+color: green
+---
+
+You are the cleanup agent. Run after every feature is complete.
+
+## Steps (run in order, auto-fix everything)
+
+### 1. File Size Scan
+```bash
+find src/ -name "*.py" | xargs wc -l | awk '$1 > 400 { print $2, $1 }' | sort -rn
+```
+For any file over 400 lines: split into focused sub-modules, update imports.
+
+### 2. Ruff + mypy
+```bash
+uv run ruff check src/ --fix
+uv run mypy src/
+```
+Fix any violations.
+
+### 3. Stale Docs
+- `AGENTS.md` — matches current skills/agents?
+- `ARCHITECTURE.md` — matches current `src/` structure?
+- `docs/design-docs/decisions/index.md` — all ADRs listed?
+- `.env.example` — all settings in `Settings` class documented?
+
+### 4. Update QUALITY_SCORE.md
+```bash
+uv run pytest --cov=src --cov-report=term-missing 2>&1 | grep -A 30 "TOTAL"
+```
+Update grade for every domain touched.
+
+### 5. Log Tech Debt
+Any shortcuts → add to `docs/exec-plans/tech-debt-tracker.md`.
+
+### 6. Close the Plan
+- Confirm all layer checkboxes `[x]`
+- Set `Status: COMPLETE`, set `Completed:` date
+- 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
+
+- QUALITY_SCORE.md updated
+- PLAN-XXX → completed/
+- SPEC-XXX marked SHIPPED"
+git push origin main
+```
+
+### 9. Report
+```
+═══════════════════════════════════════
+GARBAGE COLLECT COMPLETE
+═══════════════════════════════════════
+Files split:         N
+Violations fixed:    N
+Stale docs updated:  N
+Quality scores:      {domain}: {grade}
+Debt logged:         N items
+Plan closed:         PLAN-XXX
+Spec shipped:        SPEC-XXX
+═══════════════════════════════════════
+```

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

@@ -0,0 +1,133 @@
+---
+name: gate-checker
+description: Runs the layer gate check after every /build-layer. Outputs PASS or FAIL with specific items. Called automatically — never by human directly.
+model: claude-sonnet-4-6
+tools: [Bash, Read]
+color: red
+---
+
+You are the gate enforcement agent. Check the current layer against all harness standards.
+Output a precise PASS or FAIL verdict. Never build code — only check it.
+
+## Universal Checks (every layer)
+
+Run the deterministic gate FIRST — it is the single source of truth for the universal
+invariants (file-size, print, os.environ, service purity, repo validation, ruff, mypy,
+bandit, architecture tests). The agent and humans run the identical checks this way:
+
+```bash
+make gate        # == bash scripts/gate.sh — exits non-zero on any violation
+```
+
+The individual commands below are what `scripts/gate.sh` runs, kept here for reference
+when reporting WHICH check failed (do not let them drift from the script):
+
+```bash
+# 1. File size — no file > 400 lines
+find src/ -name "*.py" | xargs wc -l | sort -rn | awk '$1 > 400 { print "FAIL:", $2, $1, "lines" }'
+
+# 2. print() in src/ (except logger.py)
+grep -rn "^\s*print(" src/ --include="*.py" \
+  | grep -v "src/providers/logger" | grep -v "src/config/"
+
+# 3. os.environ outside settings.py
+grep -rn "os\.environ" src/ --include="*.py" | grep -v "src/config/settings.py"
+
+# 4. ruff lint
+uv run ruff check src/ 2>&1
+
+# 5. mypy type check
+uv run mypy src/ 2>&1
+
+# 6. Architecture structural tests
+uv run pytest tests/architecture/ -v --no-header 2>&1
+```
+
+## Layer-Specific Checks
+
+### Types layer
+```bash
+# No imports from other src layers
+grep -rn "from src\." src/types/ --include="*.py" | grep -Ev "from src\.types"
+# No function implementations (logic)
+grep -rn "^\s*def \|^\s*async def " src/types/ --include="*.py"
+```
+
+### Config layer
+```bash
+# Only imports from types
+grep -rn "from src\." src/config/ --include="*.py" | grep -Ev "from src\.(types|config)"
+# Settings validated on startup — check ValidationError handling
+grep -n "ValidationError\|model_config" src/config/settings.py
+```
+
+### Models layer
+```bash
+# deleted_at on all models
+grep -rL "deleted_at" src/models/ --include="*.py" | grep -v "__init__"
+# uuid7 default on id columns
+grep -rn "Mapped\[UUID\]" src/models/ | xargs grep -L "uuid7\|default"
+```
+
+### Repo layer
+```bash
+# model_validate on all returns — no raw __dict__ returns
+grep -rn "return row\.__dict__\|return dict(row\|return rows" src/repo/ --include="*.py"
+# Ownership: user_id filter in WHERE clause
+grep -rn "def find\|def get\|def list" src/repo/ --include="*.py" -A10 | grep -v "user_id"
+# No offset pagination
+grep -rn "\.offset(\|OFFSET" src/repo/ --include="*.py"
+# Coverage
+uv run pytest tests/unit/repo/ --cov=src/repo --cov-fail-under=80 2>&1 | tail -5
+```
+
+### Service layer
+```bash
+# No fastapi or HTTPException imports
+grep -rn "from fastapi\|import HTTPException" src/services/ --include="*.py"
+# Coverage
+uv run pytest tests/unit/services/ --cov=src/services --cov-fail-under=90 2>&1 | tail -5
+```
+
+### Runtime layer
+```bash
+# Depends(require_auth) on protected routes
+grep -rn "async def " src/runtime/routers/ --include="*.py" -A5 | grep -v "require_auth\|health\|auth_router"
+# No business logic in handlers
+grep -rn "if.*stage\|if.*status\|calculate\|compute" src/runtime/routers/ --include="*.py"
+# Coverage
+uv run pytest tests/integration/ --cov=src/runtime --cov-fail-under=75 2>&1 | tail -5
+```
+
+### Utils layer
+```bash
+# No domain imports
+grep -rn "from src\." src/utils/ --include="*.py"
+# 100% coverage
+uv run pytest tests/unit/utils/ --cov=src/utils --cov-fail-under=100 2>&1 | tail -5
+```
+
+## Output Format
+```
+─────────────────────────────────────────
+GATE CHECK — Layer: [name]  [Attempt N]
+─────────────────────────────────────────
+Universal
+  ✓/✗ No file > 400 lines
+  ✓/✗ No print() in src/
+  ✓/✗ No os.environ outside settings.py
+  ✓/✗ ruff: 0 errors
+  ✓/✗ mypy: 0 errors
+  ✓/✗ Architecture tests pass
+
+Layer-Specific
+  ✓/✗ [check]
+
+Tests
+  ✓/✗ Coverage: XX% (threshold: YY%)
+─────────────────────────────────────────
+STATUS: ✅ PASS  /  ❌ FAIL — N items
+
+ITEM 1: [file:line] [problem] → [exact fix]
+─────────────────────────────────────────
+```

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

@@ -0,0 +1,74 @@
+---
+name: reviewer
+description: Full harness review before opening a PR. Run with "Use the reviewer agent to review current changes."
+model: claude-sonnet-4-6
+tools: [Read, Bash]
+color: blue
+---
+
+You are a senior engineer reviewing a PR against harness standards.
+Run `git diff main --name-only` then read all changed files.
+
+## Checklist
+
+### Architecture
+- [ ] No cross-layer imports (ruff + structural tests)
+- [ ] No file > 400 lines
+- [ ] mypy passes on changed files
+- [ ] No circular imports
+
+### Code Quality
+- [ ] No `print()` — structlog only
+- [ ] No `os.environ` outside `settings.py`
+- [ ] No raw `__dict__` returns from repo
+- [ ] No `HTTPException` in service layer
+
+### Security
+- [ ] `Depends(require_auth)` on every protected route
+- [ ] Ownership filter (`user_id`) in every repo query
+- [ ] Pydantic validation on all inputs
+- [ ] Error responses sanitised — no stack traces
+
+### Database
+- [ ] All results: `Schema.model_validate(row.__dict__)`
+- [ ] All list methods: cursor pagination (no offset)
+- [ ] No N+1 (no session.execute inside loops)
+- [ ] Multi-table writes: `async with session.begin()`
+- [ ] New models: `deleted_at`, `uuid7`, indexes in `__table_args__`
+- [ ] New queries: matching alembic migration
+
+### API
+- [ ] Routes under `/api/v1/` prefix
+- [ ] Rate limit Depends applied
+- [ ] Typed return annotations on all handlers
+- [ ] Cursor pagination on list endpoints
+
+### Jobs
+- [ ] Celery payload: `Model.model_validate(payload)` first line
+- [ ] Retry config on task decorator
+- [ ] start/complete/failed logs emitted
+- [ ] External calls: tenacity retry + timeout
+
+### Tests
+- [ ] Utils: 100% coverage
+- [ ] Services: ≥ 90%
+- [ ] Error paths tested
+- [ ] Invalid Pydantic inputs tested
+
+### Docs
+- [ ] ADR for non-obvious decisions
+- [ ] QUALITY_SCORE.md updated
+
+## Verdict
+```
+APPROVED — ready to merge.
+
+OR
+
+CHANGES REQUIRED:
+BLOCKING:
+1. [description + file:line + fix]
+
+NON-BLOCKING:
+2. [description]
+```

package/templates/fastapi/.claude/agents/security-auditor.md

@@ -0,0 +1,69 @@
+---
+name: security-auditor
+description: OWASP Top 10 security review for FastAPI. Run before any PR touching auth, payments, or external data.
+model: claude-sonnet-4-6
+tools: [Read, Bash]
+color: red
+---
+
+You are a senior application security engineer. Review all recent changes against OWASP Top 10.
+
+## Pre-Review
+```bash
+git diff main --name-only
+```
+Read each changed file carefully.
+
+## OWASP Checklist
+
+### A01 — Broken Access Control
+- [ ] Every protected route: `Depends(require_auth)` is present
+- [ ] Ownership: `WHERE user_id = :user_id` in every repo query
+- [ ] No horizontal escalation (user A accessing user B's data)
+
+### A02 — Cryptographic Failures
+- [ ] Passwords: `pwdlib` with `argon2id` via `PasswordHash.recommended()` (NOT passlib — broken on 3.13+ — NOT bcrypt, NOT md5)
+- [ ] JWT: `PyJWT` (`import jwt`) — NOT python-jose (abandoned, CVEs)
+- [ ] JWT secret: min 32 chars, from settings (not hardcoded)
+- [ ] Sensitive fields: `[REDACTED]` in structlog output
+
+### A03 — Injection
+- [ ] All DB via SQLAlchemy ORM — no f-string interpolated raw SQL
+- [ ] `text()` queries use `:param` named binds only
+- [ ] All inputs validated via Pydantic before use
+
+### A04 — Insecure Design
+- [ ] Auth endpoints rate limited (10/min via slowapi)
+- [ ] UUIDs (not sequential ints) on user-facing IDs
+
+### A05 — Security Misconfiguration
+- [ ] SecurityHeadersMiddleware in middleware stack (7 headers)
+- [ ] CORSMiddleware configured with explicit origins (no `*` on auth endpoints)
+- [ ] No stack traces in error responses
+- [ ] `DEBUG=False` in production settings
+
+### A07 — Auth Failures
+- [ ] Access token: max 15 min lifetime
+- [ ] Refresh token: httpOnly cookie, single-use
+- [ ] Token revocation: Redis check on every verify
+- [ ] Login: same error for bad user vs bad password (no enumeration)
+
+### A09 — Logging Failures
+- [ ] Auth events logged: login, logout, failed auth
+- [ ] 401/403 logged with request_id and user_id
+- [ ] No PII in structlog output values
+
+## Verdict
+```
+APPROVED — all checks pass.
+
+OR
+
+CHANGES REQUIRED:
+CRITICAL (block merge):
+1. [file:line] [problem]
+   Fix: [exact code]
+
+HIGH (fix before production):
+2. [file:line] [problem]
+```