All Rework

.github/workflows/ci-template.yml

@@ -0,0 +1,31 @@
+name: CI Template
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  bake-smoke:
+    name: bake (3 combos, smoke)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v7
+        with: { enable-caching: true }
+      - run: uv sync --group dev
+      - run: uv run pytest -m unit -v
+      - run: uv run ruff check hooks/ tests/
+
+  bake-integration:
+    name: bake + ruff + custom lints + pytest unit on baked project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v7
+        with: { enable-caching: true }
+      - run: uv sync --group dev
+      - run: uv run pytest -m integration -v

.gitignore

@@ -52,3 +52,10 @@ Thumbs.db
 .env
 .env.*
 !.env.example
+
+# Cookiecutter local bake outputs
+/tmp-bake/
+/.bake/
+# Locally baked test projects (any baked project living at the repo root).
+# Keep them out of version control so devs can experiment freely.
+/toto/

.pre-commit-config.yaml

@@ -1,3 +1,11 @@
+# Pre-commit for the template repo itself.
+# The heavy guardrails (custom lints, ty, pytest, mutmut) live inside the
+# generated project at {{cookiecutter.project_slug}}/.pre-commit-config.yaml.
+# Cookiecutter-templated files contain Jinja syntax that breaks YAML/TOML
+# parsers, so we exclude that whole directory from syntactic checks.
+
+exclude: '^\{\{cookiecutter\.project_slug\}\}/'
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
@@ -8,6 +16,7 @@ repos:
       - id: check-toml
       - id: detect-private-key
       - id: check-added-large-files
+      - id: check-merge-conflict
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.9.0

CLAUDE.md

@@ -0,0 +1,48 @@
+# dev-soma-template — Repo IA Rules
+
+> This file governs **AI editing of the template itself**.
+> The generated projects ship their own `CLAUDE.md` inside `{{cookiecutter.project_slug}}/CLAUDE.md`.
+
+## What this repo is
+
+A **Cookiecutter** that generates SOMA Python services. Output = a project with FastAPI + Clean Architecture + observability + Helm + multi-layer guardrails (Claude skills, hooks, pre-commit, CI).
+
+The design rationale lives in the git history (commit messages are the source of truth for "why"). Each generated project ships its own `docs/architecture.md` and `docs/adr/`.
+
+## Repo layout
+
+```
+.
+├── cookiecutter.json                      # template variables
+├── hooks/                                 # pre/post_gen_project Python hooks
+├── tests/                                 # pytest-cookies bake tests of the template
+└── {{cookiecutter.project_slug}}/         # the generated project (see its own CLAUDE.md)
+```
+
+## Hard rules for AI editors
+
+1. **Two roots, two pyprojects, two CLAUDE.md** — never confuse them:
+   - root `pyproject.toml` = template tooling (cookiecutter, pytest, pytest-cookies, ruff)
+   - `{{cookiecutter.project_slug}}/pyproject.toml` = generated project deps (FastAPI, SQLAlchemy, etc.)
+2. **Never** edit `{{cookiecutter.project_slug}}/` files to fix a generated-project bug discovered downstream — fix at the template level so the next bake inherits the fix.
+3. **Cookiecutter templating syntax** uses `{{ cookiecutter.<var> }}`. Be careful when editing JSON/YAML files: Jinja braces inside JSON strings need to remain valid Jinja, not break JSON parsing.
+4. **Bake tests are the contract** — adding a feature without updating `tests/test_template_bake.py` is a regression.
+5. **Conventional commits** required. Branches: `feat/*`, `fix/*`, `docs/*`, `refactor/*`, `chore/*`. PRs must pass all CI checks.
+
+## Editing workflow
+
+1. Edit either the template machinery (root) **or** the generated project skeleton (`{{cookiecutter.project_slug}}/`) — rarely both in the same change.
+2. Run bake tests locally: `uv run pytest`.
+3. Write the commit message so it captures the *why* of the change (it's the long-term decision record).
+
+## Commands
+
+```bash
+uv sync                                    # install template tooling
+uv run pytest                              # run bake tests
+uv run cookiecutter . --no-input -o /tmp   # bake with default values for manual inspection
+uv run ruff check hooks/ tests/            # only on the template machinery — see note below
+uv run ruff format hooks/ tests/
+```
+
+**Note on ruff paths**: `uv run ruff check .` fails because ruff walks into `{{cookiecutter.project_slug}}/` and tries to parse the Jinja-templated `pyproject.toml` as a nested config. Always pass explicit paths (`hooks/`, `tests/`) at the template root. Pre-commit handles this transparently via its `exclude` regex.

README.md

@@ -1,42 +1,91 @@
-# [NOM DU PROJET]
+# dev-soma-template
 
-> Template SOMA — remplacer ce fichier par la documentation du projet.
+A **Cookiecutter** template that generates state-of-the-art SOMA Python services.
 
-## Description
+What you get out-of-the-box:
 
-[Description du projet en 2-3 phrases]
+- **FastAPI 0.115+** + **SQLAlchemy 2.0 async** + **asyncpg** + **Alembic**
+- **Clean Architecture** (Uncle Bob strict): `domain` / `application` / `infrastructure` / `presentation`
+- **uv** + **ruff** (extended ruleset) + **ty** (Astral type checker) + **mutmut** (mutation testing)
+- **OpenTelemetry** auto-switching between console and OTLP exporters
+- **structlog** with technical (JSON) and human-readable formats
+- **Devcontainer** with full local stack (Postgres + Jaeger + OTel collector)
+- **Helm chart** with multi-environment values, schema validation, migrations job
+- **Multi-layer guardrails** preventing convention drift: Claude Code skills + hooks, pre-commit, git hooks, CI
 
-## Stack
+## Generate a new project
 
-- Python 3.13
-- [Framework principal]
-- [Autres dépendances clés]
-
-## Installation
+### Interactive (recommended for first use)
 
 ```bash
-# Installer les dépendances
-uv sync
+# Install cookiecutter (one-time, globally or via pipx/uvx)
+uvx cookiecutter gh:soma-smart/dev-soma-template
 
-# Installer le hook de commit (conventional commits)
-bash /chemin/vers/doc-soma-manifest/templates/install-hooks.sh
+# Or from a local clone
+git clone git@github.com:soma-smart/dev-soma-template.git
+uvx cookiecutter ./dev-soma-template
 ```
 
-## Lancer le projet
+### Non-interactive (CI, scripts, repeat bakes)
+
+`cookiecutter` accepts overrides as positional `key=value` arguments
+**after** the template path. Combine with `--no-input` to skip every
+prompt and `-o <path>` to control the output directory:
 
 ```bash
-[commandes pour démarrer le projet]
+uvx cookiecutter ./dev-soma-template --no-input \
+    -o /tmp/out \
+    project_name="Billing API" \
+    database=postgres \
+    include_helm=yes
 ```
 
-## Tests
+Any variable not passed on the CLI uses its default from `cookiecutter.json`.
+For larger configs, point `--config-file <path>` at a YAML file with a
+`default_context:` mapping.
+
+### Variables
+
+You will be prompted for:
+
+| Variable               | Default               | Description                                         |
+| ---------------------- | --------------------- | --------------------------------------------------- |
+| `project_name`         | `My SOMA Service`     | Human-readable project name                         |
+| `project_slug`         | derived from name     | Folder + repo slug (`kebab-case`)                   |
+| `package_name`         | derived from slug     | Importable Python package (`snake_case`)            |
+| `project_description`  |                       | One-liner                                           |
+| `author_name`          | `SOMA`                |                                                     |
+| `author_email`         | `team@soma-smart.com` |                                                     |
+| `python_version`       | `3.13`                | `3.13` or `3.14`                                    |
+| `database`             | `postgres`            | `postgres` (full) or `sqlite` (light)               |
+| `include_helm`         | `yes`                 | Ship a Helm chart                                   |
+| `include_otel`         | `yes`                 | Wire OpenTelemetry instrumentations                 |
+| `license`              | `proprietary`         | `proprietary`, `MIT`, `Apache-2.0`                  |
+
+After generation, the post-hook automatically:
+
+1. `git init` + initial commit
+2. `uv sync --group dev`
+3. `cp .env.example .env`
+4. `pre-commit install` (commit-msg + pre-push hooks)
+
+## Develop on the template itself
 
 ```bash
-uv run pytest
+uv sync                                       # template tooling
+uv run pytest                                 # bake tests (pytest-cookies)
+uv run cookiecutter . --no-input -o /tmp/out  # smoke-bake with defaults
+uv run ruff check . && uv run ruff format .
 ```
 
-## Linter
+Bake with custom values for manual inspection — same positional
+`key=value` syntax as the user-facing flow above:
 
 ```bash
-uv run ruff check .
-uv run ruff format .
+uv run cookiecutter . --no-input -o /tmp/out \
+    project_name="Smoke Bake" \
+    database=sqlite \
+    include_helm=no
 ```
+
+See [`CLAUDE.md`](CLAUDE.md) for AI-assisted editing rules.