# Spec-Kit – UnionFlow

Configuration **Spec-Driven Development** pour le projet UnionFlow. Ce document décrit l’ensemble des artefacts, commandes et conventions du Spec-Kit. **En cas de divergence avec le code source, le code fait foi** ; l’inventaire et la documentation doivent être tenus à jour.

---

## 1. Structure des artefacts

```
unionflow/
├── .specify/
│   ├── memory/
│   │   ├── constitution.md      # Principes projet (sync avec CONSTITUTION.md)
│   │   └── inventaire-code.md   # Référence anti-hallucination (packages, routes, features)
│   ├── scripts/
│   │   └── powershell/          # Scripts workflow (pas de Bash dans ce dépôt)
│   │       ├── common.ps1
│   │       ├── check-prerequisites.ps1
│   │       ├── setup-plan.ps1
│   │       ├── create-new-feature.ps1
│   │       └── update-agent-context.ps1
│   └── templates/
│       ├── spec-template.md
│       ├── plan-template.md
│       ├── tasks-template.md
│       ├── checklist-template.md
│       ├── constitution-template.md
│       └── agent-file-template.md
├── .cursor/
│   ├── commands/                # Commandes /speckit.*
│   │   ├── speckit.constitution.md
│   │   ├── speckit.specify.md
│   │   ├── speckit.plan.md
│   │   ├── speckit.tasks.md
│   │   ├── speckit.implement.md
│   │   ├── speckit.clarify.md
│   │   ├── speckit.checklist.md
│   │   ├── speckit.analyze.md
│   │   └── speckit.taskstoissues.md
│   └── rules/
│       ├── unionflow-spec-kit.mdc   # Toujours appliqué
│       ├── unionflow-backend.mdc
│       └── unionflow-mobile.mdc
├── specs/
│   ├── 000-unionflow-baseline/
│   │   └── spec.md              # Baseline (état actuel du projet)
│   └── 00X-nom-court/           # Par feature
│       ├── spec.md
│       ├── plan.md
│       ├── tasks.md
│       ├── research.md          # Optionnel (Phase 0)
│       ├── data-model.md        # Optionnel (Phase 1)
│       ├── quickstart.md        # Optionnel (Phase 1)
│       ├── contracts/           # Optionnel (Phase 1)
│       └── checklists/          # Optionnel (qualité spec / pré-impl)
├── CONSTITUTION.md              # Référence principale (principes, DDD, API, sécurité)
└── SPEC-KIT.md                  # Ce fichier
```

Tous les chemins des scripts sont **relatifs à la racine du dépôt** (`unionflow/`). Environnement supporté : **Windows, PowerShell** (scripts Bash non fournis).

---

## 2. Workflow feature (ordre établi)

1. **`/speckit.specify`** + description → crée la branche feature et `specs/00X-nom/spec.md`.
2. **`/speckit.clarify`** (optionnel) → précise les exigences avant le plan.
3. **`/speckit.plan`** + contexte technique → génère `plan.md`, éventuellement `research.md`, `data-model.md`, `contracts/`, `quickstart.md`.
4. **`/speckit.tasks`** → génère `tasks.md` à partir de `plan.md` et `spec.md`.
5. **`/speckit.implement`** → exécute les tâches de `tasks.md` (après vérification des prérequis et optionnellement des checklists).

**Prérequis pour plan / tasks / implement** : le répertoire `specs/00X-nom/` doit exister. Pour cela :
- être sur une **branche feature** (ex. `001-mutuelles-anti-blanchiment`), **ou**
- définir la variable d’environnement **`SPECIFY_FEATURE`** (ex. `SPECIFY_FEATURE=001-mutuelles-anti-blanchiment`).

Sans cela, les scripts PowerShell renverront une erreur du type « Feature directory not found: specs/master » (sur branche `master`/`main`). La commande `/speckit.specify` crée elle-même la branche et le répertoire.

Commandes complémentaires : `/speckit.constitution` (principes), `/speckit.checklist` (listes de vérification), `/speckit.analyze` (analyse de cohérence), `/speckit.taskstoissues` (export des tâches en issues).

---

## 3. Commandes et scripts

| Commande | Usage | Script PowerShell (depuis racine dépôt) |
|----------|--------|----------------------------------------|
| `/speckit.constitution` | Créer ou mettre à jour les principes | — |
| `/speckit.specify` | Décrire une nouvelle feature (branche + spec) | `.specify/scripts/powershell/create-new-feature.ps1 -Json …` |
| `/speckit.clarify` | Clarifier les exigences | — |
| `/speckit.plan` | Générer le plan technique | `.specify/scripts/powershell/setup-plan.ps1 -Json` |
| `/speckit.tasks` | Décomposer en tâches | `.specify/scripts/powershell/check-prerequisites.ps1 -Json` |
| `/speckit.implement` | Exécuter l’implémentation | `.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` |
| `/speckit.checklist` | Listes de vérification | — |
| `/speckit.analyze` | Analyse de cohérence | — |
| `/speckit.taskstoissues` | Tâches → issues | — |

Les commandes qui s’appuient sur un script utilisent **uniquement** les scripts PowerShell ci-dessus. Les chemins `FEATURE_DIR`, `IMPL_PLAN`, `TASKS`, etc. sont déduits de la branche courante (ou de `SPECIFY_FEATURE`) et du répertoire contenant `.specify` (racine du dépôt).

---

## 4. Références obligatoires

- **Avant toute implémentation** (backend ou mobile) : lire `CONSTITUTION.md` (ou `.specify/memory/constitution.md`) pour les conventions DDD, API, tests, sécurité.
- **Anti-hallucination** : pour toute affirmation sur l’existant (packages, classes, endpoints, routes, migrations), s’appuyer sur `.specify/memory/inventaire-code.md`. Ne jamais inventer de fichier, package ou endpoint non listé ; en cas de doute, vérifier dans le code.
- **Baseline** : `specs/000-unionflow-baseline/spec.md` décrit l’état actuel du projet (modules, workflow Spec-Kit, inventaire consolidé).

---

## 5. Conventions

- **Branches feature** : format `001-nom-court`, `002-autre-feature`. Les specs vivent dans `specs/001-nom-court/`.
- **Langue** : tout contenu rédigé pour le projet (specs, plans, tâches, commentaires utilisateur visibles) est **en français**. Le code (noms de variables, classes, messages techniques) peut rester en anglais si c’est la convention du module.
- **Priorité** : en cas de divergence entre la documentation Spec-Kit et le code source, **le code fait foi** ; mettre à jour l’inventaire (et si besoin la constitution / le baseline) pour refléter l’état réel.

---

## 6. Environnement

- **OS** : Windows (scripts PowerShell).
- **Agent** : Cursor.
- **Projet** : Brownfield (existant). Monorepo : unionflow-server-api, unionflow-server-impl-quarkus, unionflow-client-quarkus-primefaces-freya, unionflow-mobile-apps.

---

## 7. Liens utiles

- **CONSTITUTION.md** (à la racine de `unionflow/`) – Principes du projet.
- **.specify/memory/inventaire-code.md** – Liste exacte des packages, migrations, features mobile, routes, DI.
- **specs/000-unionflow-baseline/spec.md** – Résumé de l’architecture et des commandes.