create-rigel 0.1.0

package/templates/fastapi/AGENTS.md

@@ -0,0 +1,87 @@
+# AGENTS.md — Navigation Map
+
+Stack: Python 3.14 · FastAPI 0.115 · SQLAlchemy 2 (async) · PostgreSQL · Redis · Celery · uv
+
+---
+
+## 🗺️ Where Everything Lives
+
+| What you need | Where |
+|---|---|
+| Daily-driver commands | `Makefile` (`make bootstrap/dev/lint/test/gate/migrate/openapi`) |
+| Runnable gate (same checks as gate-checker) | `scripts/gate.sh` (`make gate`) |
+| Layer rules + dependency diagram | `ARCHITECTURE.md` |
+| Engineering constitution (the WHY) | `docs/design-docs/core-beliefs.md` |
+| Active execution plan | `docs/exec-plans/active/` |
+| Completed plans (history) | `docs/exec-plans/completed/` |
+| Product roadmap (epics → specs, dependency order) | `docs/product-specs/ROADMAP.md` |
+| Product specs (draft) | `docs/product-specs/draft/` |
+| Product specs (approved) | `docs/product-specs/ready/` |
+| Architectural decisions (ADRs) | `docs/design-docs/decisions/` |
+| Known tech debt | `docs/exec-plans/tech-debt-tracker.md` |
+| Domain health grades | `docs/QUALITY_SCORE.md` |
+| Plan format + lifecycle | `docs/PLANS.md` |
+| Generated DB schema | `docs/generated/db-schema.md` |
+
+---
+
+## ⚡ Slash Commands
+
+| Command | What it does |
+|---|---|
+| `/infra-setup` | Phase 0 — full infra scaffold (run once) |
+| `/write-roadmap` | Turn a product brief into an ordered spec roadmap → `docs/product-specs/ROADMAP.md` |
+| `/write-spec` | Write a product spec → `docs/product-specs/draft/` |
+| `/write-plan` | Turn a READY spec into an execution plan |
+| `/build-layer` | Build next unchecked layer from active plan + run gate |
+| `/validate-layer` | Run gate check on current layer without building |
+| `/push-layer` | Commit + push current layer with conventional message |
+| `/layer-check` | Ad-hoc architecture violation scan |
+| `/garbage-collect` | End-of-feature cleanup pass |
+| `/doc-garden` | Scan + fix stale documentation |
+| `/db-optimize` | EXPLAIN ANALYZE workflow for slow queries |
+| `/load-test` | Run k6 smoke / stress / soak test |
+
+---
+
+## 🤖 Agents
+
+| Agent | When to use |
+|---|---|
+| `gate-checker` | Called automatically by `/build-layer` — PASS/FAIL per layer |
+| `reviewer` | Before opening a PR — full harness review |
+| `arch-validator` | Deep import + layer compliance scan |
+| `db-optimizer` | N+1, missing index, pagination audit on repo layer |
+| `security-auditor` | OWASP Top 10 review — run before any auth/payment PR |
+| `doc-gardener` | Use the `/doc-garden` skill |
+| `garbage-collector` | Use the `/garbage-collect` skill |
+
+---
+
+## ✅ Non-Negotiable Invariants
+
+- No `print()` → use `logger` from `src/providers/logger.py`
+- No `os.environ` outside `src/config/settings.py`
+- No raw dict cast on SQLAlchemy results → `Model.model_validate(row.__dict__)` only
+- No file > 400 lines → split into focused modules
+- No cross-layer imports → enforced by `ruff` + structural tests
+- Every DB query result → `PydanticSchema.model_validate()`
+- Every list endpoint → cursor-based pagination
+- Every protected route → `Depends(require_auth)` as first dependency
+- Every external call → `tenacity` retry + timeout
+- All tests pass before `/push-layer`
+- `raise HTTPException` only in runtime layer — never in service layer
+
+---
+
+## 🔁 The Flow
+
+```
+# Whole product (run once at the start):
+/write-roadmap  →  human reviews ROADMAP  →  pick the walking-skeleton spec
+
+# Every feature (repeat down the roadmap):
+/write-spec (roadmap-guided)  →  human marks READY  →  /write-plan
+  →  /build-layer (repeats, gate-enforced)
+  →  /garbage-collect  →  plan closed
+```

package/templates/fastapi/ARCHITECTURE.md

@@ -0,0 +1,141 @@
+# ARCHITECTURE.md — Layered Architecture
+
+Stack: Python 3.14 · FastAPI 0.115 · SQLAlchemy 2 (async) · Alembic · PostgreSQL · Redis · Celery
+
+---
+
+## Dependency Layer Diagram
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Utils  — stateless helpers, zero domain imports         │
+│           100% test coverage required                     │
+└───────────────────────┬──────────────────────────────────┘
+                        │ (imported by all layers below)
+┌───────────────────────▼──────────────────────────────────┐
+│                                                           │
+│  Types ──► Config ──► Models ──► Repo                    │
+│                                    │                      │
+│                                    ▼                      │
+│                                 Service                   │
+│                                    │                      │
+│                                    ▼                      │
+│                    Runtime { Routers · Workers }          │
+│                                                           │
+│  Providers (auth, logger, db session, redis, telemetry)  │
+│  └─ enter domain via FastAPI Depends() only              │
+│                                                           │
+└───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Layer Definitions
+
+### Types (`src/types/`)
+- Pure Pydantic `BaseModel` schemas, enums, TypedDicts
+- **Zero imports** from other layers
+- **Zero logic** — only field definitions and validators
+- Examples: `ApplicationStage`, `CreateApplicationInput`, `PageResult[T]`
+
+### Config (`src/config/`)
+- `pydantic-settings` `BaseSettings` — typed, validated on startup
+- Imports: **Types only**
+- `settings.py` raises `ValidationError` on bad env → process never starts
+- Examples: `settings.py`, `constants.py`, `timeouts.py`
+
+### Models (`src/models/`)
+- SQLAlchemy 2 ORM model classes — schema only, no logic
+- Imports: **Types, Config**
+- All models: `__mapper_args__` soft delete pattern, `uuid7()` default on id
+- Indexes defined in model `__table_args__`
+- Examples: `user.py`, `application.py`
+
+### Repo (`src/repo/`)
+- Async DB access **and** outbound external-API gateways (`*_gateway.py`, httpx + tenacity). All output validated with Pydantic.
+- This is the home for "external APIs go via Repo" — services never make inline HTTP calls.
+- Imports: **Types, Config, Models**
+- **Every** query/response result: `Schema.model_validate(row.__dict__)`
+- All list methods: cursor-based pagination (`WHERE created_at < :cursor`)
+- Ownership enforced: `WHERE id = :id AND user_id = :user_id`
+- Examples: `user_repo.py`, `application_repo.py`
+
+### Service (`src/services/`)
+- Business logic and use-case orchestration
+- Imports: **Types, Config, Repo**
+- **No** `Request`, `HTTPException`, `fastapi` imports
+- **No** inline HTTP calls — external APIs go via Repo
+- `raise DomainError(...)` — never `raise HTTPException`
+- Examples: `application_service.py`, `auth_service.py`
+
+### Runtime (`src/runtime/`)
+- FastAPI routers, Celery workers, CLI entry points
+- Imports: **Types, Config, Repo, Service**
+- Routes: `Depends(require_auth)` first, then validate, then service, then respond
+- Thin layer — zero business logic
+- Maps `DomainError` → `HTTPException` in exception handlers
+- Examples: `routers/v1/applications.py`, `workers/reminder_worker.py`
+
+### Providers (`src/providers/`)
+- Cross-cutting: logger, db session factory, redis, auth, telemetry
+- Injected via FastAPI `Depends()` — never imported directly by Service
+- Examples: `logger.py`, `database.py`, `auth/jwt.py`
+
+### Utils (`src/utils/`)
+- Stateless helpers — **zero domain imports**
+- **100% test coverage** required
+- Examples: `retry.py`, `pagination.py`, `uuid_util.py`
+
+---
+
+## Allowed Imports (strict — ruff enforces)
+
+```
+Types   →  (nothing)
+Config  →  Types
+Models  →  Types, Config
+Repo    →  Types, Config, Models
+Service →  Types, Config, Repo
+Runtime →  Types, Config, Repo, Service
+Utils   →  (nothing)
+Providers → Types, Config only
+```
+
+**Forbidden:**
+- Service importing `fastapi`, `HTTPException`, or anything from Runtime
+- Repo containing business logic (if/else beyond null checks)
+- Utils importing any domain layer
+- Circular imports of any kind
+- `os.environ` outside `src/config/settings.py`
+
+---
+
+## File Size Limit
+- **400 lines maximum** per file
+- Enforced by: PostToolUse hook + gate-checker agent
+
+---
+
+## Naming Conventions
+
+| Layer | Pattern | Example |
+|---|---|---|
+| Types | `*_schema.py` or `*_types.py` | `application_schema.py` |
+| Config | `settings.py`, `constants.py` | `settings.py` |
+| Models | `*.py` in `models/` | `application.py` |
+| Repo | `*_repo.py` | `application_repo.py` |
+| Service | `*_service.py` | `application_service.py` |
+| Router | `*.py` in `routers/v1/` | `applications.py` |
+| Worker | `*_worker.py` | `reminder_worker.py` |
+| Utils | `*_util.py` | `retry_util.py` |
+| Pydantic schemas | `PascalCase` | `ApplicationResponse` |
+
+---
+
+## Mechanical Enforcement Stack
+
+1. **ruff rules** — `no-os-environ`, `no-cross-layer-import`, `no-print`
+2. **PostToolUse hooks** — fire on every file write (size, print, os.environ)
+3. **Structural tests** — `tests/architecture/test_layers.py` — fails CI on violations
+4. **gate-checker agent** — PASS required before every commit
+5. **mypy** — strict type checking on every CI run

package/templates/fastapi/Makefile

@@ -0,0 +1,42 @@
+# Makefile — single-command developer experience for the FastAPI harness.
+# Every command in the docs goes through a target here so humans and agents
+# run the exact same thing. Generated/maintained alongside /infra-setup.
+
+.PHONY: bootstrap dev lint format typecheck test gate migrate openapi up down lgtm
+
+bootstrap:        ## one-command setup: sync deps + install git hooks
+	uv sync && uv run pre-commit install
+
+dev:              ## run the API with autoreload
+	uv run uvicorn src.runtime.main:app --reload
+
+lint:             ## ruff lint
+	uv run ruff check src/ tests/
+
+format:           ## ruff format (writes)
+	uv run ruff format src/ tests/
+
+typecheck:        ## mypy strict
+	uv run mypy src/
+
+test:             ## full test suite + coverage
+	uv run pytest
+
+gate:             ## deterministic gate — same checks the gate-checker agent runs
+	bash scripts/gate.sh
+
+migrate:          ## apply migrations
+	uv run alembic upgrade head
+
+openapi:          ## export OpenAPI spec to openapi.json (loads .env if present so settings validate)
+	set -a; [ -f .env ] && . ./.env; set +a; \
+	uv run python -c "import json,sys; from src.runtime.main import app; json.dump(app.openapi(), sys.stdout)" > openapi.json
+
+up:               ## start local stack (app + postgres + redis)
+	docker compose up -d
+
+down:             ## stop local stack
+	docker compose down
+
+lgtm:             ## start local observability stack (Grafana/Loki/Tempo/Prometheus)
+	docker compose -f infra/monitoring/docker-compose.lgtm.yml up -d

package/templates/fastapi/README.md

@@ -0,0 +1,179 @@
+# FastAPI Agent Template
+
+Production-ready FastAPI template with layered architecture, SQLAlchemy 2 async, OpenTelemetry, and full agent harness for spec → plan → build → test → deploy workflow.
+
+---
+
+## Quick Start
+
+```bash
+# Initialize new project
+/infra-setup
+
+# Plan a whole product (run before /write-spec)
+/write-roadmap # → docs/product-specs/ROADMAP.md (brief → ordered, dependency-aware specs)
+
+# Build a feature
+/write-spec    # → docs/product-specs/draft/ (roadmap-guided)
+/write-plan    # → docs/exec-plans/active/
+/build-layer   # → auto-build + gate + commit + push (one layer at a time)
+
+# Quality gates
+/validate-layer    # Run gate without building
+/layer-check       # Ad-hoc architecture violation scan
+/db-optimize       # N+1 query detection, missing indexes
+/load-test smoke   # k6 performance test
+```
+
+---
+
+## Stack
+
+| Category | Packages |
+|---|---|
+| **Runtime** | Python 3.14, FastAPI 0.115, uvicorn[standard] 0.32 |
+| **ORM** | SQLAlchemy 2 (async), Alembic, asyncpg |
+| **Auth** | PyJWT[crypto] 2.9, pwdlib[argon2] 0.2, argon2-cffi |
+| **Queue** | Celery 5, Redis 5 |
+| **Logging** | structlog 24 |
+| **Tracing** | opentelemetry-sdk, opentelemetry-instrumentation-fastapi, prometheus-fastapi-instrumentator |
+| **Validation** | pydantic 2, pydantic-settings 2, email-validator |
+| **HTTP Client** | httpx, tenacity |
+| **Rate Limit** | slowapi, limits (Redis store) |
+| **Testing** | pytest 8, pytest-asyncio, pytest-cov, httpx AsyncClient, factory-boy, faker |
+| **Security** | bandit |
+| **Tooling** | uv, ruff, mypy, pre-commit |
+
+---
+
+## ✅ Key Features
+
+- **Layered architecture** enforced by ruff + AST structural tests
+- **Pydantic v2 validation** at every DB boundary (`model_validate` required)
+- **Structured JSON logging** with PII redaction (structlog)
+- **OpenTelemetry** instrumentation (FastAPI + SQLAlchemy)
+- **Rate limiting** with Redis store (3 tiers: auth, public, user)
+- **Cursor pagination** with opaque base64url tokens (no leaking impl details)
+- **Response envelopes** standardized: `{ ok, data, meta }` success, `{ ok: false, error, meta }` errors
+- **Security headers** middleware (7 headers: CSP, HSTS, X-Frame-Options, etc.)
+- **GDPR deletion** utility (anonymize PII, hard-delete sensitive, keep audit)
+- **Audit logging** utility (who, what, resource, timestamp)
+- **Cross-user isolation** tests (404 not 403 — don't leak resource existence)
+- **k6 load tests** (smoke + stress with P95/P99 budgets enforced in CI)
+- **schemathesis** OpenAPI contract/fuzz tests against `/openapi.json`
+- **Multi-stage Dockerfile** + `.dockerignore` (non-root user, HEALTHCHECK)
+- **GitHub Actions CI** — parallel jobs: quality (ruff + mypy), test (pytest + schemathesis), security (bandit + pip-audit + gitleaks), image (Trivy scan + SBOM)
+- **Dependabot** (uv + GitHub Actions + Docker)
+- **Makefile** single-command DX (`make bootstrap/dev/lint/test/gate/migrate/openapi`) + runnable `scripts/gate.sh`
+- **Agent-first workflow** (spec → plan → build loop with auto-gating)
+
+---
+
+## Why `>=` Version Bounds?
+
+All dependencies use `>=` (no upper bounds):
+
+```toml
+fastapi = ">=0.115"
+pydantic = ">=2.0"
+```
+
+**Reasoning:**
+
+- `uv.lock` pins exact versions for reproducible builds (lock file does the pinning)
+- Upper bounds cause **dependency hell** in libraries (if lib A pins `pydantic<3` and lib B pins `pydantic<2.5`, they're incompatible)
+- Security updates apply immediately via `uv sync --upgrade` (no waiting for maintainer to bump upper bound)
+- Dependabot raises weekly PRs that bump `uv.lock` and re-run the full CI gate, so updates are reviewed, not blind
+- Lockfile-first dependency management (pin the lock, range the manifest) is standard modern practice
+
+This is the same strategy as Rust (Cargo.toml) and modern Python packaging (PEP 440 discourages upper bounds).
+
+---
+
+## Architecture Layers
+
+```
+src/
+├── types/         # Domain exceptions, common types (no imports allowed)
+├── config/        # Settings, constants, timeouts (pydantic-settings)
+├── models/        # SQLAlchemy models (ORM only)
+├── repo/          # DB queries, cursor pagination, ownership filters
+├── services/      # Business logic (raise DomainError, never HTTPException)
+├── utils/         # Pure functions (no domain imports)
+├── providers/     # External integrations (DB, Redis, auth, logger, telemetry)
+└── runtime/       # FastAPI routers, middleware, exception handlers
+```
+
+**Enforced by:**
+
+- ruff import rules
+- `tests/architecture/test_layers.py` (AST-based structural tests)
+- post-write hook (catches `print()`, `os.environ`, HTTPException in services)
+
+---
+
+## Project Files
+
+| File | Purpose |
+|---|---|
+| `ARCHITECTURE.md` | Layer rules + dependency graph |
+| `AGENTS.md` | Navigation map for agents (which files do what) |
+| `.claude/CLAUDE.md` | Agent entry point (read first on every session) |
+| `.claude/rules/*.md` | Path-scoped rules (auto-injected based on file being edited) |
+| `.claude/skills/*.md` | Slash commands (`/infra-setup`, `/build-layer`, etc.) |
+| `docs/product-specs/ROADMAP.md` | Whole-product spec roadmap (epics, dependency order, walking skeleton) |
+| `docs/exec-plans/active/` | Current execution plan (checked boxes = done) |
+| `docs/design-docs/decisions/` | ADRs (Architecture Decision Records) |
+| `docs/product-specs/ready/` | Approved specs ready for implementation |
+
+---
+
+## OpenAPI → Frontend Sync
+
+FastAPI auto-generates OpenAPI spec at `GET /openapi.json`. To sync with frontend:
+
+```bash
+# 1. Export the OpenAPI spec (no running server needed)
+make openapi          # → openapi.json  (app.openapi() dumped to file)
+
+# 2. In frontend repo
+/api-sync             # generates TypeScript types from openapi.json
+```
+
+This keeps frontend types in sync with backend contract.
+
+---
+
+## Celery vs arq
+
+Template uses **Celery 5** by default. Trade-offs:
+
+| Feature | Celery | arq |
+|---|---|---|
+| **Async support** | Sync-first (requires `asyncio.run()` wrapper) | Native async |
+| **Scheduling** | Beat (cron-like) | None (use external scheduler) |
+| **Workflows** | Chain, chord, group primitives | Manual composition |
+| **Ecosystem** | Large (flower, django-celery, etc.) | Small (Pydantic team only) |
+| **Type safety** | Manual | Built-in (Pydantic v2) |
+
+**When to use arq:** If you don't need beat scheduling or chord/chain and want native async + type safety, consider arq.
+
+**Decision documented in:** `docs/design-docs/decisions/ADR-000-infrastructure.md` (scaffolded by `/infra-setup`)
+
+---
+
+## License
+
+MIT (or your org's standard license)
+
+---
+
+## Contributing
+
+This is a template repository. To update:
+
+1. Edit `.claude/skills/*.md` (skill scaffolds)
+2. Edit `.claude/rules/*.md` (path-scoped rules)
+3. Edit `CLAUDE.md`, `ARCHITECTURE.md`, `AGENTS.md` (agent context)
+4. Update `Verified:` headers on skills when libraries change
+5. Run staleness detection: if `Verified:` date > 60 days, fetch current docs via `ctx7`

package/templates/fastapi/docs/PLANS.md

@@ -0,0 +1,26 @@
+# PLANS.md — Execution Plan Format
+
+## 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 memory.
+
+## Plan Template
+See any file in docs/exec-plans/ for the full template.
+
+## 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: linter failures, test failures, technical unknowns — fix those.

package/templates/fastapi/docs/QUALITY_SCORE.md

@@ -0,0 +1,26 @@
+# QUALITY_SCORE.md — Domain Health Grades
+
+Updated by /garbage-collect after every feature.
+
+## Grading Rubric
+| Grade | Meaning |
+|---|---|
+| A | All invariants met, ≥ 90% coverage, zero known debt |
+| B | Minor issues, ≥ 80% coverage, low-priority debt logged |
+| C | Layer violation OR < 80% coverage OR unresolved medium debt |
+| D | Multiple violations, < 70% coverage, active bugs |
+| F | Blocking issues, data integrity risk, security concern |
+
+## Architecture Health
+| Check | Status |
+|---|---|
+| No circular imports | — |
+| No files > 400 lines | — |
+| No os.environ outside config | — |
+| No print() in src/ | — |
+| Utils: 100% test coverage | — |
+
+## Domain Grades
+| Domain | Grade | Coverage | Last Updated | Notes |
+|---|---|---|---|---|
+| *(no domains yet)* | — | — | — | — |

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

@@ -0,0 +1,46 @@
+# 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 here, it doesn't exist. Verbal agreements and Slack messages are invisible to agents and future engineers.
+**Consequence:** Every decision → ADR. Every product → ROADMAP.md. Every intent → spec. Every plan → PLAN-XXX.md.
+
+## 2. Enforce Mechanically, Not Aspirationally
+A ruff rule that blocks CI is worth ten documentation paragraphs. Agents respond to linter output.
+**Consequence:** Every constraint is a ruff rule, a structural test, or a hook — not just a doc.
+
+## 3. Agents Execute. Humans Steer.
+Human attention is the scarcest resource. Optimize everything around preserving it.
+**Consequence:** Maximum agent autonomy. Escalate only when judgment is needed.
+
+## 4. Layers Protect Business Logic
+Service layer is pure business logic. No HTTP, no FastAPI, no ORM models. It receives an injected `AsyncSession` and orchestrates repos — testable against a real test session, no web-layer mocks.
+**Consequence:** `raise HTTPException` only in runtime. Services raise `DomainError`. ORM models and `session.add` live only in the repo layer.
+
+## 5. External Data Is Adversarial Until Validated
+SQLAlchemy row `__dict__` is untyped. Pydantic `model_validate()` is the gate.
+**Consequence:** `Schema.model_validate(row.__dict__)` at every repo boundary. No raw dicts.
+
+## 6. Observability Is Not Optional
+Structured logs + traces are the only way to reproduce production bugs autonomously.
+**Consequence:** structlog on every service boundary. OTel spans on every DB query.
+
+## 7. Gate Before Commit — Always
+Every layer gated before commit. Auto-fix enabled — no reason to leave violations in.
+**Consequence:** gate-checker runs after every layer. PASS required before push.
+
+## 8. Small, Boring, Legible
+400 lines max. Well-known libraries. No premature abstraction.
+**Consequence:** uv, FastAPI, SQLAlchemy — widely used, well-documented, excellent agent training data.
+
+## 9. Technical Debt Is a High-Interest Loan
+Log debt immediately. Pay it in small daily amounts.
+**Consequence:** tech-debt-tracker.md updated after every feature. Garbage collect after every plan.
+
+## 10. The Fix Is Never "Try Harder"
+Repeated failures indicate a missing capability — tool, constraint, or abstraction.
+**Consequence:** Diagnose → build the capability → solve permanently.

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

@@ -0,0 +1,79 @@
+# ADR-000 — Infrastructure & Stack Choices
+
+**Status:** ACCEPTED
+**Date:** *(fill when /infra-setup is run)*
+**Plan:** Phase 0
+
+---
+
+## Context
+Starting a new Python backend project. Stack choices made here are expensive to change.
+
+---
+
+## Decisions
+
+### Runtime: Python 3.14 + FastAPI 0.115
+- Python 3.14 is the latest stable (released Oct 2025) — improved performance, better typing
+- FastAPI: async-native, auto OpenAPI, Pydantic v2 integration, best-in-class DX
+- Alternatives rejected: Flask (no async-native), Django (too opinionated for API-only)
+
+### ORM: SQLAlchemy 2 (async) + Alembic
+- SQLAlchemy 2 has proper async support (not bolted on)
+- `asyncpg` driver — fastest async PostgreSQL driver available
+- Alembic is SQLAlchemy's own migration tool — tight integration
+- Alternatives rejected: Tortoise ORM (less mature), SQLModel (thin wrapper, less control)
+
+### Validation: Pydantic v2
+- FastAPI's native schema layer — zero friction integration
+- v2 is 5-17x faster than v1 (Rust core)
+- Used at every external data boundary via `model_validate()`
+
+### Auth: PyJWT[crypto] + pwdlib[argon2]
+- PyJWT: FastAPI's official recommendation, actively maintained, RS256/HS256 support
+- pwdlib (`PasswordHash.recommended()` → argon2id): created by the FastAPI Users maintainer, Python 3.13+ compatible
+- argon2id: OWASP-recommended, winner of the Password Hashing Competition — GPU-resistant
+- Alternatives rejected:
+  - python-jose (abandoned — last release 2023, open CVEs)
+  - passlib (BROKEN on Python 3.13+ — `crypt` module removed in 3.13)
+  - bcrypt directly (GPU-vulnerable vs argon2id)
+
+### Queue: Celery 5 + Redis
+- Most mature Python task queue — battle-tested at scale
+- Redis broker: same Redis instance used for caching and rate limiting
+- Alternatives considered: dramatiq (simpler but less ecosystem), RQ (less features)
+
+### Logging: structlog 24
+- Structured JSON logging — equivalent of pino for Python
+- Built-in context binding, redaction, async support
+- Alternatives rejected: loguru (less structured), standard logging (no structured output)
+
+### Rate Limiting: slowapi + limits (Redis store)
+- slowapi: FastAPI-native rate limiting via Depends()
+- Redis store: distributed — works across multiple uvicorn workers
+- Alternatives: custom middleware (more work, same result)
+
+### Package Manager: uv
+- 10-100x faster than pip
+- Manages Python version + virtualenv + dependencies in one tool
+- Replaces: pip, pip-tools, pyenv, virtualenv
+- Lockfile (`uv.lock`) committed for reproducible installs
+
+### Linter/Formatter: ruff
+- Replaces: flake8 + black + isort + pyupgrade in one tool
+- Written in Rust — 10-100x faster than alternatives
+- Single config in `pyproject.toml`
+
+### PgBouncer
+- NOT in application code — infrastructure concern
+- Uncomment in `docker-compose.yml` when concurrent users > 50
+- App connects to PgBouncer (port 6432), PgBouncer connects to PostgreSQL
+
+---
+
+## Consequences
+- FastAPI async: all DB calls must be `await session.execute(...)` — no sync ORM calls
+- SQLAlchemy async: sessions are NOT thread-safe — inject via `Depends(get_session)`, never share
+- Celery: sync tasks (Celery is sync by default) — use `asyncio.run()` inside tasks for async calls
+- PyJWT: stateless tokens — revocation requires a Redis denylist check on every verify
+- argon2id (pwdlib): intentionally slow — login endpoint will be slower than bcrypt (~200ms vs ~100ms)

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

@@ -0,0 +1,7 @@
+# ADR Index
+
+| ID | Title | Status | Date | Plan |
+|---|---|---|---|---|
+| ADR-000 | Infrastructure & Stack Choices | ACCEPTED | *(fill on /infra-setup)* | — |
+
+Add a row here after every new ADR.

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

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

package/templates/fastapi/docs/exec-plans/tech-debt-tracker.md

@@ -0,0 +1,19 @@
+# Technical Debt Tracker
+
+## Severity
+| Level | Fix by |
+|---|---|
+| P0 | Immediately — security/data integrity |
+| P1 | Within 2 sprints — blocks features |
+| P2 | Within quarter — degrades quality |
+| P3 | When in area — code smell |
+
+## Open Debt
+| ID | Severity | Area | Description | Created By | Date |
+|---|---|---|---|---|---|
+| *(none yet)* | — | — | — | — | — |
+
+## Resolved Debt
+| ID | Description | Resolved By | Date |
+|---|---|---|---|
+| *(none yet)* | — | — | — |