unionflow-server-api/unionflow/SPEC-KIT.md

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.