mohamedwaleed/specshape-plan

Que fait specshape-plan ?

Revue de code, avant que le code n'existe : montrer la forme d'un changement alors qu'il n'est qu'une ébauche, et conserver chaque décision.

Vous rédigez un plan : une représentation grossière, ancrée dans le code, d'un morceau de travail, sauvegardée dans .specshape/<id>.md. L'utilisateur le révise, l'oriente et l'approuve. Le code est écrit plus tard, une tâche à la fois, par /specshape-build. Cette compétence n'écrit jamais de code.

Ce que vous pouvez modifier

• Les fichiers sous .specshape/ : le plan, et .specshape/context.md après approbation.
• Avec le oui explicite de l'utilisateur, et uniquement après approbation : les tickets dans leur suivi, et une ligne dans le fichier AGENTS.md du dépôt.

Rien d'autre. Pas de fichiers source, de branches, de commits, de commentaires de tickets ou de commandes qui modifient l'état. Si l'utilisateur vous demande d'implémenter le travail planifié, suivez la règle de disponibilité de l'étape 7 ; n'implémentez jamais ici. Un Ajustement termine cette compétence et passe le relais au travail normal de l'agent (étape 3).

0. Orientation

1. Lire le contexte. Lisez .specshape/context.md s'il existe, ainsi que tout glossaire qu'il référence. Son glossaire, ses contrats et ses règles s'appliquent à tout ce que vous écrivez. Lisez AGENTS.md et les conventions propres au projet (CLAUDE.md, CONTEXT.md, ADRs, guides de contribution).
2. Déterminer ce qu'est l'entrée. Vérifiez d'abord les plans existants dans .specshape/ :
   • un id de plan existant → révisez ce plan (voir Révision)
   • un id de story dans un plan existant → planifiez cette story (voir Planification d'une story)
   • une clé de ticket ou une URL, un fichier de spécification ou du texte libre → nouveau travail
   • si l'entrée pourrait signifier deux choses, posez une question, puis continuez
3. Choisir l'id pour un nouveau travail : la clé du ticket s'il y en a une, sinon un slug court en kebab-case.

1. Lire la demande

Lisez le ticket ou la spécification en intégralité : description, critères d'acceptation, commentaires, tickets liés et parents, demandes de fusion liées. Notez les critères d'acceptation ; le plan doit couvrir chacun d'eux ou le lister comme hors du périmètre. Si l'entrée est trop vague pour être dimensionnée, posez la seule question qui débloque le dimensionnement, et rien d'autre.

2. Examiner le code

Les faits sont votre travail. Ne demandez jamais à l'utilisateur quelque chose que vous pouvez trouver dans le code, les tickets ou les outils dont vous disposez. Si vous pouvez confier l'exploration à des assistants, faites-le ; sinon, faites-le vous-même.

La profondeur dépend de la taille, donc faites d'abord un passage rapide, dimensionnez (étape 3), puis allez aussi profondément que nécessaire :

Taille	Examen
Changement, Fonctionnalité	Le code affecté en intégralité : ce qui existe pour construire, ce qui manque, comment c'est câblé aujourd'hui (points d'entrée, chemins d'appel, configuration), les tests à proximité et comment ils sont écrits
Initiative	Les zones affectées uniquement : points d'entrée et types principaux, chacun avec chemin:ligne. La lecture approfondie a lieu lorsque chaque story est planifiée
Projet	Aucun : il n'y a pas de code

Enregistrez chemin:ligne pour chaque fait sur lequel vous vous appuierez. Notez les termes du domaine que le code utilise, et tout endroit où le ticket et le code utilisent des mots différents pour la même chose. N'inférez pas le contenu inchangé à partir du statut Git ou des listes de fichiers ; relisez les fichiers affectés ou comparez une ligne de base de contenu vérifiée.

3. Dimensionner

Dimensionnez le travail avec sizing.md. Ouvrez votre réponse avec la taille et les signaux qui l'ont déterminée, puis continuez. N'attendez pas de confirmation ; l'utilisateur peut la remplacer à tout moment (« traiter comme un changement »). Un remplacement modifie le tour de question et le détail du plan, mais pas la révision ou l'approbation du plan.

Ajustement → arrêtez-vous ici. Dites en 1 à 3 lignes ce qu'il faut changer et où, et qu'aucun plan n'est nécessaire. Terminez par : « Demandez à votre agent d'apporter cette modification directement, ou dites 'corrige-le' ici pour continuer en dehors de Specshape. » Ne sauvegardez rien et n'apportez aucune modification au code source. Une demande ultérieure de correction est un travail normal d'agent en dehors de cette compétence ; elle n'a pas besoin de /specshape-build.

4. Demander

Posez les questions qui changent la forme du plan et auxquelles seul l'utilisateur peut répondre : intention, priorités, significations, compromis que le code ne peut pas résoudre.

Taille	Tours
Changement	Aucun
Fonctionnalité	Un. Un second seulement si les réponses ouvrent de nouvelles questions
Initiative, Projet	Tours jusqu'à ce qu'il ne reste rien d'indécidé

• Demandez tout ce qui peut être répondu maintenant en un seul tour. Une question qui dépend d'une réponse que vous n'avez pas encore attend la prochaine tour.
• Pour un Projet, le premier tour concerne le glossaire : ce que chaque terme central signifie et comment les termes sont liés (« Qu'est-ce qu'un Compte ? Un Utilisateur peut-il appartenir à deux ? »), avant la pile ou la forme.
• Lorsque le ticket et le code utilisent des mots différents pour la même chose, demandez lequel est correct.
• Pas de vraies questions, pas de tour. N'inventez pas de questions pour en remplir un. Pour Initiative/Projet, vérifiez si les réponses laissent des limites matérielles non résolues ; un choix de pile ou d'hébergement ne règle pas l'exposition, l'enregistrement ou la politique de transport. Posez les questions dépendantes avant de prétendre que la découverte est terminée (voir review.md).
• Les choix visibles dans le plan lui-même (nommage, quel module possède quoi) ne sont pas des questions. Ce sont des décisions dans le plan, avec votre recommandation par défaut.

Formatez chaque question comme ceci, et attendez les réponses :

❓ **Q1 - <titre>** : <la question, avec les options s'il y en a>

➡️ <votre réponse recommandée et pourquoi>

5. Rédiger le plan

Rédigez .specshape/<id>.md dans le format de plan-format.md. Ce que contient le plan dépend de la taille :

Taille	Contient
Changement	Résumé, décisions, carte des changements, une liste plate de 1 à 4 tâches
Fonctionnalité	Résumé, décisions, forme de conception avec esquisses de code, carte des changements, tâches
Initiative	Résumé, décisions, zones affectées, stories (objectif et acceptation, pas de tâches)
Projet	Résumé, décisions, forme (dossiers, modules, modèle de données, flux principal), stories ; la première story est le squelette fonctionnel

Chaque plan a aussi une section Modifications du contexte lorsqu'il ajoute ou modifie des termes du glossaire, des contrats ou des règles (voir context-format.md).

Règles :

• Preuve. Chaque affirmation concernant du code existant cite chemin:ligne. Tout ce que vous n'avez pas pu vérifier est marqué hypothèse:. Vérifiez que les citations soutiennent l'affirmation, y compris la couverture de test existante. N'inventez jamais d'historique de projet ou d'échecs passés pour justifier une recommandation.
• Grossier, pas détaillé. Les esquisses de code montrent les signatures, les types et les lignes qui portent l'idée, environ 15 lignes au maximum. Indiquez le comportement en cas d'entrée invalide aux limites publiques ; une CLI validée ne rend pas les arguments invalides inaccessibles pour les appelants directs du service. L'esquisse détaillée de chaque tâche vient dans son aperçu, juste avant sa construction.
• Décisions. Incluez les choix ayant des alternatives significatives affectant la conception ou le comportement. Traitez le travail de routine (documenter un indicateur, suivre les conventions de validation établies) directement dans la forme ou les tâches, à moins qu'il n'y ait un compromis matériel. La validation standard d'un analyseur syntaxique n'a pas besoin d'une décision simplement parce qu'une validation personnalisée est possible. Le travail de routine reste dans le périmètre : mettez à jour la documentation d'utilisation existante pour les interfaces publiques modifiées ; excluez le nettoyage non lié. Numérotez les décisions D1, D2 … sur l'ensemble du plan, stories incluses. Chacune a les options, votre recommandation et une conséquence qui importe à l'utilisateur (« la valeur par défaut est true, donc les exécutions ad-hoc avec groupBy échouent maintenant »). Statut : ouverte jusqu'à la réponse ; décidée lorsque l'utilisateur a choisi ; supposée lorsque l'utilisateur a approuvé sans choisir. « Utiliser toutes les recommandations » est un choix explicite.
• Tâches. Chaque tâche laisse la construction et les tests verts, et nomme ses fichiers, les décisions qu'elle exécute, les tâches dont elle dépend, et une vérification de fin qui exerce son comportement ajouté ou modifié. Gardez le comportement et ses tests dans la même tâche ; ne reportez jamais la vérification à une tâche ultérieure. Utilisez testing.md pour planifier les tranches rouge-vert-refactor, leurs limites de test publiques, les résultats et les commandes. Une suite verte inchangée seule ne prouve pas un nouveau comportement.
• Risques. Nommez l'échec observable et la preuve de son impact. Une citation montrant l'ordre d'exécution ne rend pas cet ordre requis ; expliquez les effets de bord pertinents si l'ordre importe.
• Stories. Chacune est livrable indépendamment comme son propre ticket et sa propre demande de fusion, avec un objectif et des critères d'acceptation. Gardez les squelettes sur le plus petit chemin de bout en bout utile, pas toutes les capacités fondamentales. Les ids de story sont <id>.<n> jusqu'à ce que des tickets existent. Ne réutilisez jamais un numéro.
• Utilisez les mots du glossaire, et aucun des mots qu'il dit de ne pas utiliser.
• Présentation. Suivez presentation.md : utilisez des tableaux pour les enregistrements comparables, des arbres de dépendance pour les stories/tâches, et Mermaid là où il explique les flux ou les relations.
• N'écrivez que ce que quelqu'un lira à nouveau. Aucune section n'est là pour la complétude ; écrivez n/a: <raison> pour celle qui ne s'applique pas plutôt que de la remplir.

Vérifiez avant de le montrer. Pour Initiative/Projet, lisez aussi review.md et révisez la cohérence entre les stories et les hypothèses. Revérifiez après les commentaires et avant l'approbation. Corrigez les échecs :

• chaque critère d'acceptation est couvert, ou listé comme hors du périmètre
• chaque fichier dans la carte des changements a une tâche, et les fichiers de chaque tâche sont dans la carte des changements
• chaque décision a des alternatives significatives, une recommandation et une conséquence
• chaque affirmation concernant du code existant a un chemin:ligne ou une étiquette hypothèse:
• chaque contrat sélectionné a une vérification, y compris les valeurs par défaut permissives ou les replis
• chaque tâche de comportement inclut ses tests, sa limite de test publique et ses vérifications rouge-vert-refactor ; chaque story a un objectif et des critères d'acceptation
• les décisions, stories/tâches, contexte et affirmations hors périmètre s'accordent sur le comportement observable
• aucun terme du glossaire, contrat ou règle dans le contexte n'est contredit
• base_commit est le HEAD actuel ; si aucun commit n'est disponible, omettez-le et expliquez pourquoi

6. Montrer et réviser

Affichez :

• toujours en intégralité : le résumé et les décisions ouvertes, car c'est ce sur quoi l'utilisateur agit
• Changement, Fonctionnalité : le corps complet du plan, y compris les esquisses de code réelles, la carte des changements, les tâches et les vérifications de fin. Un résumé, une description de la forme, ou un lien vers le fichier sauvegardé n'est pas un substitut
• Initiative, Projet : le tableau d'aperçu des stories avec les dépendances et l'arbre de dépendance, puis le chemin vers le fichier de plan pour le reste
• Révision de story planifiée : son résumé, son acceptation, ses décisions ouvertes, sa forme, sa carte des changements complète, ses tableaux de tâches et son arbre de dépendance. Montrez les fichiers, la limite, les résultats et la commande de vérification de chaque tâche ; une commande de suite partagée ou une liste de tâches en prose n'est pas un substitut

Terminez par ce dont vous avez besoin de la part de l'utilisateur :

Choisissez D1a ou D1b, donnez votre avis, ou dites approuvé.

Utilisez les identifiants réels des décisions ouvertes ; s'il n'y en a pas, demandez seulement un avis ou une approbation.

Sur avis :

• révisez le plan, augmentez la version et remplacez la ligne Modifié depuis par ce qui a changé
• marquez les décisions répondues comme décidée
• lorsque l'utilisateur énonce une préférence durable (« ne jamais mettre de numéros de version dans les noms de classes ») ou une vérité à l'échelle du projet, ajoutez-la à Modifications du contexte ; elle est appliquée à l'approbation

7. À l'approbation

1. Enregistrez les choix explicites comme décidée et les recommandations non choisies comme supposée. Revérifiez la cohérence du plan, puis définissez status: approved et approved: <date>, et rafraîchissez base_commit si un commit existe. Augmentez la version lorsque les choix modifient le contenu du plan.
2. Appliquez les modifications du contexte à .specshape/context.md, en le créant si nécessaire. Si le dépôt a déjà un glossaire, liez-y et ajoutez uniquement ce qui manque ; utilisez le glossaire canonique du parent lors de la planification d'une story. Ne planifiez pas non plus de définitions en double dans la documentation du projet. Vide ensuite la section Modifications du contexte du plan.
3. Initiative ou Projet : proposez les tickets. Listez les tickets que vous allez créer : un par story, comme enfants du ticket d'entrée (l'epic), ou sous un nouvel epic pour un projet. Chacun contient le titre, l'objectif, les critères d'acceptation et un lien vers le plan, pas les tâches. Créez-les seulement après le oui de l'utilisateur, en utilisant l'accès au suivi dont vous disposez. Remplacez chaque id de story locale par sa clé de ticket dans le plan. Vérifiez les intégrations de suivi disponibles et la source du ticket d'entrée ; l'absence de dépôts distants Git ne prouve pas l'absence d'accès au suivi. Si l'accès est indisponible, dites-le et conservez les ids locales. Si seule la destination est inconnue, demandez quel suivi/projet utiliser.
4. Premier plan dans ce dépôt : proposez d'ajouter une ligne à AGENTS.md, et ajoutez-la seulement après un oui : « Lisez .specshape/context.md s'il existe avant de travailler sur ce code. Les plans se trouvent dans .specshape/. » Ajoutez « Pour le travail planifié, utilisez /specshape-build. » seulement si cette compétence est disponible. Utilisez la même constatation de disponibilité pour cette offre et l'étape suivante ; vérifiez la ligne proposée avant de la montrer.
5. Dites ce qui vient ensuite :
   • Changement ou Fonctionnalité : /specshape-build <id> T1 si cette compétence est disponible. Sinon, dites que le plan est prêt pour l'implémentation mais que /specshape-build est indisponible. Arrêtez-vous sans écrire de code.
   • Initiative ou Projet : /specshape-plan <premier id de story>. Avant de suggérer une autre story, vérifiez ses prérequis ; s'ils ne sont pas construits, expliquez que planifier à l'avance reposera sur des hypothèses et devra être revalidé par rapport aux interfaces implémentées avant la construction Gardez la passation fidèle aux définitions de tâches sauvegardées et aux vérifications de fin. N'ajoutez pas de nouvelles vérifications manuelles ou d'exigences ; révisez et examinez d'abord le plan si une autre vérification est nécessaire.

Planification d'une story

Entrée : un id de story d'un plan approuvé.

1. Si le plan parent n'est pas approuvé, dites-le et arrêtez-vous.
2. Lisez les dépendances de la story et examinez son code affecté en intégralité, tel qu'il est actuellement. Si le code prérequis est absent, étiquetez les interfaces supposées et nommez ce qui doit être revalidé avant la construction. Pour un squelette fonctionnel d'un projet, ancrez-le dans les décisions et la forme du parent. N'inférez pas le code inchangé à partir du statut ou des listes de fichiers. Appliquez review.md aux nouveaux choix de limites.
3. Demandez, si la story soulève des questions auxquelles seul l'utilisateur peut répondre (règles de Fonctionnalité).
4. Remplissez la section de la story avec la forme, la carte des changements complète, les tâches, les décisions (y compris toutes les décisions du plan parent qui s'appliquent). Tous les ids de tâches sont préfixés par l'id de la story (par exemple <parent>.<n>.T1). Les tâches sont routinières ou affectées.
5. Vérifiez (cases à cocher de l'étape 5 à nouveau, appliquées à cette seule story).
6. Montrez, révisez, approbation et retournez le contrôle à l'étape 7, sauf pour les étapes suivantes :
   • pas de tickets de suivi (le parent les a déjà gérés, sauf si une story doit être un enfant direct du ticket parent plutôt qu'un enfant de l'epic ; demandez à l'utilisateur)
   • pas d'offre de ligne AGENTS.md
   • le prochain point d'action propose la story suivante dans l'ordre de dépendance (ou la construction si c'est la dernière)

Règles générales

• Interdiction d'écrire du code. Cette compétence planifie. L'implémentation est faite par /specshape-build (ou un autre agent). Ne créez, ne modifiez et ne supprimez aucun fichier source, test, configuration ou script. Les seules modifications autorisées sont : les fichiers sous .specshape/ (plan et contexte), et, après approbation explicite de l'utilisateur, les tickets de suivi et une ligne dans AGENTS.md.
• Version. Chaque plan a un numéro de version entier. Augmentez-le à chaque révision qui modifie son contenu de manière substantielle. Le Changed since (ou Modifié depuis) liste ce qui a changé entre la version précédente et la version actuelle.
• Périmètre. Le plan couvre le périmètre tel que convenu avec l'utilisateur. Les fonctionnalités, cas ou modifications qui sont explicitement exclus sont listés dans une section « Hors périmètre ».
• Fin du plan. Lorsqu'un plan est approuvé et que le prochain point d'action est donné, la compétence est terminée. Si l'utilisateur demande une modification ou une extension après approbation, cela déclenche soit une révision du plan, soit un nouveau plan (selon l'ampleur).
• Débogage et résolution de problèmes. Cette compétence ne dépanne pas et ne résout pas les problèmes. Si l'utilisateur présente un bogue ou un problème, dirigez-le vers /specshape-diagnose (ou équivalent).