bmad-gitlab : le sprint BMAD dans GitLab, sans que l'outil écrive à votre place
💻 Code source (MIT) : github.com/patlegu/bmad-gitlab
BMAD en bref
Le projet BMAD se décrit ainsi : « Agile AI Driven Development : transformer une idée ou une demande de changement en logiciel qui fonctionne, sans renoncer à la réflexion » (ma traduction). Son constat de départ est que les assistants de code sont efficaces pour l’implémentation, mais transforment souvent des hypothèses non dites en code. BMAD cherche à garder la main à l’humain : ses agents et ses workflows (produit, architecture, UX, développement, test) rendent les décisions importantes explicites, puis les conservent comme contexte pour la suite du travail, avec un processus qui s’ajuste à la taille du changement.
D’où vient le besoin
Ce contexte est conservé dans des fichiers du dépôt, et pour le suivi d’un sprint il y en a deux. epics.md
contient les épiques et leurs stories, avec leur texte et leurs critères d’acceptation. sprint-status.yaml dit où en
est chacune :
project: orbit
development_status:
epic-1: in-progress
1-1-plan-a-café-stop: done
1-2-list-the-planets: review
1-3-show-one-planet: backlog
Une story passe de backlog à ready-for-dev, in-progress, review puis done ; son épique passe à
in-progress dès que la première démarre. Ce sont les agents de BMAD (le développeur, le relecteur) qui mettent
le fichier à jour au fil du travail, et c’est ce qui rend la méthode reproductible : tout l’état du sprint est dans
le dépôt, versionné avec le code.
Le revers, c’est que personne d’autre que l’agent ne regarde ce YAML. Dans une équipe, celui qui veut savoir où en est le sprint ouvre le tracker : un tableau, des filtres, des notifications, des tickets que l’on référence depuis une merge request. Si ce tracker n’est pas alimenté, deux situations se présentent : il reste vide et personne ne s’en sert, ou quelqu’un recopie les statuts à la main et les deux sources divergent dès la première semaine.
bmad-gitlab règle ce point précis : il fait apparaître le sprint dans GitLab, avec un ticket par épique et par
story, le statut en label, et un tableau.
Ce que je demandais à l’outil
Avant d’écrire du code, j’ai fixé six contraintes. Elles expliquent la plupart des choix qui suivent.
- Les fichiers restent la référence. GitLab est une vue : on n’écrit rien dans
sprint-status.yaml, que BMAD régénère de toute façon, et rien de ce qui est fait dans GitLab ne remonte vers les fichiers. - Un ticket par story, retrouvé de façon sûre. On doit pouvoir renommer une story, corriger sa description, et retomber sur le même ticket, sans dépendre de son titre.
- Rejouable à volonté. Lancer la commande dix fois de suite ne doit créer ni doublon ni changement inutile.
- Rien n’est écrit avant que l’utilisateur ait vu le plan.
- Fonctionner sur GitLab gratuit. Pas d’épiques GitLab, pas de labels exclusifs, pas d’itérations : tout cela est réservé aux offres payantes. Il reste des labels, un tableau et des tickets, c’est suffisant.
- Ne gérer aucun secret. L’authentification reste celle de la CLI
glab, déjà connectée par l’utilisateur.
Pourquoi un moteur et pas un agent
La tentation est de dire à l’agent : « crée les tickets GitLab à partir de ces fichiers ». Cela marche une fois, puis on bute sur trois choses.
- Ce n’est pas rejouable. Pour savoir si un ticket existe déjà, l’agent doit le reconnaître, et il n’a pour cela que le titre, qu’il peut avoir reformulé la fois précédente. Au deuxième passage, il crée un doublon ou en saute un.
- Ce n’est pas testable. On ne peut pas vérifier le comportement d’un modèle sur les cas limites (un titre avec des accents, deux sprints qui réutilisent les mêmes numéros, un fichier mal formé) comme on le fait pour une fonction.
- Un échec peut passer pour un succès. Si la lecture de la liste des tickets s’interrompt à mi-chemin, un agent peut conclure qu’il n’y a rien à faire. Un programme, lui, doit s’arrêter avec une erreur.
Le module est donc coupé en deux. Le moteur, en Python, lit les fichiers, interroge GitLab, calcule un plan, puis l’exécute : c’est du code déterministe et testé. Le skill BMAD qui l’enveloppe est très mince : il dit à l’agent quand lancer le moteur, lui fait résumer le plan en quelques lignes, et lui impose de demander l’accord de l’utilisateur avant d’écrire. L’agent ne décide jamais de ce qu’il faut créer ou modifier ; il fait ce qu’un modèle fait bien, parler à la personne, et rien de plus.
flowchart LR
A[sprint-status.yaml<br/>epics.md] --> B[moteur : lecture<br/>et plan]
G[(GitLab<br/>via glab api)] --> B
B --> C{--apply ?}
C -- non --> D[plan affiché,<br/>rien n'est écrit]
C -- oui --> E[labels, tickets,<br/>tableau]
E --> G
Ce que ça donne
Sur un sprint d’essai inventé (sept épiques, vingt-quatre stories), un premier passage à blanc affiche ceci :
sprint orbit
+ label type:epic #6B5CE7
+ label status:backlog #95A5A6
+ label prd:orbit #6C757D
+ label epic:orbit:1 #428BCA
…
+ issue "Epic 1: Planets and catalogue" [type:epic status:backlog prd:orbit epic:orbit:1]
+ issue "Story 1.1: Plan a café stop" [type:story status:backlog prd:orbit epic:orbit:1]
+ issue "Story 1.2: List the planets" [type:story status:backlog prd:orbit epic:orbit:1]
…
11 labels to create, 31 issues to create, 0 issues to update, 0 warnings
Avec --apply, il crée tout. Un second passage répond :
sprint orbit
nothing to do
C’est le test qui compte. Pour que « rejouer » ne change rien, chaque ticket porte à la fin de sa description un marqueur caché :
<!-- bmad:v1 sprint=orbit key=1-1-plan-a-café-stop hash=3f9a… -->
Il dit à quelle clé BMAD le ticket correspond et donne l’empreinte (douze caractères d’un SHA-256) du titre et du
texte d’origine. Rien n’est stocké dans sprint-status.yaml, que BMAD régénère. Si la story change dans
epics.md, l’empreinte diffère et le ticket est mis à jour. Si son statut passe à done, le label status:
change et le ticket est fermé ; s’il revient en arrière, il est rouvert.
Les statuts sont des labels
Faute d’épiques GitLab, les épiques sont des tickets comme les autres, et tout passe par des labels simples :
type:epic ou type:story, status:in-progress, prd:<sprint> et epic:<sprint>:N, ce dernier pour regrouper
les stories d’un épique. Le tableau a une colonne par statut.
Un point mérite d’être dit : l’outil ajoute et retire des labels au lieu de les remplacer, et il ne retire que les
cinq status: qu’il écrit lui-même. Un label status:blocked ajouté à la main par quelqu’un reste en place. C’est un
défaut que l’audit a trouvé : la première version retirait tout label commençant par status:.
L’installer et s’en servir
Le module s’installe comme n’importe quel module BMAD personnalisé :
$ npx bmad-method install --directory . \
--custom-source https://github.com/patlegu/bmad-gitlab --tools claude-code
Il pose les questions utiles (projet GitLab, hôte, autorisation d’appliquer sans demander) et installe le skill
bmad-gitlab, qui embarque le moteur. Il faut disposer de uv et de la CLI
GitLab glab connectée à votre GitLab : l’authentification reste dans glab,
l’outil ne stocke aucun jeton.
Trois intentions :
- sync : planifier, montrer le plan, demander, puis appliquer ;
- status : dire ce qui diffère entre les fichiers et GitLab, sans rien écrire ;
- setup : configurer le projet, les sprints supplémentaires, les préfixes de titre et le hook.
Le hook est l’instruction on_complete du skill bmad-sprint-planning : à la fin de la planification, le plan est
montré. Rien n’est écrit dans GitLab sans votre accord, sauf si vous avez mis auto_apply à vrai, ce qui n’est pas
le cas par défaut.
Le moteur se lance aussi sans BMAD :
$ bmad-gitlab sync --project groupe/projet \
--sprint sprint-status.yaml epics.md # essai à blanc
$ bmad-gitlab sync --project groupe/projet \
--sprint sprint-status.yaml epics.md --apply # écrit
Ce qu’il refuse de faire
Le moteur est conçu pour échouer plutôt que pour deviner :
- une recherche qui échoue est une erreur, jamais « rien à faire » ; un état de ticket inconnu est une erreur ;
- si les fichiers se contredisent (une clé sans section dans
epics.md, une section sans clé, deux clés pour la même story), il le dit et refuse d’appliquer tant qu’on ne passe pas--allow-problems; - une liste GitLab est lue page par page, avec un plafond, et chaque identifiant lu est vérifié ;
- les nombres des clés sont strictement des chiffres, un épique numéroté 0 est refusé ;
- des codes de sortie distincts : 0, 2 (fichiers ou arguments), 3 (problèmes avec
--apply), 4 (erreur GitLab).
Il sait aussi traiter deux sprints dans un même projet, même s’ils réutilisent les mêmes numéros : le nom du
sprint figure dans les labels et dans le marqueur, et --prefix 'sprint-2=[extras]' met un préfixe devant les
titres. Un nom de projet BMAD avec des espaces (My project) devient un nom de sprint sans espaces
(My-project) : c’est la seule règle de renommage, l’outil le signale, et il refuse deux projets qui
donneraient le même nom.
Ce qu’il ne fait pas
- Un seul sens. GitLab ne réécrit pas les fichiers BMAD. Si quelqu’un déplace un ticket dans le tableau, le prochain passage le remet dans l’état des fichiers.
- Les rétrospectives ne sont pas reflétées.
- Un ticket dont la clé n’existe plus dans le sprint est signalé, pas supprimé.
- Pas de jalons, d’assignations ni de liens vers les merge requests.
- GitLab seulement, via
glab. - Ce que je n’ai pas mesuré : si GitLab compare les noms de labels sans tenir compte de la casse (le moteur, lui, la respecte). Il me faudrait un projet GitLab pour l’établir.
Trois défauts que des fichiers d’exemple ne montraient pas
Les deux premiers sont apparus aux premiers essais sur un projet réel, le troisième à l’audit. Aucun n’était visible avec les fichiers d’exemple du départ.
- La disposition par défaut de BMAD. L’outil lisait
## Épique Nsuivi de### Story N.M. BMAD, lui, écrit d’abord une « Epic List », puis une partie « Epic Details » où les épiques sont au niveau 3 et les stories au niveau 4. Le moteur ne trouvait aucune section. Il lit maintenant les deux dispositions. - Le nom du projet.
project_namepeut contenir des espaces. Or le nom du sprint est écrit dans le marqueur caché, qui se termine au premier espace, et dans une liste de labels séparée par des virgules. Le marqueur était coupé, donc le ticket jamais retrouvé, donc recréé à chaque passage. D’où la règle de renommage plus haut. - Les blocs de code. Un
### Storyqui apparaît dans un exemple, à l’intérieur d’un bloc de code, n’est pas une story. Le moteur ignorait déjà les blocs de trois apostrophes inversées ; il suit maintenant les règles de CommonMark (longueur de la clôture, texte après l’ouverture), parce qu’une clôture de quatre apostrophes contenant une ligne de trois faisait apparaître une fausse story et avalait la vraie.
La qualité, mesurée, et ce que le score veut dire
La suite compte 435 tests pour une couverture de 99 % des branches, un typage strict, et des limites de
complexité imposées par le linter. J’ai surtout regardé les mutations : on casse volontairement une ligne du
code (un séparateur, une comparaison, un en-tête) et on exige qu’un test devienne rouge. Plusieurs fois, un test
vert ne prouvait rien : une assertion "1 issues to create" in ligne est aussi satisfaite par
"-1 issues to create", et un test censé vérifier la coupe d’un message d’erreur n’atteignait jamais la
fonction de coupe.
Le code a passé quatre audits successifs, chacun reproduisant ses constats avant de les consigner :
| Version | Indice de qualité (sur 10) | Ce que l’audit a trouvé |
|---|---|---|
| 0.1.1 | 8,3 | le marqueur et le nom de sprint, glab absent |
| 0.1.3 | 8,4 | épique 0, réponses GitLab mal typées, configuration illisible |
| 0.1.4 | 8,5 | labels status: d’autrui supprimés, clés en double, écriture non atomique |
| 0.1.5 | 8,6 | analyseur de blocs de code, décompte des fermetures, lien symbolique remplacé |
Un des défauts de la dernière ligne vient de mon propre correctif : en rendant l’écriture de la configuration atomique (fichier temporaire puis renommage), j’avais fait remplacer un lien symbolique par un fichier ordinaire. Un correctif a ses propres défauts, et c’est la raison pour laquelle on rejoue l’audit.
Je ne vends pas un « 9 » : le score est celui que j’exigeais, et il n’est pas atteint. Il monte de 0,1 à chaque
tour, ce qui est inférieur à l’écart habituel entre deux audits du même code (0,3 à 0,5), donc ces quatre chiffres
ne sont pas quatre niveaux distincts. Les défauts reproduits, eux, sont des faits. Les rapports sont dans
docs/audits/, avec ce qui reste ouvert.
En pratique
Si votre sprint BMAD vit déjà dans des fichiers et que votre équipe vit dans GitLab, le module vous évite de recopier le statut à la main, sans vous retirer la main sur ce qui est écrit. Le premier passage reste un essai à blanc : lisez le plan, puis appliquez.
Le dépôt est sous licence MIT. Les retours, les cas d’epics.md qui ne passent pas et les différences de comportement
d’un GitLab auto-hébergé m’intéressent : ouvrez un ticket sur
github.com/patlegu/bmad-gitlab.
À faire
Ce qui suit est une liste de travail, pas une promesse de calendrier. Les trois premiers points sont ceux que je compte traiter ; les suivants sont des idées que je n’ai pas encore tranchées.
- Passer sous BMAD v7. Le module est fait pour la version 6.12. La v7 est en préversion et change l’installation et la forme des skills : il faudra adapter le packaging, et probablement le hook de fin de planification.
- Atteindre 9 à l’audit. Il reste les points ouverts consignés dans
docs/audits/: une règle de préfixe écrite à deux endroits, unmodel.pyqui fait trois choses, un paramètre de sortie à remplacer par un retour. Tant que le score n’y est pas, la dérogation de CI de mon dépôt privé reste en place. - Mesurer la casse des noms de labels sur un GitLab réel, puisque le moteur et GitLab pourraient ne pas la traiter de la même façon.
- Les tickets orphelins. Aujourd’hui une clé qui disparaît du sprint est seulement signalée. Proposer de la fermer, avec accord explicite, éviterait de les laisser traîner.
- Les rétrospectives et leurs actions.
sprint-status.yamlporte des rétrospectives et une liste d’actions que le moteur ne lit pas encore. - Le sens inverse. Permettre que GitLab devienne la référence quand plusieurs personnes travaillent sur le même sprint en parallèle. C’est la plus grosse évolution : elle change la règle « les fichiers font foi » et demande de décider comment trancher un conflit entre un fichier et un ticket.
- Voir ce que GitLab apporte à hephaistos. hephaistos est mon moteur de workflow d’agents (non publié) : chaque story y devient une « carte » que des agents réclament, produisent et déposent, le moteur gardant l’état dans des fichiers versionnés. À étudier : projeter l’état des cartes en tickets, en lecture seule, avec un label pour l’état « en attente d’arbitrage » et un lien vers la branche et la merge request. Cela donnerait un tableau et des notifications sans rien construire. Cela ne simplifierait pas la réclamation d’une carte (bail, numéro d’époque, battement de cœur), qui demande une écriture atomique qu’une API de tickets n’offre pas ; et un projet confidentiel ne peut pas envoyer son contenu à un GitLab externe.
- Au-delà de GitLab. GitHub Issues demanderait une autre couche d’accès, le moteur de planification restant le même. Je n’en ai pas le besoin pour l’instant.
