Feature Par Ia

Feature par IA (TDD + documentation)

Protocole obligatoire pour concevoir et implémenter une feature. Ne saute aucune gate. Ne commence jamais le code de production avant que les tests de l'étape courante soient validés par l'utilisateur.

Lis ce fichier en entier. Charge ensuite uniquement la référence de la phase en cours :

Templates : assets/FEATURE.md.template, assets/status.yaml.template.

Skill globale : elle vit dans ce plugin (ou ~/.cursor/skills/feature-par-ia/ après install.sh). Les docs de feature sont toujours écrites dans le projet courant (docs/features/…).

Pour créer le dossier : lance scripts/init-feature.sh <feature-name> depuis le dossier de cette skill (le script cible le git rev-parse --show-toplevel du cwd, jamais le dossier du skill).

Règles dures

1. Une feature = un dossier docs/features/{{featureName}}/. Jamais un fichier isolé à la racine de docs/.
2. {{featureName}} est un slug kebab-case ASCII (panier-achat, pas Panier Achat ni panier_achat).
3. Le document principal est docs/features/{{featureName}}/{{featureName}}.md. Les wikilinks Obsidian [[featureName]] pointent vers ce fichier.
4. Quatre parties dans cet ordre, toujours présentes, dès le premier jet : résumé → features liées → tests fonctionnels E2E → recap des tests unitaires.
5. Le résumé est purement fonctionnel : aucun stack, fichier, framework ou détail d'implémentation.
6. Les features liées utilisent des wikilinks Obsidian [[nom-feature]] et expliquent le lien dans le code (fichiers, imports, données partagées).
7. Stop et attends à chaque gate. N'enchaîne pas « pour avancer ». Un « ok », « valide », « continue », « go » explicite débloque la gate.
8. Tant que l'utilisateur n'a pas validé les tests de l'étape, les fichiers de logique restent des stubs (not implemented / throw). Pas de code métier.
9. Une étape n'est finie que si le build, les TU de l'étape et les tests d'intégration/E2E automatisés de l'étape sont verts.
10. Mets à jour status.yaml à chaque changement de phase.
11. Reprend une feature existante au lieu d'en recréer une si docs/features/{{featureName}}/status.yaml existe déjà.

Machine d'états

INIT
  → DESCRIBE          (points fonctionnels + découpage en étapes)
  → GATE_DECOUPAGE    ★ stop — validation utilisateur
  → pour chaque étape :
        FUNC_DOC      (tests fonctionnels humains dans le .md)
        → GATE_FUNC   ★ stop — validation utilisateur
        FUNC_AUTO     (tests E2E / intégration automatisés)
        TDD_SCAFFOLD  (stubs de logique + TU commentés)
        → GATE_TU     ★ stop — validation utilisateur
        LOOP_BUILD    (implémenter → build → TU → intégration, jusqu'au vert)
  → DONE

Phases status.yaml : describe | gate_decoupage | func_doc | gate_func | func_auto | tdd_scaffold | gate_tu | loop_build | done.

Reprise

1. Liste docs/features/*/status.yaml.
2. Si l'utilisateur nomme une feature, ouvre son status.yaml.
3. Reprends exactement à phase / current_step.
4. Si une gate est en attente, ne continue pas : réaffiche ce qui doit être validé.

Phase INIT

1. Si la demande est vague, pose 3 à 7 questions fonctionnelles max (acteur, résultat visible, cas d'erreur, hors-scope). Utilise AskQuestion quand c'est disponible.
2. Inspecte le repo : README, arborescence, runner de tests, features déjà documentées dans docs/features/.
3. Choisis featureName (slug). Confirme-le si le nom n'est pas évident.
4. Lance scripts/init-feature.sh (crée le dossier, copie les templates). Si le script n'est pas utilisable, reproduis-le à la main.

Phase DESCRIBE

Rédige dans {{featureName}}.md :

• Le résumé (5 à 12 lignes, fonctionnel, sans technique).
• Les points principaux de la feature, simples, testables, en liste.
• Le découpage en étapes : 2 à 8 étapes max, chacune livrable et testable isolément. Ordre = dépendances fonctionnelles.
• La section Features liées : parcours docs/features/, pose un wikilink pour chaque doc utile, et dis en une phrase le lien code (ou « Aucune feature liée identifiée. »).
• Laisse les sections tests E2E et TU prêtes, éventuellement vides.

Dans status.yaml : liste les étapes (id, name, status: pending), phase: gate_decoupage.

GATE_DECOUPAGE ★

Affiche :

• le résumé
• les points
• le découpage numéroté
• les features liées proposées

Demande de valider le découpage. Propose des options (valider / modifier le découpage / fusionner des étapes / retirer une étape) via AskQuestion si disponible.

Interdit : écrire des tests ou du code avant le « ok » utilisateur.

Boucle d'étape (répéter pour chaque étape)

Annonce clairement : Étape N/M — {{nom}}.

FUNC_DOC

Charge references/tests-fonctionnels.md.

Pour cette étape seulement, rédige les tests fonctionnels E2E dans le document de feature, sous un titre d'étape. Structure imposée :

### Titre du test

- Description : feature testée, comportement exercé, comportement attendu.
  - Input : …
  - Output attendu : …

Couvre le nominal, au moins un cas d'erreur / refus, et les bords évidents de l'étape. Pas de détails d'implémentation dans ces tests.

phase: gate_func.

GATE_FUNC ★

Montre uniquement les tests de l'étape courante. Attends la validation. Si l'utilisateur corrige, réécris puis re-gate.

FUNC_AUTO

Écris les tests automatisés qui matérialisent ces tests fonctionnels (Playwright, Cypress, tests d'intégration API, etc. selon le repo).

• Suit les conventions du projet. Sinon : tests/e2e/{{featureName}}/etape-{{n}}-{{slug}}.test.*
• Un test automatisé ↔ un test fonctionnel documenté. Même titre.
• Ils échouent tant que le métier n'existe pas. C'est voulu.
• Enregistre les chemins dans status.yaml (automated_tests).

TDD_SCAFFOLD

Charge references/boucle-tdd.md.

1. Crée les fichiers de logique stubs (signatures, types, exports publics). Corps = not implemented / throw. Pas de métier.
2. Crée les TU. Chaque test a un commentaire de descriptif fonctionnel (titre, description, input, output attendu) au-dessus du cas. Modèle : assets/commentaire-tu.template.
3. Les TU échouent (stubs). C'est voulu.
4. Mets à jour la 4ᵉ partie du document (fichier → liste des TU).

phase: gate_tu.

GATE_TU ★

Montre :

• les fichiers de logique créés (chemins)
• chaque TU avec son commentaire fonctionnel
• le mapping TU ↔ test fonctionnel quand il existe

Attends la validation. Pas d'implémentation avant.

LOOP_BUILD (auto, plus de gate)

1. Implémente le minimum pour faire passer les TU de l'étape.
2. Lance le build de l'étape (script du projet : build, tsc, compile, etc.). Si aucun build n'existe, lance au moins le typecheck / la compilation des tests.
3. Lance les TU de l'étape.
4. Lance les tests d'intégration / E2E automatisés de l'étape.
5. Si un de ces trois est rouge :
   • lis les erreurs
   • corrige ou pose une question si le besoin est ambigu (ne devine pas un métier non spécifié)
   • relance depuis le build
6. Plafonds : 8 itérations. Au-delà, stop et demande à l'utilisateur (erreurs, hypothèses, options).
7. Vert : marque l'étape done dans status.yaml, complète le recap TU du document, passe à l'étape suivante (FUNC_DOC).

Ne demande pas de validation humaine dans LOOP_BUILD, sauf question bloquante ou plafond atteint.

Phase DONE

1. Relis le document : les 4 parties sont à jour, plus de TODO vides si du contenu est censé exister.
2. phase: done, toutes les étapes done.
3. Résume à l'utilisateur : comportement livré, chemins de docs, de tests, de code.

Communication pendant les gates

Chaque message de gate se termine par un bloc :

**En attente de validation — {{nom de la gate}}**

À valider :
- …

Réponds **valide** pour continuer, ou indique les corrections.

Ne commence aucun travail de la phase suivante dans le même tour.

Langue

Rédige le document, les tests fonctionnels et les commentaires de TU dans la langue de la conversation (français par défaut si l'utilisateur écrit en français).