devflow-cli 2.0.0__tar.gz → 2.2.0__tar.gz

devflow_cli-2.2.0/.specify/specs/020-migrate-speckit/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Migration speckit vers devflow
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-20
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items pass. Spec ready for `/devflow.clarify` or `/devflow.plan`.

devflow_cli-2.2.0/.specify/specs/020-migrate-speckit/data-model.md

@@ -0,0 +1,87 @@
+# Data Model: Migration speckit vers devflow
+
+**Feature**: 020-migrate-speckit | **Date**: 2026-03-20
+
+## Entités
+
+### SpeckitState (lecture seule — JSON brut)
+
+Un `state.json` au format speckit, lu directement depuis le fichier (pas via `read_state()` qui normalise).
+
+| Champ | Type | Obligatoire | Description |
+|-------|------|-------------|-------------|
+| `issueId` | string | Oui | Identifiant de la feature |
+| `currentStep` | string | Oui | Étape courante (vocabulaire speckit) |
+| `completedSteps` | string[] | Oui | Étapes complétées (vocabulaire speckit) |
+| `createdAt` | string | Non | Date de création ISO |
+| `updatedAt` | string | Non | Date de mise à jour ISO |
+
+**Critère d'identification** : absence du champ `reviewIterations` dans le JSON brut.
+
+**Valeurs possibles de `currentStep`** : `specify`, `clarify`, `plan`, `tasks`, `checklist`, `analyze`, `implement`.
+
+### FeatureState (existant — cible de conversion)
+
+Défini dans `src/devflow_cli/core/state.py`. Champs ajoutés lors de la conversion :
+
+| Champ | Valeur post-conversion |
+|-------|----------------------|
+| `currentStep` | Mappé selon table (ex: `specify` → `spec`) |
+| `completedSteps` | Mappées + étapes devflow intermédiaires injectées |
+| `stepTimestamps` | `{}` (pas de données source) |
+| `reviewIterations` | `{gate: 0}` pour chaque gate auto-validée |
+| `mode` | `"full"` |
+| `skippedSteps` | `[]` |
+
+### StepMapping (constante)
+
+Dictionnaire statique défini dans `state.py`.
+
+```python
+SPECKIT_STEP_MAP = {
+    "specify": "spec",
+    "clarify": "clarify",
+    "plan": "plan",
+    "tasks": "tasks",
+    "implement": "implement",
+}
+
+SPECKIT_IGNORED_STEPS = {"checklist", "analyze"}
+```
+
+### MigrationReport (sortie CLI)
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `migrated` | int | Nombre de features converties |
+| `skipped` | int | Nombre de features déjà devflow (idempotent) |
+| `errors` | int | Nombre de features en erreur |
+| `details` | list[MigrationDetail] | Détail par feature |
+
+### MigrationDetail
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `feature_dir` | string | Nom du dossier feature |
+| `issue_id` | string | Identifiant de la feature |
+| `status` | string | `"migrated"`, `"skipped"`, `"error"` |
+| `from_step` | string | Étape speckit originale |
+| `to_step` | string | Étape devflow après conversion |
+| `message` | string | Message d'erreur si applicable |
+
+## Relations
+
+```
+SpeckitState --(conversion)--> FeatureState
+    via StepMapping (constante)
+    produit MigrationDetail (rapport)
+
+MigrationDetail[] --> MigrationReport (agrégé par la commande CLI)
+```
+
+## Règles de validation
+
+1. Un `state.json` sans `issueId` ou `currentStep` est invalide → erreur, feature skippée.
+2. Un `currentStep` non présent dans `SPECKIT_STEP_MAP` ni dans `SPECKIT_IGNORED_STEPS` → erreur si pas dans STEPS devflow non plus.
+3. Un `state.json` avec `reviewIterations` déjà présent → skip (idempotent). — Réf: FR-005
+4. Les `completedSteps` sont filtrées : `checklist` et `analyze` sont retirées, les étapes valides sont mappées. — Réf: FR-002

devflow_cli-2.2.0/.specify/specs/020-migrate-speckit/plan.md

@@ -0,0 +1,74 @@
+# Implementation Plan: Migration speckit vers devflow
+
+**Branch**: `020-migrate-speckit` | **Date**: 2026-03-20 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/020-migrate-speckit/spec.md`
+
+## Summary
+
+Ajouter une commande `devflow migrate-speckit` qui détecte les features speckit (state.json sans `reviewIterations`), convertit leur state.json vers le format devflow (mapping d'étapes + injection des review gates auto-validées), crée une constitution starter si absente, et propose un nettoyage optionnel des commandes/templates speckit.
+
+## Technical Context
+
+**Language/Version**: Python 3.11+
+**Primary Dependencies**: Typer (>=0.12), Rich (>=13), hashlib (stdlib)
+**Storage**: Fichiers locaux (state.json, constitution.md, templates)
+**Testing**: pytest avec fixtures isolées (répertoires temporaires)
+**Target Platform**: macOS, Linux
+**Project Type**: CLI
+**Performance Goals**: <5s pour 10 features (SC-004)
+**Constraints**: Non-destructive, backup .bak obligatoire, idempotent
+**Scale/Scope**: Projets avec 1-50 features speckit
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principe | Statut | Justification |
+|----------|--------|---------------|
+| I. Spec-Driven | PASS | Spec complète avec 7 clarifications, user stories, acceptance scenarios |
+| II. Pipeline Séquentiel | PASS | La migration convertit les state.json pour respecter le pipeline devflow |
+| III. Gates de Review | PASS | Les gates manquantes sont auto-validées avec `reviewIterations: 0` — cohérent avec la rétrocompatibilité |
+| IV. Rétrocompatibilité | PASS | Backup .bak, dry-run, artefacts markdown inchangés, idempotent |
+| V. Simplicité (YAGNI) | PASS | Nouvelle commande + 1 fonction de conversion dans state.py, pas de nouvelle abstraction |
+| VI. Testabilité | PASS | Tests pytest avec fixtures speckit temporaires, pattern existant dans test_cmd_migrate.py |
+| VII. Intégration Linear | N/A | La migration ne touche pas Linear — le mapping STEP_LINEAR_MAPPING existant s'applique post-migration |
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/020-migrate-speckit/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+└── tasks.md             # Phase 2 output (/speckit.tasks)
+```
+
+### Source Code (repository root)
+
+```text
+src/devflow_cli/
+├── __init__.py              # +SPECKIT_STEP_MAP, SPECKIT_IGNORED_STEPS
+├── cli.py                   # +1 commande enregistrée (migrate_speckit)
+├── commands/
+│   ├── migrate_cmd.py       # Existant (migration legacy docs/features/)
+│   └── migrate_speckit.py   # NOUVEAU — commande migrate-speckit
+├── core/
+│   ├── state.py             # +convert_speckit_state(), +is_speckit_state()
+│   └── manifest.py          # Réutilisé pour checksums templates (--clean-speckit)
+└── utils/
+    └── console.py           # Réutilisé (ok, info, warn, fail, header)
+
+tests/
+├── conftest.py              # +fixture mock_speckit_state
+├── test_cmd_migrate_speckit.py  # NOUVEAU — tests commande
+└── test_state.py            # +tests conversion speckit
+```
+
+**Structure Decision**: Single project existant. Nouveau fichier `commands/migrate_speckit.py` pour la commande, fonctions de conversion ajoutées dans `core/state.py`. Pas de nouveau module — réutilisation maximale du code existant.
+
+## Complexity Tracking
+
+Aucune violation de simplicité. Tous les composants suivent les patterns existants (commande Typer + fonctions core + tests pytest).

devflow_cli-2.2.0/.specify/specs/020-migrate-speckit/quickstart.md

@@ -0,0 +1,64 @@
+# Quickstart: Migration speckit vers devflow
+
+**Feature**: 020-migrate-speckit | **Date**: 2026-03-20
+
+## Prérequis
+
+- Python 3.11+
+- devflow installé (`pip install -e ".[dev]"`)
+- Projet avec des features speckit dans `.specify/specs/`
+
+## Usage
+
+### 1. Prévisualiser la migration
+
+```bash
+devflow migrate-speckit --dry-run
+```
+
+Affiche un rapport de ce qui serait converti sans modifier aucun fichier.
+
+### 2. Exécuter la migration
+
+```bash
+devflow migrate-speckit
+```
+
+Convertit tous les `state.json` speckit en format devflow :
+- Crée un backup `.bak` de chaque state.json
+- Mappe les étapes (`specify` → `spec`)
+- Injecte les étapes devflow manquantes (review gates, etc.)
+- Crée une constitution starter si absente
+
+### 3. Nettoyer les résidus speckit
+
+```bash
+devflow migrate-speckit --clean-speckit
+```
+
+Supprime les commandes `speckit.*.md` de `~/.claude/commands/` et les templates speckit non personnalisés de `.specify/templates/`.
+
+### 4. Vérifier le résultat
+
+```bash
+devflow status
+```
+
+## Développement
+
+### Lancer les tests
+
+```bash
+pytest tests/test_cmd_migrate_speckit.py tests/test_state.py -v
+```
+
+### Fichiers modifiés
+
+| Fichier | Modification |
+|---------|-------------|
+| `src/devflow_cli/cli.py` | Enregistrement commande `migrate-speckit` |
+| `src/devflow_cli/commands/migrate_speckit.py` | Nouvelle commande |
+| `src/devflow_cli/core/state.py` | `is_speckit_state()`, `convert_speckit_state()` |
+| `tests/test_cmd_migrate_speckit.py` | Tests commande |
+| `tests/test_state.py` | Tests conversion |
+| `tests/conftest.py` | Fixture `mock_speckit_state` |

devflow_cli-2.2.0/.specify/specs/020-migrate-speckit/research.md

@@ -0,0 +1,75 @@
+# Research: Migration speckit vers devflow
+
+**Feature**: 020-migrate-speckit | **Date**: 2026-03-20
+
+## R1: Mapping complet des étapes speckit → devflow
+
+**Decision**: Mapping direct 1:1 pour les 5 étapes communes, ignorance des 2 étapes speckit-only, injection des étapes devflow intermédiaires.
+
+**Rationale**: Le pipeline speckit (7 étapes) est un sous-ensemble fonctionnel du pipeline devflow (13 étapes). Les étapes communes ont la même sémantique, seul le nom `specify` change en `spec`. Les étapes `checklist` et `analyze` n'ont pas d'équivalent devflow et ne produisent pas d'artefacts critiques.
+
+**Table de mapping**:
+
+| Étape speckit | Étape devflow | Action |
+|---------------|---------------|--------|
+| `specify` | `spec` | Renommer |
+| `clarify` | `clarify` | Conserver tel quel |
+| `plan` | `plan` | Conserver tel quel |
+| `tasks` | `tasks` | Conserver tel quel |
+| `checklist` | — | Ignorer (pas d'équivalent devflow) |
+| `analyze` | — | Ignorer (pas d'équivalent devflow) |
+| `implement` | `implement` | Conserver tel quel |
+
+**Étapes devflow injectées** (auto-validées si déjà dépassées) :
+
+| Étape devflow | Injectée après | Condition |
+|---------------|----------------|-----------|
+| `constitution` | — | Toujours injectée en premier |
+| `review-spec` | `clarify` | Si `plan` ou ultérieur est complété |
+| `research` | `review-spec` | Si `plan` ou ultérieur est complété |
+| `contracts` | `plan` | Si `tasks` ou ultérieur est complété |
+| `review-tasks` | `tasks` | Si `implement` ou ultérieur est complété |
+| `review-impl` | `implement` | Si `implement` est complété |
+| `docs` | `review-impl` | Si `implement` est complété |
+| `done` | `docs` | Jamais auto-injecté |
+
+**Alternatives considered**:
+- Mapping interactif (demander à l'utilisateur pour chaque étape) — rejeté car complexe et le mapping est déterministe.
+- Conserver `checklist`/`analyze` dans un champ `legacySteps` — rejeté car ajoute de la complexité sans valeur.
+
+## R2: Détection fiable d'un state.json speckit
+
+**Decision**: Critère principal = absence du champ `reviewIterations` dans le JSON brut.
+
+**Rationale**: Le champ `reviewIterations` est exclusif au format devflow. Un state.json speckit ne contient que `issueId`, `currentStep`, `completedSteps`, et potentiellement `createdAt`/`updatedAt`. La fonction `read_state()` actuelle ignore silencieusement les champs inconnus et ajoute des defaults — donc un state.json speckit chargé via `read_state()` aurait `reviewIterations: {}`, ce qui est aussi la valeur par défaut d'un state devflow. Il faut donc lire le JSON brut.
+
+**Critères secondaires** (pour confirmation) :
+- `currentStep` contient une valeur speckit-only (`specify`, `checklist`, `analyze`)
+- Absence du champ `mode`
+- `completedSteps` contient `specify` au lieu de `spec`
+
+**Alternatives considered**:
+- Champ `version` dans state.json — absent des deux formats, nécessiterait une migration de tous les states existants.
+- Heuristique sur les artefacts présents — fragile, un projet devflow peut aussi avoir peu d'artefacts.
+
+## R3: Stratégie de backup et idempotence
+
+**Decision**: Backup `.bak` avant modification + détection idempotente via `reviewIterations` présent dans le JSON brut.
+
+**Rationale**: Le pattern `.bak` est simple et ne nécessite pas de dépendance. L'idempotence est gratuite : si `reviewIterations` existe dans le JSON brut, le state est déjà au format devflow → skip.
+
+**Alternatives considered**:
+- Backup dans un sous-dossier `.migration-backup/` — sur-ingénierie pour un backup ponctuel.
+- Checksum de l'état pré-migration — complexe et inutile puisque le `.bak` suffit.
+
+## R4: Nettoyage templates avec protection des personnalisations
+
+**Decision**: Utiliser `compute_file_hash()` de `manifest.py` pour comparer les checksums des templates installés avec les originaux speckit connus.
+
+**Rationale**: Le module `manifest.py` fournit déjà `compute_file_hash()` (SHA-256). Il suffit de maintenir une liste des checksums originaux des templates speckit standards (ou de les calculer depuis les fichiers sources speckit s'ils sont disponibles dans le projet).
+
+**Approche pratique** : Comme les templates speckit originaux ne sont pas forcément disponibles dans le projet cible, on adopte une approche simplifiée — supprimer uniquement les fichiers qui correspondent au pattern `speckit*` ou aux noms connus des templates speckit standards. Pour les templates au nom générique (ex: `spec-template.md`), comparer avec les templates devflow — si identiques, supprimer ; sinon, avertir.
+
+**Alternatives considered**:
+- Suppression aveugle de tout `.specify/templates/` — risque de perte de personnalisations.
+- Manifeste speckit embarqué — sur-ingénierie, les checksums suffisent.

devflow_cli-2.2.0/.specify/specs/020-migrate-speckit/spec.md

@@ -0,0 +1,163 @@
+# Feature Specification: Migration speckit vers devflow
+
+**Feature Branch**: `020-migrate-speckit`
+**Created**: 2026-03-20
+**Status**: Draft
+**Project Type**: Brownfield
+**Input**: Commande devflow migrate-speckit pour convertir les anciens projets speckit en projets devflow
+
+## Clarifications
+
+### Session 2026-03-20
+
+- Q: Comment gérer les review gates manquantes lors de la conversion speckit → devflow ? → A: Auto-valider les gates manquantes (marquer complétées avec `reviewIterations: 0`)
+- Q: Quel critère discrimine un state.json speckit d'un state.json devflow ? → A: Absence du champ `reviewIterations` (exclusif à devflow)
+- Q: Que couvre le nettoyage `--clean-speckit` ? → A: Commandes `~/.claude/commands/speckit.*.md` + templates `.specify/templates/` du projet courant
+- Q: Quel type de constitution créer si absente ? → A: Template générique (identique à `devflow init --with-constitution`)
+- Q: Quel mapping complet appliquer pour les 7 étapes speckit vers les 13 étapes devflow ? → A: Mapping direct 1:1 (`specify→spec`, `clarify→clarify`, `plan→plan`, `tasks→tasks`, `implement→implement`), `checklist` et `analyze` ignorés (non présents dans devflow), étapes devflow intermédiaires (review gates, research, contracts, docs, done) injectées comme auto-validées si déjà dépassées.
+- Q: Mode batch ou interactif pour la migration multi-features ? → A: Batch automatique — toutes les features migrées d'un coup avec rapport final récapitulatif.
+- Q: Comment gérer les templates personnalisés lors du `--clean-speckit` ? → A: Comparer les checksums avec les originaux speckit — supprimer les non-modifiés, avertir et conserver les personnalisés.
+
+## Comportement existant
+
+### État actuel
+
+devflow dispose d'une commande `devflow migrate` qui convertit les features depuis `docs/features/` (ancien emplacement legacy) vers `.specify/specs/`. Cependant, cette commande ne gère que le changement de répertoire — elle ne convertit **pas** un projet utilisant le workflow speckit (commandes `/speckit.*`, templates speckit, structure speckit) vers le workflow devflow complet.
+
+Un projet speckit typique contient :
+- Des commandes `/speckit.*` installées globalement dans `~/.claude/commands/`
+- Des templates dans `.specify/templates/` (format speckit)
+- Des artefacts dans `.specify/specs/` avec un pipeline 7 étapes (specify → clarify → plan → tasks → checklist → analyze → implement)
+- Des `state.json` sans les champs `mode`, `skippedSteps`, ni les étapes devflow (`review-spec`, `research`, `contracts`, `review-tasks`, `review-impl`, `docs`, `done`)
+- Pas de constitution formalisée dans `.specify/memory/constitution.md`
+
+### Flux existants
+
+1. **Migration legacy (existante)** : `devflow migrate` détecte les features dans `docs/features/`, demande un short-name pour chacune, et les déplace vers `.specify/specs/` avec numérotation auto-incrémentée.
+2. **Init devflow (existante)** : `devflow init --here` installe les commandes/agents/templates devflow dans `~/.claude/` et crée la structure `.specify/` si absente.
+
+### Dépendances identifiées
+
+- **`src/devflow_cli/commands/migrate_cmd.py`** : commande migrate existante, à étendre ou à compléter
+- **`src/devflow_cli/core/state.py`** : `FeatureState`, `read_state`, `write_state` — doit gérer la conversion de format
+- **`src/devflow_cli/core/installer.py`** : non utilisé directement — la création constitution est réimplémentée dans la commande migrate-speckit
+- **`src/devflow_cli/utils/paths.py`** : résolution des chemins features (fallback triple)
+
+### Limitations connues
+
+- `devflow migrate` ne gère que le déplacement `docs/features/` → `.specify/specs/`, pas la conversion de workflow
+- Les `state.json` speckit sont lisibles par devflow (rétrocompatibilité) mais leur `currentStep` peut référencer des étapes inexistantes dans le pipeline devflow (ex: `specify` au lieu de `spec`)
+- Les projets speckit n'ont pas de gates de review dans leur historique — impossible de reconstruire `reviewIterations`
+- Les commandes `/speckit.*` restent installées globalement après migration, ce qui peut créer de la confusion
+
+## Impact sur l'existant
+
+### Composants affectés
+
+- **`cli.py`** : ajout de la commande `migrate-speckit` (nouvelle commande enregistrée)
+- **`state.py`** : ajout d'une fonction de conversion `state.json` speckit → devflow
+- **`installer.py`** : potentiellement réutilisé pour installer les templates devflow dans le projet cible
+
+### Risques de régression
+
+- **state.json corrompus** : la conversion doit être non-destructive — créer un backup avant modification. Mitigation : option `--dry-run` disponible, backup automatique `.bak`
+- **Confusion commandes** : les commandes `/speckit.*` et `/devflow.*` coexisteront dans `~/.claude/commands/`. Mitigation : avertir l'utilisateur, proposer le nettoyage optionnel
+
+### Stratégie de migration
+
+La migration est **opt-in et non-destructive** :
+1. Backup des `state.json` avant conversion (`.bak`)
+2. Mode `--dry-run` pour prévisualiser les changements
+3. Rétrocompatibilité préservée — les artefacts convertis restent lisibles par speckit
+4. Proposition optionnelle de nettoyage des commandes speckit
+
+## User Scenarios & Testing
+
+### User Story 1 - Convertir un projet speckit existant (Priority: P1)
+
+Un développeur utilisant speckit sur un projet existant veut passer au workflow devflow pour bénéficier des gates de review, du rollback, et de l'intégration Linear. Il lance `devflow migrate-speckit` dans son projet et obtient un projet devflow fonctionnel.
+
+**Why this priority** : C'est le cas d'usage principal — sans cette conversion, l'utilisateur doit recréer manuellement toutes ses features.
+
+**Independent Test** : Créer un répertoire temporaire avec une structure speckit (state.json speckit, artefacts), lancer la migration, vérifier que le state.json est converti et que `devflow status` fonctionne.
+
+**Acceptance Scenarios** :
+
+1. **Given** un projet avec `.specify/specs/001-my-feature/state.json` au format speckit (currentStep: `plan`, completedSteps: `["specify", "clarify", "plan"]`), **When** l'utilisateur lance `devflow migrate-speckit`, **Then** le `state.json` est converti avec `currentStep: "plan"`, `completedSteps: ["constitution", "spec", "clarify", "review-spec", "plan"]`, les champs `stepTimestamps`, `reviewIterations`, `mode: "full"` et `skippedSteps` sont ajoutés, et un backup `.bak` est créé.
+
+2. **Given** un projet speckit sans `.specify/memory/constitution.md`, **When** l'utilisateur lance `devflow migrate-speckit`, **Then** la commande crée une constitution starter et avertit l'utilisateur de la personnaliser.
+
+3. **Given** un projet speckit avec plusieurs features à différentes étapes, **When** l'utilisateur lance `devflow migrate-speckit`, **Then** toutes les features sont migrées en batch automatique avec un rapport final récapitulatif (nombre migrées, skippées, erreurs).
+
+---
+
+### User Story 2 - Prévisualiser la migration (Priority: P1)
+
+Un développeur veut vérifier ce que la migration va changer avant de l'exécuter.
+
+**Why this priority** : La confiance dans l'outil passe par la transparence — un dry-run est essentiel pour l'adoption.
+
+**Independent Test** : Lancer `devflow migrate-speckit --dry-run`, vérifier qu'aucun fichier n'est modifié et que le rapport est affiché.
+
+**Acceptance Scenarios** :
+
+1. **Given** un projet speckit avec 3 features, **When** l'utilisateur lance `devflow migrate-speckit --dry-run`, **Then** un rapport affiche pour chaque feature : l'étape actuelle, l'étape cible après conversion, les champs ajoutés, et aucun fichier n'est modifié.
+
+---
+
+### User Story 3 - Nettoyer les commandes speckit (Priority: P2)
+
+Après la migration, l'utilisateur veut supprimer les commandes `/speckit.*` de `~/.claude/commands/` pour éviter la confusion.
+
+**Why this priority** : Confort d'usage — pas critique pour le fonctionnement, mais réduit la confusion.
+
+**Independent Test** : Lancer la migration avec `--clean-speckit`, vérifier que les fichiers `speckit.*.md` sont supprimés de `~/.claude/commands/`.
+
+**Acceptance Scenarios** :
+
+1. **Given** un projet migré et des commandes `/speckit.*` dans `~/.claude/commands/`, **When** l'utilisateur lance `devflow migrate-speckit --clean-speckit`, **Then** les fichiers `speckit.*.md` sont supprimés de `~/.claude/commands/` et un rapport liste les fichiers supprimés.
+
+2. **Given** un projet migré, **When** l'utilisateur lance `devflow migrate-speckit` sans `--clean-speckit`, **Then** un message informe que les commandes speckit sont toujours présentes et propose d'utiliser `--clean-speckit`.
+
+---
+
+### Edge Cases
+
+- Que se passe-t-il si le `state.json` est déjà au format devflow ? La migration le détecte et le skip (idempotent).
+- Que se passe-t-il si le `state.json` est corrompu ou illisible ? Un warning est affiché, la feature est skippée, les autres features sont traitées.
+- Que se passe-t-il si le projet n'a aucune feature speckit ? Un message "Aucune feature speckit détectée" est affiché.
+- Que se passe-t-il si une feature speckit est à l'étape `implement` ? Les étapes de review manquantes sont marquées comme implicitement validées (`reviewIterations: 0`) pour ne pas bloquer le pipeline.
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001** : Le système DOIT détecter les features speckit en scannant les `state.json` dans `.specify/specs/` et en identifiant l'absence du champ `reviewIterations` (critère discriminant principal).
+- **FR-002** : Le système DOIT convertir le mapping d'étapes speckit → devflow selon la table : `specify→spec`, `clarify→clarify`, `plan→plan`, `tasks→tasks`, `implement→implement`. Les étapes speckit `checklist` et `analyze` sont ignorées (non présentes dans devflow). Les étapes devflow intermédiaires manquantes (review gates, research, contracts, docs, done) sont injectées comme auto-validées avec `reviewIterations: 0` si l'utilisateur les a déjà dépassées.
+- **FR-003** : Le système DOIT créer un backup `.bak` de chaque `state.json` avant modification.
+- **FR-004** : Le système DOIT supporter un mode `--dry-run` qui affiche le plan de migration sans modifier de fichiers.
+- **FR-005** : Le système DOIT être idempotent — relancer la migration sur un projet déjà migré ne produit aucun changement.
+- **FR-006** : Le système DOIT détecter l'absence de `.specify/memory/constitution.md` et créer une constitution starter via le template générique (identique à `devflow init --with-constitution`), puis avertir l'utilisateur de la personnaliser.
+- **FR-007** : Le système DOIT afficher un rapport final avec le nombre de features migrées, skippées et en erreur.
+- **FR-008** : Le système DOIT supporter `--clean-speckit` pour supprimer les commandes `~/.claude/commands/speckit.*.md` et les templates `.specify/templates/` du projet courant. Les templates personnalisés (checksum différent de l'original speckit) sont conservés avec un avertissement.
+
+### Key Entities
+
+- **SpeckitState** : un `state.json` au format speckit — identifiable par l'absence du champ `reviewIterations`.
+- **StepMapping** : correspondance entre les étapes speckit et devflow : `specify→spec`, `clarify→clarify`, `plan→plan`, `tasks→tasks`, `implement→implement`. Les étapes `checklist` et `analyze` sont ignorées. Les étapes devflow intermédiaires sont injectées comme auto-validées si déjà dépassées.
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001** : 100% des features speckit valides sont converties avec succès en une seule exécution.
+- **SC-002** : Après migration, `devflow status` affiche correctement toutes les features converties avec leur étape actuelle.
+- **SC-003** : No regression — les commandes existantes (`devflow feature`, `devflow status`, `devflow migrate`, `devflow rollback`) continuent de fonctionner identiquement après l'ajout de `migrate-speckit`.
+- **SC-004** : La migration complète d'un projet avec 10 features prend moins de 5 secondes.
+
+## Assumptions
+
+- Les projets speckit utilisent la structure `.specify/specs/` (pas un emplacement custom).
+- Les `state.json` speckit suivent le format `FeatureState` existant (au minimum `issueId`, `currentStep`, `completedSteps`).
+- Les artefacts markdown (spec.md, plan.md, tasks.md) sont compatibles entre speckit et devflow — seul le `state.json` nécessite une conversion.
+- Les commandes speckit sont dans `~/.claude/commands/speckit.*.md` (emplacement standard).