Compare commits
8 Commits
33f72d73ee
...
62804795ef
| Author | SHA1 | Date |
|---|---|---|
Emmanuel Atsé
|
62804795ef | |
Emmanuel Atsé
|
2d2b6b83a3 | |
|
Emmanuel Atsé
|
30f1339671 | |
|
Emmanuel Atsé
|
b319db4046 | |
|
Emmanuel Atsé
|
e50c73f1b2 | |
|
Emmanuel Atsé
|
189c2b85eb | |
Rayan Salhab
|
f28d04a92a | |
Brian
|
aa6dece05d |
|
|
@ -20,7 +20,7 @@
|
|||
"skills": [
|
||||
"./src/core-skills/bmad-help",
|
||||
"./src/core-skills/bmad-brainstorming",
|
||||
"./src/core-skills/bmad-distillator",
|
||||
"./src/core-skills/bmad-spec",
|
||||
"./src/core-skills/bmad-party-mode",
|
||||
"./src/core-skills/bmad-shard-doc",
|
||||
"./src/core-skills/bmad-advanced-elicitation",
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Spusťte jakýkoli základní nástroj zadáním jeho názvu skillu (např. `bma
|
|||
| [`bmad-help`](#bmad-help) | Task | Kontextové poradenství, co dělat dál |
|
||||
| [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Facilitace interaktivních brainstormingových sezení |
|
||||
| [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrace skupinových diskuzí více agentů |
|
||||
| [`bmad-distillator`](#bmad-distillator) | Task | Bezeztrátová LLM-optimalizovaná komprese dokumentů |
|
||||
| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work (translation pending) |
|
||||
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | Iterativní zdokonalování LLM výstupu |
|
||||
| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | Cynická revize hledající chybějící a chybné |
|
||||
| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | Vyčerpávající analýza větvících cest pro neošetřené hraniční případy |
|
||||
|
|
@ -97,32 +97,6 @@ Kouzlo se děje v nápadech 50–100. Workflow povzbuzuje generování 100+ náp
|
|||
|
||||
**Výstup:** Real-time multi-agentní konverzace s udržovanými osobnostmi agentů
|
||||
|
||||
## bmad-distillator
|
||||
|
||||
**Bezeztrátová LLM-optimalizovaná komprese zdrojových dokumentů.** — Produkuje husté, tokenově efektivní destiláty, které zachovávají všechny informace pro následné LLM zpracování. Ověřitelné prostřednictvím round-trip rekonstrukce.
|
||||
|
||||
**Použijte když:**
|
||||
|
||||
- Dokument je příliš velký pro kontextové okno LLM
|
||||
- Potřebujete tokenově efektivní verze výzkumů, specifikací nebo plánovacích artefaktů
|
||||
- Chcete ověřit, že během komprese nebyly ztraceny žádné informace
|
||||
|
||||
**Jak to funguje:**
|
||||
|
||||
1. **Analýza** — Čte zdrojové dokumenty, identifikuje hustotu informací a strukturu
|
||||
2. **Komprese** — Převádí prózu na hustý odrážkový formát, odstraňuje dekorativní formátování
|
||||
3. **Ověření** — Kontroluje úplnost pro zajištění zachování všech informací
|
||||
4. **Validace** (volitelné) — Round-trip rekonstrukční test dokazuje bezeztrátovou kompresi
|
||||
|
||||
**Vstup:**
|
||||
|
||||
- `source_documents` (povinné) — Cesty k souborům, složkám nebo glob vzory
|
||||
- `downstream_consumer` (volitelné) — Co to konzumuje (např. „tvorba PRD“)
|
||||
- `token_budget` (volitelné) — Přibližná cílová velikost
|
||||
- `--validate` (příznak) — Spuštění round-trip rekonstrukčního testu
|
||||
|
||||
**Výstup:** Destilátové markdown soubory s reportem kompresního poměru (např. „3.2:1“)
|
||||
|
||||
## bmad-advanced-elicitation
|
||||
|
||||
**Iterativní zdokonalování LLM výstupu metodami elicitace.** — Vybírá z knihovny elicitačních technik pro systematické zlepšování obsahu více průchody.
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ BMad ships six named agents, each anchored to a phase of the BMad Method:
|
|||
| 📋 **John**, Product Manager | Planning | PRD creation, epic/story breakdown, implementation readiness |
|
||||
| 🎨 **Sally**, UX Designer | Planning | UX design specifications |
|
||||
| 🏗️ **Winston**, System Architect | Solutioning | technical architecture, alignment checks |
|
||||
| 💻 **Amelia**, Senior Engineer | Implementation | story execution, quick-dev, code review, sprint planning |
|
||||
| 💻 **Amelia**, Senior Engineer | Implementation | story execution, quick-dev, code review, sprint planning, [forensic investigation](./forensic-investigation.md) |
|
||||
|
||||
They each have a hardcoded identity (name, title, domain) and a customizable layer (role, principles, communication style, icon, menu). You can rewrite Mary's principles or add menu items; you can't rename her — that's deliberate. Brand recognition survives customization so "hey Mary" always activates the analyst, regardless of how a team has shaped her behavior.
|
||||
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ Avertissements critiques uniquement — perte de données, problèmes de sécuri
|
|||
|
||||
## Formats de tableau standards
|
||||
|
||||
**Phases :**
|
||||
**Phases :**
|
||||
|
||||
```md
|
||||
| Phase | Nom | Ce qui se passe |
|
||||
|
|
@ -59,7 +59,7 @@ Avertissements critiques uniquement — perte de données, problèmes de sécuri
|
|||
| 2 | Planification | Exigences — PRD ou spécification technique *(requis)* |
|
||||
```
|
||||
|
||||
**Skills :**
|
||||
**Skills :**
|
||||
|
||||
```md
|
||||
| Skill | Agent | Objectif |
|
||||
|
|
@ -243,7 +243,7 @@ votre-projet/
|
|||
1. Titre + Accroche
|
||||
2. Éléments (## pour chaque élément)
|
||||
- Brève description (une phrase)
|
||||
- **Skills :** ou **Infos clés :** sous forme de liste simple
|
||||
- **Skills :** ou **Infos clés :** sous forme de liste simple
|
||||
3. Universel/Partagé (## section) (optionnel)
|
||||
```
|
||||
|
||||
|
|
@ -304,9 +304,9 @@ Starlight génère la navigation « Sur cette page » à droite à partir de
|
|||
### Format de tableau
|
||||
|
||||
|
||||
```md
|
||||
## Nom de catégorie
|
||||
|
||||
```md
|
||||
| Terme | Définition |
|
||||
|--------------|------------------------------------------------------------------------------------------------------------|
|
||||
| **Agent** | Personnalité IA spécialisée avec une expertise spécifique qui guide les utilisateurs dans les workflows. |
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Une technique de revue où le réviseur *doit* trouver des problèmes. Pas de «
|
|||
|
||||
Il ne s’agit pas d’être négatif. Il s’agit de forcer une analyse authentique au lieu d’un coup d’œil superficiel qui valide automatiquement ce qui a été soumis.
|
||||
|
||||
**La règle fondamentale :** Il doit trouver des problèmes. Zéro constatation déclenche un arrêt - réanalyse ou explique pourquoi.
|
||||
**La règle fondamentale :** Il doit trouver des problèmes. Zéro constatation déclenche un arrêt - réanalyse ou explique pourquoi.
|
||||
|
||||
## Pourquoi Cela Fonctionne
|
||||
|
||||
|
|
@ -30,7 +30,7 @@ La revue contradictoire apparaît dans tous les workflows BMad - revue de code,
|
|||
|
||||
## Filtrage Humain Requis
|
||||
|
||||
Parce que l’IA est *instruite* de trouver des problèmes, elle trouvera des problèmes - même lorsqu’ils n’existent pas. Attendez-vous à des faux positifs : des détails présentés comme des problèmes, des malentendus sur l’intention, ou des préoccupations purement hallucinées[^3].
|
||||
Parce que l’IA est *instruite* de trouver des problèmes, elle trouvera des problèmes - même lorsqu’ils n’existent pas. Attendez-vous à des faux positifs : des détails présentés comme des problèmes, des malentendus sur l’intention, ou des préoccupations purement hallucinées[^3].
|
||||
|
||||
**C’est vous qui décidez ce qui est réel.** Examinez chaque constatation, ignorez le bruit, corrigez ce qui compte.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ Libérez votre créativité grâce à une exploration guidée.
|
|||
|
||||
Lancez `bmad-brainstorming` et vous obtenez un facilitateur créatif qui fait émerger vos idées - pas qui les génère pour vous. L’IA agit comme coach et guide, utilisant des techniques éprouvées pour créer les conditions où votre meilleure réflexion émerge.
|
||||
|
||||
**Idéal pour :**
|
||||
**Idéal pour :**
|
||||
|
||||
- Surmonter les blocages créatifs
|
||||
- Générer des idées de produits ou de fonctionnalités
|
||||
|
|
|
|||
|
|
@ -31,12 +31,12 @@ BMad embarque six agents nommés, chacun ancré à une phase de la méthode BMad
|
|||
|
||||
| Agent | Phase | Module |
|
||||
|------------------------------------|----------------|-------------------------------------------------------------------------------------------------------------------------|
|
||||
| 📊 **Mary**, Analyste d’affaires | Analyse | étude de marché, brainstorming, product briefs, PRFAQs |
|
||||
| 📚 **Paige**, Rédactrice technique | Analyse | documentation de projet, diagrammes, validation de docs |
|
||||
| 📋 **John**, Chef de produit | Planification | création de PRD, décomposition epic/story, vérification de la préparation à l’implémentation |
|
||||
| 🎨 **Sally**, Designer UX | Planification | spécifications de design UX |
|
||||
| 🏗️ **Winston**, Architecte système | Solutioning | architecture technique, vérifications d’alignement |
|
||||
| 💻 **Amelia**, Ingénieure senior | Implémentation | exécution de stories, quick-dev, revue de code, planification de sprint, [enquête de code](./forensic-investigation.md) |
|
||||
| 📊 **Mary**, Analyste d’affaires | Analyse | étude de marché, brainstorming, product briefs, PRFAQs |
|
||||
| 📚 **Paige**, Rédactrice technique | Analyse | documentation de projet, diagrammes, validation de docs |
|
||||
| 📋 **John**, Chef de produit | Planification | création de PRD, décomposition epic/story, vérification de la préparation à l’implémentation |
|
||||
| 🎨 **Sally**, Designer UX | Planification | spécifications de design UX |
|
||||
| 🏗️ **Winston**, Architecte système | Solutioning | architecture technique, vérifications d’alignement |
|
||||
| 💻 **Amelia**, Ingénieure senior | Implémentation | exécution de stories, quick-dev, revue de code, planification de sprint, [enquête de code](./forensic-investigation.md) |
|
||||
|
||||
Chacun possède une identité codée en dur (nom, titre, domaine) et une couche personnalisable (rôle, principes, style de communication, icône, menu). Vous pouvez réécrire les principes de Mary ou ajouter des éléments de menu ; vous ne pouvez pas la renommer — c’est délibéré. La reconnaissance de marque persiste après personnalisation pour que « hey Mary » active toujours l’analyste, indépendamment de la façon dont une équipe a façonné son comportement.
|
||||
|
||||
|
|
|
|||
|
|
@ -24,35 +24,35 @@ La conversation continue aussi longtemps que vous le souhaitez. Posez des questi
|
|||
|
||||
### Remettre en question une mauvaise architecture
|
||||
|
||||
**Vous :** « Ok l’équipe, notre dernier sprint a été un désastre. Le service d’authentification est tombé trois fois. Qui a cafouillé ? »
|
||||
**Vous :** « Ok l’équipe, notre dernier sprint a été un désastre. Le service d’authentification est tombé trois fois. Qui a cafouillé ? »
|
||||
|
||||
**Architecte :** « Le design était solide - authentification distribuée avec des fallbacks appropriés. Si l’implémentation a dévié des specs... »
|
||||
**Architecte :** « Le design était solide - authentification distribuée avec des fallbacks appropriés. Si l’implémentation a dévié des specs... »
|
||||
|
||||
**Développeur :** « J’ai suivi le document d’architecture à la lettre. Les specs ne prenaient pas en compte les race conditions lors de l’invalidation de sessions concurrentes. »
|
||||
**Développeur :** « J’ai suivi le document d’architecture à la lettre. Les specs ne prenaient pas en compte les race conditions lors de l’invalidation de sessions concurrentes. »
|
||||
|
||||
**PM :** « Vous avez tous les deux raté le vrai problème - nous n’avons pas validé les exigences de gestion des sessions dans le PRD. C’est de ma faute de ne pas l’avoir repéré. »
|
||||
**PM :** « Vous avez tous les deux raté le vrai problème - nous n’avons pas validé les exigences de gestion des sessions dans le PRD. C’est de ma faute de ne pas l’avoir repéré. »
|
||||
|
||||
**TEA :** « Et j’aurais dû le repérer dans les tests d’intégration. Les scénarios de test ne couvraient pas l’invalidation concurrente. »
|
||||
**TEA :** « Et j’aurais dû le repérer dans les tests d’intégration. Les scénarios de test ne couvraient pas l’invalidation concurrente. »
|
||||
|
||||
### Brainstorming créatif
|
||||
|
||||
**Vous :** « Comment rendre l’onboarding magique au lieu d’ennuyeux ? »
|
||||
**Vous :** « Comment rendre l’onboarding magique au lieu d’ennuyeux ? »
|
||||
|
||||
**Designer UX :** « Commençons par la divulgation progressive - révélons les fonctionnalités au fur et à mesure que les utilisateurs en ont besoin, pas d’un coup dans un tutoriel. »
|
||||
**Designer UX :** « Commençons par la divulgation progressive - révélons les fonctionnalités au fur et à mesure que les utilisateurs en ont besoin, pas d’un coup dans un tutoriel. »
|
||||
|
||||
**Storyteller :** « Et si l’onboarding était une histoire ? Chaque étape révèle le parcours d’un personnage - l’utilisateur EST le héros. »
|
||||
**Storyteller :** « Et si l’onboarding était une histoire ? Chaque étape révèle le parcours d’un personnage - l’utilisateur EST le héros. »
|
||||
|
||||
**Game Designer :** « En partant de là - et si la première « quête » consistait à résoudre un vrai problème utilisateur ? Ils apprennent en faisant quelque chose d’utile. »
|
||||
**Game Designer :** « En partant de là - et si la première « quête » consistait à résoudre un vrai problème utilisateur ? Ils apprennent en faisant quelque chose d’utile. »
|
||||
|
||||
### Décision technique
|
||||
|
||||
**Vous :** « Monolithe ou microservices pour le MVP[^1] ? »
|
||||
**Vous :** « Monolithe ou microservices pour le MVP[^1] ? »
|
||||
|
||||
**Architecte :** « Commencez en monolithe. Les microservices ajoutent une complexité dont vous n’avez pas besoin à 1 000 utilisateurs. »
|
||||
**Architecte :** « Commencez en monolithe. Les microservices ajoutent une complexité dont vous n’avez pas besoin à 1 000 utilisateurs. »
|
||||
|
||||
**PM :** « D’accord. Le time-to-market[^2] compte plus que la scalabilité théorique. »
|
||||
**PM :** « D’accord. Le time-to-market[^2] compte plus que la scalabilité théorique. »
|
||||
|
||||
**Développeur :** « Monolithe avec des frontières de modules claires. On pourra extraire des services plus tard si nécessaire. »
|
||||
**Développeur :** « Monolithe avec des frontières de modules claires. On pourra extraire des services plus tard si nécessaire. »
|
||||
|
||||
:::tip[Meilleures décisions]
|
||||
De meilleures décisions grâce à des perspectives diverses. Bienvenue dans le party mode.
|
||||
|
|
|
|||
|
|
@ -14,10 +14,10 @@ Lorsque plusieurs agents IA implémentent différentes parties d’un système,
|
|||
Sans architecture :
|
||||
- L’agent A utilise REST avec `/users/{id}`
|
||||
- L’agent B utilise des mutations GraphQL
|
||||
- Résultat : Patterns d’API incohérents, consommateurs confus
|
||||
- Résultat : Patterns d’API incohérents, consommateurs confus
|
||||
|
||||
Avec architecture :
|
||||
- L’ADR[^1] spécifie : « Utiliser GraphQL pour toute communication client-serveur »
|
||||
- L’ADR[^1] spécifie : « Utiliser GraphQL pour toute communication client-serveur »
|
||||
- Tous les agents suivent le même pattern
|
||||
|
||||
### Conflits de conception de base de données
|
||||
|
|
@ -25,7 +25,7 @@ Avec architecture :
|
|||
Sans architecture :
|
||||
- L’agent A utilise des noms de colonnes en snake_case
|
||||
- L’agent B utilise des noms de colonnes en camelCase
|
||||
- Résultat : Schéma incohérent, requêtes illisibles
|
||||
- Résultat : Schéma incohérent, requêtes illisibles
|
||||
|
||||
Avec architecture :
|
||||
- Un document de standards spécifie les conventions de nommage
|
||||
|
|
@ -36,7 +36,7 @@ Avec architecture :
|
|||
Sans architecture :
|
||||
- L’agent A utilise Redux pour l’état global
|
||||
- L’agent B utilise React Context
|
||||
- Résultat : Multiples approches de gestion d’état, complexité
|
||||
- Résultat : Multiples approches de gestion d’état, complexité
|
||||
|
||||
Avec architecture :
|
||||
- L’ADR spécifie l’approche de gestion d’état
|
||||
|
|
@ -56,8 +56,8 @@ Chaque choix technologique significatif est documenté avec :
|
|||
### 2. Guidance spécifique aux FR/NFR[^2]
|
||||
|
||||
L’architecture associe chaque exigence fonctionnelle à une approche technique :
|
||||
- FR-001 : Gestion des utilisateurs → Mutations GraphQL
|
||||
- FR-002 : Application mobile → Requêtes optimisées
|
||||
- FR-001 : Gestion des utilisateurs → Mutations GraphQL
|
||||
- FR-002 : Application mobile → Requêtes optimisées
|
||||
|
||||
### 3. Standards et conventions
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ Le fichier `project-context.md` résout ce problème en documentant ce que les a
|
|||
|
||||
Chaque workflow d’implémentation charge automatiquement `project-context.md` s’il existe. Le workflow architecte le charge également pour respecter vos préférences techniques lors de la conception de l’architecture.
|
||||
|
||||
**Chargé par ces workflows :**
|
||||
**Chargé par ces workflows :**
|
||||
- `bmad-create-architecture` — respecte les préférences techniques pendant la phase de solutioning
|
||||
- `bmad-create-story` — informe la création de stories avec les patterns du projet
|
||||
- `bmad-dev-story` — guide les décisions d’implémentation
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Il permet au modèle de s’exécuter plus longtemps entre les points de contrô
|
|||
|
||||
Les interactions humaines dans la boucle sont nécessaires et coûteuses.
|
||||
|
||||
Les LLM actuels échouent encore de manière prévisible : ils interprètent mal l’intention, comblent les lacunes avec des suppositions assurées, dérivent vers du travail non lié, et génèrent des résultats à réviser bruyants. En même temps, l’intervention humaine constante limite la fluidité du développement. L’attention humaine est le goulot d’étranglement.
|
||||
Les LLM actuels échouent encore de manière prévisible : ils interprètent mal l’intention, comblent les lacunes avec des suppositions assurées, dérivent vers du travail non lié, et génèrent des résultats à réviser bruyants. En même temps, l’intervention humaine constante limite la fluidité du développement. L’attention humaine est le goulot d’étranglement.
|
||||
|
||||
`bmad-quick-dev` rééquilibre ce compromis. Il fait confiance au modèle pour s’exécuter sans surveillance sur de plus longues périodes, mais seulement après que le workflow ait créé une frontière suffisamment solide pour rendre cela sûr.
|
||||
|
||||
|
|
@ -25,7 +25,7 @@ Les LLM actuels échouent encore de manière prévisible : ils interprètent mal
|
|||
|
||||
Le workflow commence par compresser l’interaction de la personne et du modèle à partir de la requête en un objectif cohérent. L’entrée peut commencer sous forme d’une expression grossière de l’intention, mais avant que le workflow ne s’exécute de manière autonome, elle doit devenir suffisamment petite, claire et sans contradiction pour être exécutable.
|
||||
|
||||
L’intention peut prendre plusieurs formes : quelques phrases, un lien vers un outil de suivi de bugs, une sortie du mode planification, du texte copié depuis une session de chat, ou même un numéro de story depuis un fichier `epics.md` de BMAD. Dans ce dernier cas, le workflow ne comprendra pas la sémantique de suivi des stories de BMAD, mais il peut quand même prendre la story elle-même et l’exécuter.
|
||||
L’intention peut prendre plusieurs formes : quelques phrases, un lien vers un outil de suivi de bugs, une sortie du mode planification, du texte copié depuis une session de chat, ou même un numéro de story depuis un fichier `epics.md` de BMAD. Dans ce dernier cas, le workflow ne comprendra pas la sémantique de suivi des stories de BMAD, mais il peut quand même prendre la story elle-même et l’exécuter.
|
||||
|
||||
Ce workflow n’élimine pas le contrôle humain. Il le déplace vers un nombre réduit d’étapes à forte valeur :
|
||||
|
||||
|
|
|
|||
|
|
@ -44,12 +44,12 @@ Le dossier `_bmad/custom/` est initialement vide. Les fichiers n’apparaissent
|
|||
|
||||
Le résolveur applique quatre règles structurelles. Les noms de champ n’ont pas de traitement particulier — le comportement est déterminé uniquement par la forme de la valeur :
|
||||
|
||||
| Forme | Règle |
|
||||
|---|---|
|
||||
| Scalaire (chaîne, entier, booléen, flottant) | L’override prévaut |
|
||||
| Table | Fusion profonde (application récursive des mêmes règles) |
|
||||
| Forme | Règle |
|
||||
|-------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
|
||||
| Scalaire (chaîne, entier, booléen, flottant) | L’override prévaut |
|
||||
| Table | Fusion profonde (application récursive des mêmes règles) |
|
||||
| Tableau de tables où chaque élément partage le **même** champ identifiant (chaque élément a `code`, ou chaque élément a `id`) | Fusionner par cette clé — les clés correspondantes **remplacent sur place**, les nouvelles clés **s’ajoutent** |
|
||||
| Tout autre tableau (scalaires ; tables sans identifiant ; tableaux qui mélangent `code` et `id` entre les éléments) | **Ajouter** — éléments de base en premier, puis éléments d’équipe, puis éléments utilisateur |
|
||||
| Tout autre tableau (scalaires ; tables sans identifiant ; tableaux qui mélangent `code` et `id` entre les éléments) | **Ajouter** — éléments de base en premier, puis éléments d’équipe, puis éléments utilisateur |
|
||||
|
||||
**Pas de mécanisme de suppression.** Les overrides ne peuvent pas effacer les éléments de base. Si vous devez supprimer un élément de menu par défaut, surchargez-le via son `code` avec une description ou un prompt sans effet. Si vous devez restructurer un tableau plus en profondeur, forkez le skill.
|
||||
|
||||
|
|
@ -86,10 +86,10 @@ _bmad/custom/
|
|||
:::caution[Ne copiez PAS le `customize.toml` complet]
|
||||
Les fichiers d’override sont **allégés**. Incluez uniquement les champs que vous modifiez — rien d’autre. Chaque champ omis est hérité automatiquement de la couche inférieure (l’équipe hérite des valeurs par défaut, l’utilisateur de l’équipe ou des valeurs par défaut).
|
||||
|
||||
Copier le `customize.toml` complet dans un override est contre-productif : la prochaine mise à jour livrera de nouvelles valeurs par défaut, mais votre fichier d’override figera les anciennes valeurs. Votre configuration s’éloignera silencieusement des valeurs par défaut à chaque mise à jour.
|
||||
Copier le `customize.toml` complet dans un override est contre-productif : la prochaine mise à jour livrera de nouvelles valeurs par défaut, mais votre fichier d’override figera les anciennes valeurs. Votre configuration s’éloignera silencieusement des valeurs par défaut à chaque mise à jour.
|
||||
:::
|
||||
|
||||
**Exemple — changer l’icône et ajouter un principe :**
|
||||
**Exemple — changer l’icône et ajouter un principe :**
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-agent-pm.toml
|
||||
|
|
@ -158,7 +158,7 @@ activation_steps_append = [
|
|||
|
||||
**Pourquoi deux hooks ?** Le préfixe s’exécute avant la salutation pour que l’agent puisse charger le contexte dont il a besoin pour personnaliser la salutation elle-même. Le suffixe s’exécute après la salutation pour que l’utilisateur ne reste pas devant un terminal vide pendant les scans lourds.
|
||||
|
||||
**Personnalisation du menu (fusion par `code`).** Le menu est un tableau de tables. Chaque élément possède un champ `code` (convention BMad). Le résolveur fusionne donc par code : les codes correspondants remplacent sur place, les nouveaux codes s’ajoutent.
|
||||
**Personnalisation du menu (fusion par `code`).** Le menu est un tableau de tables. Chaque élément possède un champ `code` (convention BMad). Le résolveur fusionne donc par code : les codes correspondants remplacent sur place, les nouveaux codes s’ajoutent.
|
||||
|
||||
La syntaxe TOML pour les tableaux de tables utilise `[[agent.menu]]` pour chaque élément :
|
||||
|
||||
|
|
@ -182,13 +182,13 @@ Signaler tout écart et citer la section réglementaire pertinente.
|
|||
|
||||
Chaque élément de menu possède exactement un `skill` (invoque un skill enregistré) ou `prompt` (exécute le texte directement). Les éléments non listés dans votre override conservent leurs valeurs par défaut.
|
||||
|
||||
**Référencer des fichiers.** Quand le texte d’un champ doit pointer vers un fichier (dans `persistent_facts`, `activation_steps_prepend`/`activation_steps_append`, ou le `prompt` d’un élément de menu), utilisez un chemin complet partant de `{project-root}`. Même si le fichier se trouve à côté de votre override dans `_bmad/custom/`, écrivez le chemin complet : `{project-root}/_bmad/custom/info.md`. L’agent résout `{project-root}` à l’exécution.
|
||||
**Référencer des fichiers.** Quand le texte d’un champ doit pointer vers un fichier (dans `persistent_facts`, `activation_steps_prepend`/`activation_steps_append`, ou le `prompt` d’un élément de menu), utilisez un chemin complet partant de `{project-root}`. Même si le fichier se trouve à côté de votre override dans `_bmad/custom/`, écrivez le chemin complet : `{project-root}/_bmad/custom/info.md`. L’agent résout `{project-root}` à l’exécution.
|
||||
|
||||
### 4. Personnel vs Équipe
|
||||
|
||||
**Fichier d’équipe** (`bmad-agent-pm.toml`) : Versionné dans git. Partagé au sein de l’organisation. À utiliser pour les règles de conformité, le persona de l’entreprise, les capacités personnalisées.
|
||||
**Fichier d’équipe** (`bmad-agent-pm.toml`) : Versionné dans git. Partagé au sein de l’organisation. À utiliser pour les règles de conformité, le persona de l’entreprise, les capacités personnalisées.
|
||||
|
||||
**Fichier personnel** (`bmad-agent-pm.user.toml`) : Automatiquement ignoré par git. À utiliser pour les ajustements de ton, les préférences de workflow personnelles et les faits privés que l’agent doit garder en tête.
|
||||
**Fichier personnel** (`bmad-agent-pm.user.toml`) : Automatiquement ignoré par git. À utiliser pour les ajustements de ton, les préférences de workflow personnelles et les faits privés que l’agent doit garder en tête.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-agent-pm.user.toml
|
||||
|
|
@ -209,7 +209,7 @@ python3 {project-root}/_bmad/scripts/resolve_customization.py \
|
|||
--key agent
|
||||
```
|
||||
|
||||
**Prérequis** : Python 3.11+ (les versions antérieures n’incluent pas `tomllib`). Pas de `pip install`, pas de `uv`, pas de virtualenv. Vérifiez avec `python3 --version`. Certaines plateformes (macOS sans Homebrew, Ubuntu 22.04) ont `python3` par défaut en 3.10 ou antérieur, vous devrez peut-être installer 3.11+ séparément.
|
||||
**Prérequis** : Python 3.11+ (les versions antérieures n’incluent pas `tomllib`). Pas de `pip install`, pas de `uv`, pas de virtualenv. Vérifiez avec `python3 --version`. Certaines plateformes (macOS sans Homebrew, Ubuntu 22.04) ont `python3` par défaut en 3.10 ou antérieur, vous devrez peut-être installer 3.11+ séparément.
|
||||
|
||||
`--skill` pointe vers le répertoire installé du skill (où se trouve `customize.toml`). Le nom du skill est déduit du basename du répertoire, et le script cherche automatiquement `_bmad/custom/{skill-name}.toml` et `{skill-name}.user.toml`.
|
||||
|
||||
|
|
@ -260,7 +260,7 @@ persistent_facts = [
|
|||
on_complete = "Résumer le brief en trois points et proposer de l'envoyer par email via le skill gws-gmail-send."
|
||||
```
|
||||
|
||||
Les mêmes conventions de champs s’appliquent indifféremment aux agents et aux workflows : `activation_steps_prepend`/`activation_steps_append`, `persistent_facts` (avec refs `file:`) et les tables `[[…]]` de style menu avec `code`/`id` pour la fusion par clé. Le résolveur applique les mêmes quatre règles structurelles quelle que soit la clé de premier niveau. Les références dans SKILL.md suivent l’espace de noms : `{workflow.activation_steps_prepend}`, `{workflow.persistent_facts}`, `{workflow.on_complete}`. Tout champ supplémentaire qu’un workflow expose (chemins de sortie, bascules, paramètres de revue, drapeaux d’étape) suit les mêmes règles de fusion basées sur la forme. Lisez le `customize.toml` du workflow pour voir ce qui est personnalisable.
|
||||
Les mêmes conventions de champs s’appliquent indifféremment aux agents et aux workflows : `activation_steps_prepend`/`activation_steps_append`, `persistent_facts` (avec refs `file:`) et les tables `[[…]]` de style menu avec `code`/`id` pour la fusion par clé. Le résolveur applique les mêmes quatre règles structurelles quelle que soit la clé de premier niveau. Les références dans SKILL.md suivent l’espace de noms : `{workflow.activation_steps_prepend}`, `{workflow.persistent_facts}`, `{workflow.on_complete}`. Tout champ supplémentaire qu’un workflow expose (chemins de sortie, bascules, paramètres de revue, drapeaux d’étape) suit les mêmes règles de fusion basées sur la forme. Lisez le `customize.toml` du workflow pour voir ce qui est personnalisable.
|
||||
|
||||
### Ordre d’activation
|
||||
|
||||
|
|
@ -277,7 +277,7 @@ Après l’étape 6, le corps du workflow commence. Utilisez `activation_steps_p
|
|||
|
||||
### Périmètre de cette première passe
|
||||
|
||||
La personnalisation est déployée de manière incrémentale. Les champs documentés ci-dessus — `activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete` — sont la **surface de base** que chaque workflow personnalisable expose, et ils resteront stables d’une version à l’autre. Ils vous donnent un contrôle à grands traits dès aujourd’hui : injecter des étapes pré/post, épingler du contexte fondamental, déclencher des actions de suivi.
|
||||
La personnalisation est déployée de manière incrémentale. Les champs documentés ci-dessus — `activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete` — sont la **surface de base** que chaque workflow personnalisable expose, et ils resteront stables d’une version à l’autre. Ils vous donnent un contrôle à grands traits dès aujourd’hui : injecter des étapes pré/post, épingler du contexte fondamental, déclencher des actions de suivi.
|
||||
|
||||
Au fil du temps, les workflows individuels exposeront des **points de personnalisation plus ciblés** adaptés à ce que le workflow fait réellement — par exemple des bascules par étape, des drapeaux d’étape, des chemins de templates de sortie ou des jalons de revue. Quand ils arriveront, ils viendront s’ajouter aux champs de base plutôt que de les remplacer, pour que les personnalisations que vous rédigez aujourd’hui continuent de fonctionner.
|
||||
|
||||
|
|
@ -359,12 +359,12 @@ L’override prévaut sur ce que chaque développeur a répondu lors de son inst
|
|||
|
||||
| Besoin | Utiliser |
|
||||
|----------------------------------------------------------|-------------------------------------------------------------------------------|
|
||||
| Ajouter des appels d’outils MCP à chaque workflow de dev | Par skill : `_bmad/custom/bmad-agent-dev.toml` `persistent_facts` |
|
||||
| Ajouter un élément de menu à un agent | Par skill : `_bmad/custom/bmad-agent-{role}.toml` `[[agent.menu]]` |
|
||||
| Remplacer le template de sortie d’un workflow | Par skill : `_bmad/custom/{workflow}.toml` override scalaire |
|
||||
| Renommer le descripteur public d’un agent | **Centrale** : `_bmad/custom/config.toml` `[agents.<code>]` |
|
||||
| Ajouter un agent personnalisé ou fictif au registre | **Centrale** : `_bmad/custom/config.*.toml` nouvelle entrée `[agents.<code>]` |
|
||||
| Figer les paramètres d’installation pour l’équipe | **Centrale** : `_bmad/custom/config.toml` `[modules.<code>]` ou `[core]` |
|
||||
| Ajouter des appels d’outils MCP à chaque workflow de dev | Par skill : `_bmad/custom/bmad-agent-dev.toml` `persistent_facts` |
|
||||
| Ajouter un élément de menu à un agent | Par skill : `_bmad/custom/bmad-agent-{role}.toml` `[[agent.menu]]` |
|
||||
| Remplacer le template de sortie d’un workflow | Par skill : `_bmad/custom/{workflow}.toml` override scalaire |
|
||||
| Renommer le descripteur public d’un agent | **Centrale** : `_bmad/custom/config.toml` `[agents.<code>]` |
|
||||
| Ajouter un agent personnalisé ou fictif au registre | **Centrale** : `_bmad/custom/config.*.toml` nouvelle entrée `[agents.<code>]` |
|
||||
| Figer les paramètres d’installation pour l’équipe | **Centrale** : `_bmad/custom/config.toml` `[modules.<code>]` ou `[core]` |
|
||||
|
||||
Utilisez les deux espaces dans le même projet selon vos besoins.
|
||||
|
||||
|
|
@ -377,7 +377,7 @@ Pour des recettes orientées entreprise (façonner un agent à travers tous les
|
|||
**La personnalisation n’apparaît pas ?**
|
||||
|
||||
- Vérifiez que votre fichier se trouve dans `_bmad/custom/` avec le nom de skill correct
|
||||
- Vérifiez la syntaxe TOML : les chaînes doivent être entre guillemets, les en-têtes de table utilisent `[section]`, les tableaux de tables utilisent `[[section]]`, et toute clé scalaire ou de tableau pour une table doit apparaître *avant* toute `[[sous-table]]` de cette table dans le fichier
|
||||
- Vérifiez la syntaxe TOML : les chaînes doivent être entre guillemets, les en-têtes de table utilisent `[section]`, les tableaux de tables utilisent `[[section]]`, et toute clé scalaire ou de tableau pour une table doit apparaître *avant* toute `[[sous-table]]` de cette table dans le fichier
|
||||
- Pour les agents, la personnalisation se trouve sous `[agent]` — les champs écrits sous cet en-tête appartiennent à `agent` jusqu’à ce qu’un autre en-tête de table commence
|
||||
- Rappelez-vous que `agent.name` et `agent.title` sont en lecture seule ; les overrides n’ont aucun effet
|
||||
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Ce guide couvre le flux de travail essentiel pour l’intégration à des projet
|
|||
- Accès à un IDE IA (Claude Code ou Cursor)
|
||||
:::
|
||||
|
||||
## Étape 1 : Nettoyer les artefacts de planification terminés
|
||||
## Étape 1 : Nettoyer les artefacts de planification terminés
|
||||
|
||||
Si vous avez terminé tous les epics et stories du PRD[^1] via le processus BMad, nettoyez ces fichiers. Archivez-les, supprimez-les, ou appuyez-vous sur l’historique des versions si nécessaire. Ne conservez pas ces fichiers dans :
|
||||
|
||||
|
|
@ -23,7 +23,7 @@ Si vous avez terminé tous les epics et stories du PRD[^1] via le processus BMad
|
|||
- `_bmad-output/planning-artifacts/`
|
||||
- `_bmad-output/implementation-artifacts/`
|
||||
|
||||
## Étape 2 : Créer le contexte du projet
|
||||
## Étape 2 : Créer le contexte du projet
|
||||
|
||||
:::tip[Recommandé pour les projets existants]
|
||||
Générez `project-context.md` pour capturer les patterns et conventions de votre base de code existante. Cela garantit que les agents IA suivent vos pratiques établies lors de l’implémentation des modifications.
|
||||
|
|
@ -46,7 +46,7 @@ Vous pouvez examiner et affiner le fichier généré, ou le créer manuellement
|
|||
|
||||
[En savoir plus sur le contexte du projet](../explanation/project-context.md)
|
||||
|
||||
## Étape 3 : Maintenir une documentation de projet de qualité
|
||||
## Étape 3 : Maintenir une documentation de projet de qualité
|
||||
|
||||
Votre dossier `docs/` doit contenir une documentation succincte et bien organisée qui représente fidèlement votre projet :
|
||||
|
||||
|
|
@ -57,9 +57,9 @@ Votre dossier `docs/` doit contenir une documentation succincte et bien organis
|
|||
|
||||
Pour les projets complexes, envisagez d’utiliser le workflow `bmad-document-project`. Il offre des variantes d’exécution qui analyseront l’ensemble de votre projet et documenteront son état actuel réel.
|
||||
|
||||
## Étape 4 : Obtenir de l’aide
|
||||
## Étape 4 : Obtenir de l’aide
|
||||
|
||||
### BMad-Help : Votre point de départ
|
||||
### BMad-Help : Votre point de départ
|
||||
|
||||
**Exécutez `bmad-help` chaque fois que vous n’êtes pas sûr de la prochaine étape.** Ce guide intelligent :
|
||||
|
||||
|
|
@ -79,10 +79,10 @@ BMad-Help s’exécute également **automatiquement à la fin de chaque workflow
|
|||
|
||||
Vous avez deux options principales selon l’ampleur des modifications :
|
||||
|
||||
| Portée | Approche recommandée |
|
||||
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Petites mises à jour ou ajouts** | Exécutez `bmad-quick-dev` pour clarifier l’intention, planifier, implémenter et réviser dans un seul workflow. La méthode BMad complète en quatre phases est probablement excessive. |
|
||||
| **Modifications ou ajouts majeurs** | Commencez avec la méthode BMad, en appliquant autant ou aussi peu de rigueur que nécessaire. |
|
||||
| Portée | Approche recommandée |
|
||||
|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| **Petites mises à jour ou ajouts** | Exécutez `bmad-quick-dev` pour clarifier l’intention, planifier, implémenter et réviser dans un seul workflow. La méthode BMad complète en quatre phases est probablement excessive. |
|
||||
| **Modifications ou ajouts majeurs** | Commencez avec la méthode BMad, en appliquant autant ou aussi peu de rigueur que nécessaire. |
|
||||
|
||||
### Pendant la création du PRD
|
||||
|
||||
|
|
|
|||
|
|
@ -28,13 +28,13 @@ Avant de choisir une recette, comprenez où votre override se situe :
|
|||
| **Workflow** (ex. product-brief, create-prd) | Section `[workflow]` de `_bmad/custom/{workflow-name}.toml` | S’applique uniquement à l’exécution de ce workflow |
|
||||
| **Configuration centrale** | `[agents.*]`, `[core]`, `[modules.*]` dans `_bmad/custom/config.toml` | Registre des agents (qui est disponible pour party-mode, retrospective, elicitation), paramètres d’installation figés pour toute l’organisation |
|
||||
|
||||
En règle générale : si la règle doit s’appliquer partout où un ingénieur travaille sur le développement, personnalisez l'**agent dev**. Si elle s’applique uniquement quand quelqu’un rédige un product brief, personnalisez le **workflow product-brief**. Si elle change *qui participe* (renommer un agent, ajouter une voix personnalisée, imposer un chemin d’artefact partagé), modifiez la **configuration centrale**.
|
||||
En règle générale : si la règle doit s’appliquer partout où un ingénieur travaille sur le développement, personnalisez l'**agent dev**. Si elle s’applique uniquement quand quelqu’un rédige un product brief, personnalisez le **workflow product-brief**. Si elle change *qui participe* (renommer un agent, ajouter une voix personnalisée, imposer un chemin d’artefact partagé), modifiez la **configuration centrale**.
|
||||
|
||||
## Recette 1 : Façonner un agent à travers tous les workflows qu’il dispatche
|
||||
## Recette 1 : Façonner un agent à travers tous les workflows qu’il dispatche
|
||||
|
||||
**Cas d’usage :** Standardiser l’utilisation des outils et les intégrations avec les systèmes externes pour que chaque workflow dispatché par un agent hérite du comportement. C’est le pattern le plus impactant.
|
||||
**Cas d’usage :** Standardiser l’utilisation des outils et les intégrations avec les systèmes externes pour que chaque workflow dispatché par un agent hérite du comportement. C’est le pattern le plus impactant.
|
||||
|
||||
**Exemple : Amelia (agent dev) utilise toujours Context7 pour la documentation des bibliothèques, et se rabat sur Linear quand une story n’est pas trouvée dans la liste des epics.**
|
||||
**Exemple : Amelia (agent dev) utilise toujours Context7 pour la documentation des bibliothèques, et se rabat sur Linear quand une story n’est pas trouvée dans la liste des epics.**
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-agent-dev.toml
|
||||
|
|
@ -49,17 +49,17 @@ persistent_facts = [
|
|||
]
|
||||
```
|
||||
|
||||
**Pourquoi ça marche :** Deux phrases suffisent à reconfigurer tous les workflows de dev de l’organisation, sans duplication par workflow ni modification du code source. Chaque nouvel ingénieur qui clone le dépôt hérite automatiquement des conventions.
|
||||
**Pourquoi ça marche :** Deux phrases suffisent à reconfigurer tous les workflows de dev de l’organisation, sans duplication par workflow ni modification du code source. Chaque nouvel ingénieur qui clone le dépôt hérite automatiquement des conventions.
|
||||
|
||||
**Fichier d’équipe vs fichier personnel :**
|
||||
- `bmad-agent-dev.toml` : versionné dans git ; s’applique à toute l’équipe
|
||||
- `bmad-agent-dev.user.toml` : ignoré par git ; préférences personnelles ajoutées par-dessus
|
||||
**Fichier d’équipe vs fichier personnel :**
|
||||
- `bmad-agent-dev.toml` : versionné dans git ; s’applique à toute l’équipe
|
||||
- `bmad-agent-dev.user.toml` : ignoré par git ; préférences personnelles ajoutées par-dessus
|
||||
|
||||
## Recette 2 : Imposer les conventions de l’organisation dans un workflow spécifique
|
||||
## Recette 2 : Imposer les conventions de l’organisation dans un workflow spécifique
|
||||
|
||||
**Cas d’usage :** Façonner le *contenu* de la sortie d’un workflow pour qu’il réponde aux exigences de conformité, d’audit ou des consommateurs en aval.
|
||||
**Cas d’usage :** Façonner le *contenu* de la sortie d’un workflow pour qu’il réponde aux exigences de conformité, d’audit ou des consommateurs en aval.
|
||||
|
||||
**Exemple : chaque product brief doit inclure des champs de conformité, et l’agent connaît les conventions de publication de l’organisation.**
|
||||
**Exemple : chaque product brief doit inclure des champs de conformité, et l’agent connaît les conventions de publication de l’organisation.**
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-product-brief.toml
|
||||
|
|
@ -73,13 +73,13 @@ persistent_facts = [
|
|||
]
|
||||
```
|
||||
|
||||
**Ce qui se passe :** Les faits sont chargés durant l’étape 3 de l’activation du workflow. Quand l’agent rédige le brief, il connaît les champs requis et le document de conventions enterprise. La valeur par défaut livrée (`file:{project-root}/**/project-context.md`) se charge toujours, car il s’agit d’un ajout.
|
||||
**Ce qui se passe :** Les faits sont chargés durant l’étape 3 de l’activation du workflow. Quand l’agent rédige le brief, il connaît les champs requis et le document de conventions enterprise. La valeur par défaut livrée (`file:{project-root}/**/project-context.md`) se charge toujours, car il s’agit d’un ajout.
|
||||
|
||||
## Recette 3 : Publier les livrables finis vers des systèmes externes
|
||||
## Recette 3 : Publier les livrables finis vers des systèmes externes
|
||||
|
||||
**Cas d’usage :** Une fois le livrable produit, le publier automatiquement vers les systèmes de référence de l’entreprise (Confluence, Notion, SharePoint) et créer des tickets de suivi (Jira, Linear, Asana).
|
||||
**Cas d’usage :** Une fois le livrable produit, le publier automatiquement vers les systèmes de référence de l’entreprise (Confluence, Notion, SharePoint) et créer des tickets de suivi (Jira, Linear, Asana).
|
||||
|
||||
**Exemple : les briefs sont automatiquement publiés vers Confluence et proposent la création facultative d’un epic Jira.**
|
||||
**Exemple : les briefs sont automatiquement publiés vers Confluence et proposent la création facultative d’un epic Jira.**
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-product-brief.toml
|
||||
|
|
@ -112,18 +112,18 @@ et demander à l'utilisateur de publier manuellement.
|
|||
"""
|
||||
```
|
||||
|
||||
**Pourquoi `on_complete` et pas `activation_steps_append` :** `on_complete` s’exécute exactement une fois, au stade terminal, après que le workflow a écrit sa sortie principale. C’est le bon moment pour publier des artefacts. `activation_steps_append` s’exécute à chaque activation, avant que le workflow ne fasse son travail.
|
||||
**Pourquoi `on_complete` et pas `activation_steps_append` :** `on_complete` s’exécute exactement une fois, au stade terminal, après que le workflow a écrit sa sortie principale. C’est le bon moment pour publier des artefacts. `activation_steps_append` s’exécute à chaque activation, avant que le workflow ne fasse son travail.
|
||||
|
||||
**Arbitrages :**
|
||||
**Arbitrages :**
|
||||
- **La publication Confluence est non-destructive** et s’exécute toujours à la fin
|
||||
- **La création d’epic Jira est visible par toute l’équipe** et déclenche un processus de planification de sprint, conditionnez-la donc à la confirmation de l’utilisateur
|
||||
- **Dégradation gracieuse :** si les outils MCP échouent, passer la main à l’utilisateur plutôt que de silencieusement abandonner le livrable
|
||||
- **Dégradation gracieuse :** si les outils MCP échouent, passer la main à l’utilisateur plutôt que de silencieusement abandonner le livrable
|
||||
|
||||
## Recette 4 : Remplacer le template de sortie par le vôtre
|
||||
## Recette 4 : Remplacer le template de sortie par le vôtre
|
||||
|
||||
**Cas d’usage :** La structure de sortie par défaut ne correspond pas au format attendu par votre organisation, ou différentes organisations dans le même dépôt ont besoin de templates différents.
|
||||
**Cas d’usage :** La structure de sortie par défaut ne correspond pas au format attendu par votre organisation, ou différentes organisations dans le même dépôt ont besoin de templates différents.
|
||||
|
||||
**Exemple : pointer le workflow product-brief vers un template appartenant à l’entreprise.**
|
||||
**Exemple : pointer le workflow product-brief vers un template appartenant à l’entreprise.**
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-product-brief.toml
|
||||
|
|
@ -132,16 +132,16 @@ et demander à l'utilisateur de publier manuellement.
|
|||
brief_template = "{project-root}/docs/enterprise/brief-template.md"
|
||||
```
|
||||
|
||||
**Comment ça marche :** Le `customize.toml` du workflow est fourni avec `brief_template = "resources/brief-template.md"` (chemin relatif, résolu depuis la racine du skill). Votre override pointe vers un fichier sous `{project-root}`, donc l’agent lit votre template à l’étape 4 au lieu de celui livré par défaut.
|
||||
**Comment ça marche :** Le `customize.toml` du workflow est fourni avec `brief_template = "resources/brief-template.md"` (chemin relatif, résolu depuis la racine du skill). Votre override pointe vers un fichier sous `{project-root}`, donc l’agent lit votre template à l’étape 4 au lieu de celui livré par défaut.
|
||||
|
||||
**Conseils pour la rédaction de templates :**
|
||||
**Conseils pour la rédaction de templates :**
|
||||
- Gardez les templates dans `{project-root}/docs/` ou `{project-root}/_bmad/custom/templates/` pour qu’ils soient versionnés avec le fichier d’override
|
||||
- Utilisez les mêmes conventions structurelles que le template livré (titres de sections, frontmatter) ; l’agent s’adapte à ce qu’il trouve
|
||||
- Pour les dépôts multi-organisations, utilisez `.user.toml` pour permettre à chaque équipe de pointer vers ses propres templates sans toucher au fichier d’équipe versionné dans git
|
||||
|
||||
## Recette 5 : Personnaliser le registre des agents
|
||||
## Recette 5 : Personnaliser le registre des agents
|
||||
|
||||
**Cas d’usage :** Changer *qui sera présent dans la pièce* pour les skills basés sur le registre comme `bmad-party-mode`, `bmad-retrospective` et `bmad-advanced-elicitation`, sans modifier le code source ni forker. Voici trois variantes courantes.
|
||||
**Cas d’usage :** Changer *qui sera présent dans la pièce* pour les skills basés sur le registre comme `bmad-party-mode`, `bmad-retrospective` et `bmad-advanced-elicitation`, sans modifier le code source ni forker. Voici trois variantes courantes.
|
||||
|
||||
### 5a. Renommer un agent BMad pour toute l’organisation
|
||||
|
||||
|
|
@ -197,18 +197,18 @@ document_output_language = "English"
|
|||
|
||||
Les paramètres personnels comme `user_name`, `communication_language` ou `user_skill_level` restent dans leur propre fichier `_bmad/config.user.toml` de chaque développeur. Le fichier d’équipe ne doit pas les modifier.
|
||||
|
||||
**Pourquoi la configuration centrale vs le customize.toml par agent :** Les fichiers par agent façonnent la façon dont *un seul* agent se comporte quand il s’active. La configuration centrale façonne ce que les consommateurs du registre *voient* : quels agents existent, comment ils s’appellent, à quelle équipe ils appartiennent, et les paramètres d’installation partagés sur lesquels tout le dépôt s’accorde. Deux surfaces, des rôles différents.
|
||||
**Pourquoi la configuration centrale vs le customize.toml par agent :** Les fichiers par agent façonnent la façon dont *un seul* agent se comporte quand il s’active. La configuration centrale façonne ce que les consommateurs du registre *voient* : quels agents existent, comment ils s’appellent, à quelle équipe ils appartiennent, et les paramètres d’installation partagés sur lesquels tout le dépôt s’accorde. Deux surfaces, des rôles différents.
|
||||
|
||||
## Renforcer les règles globales dans le fichier de session de votre IDE
|
||||
|
||||
Les personnalisations BMad se chargent quand un skill est activé. Beaucoup d’outils IDE chargent aussi un fichier d’instructions global au **début de chaque session**, avant tout skill (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, `.github/copilot-instructions.md`, etc.). Pour les règles qui doivent s’appliquer même en dehors des skills BMad, reproduisez-y les plus critiques.
|
||||
|
||||
**Quand les utiliser ensemble :**
|
||||
**Quand les utiliser ensemble :**
|
||||
- Une règle est suffisamment importante pour qu’une conversation simple (sans skill actif) doive la respecter
|
||||
- Vous voulez une double sécurisation parce que les défauts des données d’entraînement pourraient autrement détourner le modèle
|
||||
- La règle est assez concise pour être répétée sans alourdir le fichier de session
|
||||
|
||||
**Exemple : une ligne dans le `CLAUDE.md` du dépôt renforçant la règle de l’agent dev de la Recette 1.**
|
||||
**Exemple : une ligne dans le `CLAUDE.md` du dépôt renforçant la règle de l’agent dev de la Recette 1.**
|
||||
|
||||
```markdown
|
||||
<!-- Toute lecture de documentation de bibliothèque passe par l'outil MCP context7
|
||||
|
|
@ -227,7 +227,7 @@ Une phrase, chargée à chaque session. Elle s’associe à la personnalisation
|
|||
|
||||
Gardez le fichier IDE **concis**. Une douzaine de lignes bien choisies sont plus efficaces qu’une liste étendue. Les modèles le lisent à chaque tour, et le superflu noie l’information utile.
|
||||
|
||||
## Recette 6 : Patterns d’intégration avancés
|
||||
## Recette 6 : Patterns d’intégration avancés
|
||||
|
||||
Plusieurs workflows BMad exposent une surface de configuration plus riche au-delà des bases couvertes dans les Recettes 1–5. Ces patterns — sources de connaissance à la demande, publication automatique des livrables, standards de documentation à la finalisation et templates interchangeables — apparaissent dans plusieurs workflows. Consultez le `customize.toml` d’un workflow pour voir quels champs il expose ; les exemples ci-dessous utilisent `bmad-prd` car il les expose tous, mais les mêmes patterns s’appliquent partout où le champ apparaît.
|
||||
|
||||
|
|
@ -317,7 +317,7 @@ on_complete = """ ... """
|
|||
persistent_facts = ["Toujours inclure une section 'Revue réglementaire' quand le domaine implique la santé, la finance ou les données d'enfants."]
|
||||
```
|
||||
|
||||
Résultat : Mary charge la règle de revue réglementaire à l’activation de son persona. Quand l’utilisateur choisit le product brief dans le menu, le workflow charge ses propres conventions par-dessus, écrit avec le template enterprise et publie vers Confluence à la fin. Chaque couche contribue, et aucune n’a nécessité de modifier le code source de BMad.
|
||||
Résultat : Mary charge la règle de revue réglementaire à l’activation de son persona. Quand l’utilisateur choisit le product brief dans le menu, le workflow charge ses propres conventions par-dessus, écrit avec le template enterprise et publie vers Confluence à la fin. Chaque couche contribue, et aucune n’a nécessité de modifier le code source de BMad.
|
||||
|
||||
## Dépannage
|
||||
|
||||
|
|
|
|||
|
|
@ -28,12 +28,12 @@ BMad-Help s’appuie sur votre configuration installée. Pour les questions sur
|
|||
Clonez ou ouvrez le [dépôt BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) et posez vos questions à votre IA. Tout outil capable d’utiliser des agents (Claude Code, Cursor, Windsurf, etc.) peut lire les sources et répondre directement à vos questions.
|
||||
|
||||
:::note[Exemple]
|
||||
**Q :** « Quel est le moyen le plus rapide de construire quelque chose avec BMad ? »
|
||||
**Q :** « Quel est le moyen le plus rapide de construire quelque chose avec BMad ? »
|
||||
|
||||
**R :** Utilisez le flux rapide : Lancez `bmad-quick-dev` — il clarifie votre intention, planifie, implémente, révise et présente les résultats dans un seul workflow, en sautant les phases de planification complètes.
|
||||
**R :** Utilisez le flux rapide : Lancez `bmad-quick-dev` — il clarifie votre intention, planifie, implémente, révise et présente les résultats dans un seul workflow, en sautant les phases de planification complètes.
|
||||
:::
|
||||
|
||||
**Conseils pour de meilleures réponses :**
|
||||
**Conseils pour de meilleures réponses :**
|
||||
|
||||
- **Soyez précis** — « Que fait l’étape 3 du workflow PRD ? » est mieux que « Comment fonctionne le PRD ? »
|
||||
- **Vérifiez les affirmations surprenantes** — Les LLM font parfois des erreurs. Consultez le fichier source ou posez la question sur Discord.
|
||||
|
|
@ -46,14 +46,14 @@ Si votre IA ne peut pas lire des fichiers locaux (ChatGPT, Claude.ai, etc.), imp
|
|||
|
||||
Si ni BMad-Help ni la source n’ont répondu à votre question, vous avez maintenant une bien meilleure question à poser.
|
||||
|
||||
| Canal | Utilisé pour |
|
||||
| ------------------------- | ------------------------------------------- |
|
||||
| Forum `help-requests` | Questions |
|
||||
| `#suggestions-feedback` | Idées et demandes de fonctionnalités |
|
||||
| Canal | Utilisé pour |
|
||||
|-------------------------|--------------------------------------|
|
||||
| Forum `help-requests` | Questions |
|
||||
| `#suggestions-feedback` | Idées et demandes de fonctionnalités |
|
||||
|
||||
**Discord :** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
|
||||
**Discord :** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
|
||||
|
||||
**GitHub Issues :** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
|
||||
**GitHub Issues :** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
|
||||
*Toi !*
|
||||
*Bloqué*
|
||||
*dans la file d’attente—*
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ Exécute l’installateur de préversion, qui fournit un snapshot plus récent d
|
|||
|
||||
Deux axes indépendants contrôlent ce qui se retrouve sur le disque.
|
||||
|
||||
### Axe 1 : canaux des modules externes
|
||||
### Axe 1 : canaux des modules externes
|
||||
|
||||
Chaque module externe — bmb, cis, gds, tea, et tout module communautaire — s’installe via l’un des trois canaux suivants :
|
||||
|
||||
|
|
@ -63,7 +63,7 @@ Chaque module externe — bmb, cis, gds, tea, et tout module communautaire — s
|
|||
|
||||
Les canaux sont définis module par module. Vous pouvez exécuter bmb sur `next` tout en laissant cis sur `stable` — les options ci-dessous permettent de les combiner librement.
|
||||
|
||||
### Axe 2 : version du binaire de l’installateur
|
||||
### Axe 2 : version du binaire de l’installateur
|
||||
|
||||
Le paquet npm `bmad-method` lui-même a deux dist-tags :
|
||||
|
||||
|
|
@ -88,10 +88,10 @@ Ils sont liés au binaire de l’installateur que vous avez exécuté :
|
|||
|
||||
Exécuter `npx bmad-method install` dans un répertoire contenant déjà `_bmad/` affiche un menu :
|
||||
|
||||
| Choix | Ce qu’il fait |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Quick Update** | Réexécute l’installation avec vos paramètres existants. Rafraîchit les fichiers, applique les correctifs et les mises à niveau mineures du canal stable, refuse les mises à niveau majeures. Rapide, non interactif. |
|
||||
| **Modify Install** | Flux interactif complet. Ajoutez ou retirez des modules, reconfigurez les paramètres, examinez et, si besoin, modifiez les canaux des modules existants. |
|
||||
| Choix | Ce qu’il fait |
|
||||
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| **Quick Update** | Réexécute l’installation avec vos paramètres existants. Rafraîchit les fichiers, applique les correctifs et les mises à niveau mineures du canal stable, refuse les mises à niveau majeures. Rapide, non interactif. |
|
||||
| **Modify Install** | Flux interactif complet. Ajoutez ou retirez des modules, reconfigurez les paramètres, examinez et, si besoin, modifiez les canaux des modules existants. |
|
||||
|
||||
### Invites de mise à niveau
|
||||
|
||||
|
|
@ -109,9 +109,9 @@ Avec `--yes`, les mises à niveau patch et mineure s’appliquent automatiquemen
|
|||
|
||||
### Changer le canal d’un module
|
||||
|
||||
**En mode interactif :** choisissez Modify → répondez **Oui** à « Review channel assignments? » → chaque module externe offre Conserver, Basculer vers stable, Basculer vers next, ou Épingler à un tag.
|
||||
**En mode interactif :** choisissez Modify → répondez **Oui** à « Review channel assignments? » → chaque module externe offre Conserver, Basculer vers stable, Basculer vers next, ou Épingler à un tag.
|
||||
|
||||
**En ligne de commande :** les recettes dans la section suivante couvrent les cas courants.
|
||||
**En ligne de commande :** les recettes dans la section suivante couvrent les cas courants.
|
||||
|
||||
## Installations CI non interactives
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ Avec `--yes`, les mises à niveau patch et mineure s’appliquent automatiquemen
|
|||
| Option | Objectif |
|
||||
|--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `--yes`, `-y` | Ignorer toutes les invites ; accepter les valeurs des options + les défauts |
|
||||
| `--directory <chemin>` | Installer dans ce répertoire (défaut : répertoire de travail courant) |
|
||||
| `--directory <chemin>` | Installer dans ce répertoire (défaut : répertoire de travail courant) |
|
||||
| `--modules <a,b,c>` | Ensemble exact de modules. Core est ajouté automatiquement. Ce n’est pas un delta — listez tout ce que vous voulez conserver. |
|
||||
| `--tools <a,b>` | Sélection d’IDE/outil. Requis pour les nouvelles installations `--yes`. Exécutez `--list-tools` pour les IDs valides. |
|
||||
| `--list-tools` | Afficher tous les IDs d’outils/IDE supportés (avec les répertoires cibles) et quitter. |
|
||||
|
|
@ -135,7 +135,7 @@ Avec `--yes`, les mises à niveau patch et mineure s’appliquent automatiquemen
|
|||
| `--list-options [module]` | Afficher chaque clé `--set` pour les modules intégrés et officiels en cache local, puis quitter. Passez un code de module pour limiter à un seul module. |
|
||||
| `--user-name`, `--communication-language`, `--document-output-language`, `--output-folder` | Raccourcis historiques équivalents à `--set core.<clé>=<valeur>` (toujours supportés) |
|
||||
|
||||
Priorité en cas de chevauchement des options : `--pin` bat `--next=` bat `--channel` / `--all-*` bat le défaut du registre (`stable`).
|
||||
Priorité en cas de chevauchement des options : `--pin` bat `--next=` bat `--channel` / `--all-*` bat le défaut du registre (`stable`).
|
||||
|
||||
:::note[Exemple de résolution]
|
||||
`--all-next --pin cis=v0.2.0` met bmb, gds et tea sur next tout en épinglant cis à v0.2.0.
|
||||
|
|
@ -143,13 +143,13 @@ Priorité en cas de chevauchement des options : `--pin` bat `--next=` bat `--cha
|
|||
|
||||
### Recettes
|
||||
|
||||
**Installation par défaut — dernière version stable pour tout :**
|
||||
**Installation par défaut — dernière version stable pour tout :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes --modules bmm,bmb,cis --tools claude-code
|
||||
```
|
||||
|
||||
**Installation entreprise verrouillée — reproductible à l’octet près :**
|
||||
**Installation entreprise verrouillée — reproductible à l’octet près :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes \
|
||||
|
|
@ -158,7 +158,7 @@ npx bmad-method install --yes \
|
|||
--tools claude-code
|
||||
```
|
||||
|
||||
**Bleeding edge — externes sur le HEAD de main :**
|
||||
**Bleeding edge — externes sur le HEAD de main :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes --modules bmm,bmb --all-next --tools claude-code
|
||||
|
|
@ -173,7 +173,7 @@ npx bmad-method install --yes --action update \
|
|||
|
||||
`--tools` est omis intentionnellement — `--action update` réutilise les outils configurés lors de la première installation.
|
||||
|
||||
**Mixer les canaux — bmb sur next, gds sur stable :**
|
||||
**Mixer les canaux — bmb sur next, gds sur stable :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes --action update \
|
||||
|
|
@ -183,9 +183,9 @@ npx bmad-method install --yes --action update \
|
|||
|
||||
### Substitutions de config de module
|
||||
|
||||
`--set <module>.<clé>=<valeur>` vous permet de définir toute option de config de module de manière non interactive. Cette option est répétable et s’adapte à chaque module — présent et futur. L’option est appliquée comme un correctif post-installation : l’installateur exécute d’abord son flux normal, puis `--set` insère ou met à jour chaque valeur dans `_bmad/config.toml` (portée équipe) ou `_bmad/config.user.toml` (portée utilisateur), et dans `_bmad/<module>/config.yaml` pour que les valeurs déclarées soient conservées à la prochaine installation.
|
||||
`--set <module>.<clé>=<valeur>` vous permet de définir toute option de config de module de manière non interactive. Cette option est répétable et s’adapte à chaque module — présent et futur. L’option est appliquée comme un correctif post-installation : l’installateur exécute d’abord son flux normal, puis `--set` insère ou met à jour chaque valeur dans `_bmad/config.toml` (portée équipe) ou `_bmad/config.user.toml` (portée utilisateur), et dans `_bmad/<module>/config.yaml` pour que les valeurs déclarées soient conservées à la prochaine installation.
|
||||
|
||||
**Exemple — installer bmm avec des connaissances projet et un niveau de compétence explicites :**
|
||||
**Exemple — installer bmm avec des connaissances projet et un niveau de compétence explicites :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes \
|
||||
|
|
@ -195,7 +195,7 @@ npx bmad-method install --yes \
|
|||
--set bmm.user_skill_level=expert
|
||||
```
|
||||
|
||||
**Découvrir les clés disponibles pour un module :**
|
||||
**Découvrir les clés disponibles pour un module :**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --list-options bmm
|
||||
|
|
@ -203,10 +203,10 @@ npx bmad-method install --list-options bmm
|
|||
|
||||
`--list-options` (sans argument) liste chaque clé que l’installateur peut trouver localement — modules intégrés (`core`, `bmm`) plus tous les modules officiels actuellement en cache. Le cache est par machine et peut être vidé, donc les modules officiels précédemment installés n’apparaîtront pas sur un nouveau checkout ou un worker CI éphémère tant qu’ils ne sont pas réinstallés. Les modules communautaires et personnalisés ne sont pas énumérés ici ; lisez directement le `module.yaml` du module pour voir les clés qu’il déclare.
|
||||
|
||||
**Comment ça fonctionne :**
|
||||
**Comment ça fonctionne :**
|
||||
|
||||
- **Routage.** L’étape de correctif cherche `[modules.<module>] <clé>` (ou `[core] <clé>`) dans `config.user.toml` en premier ; si elle y est trouvée, elle met à jour ce fichier. Sinon elle écrit dans le `config.toml` de portée équipe. Ainsi, les clés de portée utilisateur (ex. `core.user_name`, `bmm.user_skill_level`) finissent dans `config.user.toml` et les clés de portée équipe dans `config.toml`, correspondant à la partition utilisée par l’installateur.
|
||||
- **Valeurs littérales.** La valeur est écrite exactement comme vous l’avez fournie — aucun rendu de template `result:`. Pour obtenir la valeur résolue (ex. `{project-root}/research`), passez-la explicitement : `--set bmm.project_knowledge='{project-root}/research'`.
|
||||
- **Valeurs littérales.** La valeur est écrite exactement comme vous l’avez fournie — aucun rendu de template `result:`. Pour obtenir la valeur résolue (ex. `{project-root}/research`), passez-la explicitement : `--set bmm.project_knowledge='{project-root}/research'`.
|
||||
- **Persistance, clés déclarées.** Les valeurs pour les clés déclarées dans `module.yaml` sont conservées entre les installations car elles sont aussi écrites dans `_bmad/<module>/config.yaml`, que l’installateur lit comme valeur par défaut de l’invite lors de la prochaine exécution.
|
||||
- **Persistance, clés non déclarées.** Une valeur pour une clé que le schéma du module ne déclare pas est enregistrée dans `config.toml` pour l’installation courante mais ne sera pas réécrite à la prochaine installation (le partitionneur strict au schéma du manifeste ignore les clés inconnues). Repassez `--set` pour qu’elle soit persistante, ou éditez `_bmad/config.toml` directement.
|
||||
- **Pas de validation.** Les valeurs `single-select` ne sont pas vérifiées contre les choix autorisés, et les clés inconnues ne sont pas rejetées — la valeur fournie est écrite telle quelle.
|
||||
|
|
@ -221,7 +221,7 @@ Les raccourcis historiques de core (`--user-name`, `--output-folder`, etc.) fonc
|
|||
:::caution[Limitation de débit sur les IPs partagées]
|
||||
Les appels anonymes à l’API GitHub sont limités à 60/heure par IP. Une seule installation fait un appel API par module externe pour résoudre le tag stable. Les bureaux derrière NAT, les pools de runners CI et les VPN peuvent collectivement épuiser cette limite.
|
||||
|
||||
Définissez `GITHUB_TOKEN=<personal access token>` dans l’environnement pour augmenter la limite à 5000/heure par compte. Tout PAT avec accès en lecture aux dépôts publics fonctionne ; aucune portée spécifique n’est requise.
|
||||
Définissez `GITHUB_TOKEN=<personal access token>` dans l’environnement pour augmenter la limite à 5 000/heure par compte. Tout PAT avec accès en lecture aux dépôts publics fonctionne ; aucune portée spécifique n’est requise.
|
||||
:::
|
||||
|
||||
## Ce qui a été installé
|
||||
|
|
|
|||
|
|
@ -109,10 +109,10 @@ Plusieurs sources peuvent être séparées par des virgules :
|
|||
|
||||
L’installateur utilise deux modes pour trouver les modules installables dans une source :
|
||||
|
||||
| Mode | Déclencheur | Comportement |
|
||||
| ----------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| Découverte | La source contient `.claude-plugin/marketplace.json` | Liste tous les plugins du manifeste ; vous choisissez lesquels installer |
|
||||
| Direct | Aucun `marketplace.json` trouvé | Analyse le répertoire pour trouver des skills (sous-répertoires avec `SKILL.md`), les résout en un module unique |
|
||||
| Mode | Déclencheur | Comportement |
|
||||
|------------|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
|
||||
| Découverte | La source contient `.claude-plugin/marketplace.json` | Liste tous les plugins du manifeste ; vous choisissez lesquels installer |
|
||||
| Direct | Aucun `marketplace.json` trouvé | Analyse le répertoire pour trouver des skills (sous-répertoires avec `SKILL.md`), les résout en un module unique |
|
||||
|
||||
Le mode découverte est typique des modules publiés. Le mode direct est pratique pour pointer vers un répertoire de skills pendant le développement local.
|
||||
|
||||
|
|
@ -162,8 +162,8 @@ Le manifeste enregistre la source de chaque module personnalisé (`repoUrl` pour
|
|||
|
||||
Les modules personnalisés participent au flux de mise à jour normal :
|
||||
|
||||
- **Mise à jour rapide** (`--action quick-update`) : Rafraîchit tous les modules depuis leurs sources d’origine. Les modules Git sont re-téléchargés ; les modules locaux sont relus depuis leur chemin source.
|
||||
- **Mise à jour complète** : Relance la sélection de modules pour que vous puissiez ajouter ou retirer des modules personnalisés.
|
||||
- **Mise à jour rapide** (`--action quick-update`) : Rafraîchit tous les modules depuis leurs sources d’origine. Les modules Git sont re-téléchargés ; les modules locaux sont relus depuis leur chemin source.
|
||||
- **Mise à jour complète** : Relance la sélection de modules pour que vous puissiez ajouter ou retirer des modules personnalisés.
|
||||
|
||||
## Créer vos propres modules
|
||||
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ Utilisez le fichier `project-context.md` pour garantir que les agents IA respect
|
|||
- Vous travaillez sur une base de code existante avec des patterns établis
|
||||
- Vous remarquez que les agents prennent des décisions incohérentes entre les stories
|
||||
|
||||
## Étape 1 : Choisissez votre approche
|
||||
## Étape 1 : Choisissez votre approche
|
||||
|
||||
**Création manuelle** — Idéal lorsque vous savez exactement quelles règles vous souhaitez documenter
|
||||
|
||||
|
|
@ -27,9 +27,9 @@ Utilisez le fichier `project-context.md` pour garantir que les agents IA respect
|
|||
|
||||
**Génération pour les projets existants** — Idéal pour découvrir les patterns dans les bases de code existantes
|
||||
|
||||
## Étape 2 : Créez le fichier
|
||||
## Étape 2 : Créez le fichier
|
||||
|
||||
### Option A : Création manuelle
|
||||
### Option A : Création manuelle
|
||||
|
||||
Créez le fichier à l’emplacement `_bmad-output/project-context.md` :
|
||||
|
||||
|
|
@ -72,7 +72,7 @@ sections_completed: ['technology_stack', 'critical_rules']
|
|||
- Tests d'intégration utilisent MSW pour le mock API
|
||||
```
|
||||
|
||||
### Option B : Génération après l’architecture
|
||||
### Option B : Génération après l’architecture
|
||||
|
||||
Exécutez le workflow dans une nouvelle conversation :
|
||||
|
||||
|
|
@ -82,7 +82,7 @@ bmad-generate-project-context
|
|||
|
||||
Le workflow analyse votre document d’architecture et vos fichiers projet pour générer un fichier de contexte qui capture les décisions prises.
|
||||
|
||||
### Option C : Génération pour les projets existants
|
||||
### Option C : Génération pour les projets existants
|
||||
|
||||
Pour les projets existants, exécutez :
|
||||
|
||||
|
|
@ -92,7 +92,7 @@ bmad-generate-project-context
|
|||
|
||||
Le workflow analyse votre base de code pour identifier les conventions, puis génère un fichier de contexte que vous pouvez réviser et affiner.
|
||||
|
||||
## Étape 3 : Vérifiez le contenu
|
||||
## Étape 3 : Vérifiez le contenu
|
||||
|
||||
Révisez le fichier généré et assurez-vous qu’il capture :
|
||||
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ Les nouveaux skills v6 sont installés dans :
|
|||
|
||||
### 4. Migrer les artefacts de planification
|
||||
|
||||
**Si vous avez des documents de planification (Brief/PRD/UX/Architecture) :**
|
||||
**Si vous avez des documents de planification (Brief/PRD/UX/Architecture) :**
|
||||
|
||||
Déplacez-les dans `_bmad-output/planning-artifacts/` avec des noms descriptifs :
|
||||
|
||||
|
|
@ -53,7 +53,7 @@ Déplacez-les dans `_bmad-output/planning-artifacts/` avec des noms descriptifs
|
|||
- Incluez `brief`, `architecture`, ou `ux-design` selon le cas
|
||||
- Les documents divisés peuvent être dans des sous-dossiers au nom descriptif
|
||||
|
||||
**Si vous êtes en cours de planification :** Envisagez de recommencer avec les workflows v6. Utilisez vos documents existants comme entrées — les nouveaux workflows de découverte progressive avec recherche web et le mode plan de l’IDE produisent de meilleurs résultats.
|
||||
**Si vous êtes en cours de planification :** Envisagez de recommencer avec les workflows v6. Utilisez vos documents existants comme entrées — les nouveaux workflows de découverte progressive avec recherche web et le mode plan de l’IDE produisent de meilleurs résultats.
|
||||
|
||||
### 5. Migrer le développement en cours
|
||||
|
||||
|
|
@ -66,7 +66,7 @@ Si vous avez des stories[^3] créées ou implémentées :
|
|||
|
||||
## Résultat de la migration
|
||||
|
||||
**Structure unifiée v6 :**
|
||||
**Structure unifiée v6 :**
|
||||
|
||||
```text
|
||||
votre-projet/
|
||||
|
|
@ -82,22 +82,22 @@ votre-projet/
|
|||
|
||||
## Migration des modules
|
||||
|
||||
| Module v4 | Statut v6 |
|
||||
| ----------------------------- | ------------------------------------------------------ |
|
||||
| `.bmad-2d-phaser-game-dev` | Intégré dans le Module BMGD |
|
||||
| `.bmad-2d-unity-game-dev` | Intégré dans le Module BMGD |
|
||||
| `.bmad-godot-game-dev` | Intégré dans le Module BMGD |
|
||||
| `.bmad-infrastructure-devops` | Obsolète — nouvel agent DevOps bientôt disponible |
|
||||
| `.bmad-creative-writing` | Non migré — nouveau module v6 bientôt disponible |
|
||||
| Module v4 | Statut v6 |
|
||||
|-------------------------------|---------------------------------------------------|
|
||||
| `.bmad-2d-phaser-game-dev` | Intégré dans le Module BMGD |
|
||||
| `.bmad-2d-unity-game-dev` | Intégré dans le Module BMGD |
|
||||
| `.bmad-godot-game-dev` | Intégré dans le Module BMGD |
|
||||
| `.bmad-infrastructure-devops` | Obsolète — nouvel agent DevOps bientôt disponible |
|
||||
| `.bmad-creative-writing` | Non migré — nouveau module v6 bientôt disponible |
|
||||
|
||||
## Changements clés
|
||||
|
||||
| Concept | v4 | v6 |
|
||||
| ------------- | ------------------------------------- | ------------------------------------ |
|
||||
| Concept | v4 | v6 |
|
||||
|---------------|---------------------------------------------------------|------------------------------------------|
|
||||
| **Core** | `_bmad-core` correspondait en réalité à la méthode BMad | `_bmad/core/` est le framework universel |
|
||||
| **Method** | `_bmad-method` | `_bmad/bmm/` |
|
||||
| **Config** | Fichiers modifiés directement | `config.yaml` par module |
|
||||
| **Documents** | Division en fragments obligatoire ou optionnelle | Totalement flexible, analyse automatique |
|
||||
| **Method** | `_bmad-method` | `_bmad/bmm/` |
|
||||
| **Config** | Fichiers modifiés directement | `config.yaml` par module |
|
||||
| **Documents** | Division en fragments obligatoire ou optionnelle | Totalement flexible, analyse automatique |
|
||||
|
||||
|
||||
## Glossaire
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ BMad fonctionne avec tout assistant de codage IA qui prend en charge les prompts
|
|||
- **[Cursor](https://cursor.sh)** — Éditeur de code propulsé par l’IA
|
||||
- **[Codex CLI](https://github.com/openai/codex)** — Agent de codage en ligne de commande d’OpenAI
|
||||
|
||||
Vous devriez être à l’aise avec les concepts de base du développement logiciel : gestion de versions, structure de projet et méthodologies agiles. Aucune expérience préalable des systèmes d’agents de type BMad n’est requise — c’est précisément l’objet de cette documentation.
|
||||
Vous devriez être à l’aise avec les concepts de base du développement logiciel : gestion de versions, structure de projet et méthodologies agiles. Aucune expérience préalable des systèmes d’agents de type BMad n’est requise — c’est précisément l’objet de cette documentation.
|
||||
|
||||
## Rejoindre la communauté
|
||||
|
||||
|
|
|
|||
|
|
@ -32,21 +32,21 @@ Les déclencheurs de menu d’agent utilisent deux types d’invocation différe
|
|||
|
||||
La plupart des déclencheurs chargent un fichier de workflow structuré. Tapez le code du déclencheur et l’agent démarre le workflow, vous demandant de saisir les informations à chaque étape.
|
||||
|
||||
Exemples : `CP` (Create PRD), `DS` (Dev Story), `CA` (Create Architecture), `QD` (Quick Dev)
|
||||
Exemples : `CP` (Create PRD), `DS` (Dev Story), `CA` (Create Architecture), `QD` (Quick Dev)
|
||||
|
||||
### Déclencheurs conversationnels (arguments requis)
|
||||
|
||||
Certains déclencheurs lancent une conversation libre au lieu d’un workflow structuré. Ils s’attendent à ce que vous décriviez ce dont vous avez besoin à côté du code du déclencheur.
|
||||
|
||||
| Agent | Déclencheur | Ce qu’il faut fournir |
|
||||
| --- | --- | --- |
|
||||
| Rédacteur Technique (Paige) | `WD` | Description du document à rédiger |
|
||||
| Rédacteur Technique (Paige) | `US` | Préférences ou conventions à ajouter aux standards |
|
||||
| Rédacteur Technique (Paige) | `MG` | Description et type de diagramme (séquence, organigramme, etc.) |
|
||||
| Rédacteur Technique (Paige) | `VD` | Document à valider et domaines à examiner |
|
||||
| Rédacteur Technique (Paige) | `EC` | Nom du concept à expliquer |
|
||||
| Agent | Déclencheur | Ce qu’il faut fournir |
|
||||
|-----------------------------|-------------|-----------------------------------------------------------------|
|
||||
| Rédacteur Technique (Paige) | `WD` | Description du document à rédiger |
|
||||
| Rédacteur Technique (Paige) | `US` | Préférences ou conventions à ajouter aux standards |
|
||||
| Rédacteur Technique (Paige) | `MG` | Description et type de diagramme (séquence, organigramme, etc.) |
|
||||
| Rédacteur Technique (Paige) | `VD` | Document à valider et domaines à examiner |
|
||||
| Rédacteur Technique (Paige) | `EC` | Nom du concept à expliquer |
|
||||
|
||||
**Exemple :**
|
||||
**Exemple :**
|
||||
|
||||
```text
|
||||
WD Rédige un guide de déploiement pour notre configuration Docker
|
||||
|
|
|
|||
|
|
@ -11,9 +11,9 @@ Les skills sont des prompts pré-construits qui chargent des agents, exécutent
|
|||
|
||||
BMad offre deux façons de démarrer un travail, chacune ayant un usage différent.
|
||||
|
||||
| Mécanisme | Comment l’invoquer | Ce qui se passe |
|
||||
| --- | --- | --- |
|
||||
| **Skill** | Tapez le nom du skill (ex. `bmad-help`) dans votre IDE | Charge directement un agent, exécute un workflow ou lance une tâche |
|
||||
| Mécanisme | Comment l’invoquer | Ce qui se passe |
|
||||
|-------------------------------|---------------------------------------------------------------|------------------------------------------------------------------------------------------------|
|
||||
| **Skill** | Tapez le nom du skill (ex. `bmad-help`) dans votre IDE | Charge directement un agent, exécute un workflow ou lance une tâche |
|
||||
| **Déclencheur du menu agent** | Chargez d’abord un agent, puis tapez un code court (ex. `DS`) | L’agent interprète le code et démarre le workflow correspondant tout en préservant son persona |
|
||||
|
||||
Les déclencheurs du menu agent nécessitent une session agent active. Utilisez les skills lorsque vous savez quel workflow vous voulez. Utilisez les déclencheurs lorsque vous travaillez déjà avec un agent et souhaitez changer de tâche sans quitter la conversation.
|
||||
|
|
@ -24,12 +24,12 @@ Lorsque vous exécutez `npx bmad-method install`, l’installateur lit les manif
|
|||
|
||||
L’installateur utilise des modèles pour chaque type de skill :
|
||||
|
||||
| Type de skill | Ce que fait le fichier généré |
|
||||
| --- | --- |
|
||||
| **Lanceur d’agent** | Charge le fichier de persona de l’agent, active son menu et reste en caractère |
|
||||
| **Skill de workflow** | Charge la configuration du workflow et suit ses étapes |
|
||||
| **Skill de tâche** | Charge un fichier de tâche autonome et suit ses instructions |
|
||||
| **Skill d’outil** | Charge un fichier d’outil autonome et suit ses instructions |
|
||||
| Type de skill | Ce que fait le fichier généré |
|
||||
|-----------------------|--------------------------------------------------------------------------------|
|
||||
| **Lanceur d’agent** | Charge le fichier de persona de l’agent, active son menu et reste en caractère |
|
||||
| **Skill de workflow** | Charge la configuration du workflow et suit ses étapes |
|
||||
| **Skill de tâche** | Charge un fichier de tâche autonome et suit ses instructions |
|
||||
| **Skill d’outil** | Charge un fichier d’outil autonome et suit ses instructions |
|
||||
|
||||
:::note[Relancer l’installateur]
|
||||
Si vous ajoutez ou supprimez des modules, relancez l’installateur. Il régénère tous les fichiers de skill pour correspondre à votre sélection actuelle de modules.
|
||||
|
|
@ -39,12 +39,12 @@ Si vous ajoutez ou supprimez des modules, relancez l’installateur. Il régén
|
|||
|
||||
L’installateur écrit les fichiers de skill dans un répertoire spécifique à l’IDE à l’intérieur de votre projet. Le chemin exact dépend de l’IDE que vous avez sélectionné lors de l’installation.
|
||||
|
||||
| IDE / CLI | Répertoire des skills |
|
||||
| --- | --- |
|
||||
| Claude Code | `.claude/skills/` |
|
||||
| Cursor | `.cursor/skills/` |
|
||||
| Windsurf | `.windsurf/skills/` |
|
||||
| Autres IDE | Consultez la sortie de l’installateur pour le chemin cible |
|
||||
| IDE / CLI | Répertoire des skills |
|
||||
|-------------|------------------------------------------------------------|
|
||||
| Claude Code | `.claude/skills/` |
|
||||
| Cursor | `.cursor/skills/` |
|
||||
| Windsurf | `.windsurf/skills/` |
|
||||
| Autres IDE | Consultez la sortie de l’installateur pour le chemin cible |
|
||||
|
||||
Chaque skill est un répertoire contenant un fichier `SKILL.md`. Par exemple, une installation Claude Code ressemble à :
|
||||
|
||||
|
|
@ -89,16 +89,16 @@ Consultez [Agents](./agents.md) pour la liste complète des agents par défaut e
|
|||
|
||||
Les skills de workflow exécutent un processus structuré en plusieurs étapes sans charger d’abord un persona d’agent. Ils chargent une configuration de workflow et suivent ses étapes.
|
||||
|
||||
| Exemple de skill | Objectif |
|
||||
| --- | --- |
|
||||
| `bmad-product-brief` | Créer ou mettre à jour un product brief[^3] — découverte guidée lorsque votre concept est clair |
|
||||
| `bmad-prfaq` | Défi [PRFAQ Working Backwards](../explanation/analysis-phase.md#prfaq-working-backwards) pour éprouver votre concept produit |
|
||||
| `bmad-prd` | Créer, mettre à jour ou valider un PRD[^1] |
|
||||
| `bmad-create-architecture` | Concevoir l’architecture système |
|
||||
| `bmad-create-epics-and-stories` | Créer des epics et des stories |
|
||||
| `bmad-dev-story` | Implémenter une story |
|
||||
| `bmad-code-review` | Effectuer une revue de code |
|
||||
| `bmad-quick-dev` | Flux rapide unifié — clarifier l’intention, planifier, implémenter, réviser, présenter |
|
||||
| Exemple de skill | Objectif |
|
||||
|---------------------------------|------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `bmad-product-brief` | Créer ou mettre à jour un product brief[^3] — découverte guidée lorsque votre concept est clair |
|
||||
| `bmad-prfaq` | Défi [PRFAQ Working Backwards](../explanation/analysis-phase.md#prfaq-working-backwards) pour éprouver votre concept produit |
|
||||
| `bmad-prd` | Créer, mettre à jour ou valider un PRD[^1] |
|
||||
| `bmad-create-architecture` | Concevoir l’architecture système |
|
||||
| `bmad-create-epics-and-stories` | Créer des epics et des stories |
|
||||
| `bmad-dev-story` | Implémenter une story |
|
||||
| `bmad-code-review` | Effectuer une revue de code |
|
||||
| `bmad-quick-dev` | Flux rapide unifié — clarifier l’intention, planifier, implémenter, réviser, présenter |
|
||||
|
||||
Consultez la [Carte des workflows](./workflow-map.md) pour la référence complète des workflows organisés par phase.
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ Consultez la [Carte des workflows](./workflow-map.md) pour la référence compl
|
|||
|
||||
Les tâches et outils sont des opérations autonomes qui ne nécessitent pas de contexte d’agent ou de workflow.
|
||||
|
||||
**BMad-Help : Votre guide intelligent**
|
||||
**BMad-Help : Votre guide intelligent**
|
||||
|
||||
`bmad-help` est votre interface principale pour découvrir quoi faire ensuite. Il inspecte votre projet, comprend les requêtes en langage naturel et recommande la prochaine étape requise ou optionnelle en fonction de vos modules installés.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ sidebar:
|
|||
order: 3
|
||||
---
|
||||
|
||||
Chaque installation BMad comprend un ensemble de compétences principales qui peuvent être utilisées conjointement avec tout ce que vous faites — des tâches et des workflows autonomes qui fonctionnent dans tous les projets, tous les modules et toutes les phases. Ceux-ci sont toujours disponibles, quels que soient les modules optionnels que vous installez.
|
||||
Chaque installation BMad comprend un ensemble de compétences principales utilisables en complément de tout ce que vous faites — des tâches et des workflows autonomes qui fonctionnent dans tous les projets, tous les modules et toutes les phases. Elles restent toujours disponibles, quels que soient les modules optionnels que vous installez.
|
||||
|
||||
:::tip[Raccourci Rapide]
|
||||
Exécutez n’importe quel outil principal en tapant son nom de compétence (par ex., `bmad-help`) dans votre IDE. Aucune session d’agent requise.
|
||||
|
|
@ -13,63 +13,63 @@ Exécutez n’importe quel outil principal en tapant son nom de compétence (par
|
|||
|
||||
## Vue d’ensemble
|
||||
|
||||
| Outil | Type | Objectif |
|
||||
|-----------------------------------------------------------------------|----------|------------------------------------------------------------------------------|
|
||||
| [`bmad-help`](#bmad-help) | Tâche | Obtenir des conseils contextuels sur la prochaine étape |
|
||||
| [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Faciliter des sessions de brainstorming interactives |
|
||||
| [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrer des discussions de groupe multi-agents |
|
||||
| [`bmad-distillator`](#bmad-distillator) | Tâche | Compression sans perte optimisée pour LLM de documents |
|
||||
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Tâche | Pousser la sortie LLM à travers des méthodes de raffinement itératives |
|
||||
| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Tâche | Revue cynique qui trouve ce qui manque et ce qui ne va pas |
|
||||
| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Tâche | Analyse exhaustive des chemins de branchement pour les cas limites non gérés |
|
||||
| [`bmad-editorial-review-prose`](#bmad-editorial-review-prose) | Tâche | Révision de copie clinique pour la clarté de communication |
|
||||
| [`bmad-editorial-review-structure`](#bmad-editorial-review-structure) | Tâche | Édition structurelle — coupes, fusions et réorganisation |
|
||||
| [`bmad-shard-doc`](#bmad-shard-doc) | Tâche | Diviser les fichiers markdown volumineux en sections organisées |
|
||||
| [`bmad-index-docs`](#bmad-index-docs) | Tâche | Générer ou mettre à jour un index de tous les documents dans un dossier |
|
||||
| Outil | Type | Objectif |
|
||||
|-----------------------------------------------------------------------|----------|-------------------------------------------------------------------------------|
|
||||
| [`bmad-help`](#bmad-help) | Tâche | Obtenir des conseils contextuels sur la prochaine étape |
|
||||
| [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Faciliter des sessions de brainstorming interactives |
|
||||
| [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrer des discussions de groupe multi-agents |
|
||||
| [`bmad-spec`](#bmad-spec) | Workflow | Distiller toute formulation d’intention en un noyau SPEC et fichiers associés |
|
||||
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Tâche | Soumettre la sortie LLM à des méthodes de raffinement itératives |
|
||||
| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Tâche | Revue cynique qui traque ce qui manque et ce qui ne va pas |
|
||||
| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Tâche | Analyse exhaustive des chemins de branchement pour les cas limites non gérés |
|
||||
| [`bmad-editorial-review-prose`](#bmad-editorial-review-prose) | Tâche | Correction éditoriale clinique pour la clarté de communication |
|
||||
| [`bmad-editorial-review-structure`](#bmad-editorial-review-structure) | Tâche | Édition structurelle — coupes, fusions et réorganisation |
|
||||
| [`bmad-shard-doc`](#bmad-shard-doc) | Tâche | Diviser les fichiers markdown volumineux en sections organisées |
|
||||
| [`bmad-index-docs`](#bmad-index-docs) | Tâche | Générer ou mettre à jour un index de tous les documents dans un dossier |
|
||||
|
||||
## bmad-help
|
||||
|
||||
**Votre guide intelligent pour la suite.** — Inspecte l’état de votre projet, détecte ce qui a été fait et recommande la prochaine étape requise ou facultative.
|
||||
|
||||
**Utilisez-le quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- Vous avez terminé un workflow et voulez savoir ce qui suit
|
||||
- Vous avez terminé un workflow et voulez savoir quoi faire ensuite
|
||||
- Vous êtes nouveau sur BMad et avez besoin d’orientation
|
||||
- Vous êtes bloqué et voulez des conseils contextuels
|
||||
- Vous avez installé de nouveaux modules et voulez voir ce qui est disponible
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Analyse votre projet pour les artefacts existants (PRD, architecture, stories, etc.)
|
||||
1. Analyse votre projet pour détecter les artefacts existants (PRD, architecture, stories, etc.)
|
||||
2. Détecte quels modules sont installés et leurs workflows disponibles
|
||||
3. Recommande les prochaines étapes par ordre de priorité — étapes requises d’abord, puis facultatives
|
||||
4. Présente chaque recommandation avec la commande de compétence et une brève description
|
||||
|
||||
**Entrée :** Requête optionnelle en langage naturel (par ex., `bmad-help J'ai une idée de SaaS, par où commencer ?`)
|
||||
**Entrée :** Requête optionnelle en langage naturel (par ex., `bmad-help J'ai une idée de SaaS, par où commencer ?`)
|
||||
|
||||
**Sortie :** Liste priorisée des prochaines étapes recommandées avec les commandes de compétence
|
||||
**Sortie :** Liste priorisée des prochaines étapes recommandées avec les commandes de compétence
|
||||
|
||||
## bmad-brainstorming
|
||||
|
||||
**Génère des idées diverses à travers des techniques créatives interactives.** — Une session de brainstorming facilitée qui charge des méthodes d’idéation éprouvées depuis une bibliothèque de techniques et vous guide vers plus de 100 idées avant organisation.
|
||||
**Génère des idées variées grâce à des techniques créatives interactives.** — Une session de brainstorming facilitée qui charge des méthodes d’idéation éprouvées à partir d’une bibliothèque de techniques et vous guide vers plus de 100 idées avant de les organiser.
|
||||
|
||||
**Utilisez-le quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- Vous commencez un nouveau projet et devez explorer l’espace problème
|
||||
- Vous êtes bloqué dans la génération d’idées et avez besoin de créativité structurée
|
||||
- Vous voulez utiliser des cadres d’idéation éprouvés (SCAMPER, brainstorming inversé, etc.)
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Configure une session de brainstorming avec votre sujet
|
||||
2. Charge les techniques créatives depuis une bibliothèque de méthodes
|
||||
3. Vous guide à travers technique après technique, générant des idées
|
||||
4. Applique un protocole anti-biais — change de domaine créatif toutes les 10 idées pour éviter le regroupement
|
||||
2. Charge les techniques créatives à partir d’une bibliothèque de méthodes
|
||||
3. Vous guide de technique en technique, en générant des idées
|
||||
4. Applique un protocole anti-biais — bascule de domaine créatif toutes les 10 idées pour éviter les biais de regroupement
|
||||
5. Produit un document de session en mode ajout uniquement avec toutes les idées organisées par technique
|
||||
|
||||
**Entrée :** Sujet de brainstorming ou énoncé de problème, fichier de contexte optionnel
|
||||
**Entrée :** Sujet de brainstorming ou énoncé de problème, fichier de contexte optionnel
|
||||
|
||||
**Sortie :** `brainstorming-session-{date}.md` avec toutes les idées générées
|
||||
**Sortie :** `brainstorming-session-{date}.md` avec toutes les idées générées
|
||||
|
||||
:::note[Cible de Quantité]
|
||||
La magie se produit dans les idées 50–100. Le workflow encourage la génération de plus de 100 idées avant organisation.
|
||||
|
|
@ -77,122 +77,127 @@ La magie se produit dans les idées 50–100. Le workflow encourage la générat
|
|||
|
||||
## bmad-party-mode
|
||||
|
||||
**Orchestre des discussions de groupe multi-agents.** — Charge tous les agents BMad installés et facilite une conversation naturelle où chaque agent contribue depuis son expertise et personnalité uniques.
|
||||
**Orchestre des discussions de groupe multi-agents.** — Charge tous les agents BMad installés et facilite une conversation naturelle où chaque agent apporte son expertise et sa personnalité uniques.
|
||||
|
||||
**Utilisez-le quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- Vous avez besoin de multiples perspectives d’experts sur une décision
|
||||
- Vous voulez que les agents remettent en question les hypothèses des autres
|
||||
- Vous explorez un sujet complexe qui couvre plusieurs domaines
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Charge le manifeste d’agents avec toutes les personnalités d’agents installées
|
||||
2. Analyse votre sujet pour sélectionner les 2–3 agents les plus pertinents
|
||||
3. Les agents prennent des tours pour contribuer, avec des échanges naturels et des désaccords
|
||||
4. Fait rouler la participation des agents pour assurer des perspectives diverses au fil du temps
|
||||
3. Les agents contribuent à tour de rôle, avec des échanges spontanés et des désaccords
|
||||
4. Alterne la participation des agents pour garantir des perspectives variées
|
||||
5. Quittez avec `goodbye`, `end party` ou `quit`
|
||||
|
||||
**Entrée :** Sujet de discussion ou question, ainsi que la spécification des personas que vous souhaitez faire participer (optionnel)
|
||||
**Entrée :** Sujet de discussion ou question, ainsi que la spécification des personas que vous souhaitez faire participer (optionnel)
|
||||
|
||||
**Sortie :** Conversation multi-agents en temps réel avec des personnalités d’agents maintenues
|
||||
**Sortie :** Conversation multi-agents en temps réel conservant la personnalité de chaque agent
|
||||
|
||||
## bmad-distillator
|
||||
## bmad-spec
|
||||
|
||||
**Compression sans perte optimisée pour LLM de documents sources.** — Produit des distillats denses et efficaces en tokens qui préservent toute l’information pour la consommation par des LLM en aval. Vérifiable par reconstruction aller-retour.
|
||||
**Distille toute formulation d’intention en un contrat SPEC canonique pour le travail en aval.** — Accepte un brief, un PRD, un GDD, un RFC, un brain dump, une transcription, un dossier UX ou une entrée multi-source mixte et produit un `SPEC.md` structuré autour d’un noyau de cinq champs (Pourquoi, Capacités, Contraintes, Non-objectifs, Signal de succès) ainsi que des fichiers compagnons pour le contenu essentiel qui ne trouve pas sa place dans le noyau.
|
||||
|
||||
**Utilisez-le quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- Un document est trop volumineux pour la fenêtre de contexte d’un LLM
|
||||
- Vous avez besoin de versions économes en tokens de recherches, spécifications ou artefacts de planification
|
||||
- Vous voulez vérifier qu’aucune information n’est perdue pendant la compression
|
||||
- Les agents auront besoin de référencer et de trouver fréquemment des informations dedans
|
||||
- Vous devez verrouiller le QUOI avant le COMMENT pour tout type de travail (logiciel, game design, recherche, éditorial, politique, entreprise)
|
||||
- Vous souhaitez un contrat succinct optimisé pour les LLM, sans fioritures, que les compétences en aval peuvent consommer sans relire chaque artefact en amont
|
||||
- Vous voulez valider ou mettre à jour une spécification existante
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. **Analyser** — Lit les documents sources, identifie la densité d’information et la structure
|
||||
2. **Compresser** — Convertit la prose en format dense de liste de points, supprime le formatage décoratif
|
||||
3. **Vérifier** — Vérifie l’exhaustivité pour s’assurer que toute l’information originale est préservée
|
||||
4. **Valider** (optionnel) — Le test de reconstruction aller-retour prouve la compression sans perte
|
||||
1. Lit l’entrée et tout document annexe lié
|
||||
2. Distille en un noyau à cinq champs via un modèle configurable ; redirige l’excédent vers des fichiers compagnons correctement nommés
|
||||
3. Exécute une auto-validation en deux passes (règles de cohérence, puis préservation de chaque affirmation essentielle de la source)
|
||||
4. Écrit `SPEC.md`, les compagnons associés, et un `.decision-log.md` sous `{output_folder}/specs/spec-{slug}/`
|
||||
|
||||
**Entrée :**
|
||||
La loi Spec impose huit règles : les capacités expriment à la fois l’intention et le critère de succès ; les intentions décrivent le QUOI, pas le COMMENT ; les contraintes guident réellement les décisions ; les non-objectifs sont explicites ; les signaux de succès sont concrets ; les identifiants de capacité sont stables ; chaque affirmation essentielle de la source est préservée ; la rédaction est concise.
|
||||
|
||||
- `source_documents` (requis) — Chemins de fichiers, chemins de dossiers ou motifs glob
|
||||
- `downstream_consumer` (optionnel) — Ce qui va le consommer (par ex., « création de PRD »)
|
||||
- `token_budget` (optionnel) — Taille cible approximative
|
||||
- `--validate` (drapeau) — Exécuter le test de reconstruction aller-retour
|
||||
**Entrée :**
|
||||
|
||||
- `input` (requis) — Chemin ou texte fourni directement. Idée vague, brain dump, PRD, GDD, RFC, brief, transcription, dossier de maquettes, multi-source mixte
|
||||
- `slug` (optionnel) — Requis uniquement lorsque l’entrée est succincte et qu’aucun slug ne peut être dérivé du nom de fichier source
|
||||
- `target_spec_path` (optionnel) — Définir pour mettre à jour une spécification existante au lieu d’en créer une nouvelle
|
||||
|
||||
**Sortie :** Dossier de spécification contenant `SPEC.md`, les éventuels fichiers compagnons, et un `.decision-log.md`. Les appelants en mode headless reçoivent une réponse JSON avec le statut du résultat et la liste des fichiers écrits ou modifiés.
|
||||
|
||||
:::note[Contrat de mutation]
|
||||
`bmad-spec` est le seul outil autorisé à écrire `SPEC.md` et les fichiers compagnons de la spécification. Les autres compétences produisent leurs propres artefacts natifs et invoquent `bmad-spec` en mode headless lorsqu’elles ont besoin d’exprimer une intention sous forme de contrat canonique ou de proposer des mises à jour.
|
||||
:::
|
||||
|
||||
**Sortie :** Fichier(s) markdown distillé(s) avec rapport de ratio de compression (par ex., "3.2:1")
|
||||
|
||||
## bmad-advanced-elicitation
|
||||
|
||||
**Passer la sortie du LLM à travers des méthodes de raffinement itératives.** — Sélectionne depuis une bibliothèque de techniques d’élicitation pour améliorer systématiquement le contenu à travers multiples passages.
|
||||
**Soumet la sortie du LLM à des méthodes de raffinement itératives.** — Sélectionne à partir d’une bibliothèque de techniques d’élicitation pour améliorer systématiquement le contenu en plusieurs passages.
|
||||
|
||||
**Utilisez-le quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- La sortie du LLM semble superficielle ou générique
|
||||
- Vous voulez explorer un sujet depuis de multiples angles analytiques
|
||||
- Vous raffinez un document critique et voulez une réflexion plus approfondie
|
||||
- Vous voulez explorer un sujet sous plusieurs angles analytiques
|
||||
- Vous raffinez un document critique et souhaitez une réflexion plus approfondie
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Charge le registre de méthodes avec plus de 5 techniques d’élicitation
|
||||
2. Sélectionne les 5 méthodes les mieux adaptées selon le type de contenu et la complexité
|
||||
3. Présente un menu interactif — choisissez une méthode, remélangez, ou listez tout
|
||||
4. Applique la méthode sélectionnée pour améliorer le contenu
|
||||
5. Re-présente les options pour l’amélioration itérative jusqu’à ce que vous sélectionniez « Procéder »
|
||||
5. Affiche à nouveau les options d’amélioration itérative jusqu’à ce que vous sélectionniez « Procéder »
|
||||
|
||||
**Entrée :** Section de contenu à améliorer
|
||||
**Entrée :** Section de contenu à améliorer
|
||||
|
||||
**Sortie :** Version améliorée du contenu avec les améliorations appliquées
|
||||
**Sortie :** Version améliorée du contenu avec les améliorations appliquées
|
||||
|
||||
## bmad-review-adversarial-general
|
||||
|
||||
**Revue contradictoire qui suppose que des problèmes existent et les recherche.** — Adopte une perspective de réviseur sceptique et blasé avec zéro tolérance pour le travail bâclé. Cherche ce qui manque, pas seulement ce qui ne va pas.
|
||||
**Revue contradictoire qui part du principe que des problèmes existent et les traque.** — Adopte un regard de réviseur sceptique et blasé, sans aucune tolérance pour le travail bâclé. Cherche ce qui manque, pas seulement ce qui ne va pas.
|
||||
|
||||
**Utilisez-le quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- Vous avez besoin d’assurance qualité avant de finaliser un livrable
|
||||
- Vous voulez tester en conditions réelles une spécification, story ou document
|
||||
- Vous voulez éprouver une spécification, une story ou un document
|
||||
- Vous voulez trouver des lacunes de couverture que les revues optimistes manquent
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Lit le contenu avec une perspective contradictoire et critique
|
||||
2. Identifie les problèmes à travers l’exhaustivité, la justesse et la qualité
|
||||
1. Lit le contenu avec un regard contradictoire et critique
|
||||
2. Identifie les problèmes sur les plans de l’exhaustivité, de la justesse et de la qualité
|
||||
3. Recherche spécifiquement ce qui manque — pas seulement ce qui est présent et faux
|
||||
4. Doit trouver un minimum de 10 problèmes ou réanalyse plus profondément
|
||||
4. Doit trouver un minimum de 10 problèmes ou réanalyser plus en profondeur
|
||||
|
||||
**Entrée :**
|
||||
**Entrée :**
|
||||
|
||||
- `content` (requis) — Diff, spécification, story, document ou tout artefact
|
||||
- `also_consider` (optionnel) — Domaines supplémentaires à garder à l’esprit
|
||||
|
||||
**Sortie :** Liste markdown de plus de 10 constatations avec descriptions
|
||||
**Sortie :** Liste markdown de plus de 10 constatations avec descriptions
|
||||
|
||||
## bmad-review-edge-case-hunter
|
||||
|
||||
**Parcours tous les chemins de branchement et les conditions limites, ne rapporte que les cas non gérés.** — Méthodologie pure de traçage de chemin[^1] qui dérive mécaniquement les classes de cas limites. Orthogonale à la revue contradictoire — centrée sur la méthode, pas sur l’attitude.
|
||||
**Parcourt tous les chemins de branchement et les conditions limites, ne signale que les cas non gérés.** — Méthodologie pure de traçage de chemin[^1] qui dérive mécaniquement les classes de cas limites. Orthogonale à la revue contradictoire — centrée sur la méthode, pas sur l’attitude.
|
||||
|
||||
**À utiliser quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- Vous souhaitez une couverture exhaustive des cas limites pour le code ou la logique
|
||||
- Vous avez besoin d’un complément à la revue contradictoire (méthodologie différente, résultats différents)
|
||||
- Vous révisez un diff ou une fonction pour des conditions limites
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Énumère tous les chemins de branchement dans le contenu
|
||||
2. Dérive mécaniquement les classes de cas limites : else/default manquants, entrées non vérifiées, décalage d’unité, overflow arithmétique, coercition implicite des types, conditions de concurrence, écarts de timeout
|
||||
3. Teste chaque chemin contre les protections existantes
|
||||
4. Ne rapporte que les chemins non gérés — ignore silencieusement les chemins gérés
|
||||
2. Dérive mécaniquement les classes de cas limites : else/default manquants, entrées non protégées, erreurs off-by-one, dépassements arithmétiques, conversions de type implicites, conditions de concurrence, dépassements de délai
|
||||
3. Teste chaque chemin face aux protections existantes
|
||||
4. Ne signale que les chemins non gérés — ignore silencieusement les chemins gérés
|
||||
|
||||
**Entrée :**
|
||||
**Entrée :**
|
||||
|
||||
- `content` (obligatoire) — Diff, fichier complet ou fonction
|
||||
- `also_consider` (facultatif) — Zones supplémentaires à garder à l’esprit
|
||||
- `also_consider` (facultatif) — Domaines supplémentaires à garder à l’esprit
|
||||
|
||||
**Sortie :** Tableau JSON des résultats, chacun avec `location`, `trigger_condition`, `guard_snippet` et `potential_consequence`
|
||||
**Sortie :** Tableau JSON des résultats, chacun avec `location`, `trigger_condition`, `guard_snippet` et `potential_consequence`
|
||||
|
||||
:::note[Revue Complémentaire]
|
||||
Exécutez à la fois `bmad-review-adversarial-general` et `bmad-review-edge-case-hunter` pour une couverture orthogonale. La revue contradictoire détecte les problèmes de qualité et de complétude ; le chasseur de cas limites détecte les chemins non gérés.
|
||||
|
|
@ -200,99 +205,98 @@ Exécutez à la fois `bmad-review-adversarial-general` et `bmad-review-edge-case
|
|||
|
||||
## bmad-editorial-review-prose
|
||||
|
||||
**Relecture éditoriale clinique centrée sur la clarté de communication.** — Analyse le texte pour détecter les problèmes qui nuisent à la compréhension. Applique le Microsoft Writing Style Guide baseline. Préserve la voix de l’auteur.
|
||||
**Correction éditoriale clinique centrée sur la clarté de communication.** — Analyse le texte pour détecter les problèmes qui nuisent à la compréhension. Applique le Microsoft Writing Style Guide comme référence de base. Préserve la voix de l’auteur.
|
||||
|
||||
**À utiliser quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- Vous avez rédigé un document et souhaitez polir le style
|
||||
- Vous avez rédigé un document et souhaitez en polir le style
|
||||
- Vous devez assurer la clarté pour un public spécifique
|
||||
- Vous voulez des corrections de communication sans modifier les choix stylistiques
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Lit le contenu en ignorant les blocs de code et le frontmatter
|
||||
2. Identifie les problèmes de communication (pas les préférences de style)
|
||||
3. Déduit les doublons du même problème à différents emplacements
|
||||
3. Dédoublonne les occurrences d’un même problème à différents endroits
|
||||
4. Produit un tableau de corrections en trois colonnes
|
||||
|
||||
**Entrée :**
|
||||
**Entrée :**
|
||||
|
||||
- `content` (obligatoire) — Markdown, texte brut ou XML
|
||||
- `style_guide` (facultatif) — Guide de style spécifique au projet
|
||||
- `reader_type` (facultatif) — `humans` (par défaut) pour clarté/fluide, ou `llm` pour précision/consistance
|
||||
|
||||
**Sortie :** Tableau Markdown en trois colonnes : Texte original | Texte révisé | Modifications
|
||||
**Sortie :** Tableau Markdown en trois colonnes : Texte original | Texte révisé | Modifications
|
||||
|
||||
## bmad-editorial-review-structure
|
||||
|
||||
**Édition structurelle — propose des coupes, fusions, déplacements et condensations.** — Révise l’organisation du document et propose des changements substantiels pour améliorer la clarté et le flux avant la révision de copie.
|
||||
**Édition structurelle — propose des coupes, fusions, réorganisations et condensations.** — Révise l’organisation du document et propose des changements substantiels pour améliorer la clarté et le flux avant la correction éditoriale.
|
||||
|
||||
**Utilisez-le quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- Un document a été produit depuis de multiples sous-processus et a besoin de cohérence structurelle
|
||||
- Un document a été produit par plusieurs sous-processus et nécessite une cohérence structurelle
|
||||
- Vous voulez réduire la longueur du document tout en préservant la compréhension
|
||||
- Vous devez identifier les violations de portée ou les informations critiques enfouies
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Analyse le document contre 5 modèles de structure (Tutoriel, Référence, Explication, Prompt, Stratégique)
|
||||
2. Identifie les redondances, violations de portée et informations enfouies
|
||||
3. Produit des recommandations priorisées : COUPER, FUSIONNER, DÉPLACER, CONDENSER, QUESTIONNER, PRÉSERVER
|
||||
4. Estime la réduction totale en mots et pourcentage
|
||||
3. Produit des recommandations priorisées : COUPER, FUSIONNER, DÉPLACER, CONDENSER, QUESTIONNER, PRÉSERVER
|
||||
4. Estime la réduction totale en mots et en pourcentage
|
||||
|
||||
**Entrée :**
|
||||
**Entrée :**
|
||||
|
||||
- `content` (requis) — Document à réviser
|
||||
- `purpose` (optionnel) — Objectif prévu (par ex., « tutoriel de démarrage rapide »)
|
||||
- `target_audience` (optionnel) — Qui lit ceci
|
||||
- `reader_type` (optionnel) — `humans` ou `llm`
|
||||
- `length_target` (optionnel) — Réduction cible (par ex., "30% plus court")
|
||||
- `length_target` (optionnel) — Réduction cible (par ex., « 30% plus court »)
|
||||
|
||||
**Sortie :** Résumé du document, liste de recommandations priorisées et réduction estimée
|
||||
**Sortie :** Résumé du document, liste de recommandations priorisées et réduction estimée
|
||||
|
||||
## bmad-shard-doc
|
||||
|
||||
**Diviser les fichiers markdown volumineux en fichiers de sections organisés.** — Utilise les en-têtes de niveau 2 comme points de division pour créer un dossier de fichiers de sections autonomes avec un index.
|
||||
**Fractionne les fichiers markdown volumineux en sections organisées.** — Utilise les en-têtes de niveau 2 comme points de découpe pour créer un dossier de fichiers de sections autonomes avec un index.
|
||||
|
||||
**Utilisez-le quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- Un document markdown est devenu trop volumineux pour être géré efficacement (plus de 500 lignes)
|
||||
- Vous voulez diviser un document monolithique en sections navigables
|
||||
- Vous voulez découper un document monolithique en sections navigables
|
||||
- Vous avez besoin de fichiers séparés pour l’édition parallèle ou la gestion de contexte LLM
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Valide que le fichier source existe et est markdown
|
||||
2. Divise sur les en-têtes de niveau 2 (`##`) en fichiers de sections numérotées
|
||||
3. Crée un `index.md` avec manifeste de sections et liens
|
||||
1. Valide que le fichier source existe et est au format markdown
|
||||
2. Découpe sur les en-têtes de niveau 2 (`##`) en fichiers de sections numérotées
|
||||
3. Crée un `index.md` avec le manifeste de sections et les liens
|
||||
4. Vous invite à supprimer, archiver ou conserver l’original
|
||||
|
||||
**Entrée :** Chemin du fichier markdown source, dossier de destination optionnel
|
||||
**Entrée :** Chemin du fichier markdown source, dossier de destination optionnel
|
||||
|
||||
**Sortie :** Dossier avec `index.md` et `01-{section}.md`, `02-{section}.md`, etc.
|
||||
**Sortie :** Dossier avec `index.md` et `01-{section}.md`, `02-{section}.md`, etc.
|
||||
|
||||
## bmad-index-docs
|
||||
|
||||
**Générer ou mettre à jour un index de tous les documents dans un dossier.** — Analyse un répertoire, lit chaque fichier pour comprendre son objectif et produit un `index.md` organisé avec liens et descriptions.
|
||||
**Génère ou met à jour un index de tous les documents dans un dossier.** — Analyse un répertoire, lit chaque fichier pour comprendre son objectif et produit un `index.md` organisé avec liens et descriptions.
|
||||
|
||||
**Utilisez-le quand :**
|
||||
**À utiliser quand :**
|
||||
|
||||
- Vous avez besoin d’un index léger pour un scan LLM rapide des documents disponibles
|
||||
- Un dossier de documentation a grandi et a besoin d’une table des matières organisée
|
||||
- Un dossier de documentation a grandi et nécessite une table des matières organisée
|
||||
- Vous voulez un aperçu auto-généré qui reste à jour
|
||||
|
||||
**Fonctionnement :**
|
||||
**Fonctionnement :**
|
||||
|
||||
1. Analyse le répertoire cible pour tous les fichiers non cachés
|
||||
2. Lit chaque fichier pour comprendre son objectif réel
|
||||
3. Groupe les fichiers par type, objectif ou sous-répertoire
|
||||
4. Génère des descriptions concises (3–10 mots chacune)
|
||||
|
||||
**Entrée :** Chemin du dossier cible
|
||||
**Entrée :** Chemin du dossier cible
|
||||
|
||||
**Sortie :** `index.md` avec listes de fichiers organisées, liens relatifs et brèves descriptions
|
||||
**Sortie :** `index.md` avec listes de fichiers organisées, liens relatifs et brèves descriptions
|
||||
|
||||
## Glossaire
|
||||
|
||||
[^1]: Path-tracing : méthode d’analyse qui suit systématiquement tous les chemins d’exécution possibles dans un programme pour identifier les cas non gérés.
|
||||
|
||||
[^1]: Path-tracing : méthode d’analyse qui suit systématiquement tous les chemins d’exécution possibles dans un programme pour identifier les cas non gérés.
|
||||
|
|
|
|||
|
|
@ -15,11 +15,11 @@ Exécutez `npx bmad-method install` et sélectionnez les modules souhaités. L
|
|||
|
||||
Créez des agents personnalisés, des workflows et des modules spécifiques à un domaine avec une assistance guidée. BMad Builder est le méta-module pour étendre le framework lui-même.
|
||||
|
||||
- **Code :** `bmb`
|
||||
- **npm :** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder)
|
||||
- **GitHub :** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder)
|
||||
- **Code :** `bmb`
|
||||
- **npm :** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder)
|
||||
- **GitHub :** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder)
|
||||
|
||||
**Fournit :**
|
||||
**Fournit :**
|
||||
|
||||
- Agent Builder — créez des agents IA spécialisés avec une expertise et un accès aux outils personnalisés
|
||||
- Workflow Builder — concevez des processus structurés avec des étapes et des points de décision
|
||||
|
|
@ -30,11 +30,11 @@ Créez des agents personnalisés, des workflows et des modules spécifiques à u
|
|||
|
||||
Outils basés sur l’IA pour la créativité structurée, l’idéation et l’innovation pendant le développement en phase amont. La suite fournit plusieurs agents qui facilitent le brainstorming, le design thinking et la résolution de problèmes en utilisant des cadres éprouvés.
|
||||
|
||||
- **Code :** `cis`
|
||||
- **npm :** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite)
|
||||
- **GitHub :** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)
|
||||
- **Code :** `cis`
|
||||
- **npm :** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite)
|
||||
- **GitHub :** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)
|
||||
|
||||
**Fournit :**
|
||||
**Fournit :**
|
||||
|
||||
- Agents Innovation Strategist, Design Thinking Coach et Brainstorming Coach
|
||||
- Problem Solver et Creative Problem Solver pour la pensée systématique et latérale
|
||||
|
|
@ -45,11 +45,11 @@ Outils basés sur l’IA pour la créativité structurée, l’idéation et l’
|
|||
|
||||
Workflows de développement de jeux structurés adaptés pour Unity, Unreal, Godot et moteurs personnalisés. Supporte le prototypage rapide via Quick Dev et la production à grande échelle avec des sprints propulsés par epics.
|
||||
|
||||
- **Code :** `gds`
|
||||
- **npm :** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio)
|
||||
- **GitHub :** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)
|
||||
- **Code :** `gds`
|
||||
- **npm :** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio)
|
||||
- **GitHub :** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)
|
||||
|
||||
**Fournit :**
|
||||
**Fournit :**
|
||||
|
||||
- Workflow de génération de Document de Design de Jeu (GDD[^3])
|
||||
- Mode Quick Dev pour le prototypage rapide
|
||||
|
|
@ -60,11 +60,11 @@ Workflows de développement de jeux structurés adaptés pour Unity, Unreal, God
|
|||
|
||||
Stratégie de test de niveau entreprise, conseils d’automatisation et décisions de porte de release via un agent expert et neuf workflows structurés. TEA va bien au-delà du workflow QA intégré avec une priorisation basée sur les risques et une traçabilité des exigences.
|
||||
|
||||
- **Code :** `tea`
|
||||
- **npm :** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
|
||||
- **GitHub :** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)
|
||||
- **Code :** `tea`
|
||||
- **npm :** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
|
||||
- **GitHub :** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)
|
||||
|
||||
**Fournit :**
|
||||
**Fournit :**
|
||||
|
||||
- Agent Murat (Master Test Architect and Quality Advisor)
|
||||
- Workflows pour la conception de tests, ATDD, l’automatisation, la revue de tests et la traçabilité
|
||||
|
|
|
|||
|
|
@ -5,14 +5,14 @@ sidebar:
|
|||
order: 6
|
||||
---
|
||||
|
||||
BMad propose deux approches de test : un workflow QA[^1] intégré pour une génération rapide de tests et un module Test Architect installable pour une stratégie de test de qualité entreprise.
|
||||
BMad propose deux approches de test : un workflow QA[^1] intégré pour une génération rapide de tests et un module Test Architect installable pour une stratégie de test de qualité entreprise.
|
||||
|
||||
## Lequel Choisir ?
|
||||
|
||||
| Facteur | QA Intégré | Module TEA |
|
||||
| Facteur | QA Intégré | Module TEA |
|
||||
|-------------------------|----------------------------------------------|---------------------------------------------------------------------|
|
||||
| **Idéal pour** | Projets petits et moyens, couverture rapide | Grands projets, domaines réglementés ou complexes |
|
||||
| **Installation** | Rien à installer — inclus dans BMM | Installer séparément via `npx bmad-method install` |
|
||||
| **Installation** | Rien à installer — inclus dans BMM | Installer séparément via `npx bmad-method install` |
|
||||
| **Approche** | Générer les tests rapidement, itérer ensuite | Planifier d’abord, puis générer avec traçabilité |
|
||||
| **Types de tests** | Tests API et E2E | API, E2E, ATDD[^2], NFR, et plus |
|
||||
| **Stratégie** | Chemin nominal + cas limites critiques | Priorisation basée sur les risques (P0-P3) |
|
||||
|
|
@ -26,7 +26,7 @@ La plupart des projets devraient commencer avec le workflow QA intégré. Si vou
|
|||
|
||||
Le workflow QA intégré (`bmad-qa-generate-e2e-tests`) fait partie du module BMM (suite Agile), disponible via l’agent Developer. Il génère rapidement des tests fonctionnels en utilisant le framework de test existant de votre projet — aucune configuration ni installation supplémentaire requise.
|
||||
|
||||
**Déclencheur :** `QA` (via l’agent Developer) ou `bmad-qa-generate-e2e-tests`
|
||||
**Déclencheur :** `QA` (via l’agent Developer) ou `bmad-qa-generate-e2e-tests`
|
||||
|
||||
### Ce que le Workflow QA Fait
|
||||
|
||||
|
|
@ -65,9 +65,9 @@ Le workflow QA génère uniquement des tests. Pour la revue de code et la valida
|
|||
|
||||
TEA est un module autonome qui fournit un agent expert (Murat) et neuf workflows structurés pour des tests de qualité entreprise. Il va au-delà de la génération de tests pour inclure la stratégie de test, la planification basée sur les risques, les murs de qualité et la traçabilité des exigences.
|
||||
|
||||
- **Documentation :** [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
|
||||
- **Installation :** `npx bmad-method install` et sélectionnez le module TEA
|
||||
- **npm :** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
|
||||
- **Documentation :** [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
|
||||
- **Installation :** `npx bmad-method install` et sélectionnez le module TEA
|
||||
- **npm :** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)
|
||||
|
||||
### Ce que TEA Fournit
|
||||
|
||||
|
|
@ -97,8 +97,8 @@ TEA supporte également la priorisation basée sur les risques P0-P3 et des int
|
|||
|
||||
Le workflow Automate du QA intégré apparaît dans la Phase 4 (Implémentation) de la carte de workflow méthode BMad. Il est conçu pour s’exécuter **après qu’un epic complet soit terminé** — une fois que toutes les stories d’un epic ont été implémentées et revues. Une séquence typique :
|
||||
|
||||
1. Pour chaque story de l’epic : implémenter avec Dev Story (`DS`), puis valider avec Code Review (`CR`)
|
||||
2. Après la fin de l’epic : générer les tests avec `QA` (via l’agent Developer) ou le workflow Automate de TEA
|
||||
1. Pour chaque story de l’epic : implémenter avec Dev Story (`DS`), puis valider avec Code Review (`CR`)
|
||||
2. Après la fin de l’epic : générer les tests avec `QA` (via l’agent Developer) ou le workflow Automate de TEA
|
||||
3. Lancer la rétrospective (`bmad-retrospective`) pour capturer les leçons apprises
|
||||
|
||||
Le workflow QA travaille directement à partir du code source sans charger les documents de planification (PRD, architecture). Les workflows TEA peuvent s’intégrer avec les artefacts de planification en amont pour la traçabilité.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ la méthode BMad. Par ailleurs, si vous utilisez des modules ayant étendu la m
|
|||
complémentaires non extensibles, `bmad-help` s’adapte automatiquement pour couvrir tout ce qui est disponible et vous
|
||||
fournir les meilleurs conseils en temps réel.
|
||||
|
||||
Note importante : chaque workflow ci-dessous peut être exécuté directement via un skill avec l’outil de votre choix, ou
|
||||
Note importante : chaque workflow ci-dessous peut être exécuté directement via un skill avec l’outil de votre choix, ou
|
||||
en chargeant d’abord un agent depuis le menu des agents.
|
||||
|
||||
<iframe src="/workflow-map-diagram-fr.html" title="Diagramme de la carte des workflows de la méthode BMad" width="100%" height="100%" style="border-radius: 8px; border: 1px solid #334155; min-height: 900px;"></iframe>
|
||||
|
|
@ -29,7 +29,7 @@ en chargeant d’abord un agent depuis le menu des agents.
|
|||
<a href="/workflow-map-diagram-fr.html" target="_blank" rel="noopener noreferrer">Ouvrir le diagramme dans un nouvel onglet ↗</a>
|
||||
</p>
|
||||
|
||||
## Phase 1 : Analyse (Optionnelle)
|
||||
## Phase 1 : Analyse (Optionnelle)
|
||||
|
||||
Explorez l’espace problème et validez vos idées avant de vous lancer dans la planification. [**Découvrez ce que fait
|
||||
chaque outil et quand l’utiliser**](../explanation/analysis-phase.md).
|
||||
|
|
@ -41,13 +41,13 @@ chaque outil et quand l’utiliser**](../explanation/analysis-phase.md).
|
|||
| `bmad-product-brief` | Formalisez la vision stratégique — idéal lorsque votre concept est bien défini | `product-brief.md` |
|
||||
| `bmad-prfaq` | Working Backwards — mettez à l’épreuve et affinez votre concept produit | `prfaq-{project}.md` |
|
||||
|
||||
## Phase 2 : Planification
|
||||
## Phase 2 : Planification
|
||||
|
||||
Définissez ce qu’il faut construire et pour qui.
|
||||
|
||||
| Workflow | Objectif | Livrable |
|
||||
|------------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
|
||||
| `bmad-prd` | Créez, mettez à jour ou validez un PRD[^1] — découverte accompagnée, trois intentions en un seul skill | Création/Mise à jour : `prd.md`, `addendum.md`, `decision-log.md` ; Validation : `validation-report.html` + `.md` |
|
||||
| `bmad-prd` | Créez, mettez à jour ou validez un PRD[^1] — découverte accompagnée, trois intentions en un seul skill | Création/Mise à jour : `prd.md`, `addendum.md`, `decision-log.md` ; Validation : `validation-report.html` + `.md` |
|
||||
| `bmad-ux` | Concevez l’expérience utilisateur (lorsque l’UX compte) | `DESIGN.md`, `EXPERIENCE.md` |
|
||||
|
||||
:::tip[Trois intentions en un seul skill]
|
||||
|
|
@ -58,21 +58,21 @@ Définissez ce qu’il faut construire et pour qui.
|
|||
- **Valider** — évalue un PRD à l’aide d’une liste de contrôle configurable et produit un rapport de constats structuré au format HTML
|
||||
:::
|
||||
|
||||
:::tip[En amont : `bmad-product-brief`]
|
||||
:::tip[En amont : `bmad-product-brief`]
|
||||
`bmad-product-brief` (Phase 1) produit un `product-brief.md` que `bmad-prd` peut exploiter lors de la découverte, réduisant les redondances et gardant les deux documents alignés. Aucun des deux skills ne nécessite l’autre — commencez directement par `bmad-prd` si vous savez déjà ce que vous construisez.
|
||||
:::
|
||||
|
||||
## Phase 3 : Conception de la Solution
|
||||
## Phase 3 : Conception de la Solution
|
||||
|
||||
Décidez comment le construire et décomposez le travail en stories.
|
||||
|
||||
| Workflow | Objectif | Livrable |
|
||||
|---------------------------------------|---------------------------------------------------|--------------------------------|
|
||||
| `bmad-create-architecture` | Rendez explicites les décisions techniques | `architecture.md` avec ADRs[^2] |
|
||||
| `bmad-create-epics-and-stories` | Décomposez les exigences en tâches implémentables | Fichiers d’epic avec stories |
|
||||
| `bmad-check-implementation-readiness` | Jalon de validation avant implémentation | Décision OK / RÉSERVES / ÉCHEC |
|
||||
| Workflow | Objectif | Livrable |
|
||||
|---------------------------------------|---------------------------------------------------|---------------------------------|
|
||||
| `bmad-create-architecture` | Rendez explicites les décisions techniques | `architecture.md` avec ADRs[^2] |
|
||||
| `bmad-create-epics-and-stories` | Décomposez les exigences en tâches implémentables | Fichiers d’epic avec stories |
|
||||
| `bmad-check-implementation-readiness` | Jalon de validation avant implémentation | Décision OK / RÉSERVES / ÉCHEC |
|
||||
|
||||
## Phase 4 : Implémentation
|
||||
## Phase 4 : Implémentation
|
||||
|
||||
Construisez, une story à la fois. L’automatisation complète de la phase 4 arrive bientôt !
|
||||
|
||||
|
|
@ -110,7 +110,7 @@ optionnel peut être généré à la fin de la création de l’architecture, ou
|
|||
éléments clés et les garder alignés avec les conventions en vigueur.
|
||||
:::
|
||||
|
||||
**Comment le créer :**
|
||||
**Comment le créer :**
|
||||
|
||||
- **Manuellement** — Créez `_bmad-output/project-context.md` avec votre stack technique et vos règles d’implémentation
|
||||
- **Générez-le** — Exécutez `bmad-generate-project-context` pour l’auto-générer à partir de votre architecture ou de votre codebase
|
||||
|
|
|
|||
|
|
@ -26,14 +26,14 @@ Accélérez le développement de vos applications grâce à des workflows alimen
|
|||
**Développez** → Laissez BMad-Help vous guider, workflow par workflow
|
||||
:::
|
||||
|
||||
## Découvrez BMad-Help : votre guide intelligent
|
||||
## Découvrez BMad-Help : votre guide intelligent
|
||||
|
||||
**BMad-Help est le moyen le plus rapide de démarrer avec BMad.** Pas besoin de mémoriser les workflows ou les phases — posez simplement votre question et BMad-Help saura :
|
||||
|
||||
- **Inspecter votre projet** pour voir ce qui a déjà été fait
|
||||
- **Vous présenter vos options** en fonction des modules installés
|
||||
- **Vous recommander la prochaine étape** — y compris la première tâche obligatoire
|
||||
- **Répondre à vos questions**, par exemple : « J’ai une idée de SaaS, par où commencer ? »
|
||||
- **Répondre à vos questions**, par exemple : « J’ai une idée de SaaS, par où commencer ? »
|
||||
|
||||
### Comment utiliser BMad-Help
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ BMad-Help vous indiquera :
|
|||
|
||||
### Il intervient aussi dans les workflows
|
||||
|
||||
BMad-Help ne se contente pas de répondre aux questions — **il se lance automatiquement à la fin de chaque workflow** pour vous indiquer exactement la suite. Finies les devinettes et les recherches dans la doc : vous recevez des instructions claires sur le prochain workflow à exécuter.
|
||||
BMad-Help ne se contente pas de répondre aux questions — **il se lance automatiquement à la fin de chaque workflow** pour vous indiquer exactement la suite. Finies les devinettes et les recherches dans la doc : vous recevez des instructions claires sur le prochain workflow à exécuter.
|
||||
|
||||
:::tip[Commencez ici]
|
||||
Après avoir installé BMad, invoquez immédiatement le skill `bmad-help`. Il détectera les modules que vous avez installés et vous orientera vers le bon point de départ pour votre projet.
|
||||
|
|
@ -123,7 +123,7 @@ Chaque workflow possède une **skill** que vous invoquez par son nom dans votre
|
|||
Démarrez toujours un nouveau chat pour chaque workflow. Cela évite les problèmes liés aux limites de contexte de l’IA.
|
||||
:::
|
||||
|
||||
## Étape 1 : Élaborer votre plan
|
||||
## Étape 1 : Élaborer votre plan
|
||||
|
||||
Parcourez les phases 1 à 3. **Utilisez un nouveau chat pour chaque workflow.**
|
||||
|
||||
|
|
@ -133,7 +133,7 @@ Avant de commencer, pensez à créer `project-context.md` pour documenter vos pr
|
|||
Créez-le manuellement à l’emplacement `_bmad-output/project-context.md`, ou générez-le après l’architecture avec `bmad-generate-project-context`. [En savoir plus](../explanation/project-context.md).
|
||||
:::
|
||||
|
||||
### Phase 1 : Analyse (optionnelle)
|
||||
### Phase 1 : Analyse (optionnelle)
|
||||
|
||||
Tous les workflows de cette phase sont optionnels. [**Vous ne savez pas lequel choisir ?**](../explanation/analysis-phase.md)
|
||||
|
||||
|
|
@ -142,12 +142,12 @@ Tous les workflows de cette phase sont optionnels. [**Vous ne savez pas lequel c
|
|||
- **product-brief** (`bmad-product-brief`) — Document fondateur recommandé une fois votre concept bien défini
|
||||
- **prfaq** (`bmad-prfaq`) — Exercice Working Backwards pour tester et affiner votre concept produit
|
||||
|
||||
### Phase 2 : Planification (requise)
|
||||
### Phase 2 : Planification (requise)
|
||||
|
||||
**Pour les voies BMad Method et Enterprise :**
|
||||
**Pour les voies BMad Method et Enterprise :**
|
||||
|
||||
1. Exécutez `bmad-prd` dans un nouveau chat — précisez votre intention (Create / Update / Validate) ou laissez le skill vous la demander
|
||||
2. Résultat : `prd.md`, `addendum.md`, `decision-log.md`
|
||||
2. Résultat : `prd.md`, `addendum.md`, `decision-log.md`
|
||||
|
||||
:::note[Intentions de `bmad-prd`]
|
||||
|
||||
|
|
@ -157,7 +157,7 @@ Tous les workflows de cette phase sont optionnels. [**Vous ne savez pas lequel c
|
|||
:::
|
||||
|
||||
|
||||
**Pour la voie Quick Dev :**
|
||||
**Pour la voie Quick Dev :**
|
||||
|
||||
- Exécutez `bmad-quick-dev` — ce workflow couvre la planification et l’implémentation en une seule fois ; vous pouvez passer directement à l’implémentation
|
||||
|
||||
|
|
@ -165,13 +165,13 @@ Tous les workflows de cette phase sont optionnels. [**Vous ne savez pas lequel c
|
|||
Si votre projet comporte une interface utilisateur, invoquez l'**agent UX Designer** (`bmad-agent-ux-designer`) et lancez le workflow de design UX (`bmad-ux`) après avoir créé votre PRD.
|
||||
:::
|
||||
|
||||
### Phase 3 : Solutioning (BMad Method/Enterprise)
|
||||
### Phase 3 : Solutioning (BMad Method/Enterprise)
|
||||
|
||||
**Créer l’architecture**
|
||||
|
||||
1. Invoquez l'**agent Architecte** (`bmad-agent-architect`) dans un nouveau chat
|
||||
2. Exécutez `bmad-create-architecture` (`bmad-create-architecture`)
|
||||
3. Résultat : document d’architecture avec les décisions techniques
|
||||
3. Résultat : document d’architecture avec les décisions techniques
|
||||
|
||||
**Créer les epics et les stories**
|
||||
|
||||
|
|
@ -189,7 +189,7 @@ Les epics et stories sont désormais créés *après* l’architecture. Cela pro
|
|||
2. Exécutez `bmad-check-implementation-readiness` (`bmad-check-implementation-readiness`)
|
||||
3. Valide la cohérence de l’ensemble des documents de planification
|
||||
|
||||
## Étape 2 : Développer votre projet
|
||||
## Étape 2 : Développer votre projet
|
||||
|
||||
Une fois la planification terminée, passez à l’implémentation. **Chaque workflow doit être exécuté dans un nouveau chat.**
|
||||
|
||||
|
|
@ -205,7 +205,7 @@ Pour chaque story, répétez ce cycle dans de nouveaux chats :
|
|||
|-------|-------|---------------------|---------------------|--------------------------------------|
|
||||
| 1 | DEV | `bmad-create-story` | `bmad-create-story` | Créer le fichier story depuis l’epic |
|
||||
| 2 | DEV | `bmad-dev-story` | `bmad-dev-story` | Implémenter la story |
|
||||
| 3 | DEV | `bmad-code-review` | `bmad-code-review` | Validation qualité *(recommandée)* |
|
||||
| 3 | DEV | `bmad-code-review` | `bmad-code-review` | Validation qualité *(recommandée)* |
|
||||
|
||||
Après avoir terminé toutes les stories d’un epic, invoquez l'**agent Développeur** (`bmad-agent-dev`) et exécutez `bmad-retrospective` (`bmad-retrospective`).
|
||||
|
||||
|
|
@ -238,7 +238,7 @@ your-project/
|
|||
|
||||
| Workflow | Commande | Agent | Objectif |
|
||||
|---------------------------------------|---------------------------------------|-----------|-----------------------------------------------------------------|
|
||||
| **`bmad-help`** ⭐ | `bmad-help` | Tous | **Votre guide intelligent — posez n’importe quelle question !** |
|
||||
| **`bmad-help`** ⭐ | `bmad-help` | Tous | **Votre guide intelligent — posez n’importe quelle question !** |
|
||||
| `bmad-prd` | `bmad-prd` | Tous | Créer, mettre à jour ou valider un PRD |
|
||||
| `bmad-create-architecture` | `bmad-create-architecture` | Architect | Créer le document d’architecture |
|
||||
| `bmad-generate-project-context` | `bmad-generate-project-context` | Analyst | Créer le fichier de contexte projet |
|
||||
|
|
@ -265,7 +265,7 @@ Pas strictement. Une fois le flux maîtrisé, vous pouvez exécuter les workflow
|
|||
|
||||
## Obtenir de l’aide
|
||||
|
||||
:::tip[Premier réflexe : BMad-Help]
|
||||
:::tip[Premier réflexe : BMad-Help]
|
||||
**Invoquez `bmad-help` à tout moment** — c’est le moyen le plus rapide de vous débloquer. Posez-lui n’importe quelle question :
|
||||
|
||||
- « Que dois-je faire après l’installation ? »
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ This page lists the default BMM (Agile suite) agents that install with BMad Meth
|
|||
| Analyst (Mary) | `bmad-analyst` | `BP`, `MR`, `DR`, `TR`, `CB`, `WB`, `DP` | Brainstorm, Market Research, Domain Research, Technical Research, Create Brief, PRFAQ Challenge, Document Project |
|
||||
| Product Manager (John) | `bmad-pm` | `CP`, `VP`, `EP`, `CE`, `IR`, `CC` | Create/Validate/Edit PRD, Create Epics and Stories, Implementation Readiness, Correct Course |
|
||||
| Architect (Winston) | `bmad-architect` | `CA`, `IR` | Create Architecture, Implementation Readiness |
|
||||
| Developer (Amelia) | `bmad-agent-dev` | `DS`, `QD`, `QA`, `CR`, `SP`, `CS`, `ER` | Dev Story, Quick Dev, QA Test Generation, Code Review, Sprint Planning, Create Story, Epic Retrospective |
|
||||
| Developer (Amelia) | `bmad-agent-dev` | `DS`, `QD`, `QA`, `CR`, `SP`, `CS`, `ER`, `IN` | Dev Story, Quick Dev, QA Test Generation, Code Review, Sprint Planning, Create Story, Epic Retrospective, [Forensic Investigation](../explanation/forensic-investigation.md) |
|
||||
| UX Designer (Sally) | `bmad-ux-designer` | `CU` | Create UX Design |
|
||||
| Technical Writer (Paige) | `bmad-tech-writer` | `DP`, `WD`, `US`, `MG`, `VD`, `EC` | Document Project, Write Document, Update Standards, Mermaid Generate, Validate Doc, Explain Concept |
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Run any core tool by typing its skill name (e.g., `bmad-help`) in your IDE. No a
|
|||
| [`bmad-help`](#bmad-help) | Task | Get context-aware guidance on what to do next |
|
||||
| [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Facilitate interactive brainstorming sessions |
|
||||
| [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrate multi-agent group discussions |
|
||||
| [`bmad-distillator`](#bmad-distillator) | Task | Lossless LLM-optimized compression of documents |
|
||||
| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work |
|
||||
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | Push LLM output through iterative refinement methods |
|
||||
| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | Cynical review that finds what's missing and what's wrong |
|
||||
| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | Exhaustive branching-path analysis for unhandled edge cases |
|
||||
|
|
@ -97,32 +97,36 @@ The magic happens in ideas 50–100. The workflow encourages generating 100+ ide
|
|||
|
||||
**Output:** Real-time multi-agent conversation with maintained agent personalities
|
||||
|
||||
## bmad-distillator
|
||||
## bmad-spec
|
||||
|
||||
**Lossless LLM-optimized compression of source documents.** — Produces dense, token-efficient distillates that preserve all information for downstream LLM consumption. Verifiable through round-trip reconstruction.
|
||||
**Distill any intent input into the canonical SPEC contract for downstream work.** Takes a brief, PRD, GDD, RFC, brain dump, transcript, UX folder, or mixed multi-source input and produces a `SPEC.md` carrying the five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for load-bearing content that does not fit the kernel.
|
||||
|
||||
**Use it when:**
|
||||
|
||||
- A document is too large for an LLM's context window
|
||||
- You need token-efficient versions of research, specs, or planning artifacts
|
||||
- You want to verify no information is lost during compression
|
||||
- Agents will need to frequently reference and find information in it
|
||||
- You need to lock the WHAT before the HOW for any kind of work (software, game design, research, editorial, policy, business).
|
||||
- You want a LLM Optimized succinct, no-fluff contract that downstream skills can consume without re-reading every upstream artifact.
|
||||
- You want to validate or update an existing spec.
|
||||
|
||||
**How it works:**
|
||||
|
||||
1. **Analyze** — Reads source documents, identifies information density and structure
|
||||
2. **Compress** — Converts prose to dense bullet-point format, strips decorative formatting
|
||||
3. **Verify** — Checks completeness to ensure all original information is preserved
|
||||
4. **Validate** (optional) — Round-trip reconstruction test proves lossless compression
|
||||
1. Reads the input and any ancillary linked materials.
|
||||
2. Distills into the five-field kernel using a configurable template; routes overflow into appropriately-named companions.
|
||||
3. Runs a two-pass self-validate (coherence rules, then preservation of every load-bearing source claim).
|
||||
4. Writes `SPEC.md`, sibling companions, and a `.decision-log.md` under `{output_folder}/specs/spec-{slug}/`.
|
||||
|
||||
Spec Law enforces eight rules: capabilities carry both intent and success; intents are WHAT not HOW; constraints actually bend decisions; non-goals are explicit; success signals are concrete; capability IDs are stable; every load-bearing source claim is preserved; prose is lean.
|
||||
|
||||
**Input:**
|
||||
|
||||
- `source_documents` (required) — File paths, folder paths, or glob patterns
|
||||
- `downstream_consumer` (optional) — What consumes this (e.g., "PRD creation")
|
||||
- `token_budget` (optional) — Approximate target size
|
||||
- `--validate` (flag) — Run round-trip reconstruction test
|
||||
- `input` (required) — path or inline text. Vague idea, brain dump, PRD, GDD, RFC, brief, transcript, mockup folder, mixed multi-source.
|
||||
- `slug` (optional) — required only when input is sparse and no slug is derivable from a source filename.
|
||||
- `target_spec_path` (optional) — set to update an existing spec instead of creating a new one.
|
||||
|
||||
**Output:** Distillate markdown file(s) with compression ratio report (e.g., "3.2:1")
|
||||
**Output:** Spec folder containing `SPEC.md`, any companion files, and a `.decision-log.md`. Headless callers receive a JSON response with the result status and the list of files written or modified.
|
||||
|
||||
:::note[Mutation contract]
|
||||
`bmad-spec` is the only writer of `SPEC.md` and of spec-authored companions. Other skills produce their own native artifacts and invoke `bmad-spec` headless when they need to express intent as the canonical contract or propose updates.
|
||||
:::
|
||||
|
||||
## bmad-advanced-elicitation
|
||||
|
||||
|
|
|
|||
|
|
@ -694,15 +694,7 @@ Review kiểu "devil's advocate" — giả định vấn đề luôn tồn tại
|
|||
- Tìm những gì **còn thiếu**, không chỉ những gì sai
|
||||
- Trực giao với Edge Case Hunter
|
||||
|
||||
### 8.4. Distillator — Nén tài liệu cho LLM
|
||||
|
||||
```bash
|
||||
bmad-distillator
|
||||
```
|
||||
|
||||
Khi tài liệu quá lớn (PRD dài, Architecture phức tạp), Distillator nén nội dung tối ưu cho LLM mà không mất thông tin quan trọng.
|
||||
|
||||
### 8.5. Shard Large Documents — Tách file lớn
|
||||
### 8.4. Shard Large Documents — Tách file lớn
|
||||
|
||||
```bash
|
||||
bmad-shard-doc
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Chạy bất kỳ công cụ cốt lõi nào bằng cách gõ tên skill của n
|
|||
| [`bmad-help`](#bmad-help) | Tác vụ | Nhận hướng dẫn có ngữ cảnh về việc nên làm gì tiếp theo |
|
||||
| [`bmad-brainstorming`](#bmad-brainstorming) | Quy trình | Tổ chức các phiên brainstorming có tương tác |
|
||||
| [`bmad-party-mode`](#bmad-party-mode) | Quy trình | Điều phối thảo luận nhóm nhiều agent |
|
||||
| [`bmad-distillator`](#bmad-distillator) | Tác vụ | Nén tài liệu tối ưu cho LLM mà không mất thông tin |
|
||||
| [`bmad-spec`](#bmad-spec) | Quy trình | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work (translation pending) |
|
||||
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Tác vụ | Đẩy đầu ra của LLM qua các vòng tinh luyện lặp |
|
||||
| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Tác vụ | Rà soát hoài nghi để tìm chỗ thiếu và chỗ sai |
|
||||
| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Tác vụ | Phân tích toàn bộ nhánh rẽ để tìm trường hợp biên chưa được xử lý |
|
||||
|
|
@ -97,33 +97,6 @@ Chạy bất kỳ công cụ cốt lõi nào bằng cách gõ tên skill của n
|
|||
|
||||
**Đầu ra:** Cuộc hội thoại nhiều agent theo thời gian thực, vẫn giữ nguyên cá tính từng agent
|
||||
|
||||
## bmad-distillator
|
||||
|
||||
**Nén tài liệu nguồn tối ưu cho LLM mà không mất thông tin.** Công cụ này tạo ra các bản chưng cất dày đặc, tiết kiệm token nhưng vẫn giữ nguyên toàn bộ thông tin cho LLM dùng về sau. Có thể xác minh bằng tái dựng hai chiều.
|
||||
|
||||
**Dùng khi:**
|
||||
|
||||
- Một tài liệu quá lớn so với context window của LLM
|
||||
- Bạn cần phiên bản tiết kiệm token của tài liệu nghiên cứu, đặc tả hoặc artifact lập kế hoạch
|
||||
- Bạn muốn xác minh rằng không có thông tin nào bị mất trong quá trình nén
|
||||
- Các agent sẽ cần tham chiếu và tìm thông tin trong đó thường xuyên
|
||||
|
||||
**Cách hoạt động:**
|
||||
|
||||
1. **Analyze** — Đọc tài liệu nguồn, nhận diện mật độ thông tin và cấu trúc
|
||||
2. **Compress** — Chuyển văn xuôi thành dạng bullet dày đặc, bỏ trang trí không cần thiết
|
||||
3. **Verify** — Kiểm tra tính đầy đủ để đảm bảo mọi thông tin gốc còn nguyên
|
||||
4. **Validate** *(tùy chọn)* — Tái dựng hai chiều để chứng minh nén không mất mát
|
||||
|
||||
**Đầu vào:**
|
||||
|
||||
- `source_documents` *(bắt buộc)* — Đường dẫn file, thư mục hoặc mẫu glob
|
||||
- `downstream_consumer` *(tùy chọn)* — Thành phần sẽ dùng đầu ra này, ví dụ "PRD creation"
|
||||
- `token_budget` *(tùy chọn)* — Kích thước mục tiêu gần đúng
|
||||
- `--validate` *(cờ)* — Chạy kiểm tra tái dựng hai chiều
|
||||
|
||||
**Đầu ra:** Một hoặc nhiều file markdown distillate kèm báo cáo tỷ lệ nén, ví dụ `3.2:1`
|
||||
|
||||
## bmad-advanced-elicitation
|
||||
|
||||
**Đẩy đầu ra của LLM qua các phương pháp tinh luyện lặp.** Công cụ này chọn từ thư viện kỹ thuật elicitation để cải thiện nội dung một cách có hệ thống qua nhiều lượt.
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ sidebar:
|
|||
| [`bmad-help`](#bmad-help) | Task | 基于项目上下文推荐下一步 |
|
||||
| [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | 引导式头脑风暴与想法扩展 |
|
||||
| [`bmad-party-mode`](#bmad-party-mode) | Workflow | 多智能体协作讨论 |
|
||||
| [`bmad-distillator`](#bmad-distillator) | Task | 无损压缩文档，提升 LLM 消费效率 |
|
||||
| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work (translation pending) |
|
||||
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | 通过多轮技法增强 LLM 输出 |
|
||||
| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | 对抗式问题发现审查 |
|
||||
| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | 边界与分支路径穷举审查 |
|
||||
|
|
@ -80,29 +80,6 @@ sidebar:
|
|||
**输入：** 讨论主题（可指定希望参与的角色）
|
||||
**输出：** 多智能体实时对话过程
|
||||
|
||||
## bmad-distillator
|
||||
|
||||
**定位：** 在不丢失信息前提下压缩文档，降低 token 成本。
|
||||
|
||||
**适用场景：**
|
||||
- 源文档超过上下文窗口
|
||||
- 需要把研究/规格材料转成高密度引用版本
|
||||
- 想验证压缩结果是否可逆
|
||||
|
||||
**工作机制：**
|
||||
1. 分析源文档结构与信息密度
|
||||
2. 压缩为高密度结构化表达
|
||||
3. 校验信息完整性
|
||||
4. 可选执行往返重构验证（round-trip）
|
||||
|
||||
**输入：**
|
||||
- `source_documents`（必填）
|
||||
- `downstream_consumer`（可选）
|
||||
- `token_budget`（可选）
|
||||
- `--validate`（可选标志）
|
||||
|
||||
**输出：** 精馏文档 + 压缩比报告
|
||||
|
||||
## bmad-advanced-elicitation
|
||||
|
||||
**定位：** 对已有 LLM 输出做第二轮深挖与改写强化。
|
||||
|
|
|
|||
|
|
@ -52,3 +52,8 @@ bmad-bmm-sprint-planning
|
|||
bmad-bmm-sprint-status
|
||||
bmad-bmm-technical-research
|
||||
bmad-bmm-validate-prd
|
||||
|
||||
# Removed skills (post-v6.7.x)
|
||||
# bmad-distillator: superseded by bmad-spec (universal intent distiller with
|
||||
# preservation-validated contract for downstream skills).
|
||||
bmad-distillator
|
||||
|
|
|
|||
|
|
@ -1,177 +0,0 @@
|
|||
---
|
||||
name: bmad-distillator
|
||||
description: Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'.
|
||||
---
|
||||
|
||||
# Distillator: A Document Distillation Engine
|
||||
|
||||
## Overview
|
||||
|
||||
This skill produces hyper-compressed, token-efficient documents (distillates) from any set of source documents. A distillate preserves every fact, decision, constraint, and relationship from the sources while stripping all overhead that humans need and LLMs don't. Act as an information extraction and compression specialist. The output is a single dense document (or semantically-split set) that a downstream LLM workflow can consume as sole context input without information loss.
|
||||
|
||||
This is a compression task, not a summarization task. Summaries are lossy. Distillates are lossless compression optimized for LLM consumption.
|
||||
|
||||
## On Activation
|
||||
|
||||
1. **Validate inputs.** The caller must provide:
|
||||
- **source_documents** (required) — One or more file paths, folder paths, or glob patterns to distill
|
||||
- **downstream_consumer** (optional) — What workflow/agent consumes this distillate (e.g., "PRD creation", "architecture design"). When provided, use it to judge signal vs noise. When omitted, preserve everything.
|
||||
- **token_budget** (optional) — Approximate target size. When provided and the distillate would exceed it, trigger semantic splitting.
|
||||
- **output_path** (optional) — Where to save. When omitted, save adjacent to the primary source document with `-distillate.md` suffix.
|
||||
- **--validate** (flag) — Run round-trip reconstruction test after producing the distillate.
|
||||
|
||||
2. **Route** — proceed to Stage 1.
|
||||
|
||||
## Stages
|
||||
|
||||
| # | Stage | Purpose |
|
||||
|---|-------|---------|
|
||||
| 1 | Analyze | Run analysis script, determine routing and splitting |
|
||||
| 2 | Compress | Spawn compressor agent(s) to produce the distillate |
|
||||
| 3 | Verify & Output | Completeness check, format check, save output |
|
||||
| 4 | Round-Trip Validate | (--validate only) Reconstruct and diff against originals |
|
||||
|
||||
### Stage 1: Analyze
|
||||
|
||||
Run `scripts/analyze_sources.py --help` then run it with the source paths. Use its routing recommendation and grouping output to drive Stage 2. Do NOT read the source documents yourself.
|
||||
|
||||
### Stage 2: Compress
|
||||
|
||||
**Single mode** (routing = `"single"`, ≤3 files, ≤15K estimated tokens):
|
||||
|
||||
Spawn one subagent using `agents/distillate-compressor.md` with all source file paths.
|
||||
|
||||
**Fan-out mode** (routing = `"fan-out"`):
|
||||
|
||||
1. Spawn one compressor subagent per group from the analysis output. Each compressor receives only its group's file paths and produces an intermediate distillate.
|
||||
|
||||
2. After all compressors return, spawn one final **merge compressor** subagent using `agents/distillate-compressor.md`. Pass it the intermediate distillate contents as its input (not the original files). Its job is cross-group deduplication, thematic regrouping, and final compression.
|
||||
|
||||
3. Clean up intermediate distillate content (it exists only in memory, not saved to disk).
|
||||
|
||||
**Graceful degradation:** If subagent spawning is unavailable, read the source documents and perform the compression work directly using the same instructions from `agents/distillate-compressor.md`. For fan-out, process groups sequentially then merge.
|
||||
|
||||
The compressor returns a structured JSON result containing the distillate content, source headings, named entities, and token estimate.
|
||||
|
||||
### Stage 3: Verify & Output
|
||||
|
||||
After the compressor (or merge compressor) returns:
|
||||
|
||||
1. **Completeness check.** Using the headings and named entities list returned by the compressor, verify each appears in the distillate content. If gaps are found, send them back to the compressor for a targeted fix pass — not a full recompression. Limit to 2 fix passes maximum.
|
||||
|
||||
2. **Format check.** Verify the output follows distillate format rules:
|
||||
- No prose paragraphs (only bullets)
|
||||
- No decorative formatting
|
||||
- No repeated information
|
||||
- Each bullet is self-contained
|
||||
- Themes are clearly delineated with `##` headings
|
||||
|
||||
3. **Determine output format.** Using the split prediction from Stage 1 and actual distillate size:
|
||||
|
||||
**Single distillate** (≤~5,000 tokens or token_budget not exceeded):
|
||||
|
||||
Save as a single file with frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: bmad-distillate
|
||||
sources:
|
||||
- "{relative path to source file 1}"
|
||||
- "{relative path to source file 2}"
|
||||
downstream_consumer: "{consumer or 'general'}"
|
||||
created: "{date}"
|
||||
token_estimate: {approximate token count}
|
||||
parts: 1
|
||||
---
|
||||
```
|
||||
|
||||
**Split distillate** (>~5,000 tokens, or token_budget requires it):
|
||||
|
||||
Create a folder `{base-name}-distillate/` containing:
|
||||
|
||||
```
|
||||
{base-name}-distillate/
|
||||
├── _index.md # Orientation, cross-cutting items, section manifest
|
||||
├── 01-{topic-slug}.md # Self-contained section
|
||||
├── 02-{topic-slug}.md
|
||||
└── 03-{topic-slug}.md
|
||||
```
|
||||
|
||||
The `_index.md` contains:
|
||||
- Frontmatter with sources (relative paths from the distillate folder to the originals)
|
||||
- 3-5 bullet orientation (what was distilled, from what)
|
||||
- Section manifest: each section's filename + 1-line description
|
||||
- Cross-cutting items that span multiple sections
|
||||
|
||||
Each section file is self-contained — loadable independently. Include a 1-line context header: "This section covers [topic]. Part N of M."
|
||||
|
||||
Source paths in frontmatter must be relative to the distillate's location.
|
||||
|
||||
4. **Measure distillate.** Run `scripts/analyze_sources.py` on the final distillate file(s) to get accurate token counts for the output. Use the `total_estimated_tokens` from this analysis as `distillate_total_tokens`.
|
||||
|
||||
5. **Report results.** Always return structured JSON output:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "complete",
|
||||
"distillate": "{path or folder path}",
|
||||
"section_distillates": ["{path1}", "{path2}"] or null,
|
||||
"source_total_tokens": N,
|
||||
"distillate_total_tokens": N,
|
||||
"compression_ratio": "X:1",
|
||||
"source_documents": ["{path1}", "{path2}"],
|
||||
"completeness_check": "pass" or "pass_with_additions"
|
||||
}
|
||||
```
|
||||
|
||||
Where `source_total_tokens` is from the Stage 1 analysis and `distillate_total_tokens` is from step 4. The `compression_ratio` is `source_total_tokens / distillate_total_tokens` formatted as "X:1" (e.g., "3.2:1").
|
||||
|
||||
6. If `--validate` flag was set, proceed to Stage 4. Otherwise, done.
|
||||
|
||||
### Stage 4: Round-Trip Validation (--validate only)
|
||||
|
||||
This stage proves the distillate is lossless by reconstructing source documents from the distillate alone. Use for critical documents where information loss is unacceptable, or as a quality gate for high-stakes downstream workflows. Not for routine use — it adds significant token cost.
|
||||
|
||||
1. **Spawn the reconstructor agent** using `agents/round-trip-reconstructor.md`. Pass it ONLY the distillate file path (or `_index.md` path for split distillates) — it must NOT have access to the original source documents.
|
||||
|
||||
For split distillates, spawn one reconstructor per section in parallel. Each receives its section file plus the `_index.md` for cross-cutting context.
|
||||
|
||||
**Graceful degradation:** If subagent spawning is unavailable, this stage cannot be performed by the main agent (it has already seen the originals). Report that round-trip validation requires subagent support and skip.
|
||||
|
||||
2. **Receive reconstructions.** The reconstructor returns reconstruction file paths saved adjacent to the distillate.
|
||||
|
||||
3. **Perform semantic diff.** Read both the original source documents and the reconstructions. For each section of the original, assess:
|
||||
- Is the core information present in the reconstruction?
|
||||
- Are specific details preserved (numbers, names, decisions)?
|
||||
- Are relationships and rationale intact?
|
||||
- Did the reconstruction add anything not in the original? (indicates hallucination filling gaps)
|
||||
|
||||
4. **Produce validation report** saved adjacent to the distillate as `-validation-report.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: distillate-validation
|
||||
distillate: "{distillate path}"
|
||||
sources: ["{source paths}"]
|
||||
created: "{date}"
|
||||
---
|
||||
|
||||
## Validation Summary
|
||||
- Status: PASS | PASS_WITH_WARNINGS | FAIL
|
||||
- Information preserved: {percentage estimate}
|
||||
- Gaps found: {count}
|
||||
- Hallucinations detected: {count}
|
||||
|
||||
## Gaps (information in originals but missing from reconstruction)
|
||||
- {gap description} — Source: {which original}, Section: {where}
|
||||
|
||||
## Hallucinations (information in reconstruction not traceable to originals)
|
||||
- {hallucination description} — appears to fill gap in: {section}
|
||||
|
||||
## Possible Gap Markers (flagged by reconstructor)
|
||||
- {marker description}
|
||||
```
|
||||
|
||||
5. **If gaps are found**, offer to run a targeted fix pass on the distillate — adding the missing information without full recompression. Limit to 2 fix passes maximum.
|
||||
|
||||
6. **Clean up** — delete the temporary reconstruction files after the report is generated.
|
||||
|
|
@ -1,116 +0,0 @@
|
|||
# Distillate Compressor Agent
|
||||
|
||||
Act as an information extraction and compression specialist. Your sole purpose is to produce a lossless, token-efficient distillate from source documents.
|
||||
|
||||
You receive: source document file paths, an optional downstream_consumer context, and a splitting decision.
|
||||
|
||||
You must load and apply `../resources/compression-rules.md` before producing output. Reference `../resources/distillate-format-reference.md` for the expected output format.
|
||||
|
||||
## Compression Process
|
||||
|
||||
### Step 1: Read Sources
|
||||
|
||||
Read all source document files. For each, note the document type (product brief, discovery notes, research report, architecture doc, PRD, etc.) based on content and naming.
|
||||
|
||||
### Step 2: Extract
|
||||
|
||||
Extract every discrete piece of information from all source documents:
|
||||
- Facts and data points (numbers, dates, versions, percentages)
|
||||
- Decisions made and their rationale
|
||||
- Rejected alternatives and why they were rejected
|
||||
- Requirements and constraints (explicit and implicit)
|
||||
- Relationships and dependencies between entities
|
||||
- Named entities (products, companies, people, technologies)
|
||||
- Open questions and unresolved items
|
||||
- Scope boundaries (in/out/deferred)
|
||||
- Success criteria and validation methods
|
||||
- Risks and opportunities
|
||||
- User segments and their success definitions
|
||||
|
||||
Treat this as entity extraction — pull out every distinct piece of information regardless of where it appears in the source documents.
|
||||
|
||||
### Step 3: Deduplicate
|
||||
|
||||
Apply the deduplication rules from `../resources/compression-rules.md`.
|
||||
|
||||
### Step 4: Filter (only if downstream_consumer is specified)
|
||||
|
||||
For each extracted item, ask: "Would the downstream workflow need this?"
|
||||
- Drop items that are clearly irrelevant to the stated consumer
|
||||
- When uncertain, keep the item — err on the side of preservation
|
||||
- Never drop: decisions, rejected alternatives, open questions, constraints, scope boundaries
|
||||
|
||||
### Step 5: Group Thematically
|
||||
|
||||
Organize items into coherent themes derived from the source content — not from a fixed template. The themes should reflect what the documents are actually about.
|
||||
|
||||
Common groupings (use what fits, omit what doesn't, add what's needed):
|
||||
- Core concept / problem / motivation
|
||||
- Solution / approach / architecture
|
||||
- Users / segments
|
||||
- Technical decisions / constraints
|
||||
- Scope boundaries (in/out/deferred)
|
||||
- Competitive context
|
||||
- Success criteria
|
||||
- Rejected alternatives
|
||||
- Open questions
|
||||
- Risks and opportunities
|
||||
|
||||
### Step 6: Compress Language
|
||||
|
||||
For each item, apply the compression rules from `../resources/compression-rules.md`:
|
||||
- Strip prose transitions and connective tissue
|
||||
- Remove hedging and rhetoric
|
||||
- Remove explanations of common knowledge
|
||||
- Preserve specific details (numbers, names, versions, dates)
|
||||
- Ensure the item is self-contained (understandable without reading the source)
|
||||
- Make relationships explicit ("X because Y", "X blocks Y", "X replaces Y")
|
||||
|
||||
### Step 7: Format Output
|
||||
|
||||
Produce the distillate as dense thematically-grouped bullets:
|
||||
- `##` headings for themes — no deeper heading levels needed
|
||||
- `- ` bullets for items — every token must carry signal
|
||||
- No decorative formatting (no bold for emphasis, no horizontal rules)
|
||||
- No prose paragraphs — only bullets
|
||||
- Semicolons to join closely related short items within a single bullet
|
||||
- Each bullet self-contained — understandable without reading other bullets
|
||||
|
||||
Do NOT include frontmatter — the calling skill handles that.
|
||||
|
||||
## Semantic Splitting
|
||||
|
||||
If the splitting decision indicates splitting is needed, load `../resources/splitting-strategy.md` and follow it.
|
||||
|
||||
When splitting:
|
||||
|
||||
1. Identify natural semantic boundaries in the content — coherent topic clusters, not arbitrary size breaks.
|
||||
|
||||
2. Produce a **root distillate** containing:
|
||||
- 3-5 bullet orientation (what was distilled, for whom, how many parts)
|
||||
- Cross-references to section distillates
|
||||
- Items that span multiple sections
|
||||
|
||||
3. Produce **section distillates**, each self-sufficient. Include a 1-line context header: "This section covers [topic]. Part N of M from [source document names]."
|
||||
|
||||
## Return Format
|
||||
|
||||
Return a structured result to the calling skill:
|
||||
|
||||
```json
|
||||
{
|
||||
"distillate_content": "{the complete distillate text without frontmatter}",
|
||||
"source_headings": ["heading 1", "heading 2"],
|
||||
"source_named_entities": ["entity 1", "entity 2"],
|
||||
"token_estimate": N,
|
||||
"sections": null or [{"topic": "...", "content": "..."}]
|
||||
}
|
||||
```
|
||||
|
||||
- **distillate_content**: The full distillate text
|
||||
- **source_headings**: All Level 2+ headings found across source documents (for completeness verification)
|
||||
- **source_named_entities**: Key named entities (products, companies, people, technologies, decisions) found in sources
|
||||
- **token_estimate**: Approximate token count of the distillate
|
||||
- **sections**: null for single distillates; array of section objects if semantically split
|
||||
|
||||
Do not include conversational text, status updates, or preamble — return only the structured result.
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
# Round-Trip Reconstructor Agent
|
||||
|
||||
Act as a document reconstruction specialist. Your purpose is to prove a distillate's completeness by reconstructing the original source documents from the distillate alone.
|
||||
|
||||
**Critical constraint:** You receive ONLY the distillate file path. You must NOT have access to the original source documents. If you can see the originals, the test is meaningless.
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Analyze the Distillate
|
||||
|
||||
Read the distillate file. Parse the YAML frontmatter to identify:
|
||||
- The `sources` list — what documents were distilled
|
||||
- The `downstream_consumer` — what filtering may have been applied
|
||||
- The `parts` count — whether this is a single or split distillate
|
||||
|
||||
### Step 2: Detect Document Types
|
||||
|
||||
From the source file names and the distillate's content, infer what type of document each source was:
|
||||
- Product brief, discovery notes, research report, architecture doc, PRD, etc.
|
||||
- Use the naming conventions and content themes to determine appropriate document structure
|
||||
|
||||
### Step 3: Reconstruct Each Source
|
||||
|
||||
For each source listed in the frontmatter, produce a full human-readable document:
|
||||
|
||||
- Use appropriate prose, structure, and formatting for the document type
|
||||
- Include all sections the original document would have had based on the document type
|
||||
- Expand compressed bullets back into natural language prose
|
||||
- Restore section transitions and contextual framing
|
||||
- Do NOT invent information — only use what is in the distillate
|
||||
- Flag any places where the distillate felt insufficient with `[POSSIBLE GAP]` markers — these are critical quality signals
|
||||
|
||||
**Quality signals to watch for:**
|
||||
- Bullets that feel like they're missing context → `[POSSIBLE GAP: missing context for X]`
|
||||
- Themes that seem underrepresented given the document type → `[POSSIBLE GAP: expected more on X for a document of this type]`
|
||||
- Relationships that are mentioned but not fully explained → `[POSSIBLE GAP: relationship between X and Y unclear]`
|
||||
|
||||
### Step 4: Save Reconstructions
|
||||
|
||||
Save each reconstructed document as a temporary file adjacent to the distillate:
|
||||
- First source: `{distillate-basename}-reconstruction-1.md`
|
||||
- Second source: `{distillate-basename}-reconstruction-2.md`
|
||||
- And so on for each source
|
||||
|
||||
Each reconstruction should include a header noting it was reconstructed:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: distillate-reconstruction
|
||||
source_distillate: "{distillate path}"
|
||||
reconstructed_from: "{original source name}"
|
||||
reconstruction_number: {N}
|
||||
---
|
||||
```
|
||||
|
||||
### Step 5: Return
|
||||
|
||||
Return a structured result to the calling skill:
|
||||
|
||||
```json
|
||||
{
|
||||
"reconstruction_files": ["{path1}", "{path2}"],
|
||||
"possible_gaps": ["gap description 1", "gap description 2"],
|
||||
"source_count": N
|
||||
}
|
||||
```
|
||||
|
||||
Do not include conversational text, status updates, or preamble — return only the structured result.
|
||||
|
|
@ -1,51 +0,0 @@
|
|||
# Compression Rules
|
||||
|
||||
These rules govern how source text is compressed into distillate format. Apply as a final pass over all output.
|
||||
|
||||
## Strip — Remove entirely
|
||||
|
||||
- Prose transitions: "As mentioned earlier", "It's worth noting", "In addition to this"
|
||||
- Rhetoric and persuasion: "This is a game-changer", "The exciting thing is"
|
||||
- Hedging: "We believe", "It's likely that", "Perhaps", "It seems"
|
||||
- Self-reference: "This document describes", "As outlined above"
|
||||
- Common knowledge explanations: "Vercel is a cloud platform company", "MIT is an open-source license", "JSON is a data interchange format"
|
||||
- Repeated introductions of the same concept
|
||||
- Section transition paragraphs
|
||||
- Formatting-only elements (decorative bold/italic for emphasis, horizontal rules for visual breaks)
|
||||
- Filler phrases: "In order to", "It should be noted that", "The fact that"
|
||||
|
||||
## Preserve — Keep always
|
||||
|
||||
- Specific numbers, dates, versions, percentages
|
||||
- Named entities (products, companies, people, technologies)
|
||||
- Decisions made and their rationale (compressed: "Decision: X. Reason: Y")
|
||||
- Rejected alternatives and why (compressed: "Rejected: X. Reason: Y")
|
||||
- Explicit constraints and non-negotiables
|
||||
- Dependencies and ordering relationships
|
||||
- Open questions and unresolved items
|
||||
- Scope boundaries (in/out/deferred)
|
||||
- Success criteria and how they're validated
|
||||
- User segments and what success means for each
|
||||
- Risks with their severity signals
|
||||
- Conflicts between source documents
|
||||
|
||||
## Transform — Change form for efficiency
|
||||
|
||||
- Long prose paragraphs → single dense bullet capturing the same information
|
||||
- "We decided to use X because Y and Z" → "X (rationale: Y, Z)"
|
||||
- Repeated category labels → group under a single heading, no per-item labels
|
||||
- "Risk: ... Severity: high" → "HIGH RISK: ..."
|
||||
- Conditional statements → "If X → Y" form
|
||||
- Multi-sentence explanations → semicolon-separated compressed form
|
||||
- Lists of related short items → single bullet with semicolons
|
||||
- "X is used for Y" → "X: Y" when context is clear
|
||||
- Verbose enumerations → parenthetical lists: "platforms (Cursor, Claude Code, Windsurf, Copilot)"
|
||||
|
||||
## Deduplication Rules
|
||||
|
||||
- Same fact in multiple documents → keep the version with most context
|
||||
- Same concept at different detail levels → keep the detailed version
|
||||
- Overlapping lists → merge into single list, no duplicates
|
||||
- When source documents disagree → note the conflict explicitly: "Brief says X; discovery notes say Y — unresolved"
|
||||
- Executive summary points that are expanded elsewhere → keep only the expanded version
|
||||
- Introductory framing repeated across sections → capture once under the most relevant theme
|
||||
|
|
@ -1,227 +0,0 @@
|
|||
# Distillate Format Reference
|
||||
|
||||
Examples showing the transformation from human-readable source content to distillate format.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
Every distillate includes YAML frontmatter. Source paths are relative to the distillate's location so the distillate remains portable:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: bmad-distillate
|
||||
sources:
|
||||
- "product-brief-example.md"
|
||||
- "product-brief-example-discovery-notes.md"
|
||||
downstream_consumer: "PRD creation"
|
||||
created: "2026-03-13"
|
||||
token_estimate: 1200
|
||||
parts: 1
|
||||
---
|
||||
```
|
||||
|
||||
## Before/After Examples
|
||||
|
||||
### Prose Paragraph to Dense Bullet
|
||||
|
||||
**Before** (human-readable brief excerpt):
|
||||
```
|
||||
## What Makes This Different
|
||||
|
||||
**The anti-fragmentation layer.** The AI tooling space is fracturing across 40+
|
||||
platforms with no shared methodology layer. BMAD is uniquely positioned to be the
|
||||
cross-platform constant — the structured approach that works the same in Cursor,
|
||||
Claude Code, Windsurf, Copilot, and whatever launches next month. Every other
|
||||
methodology or skill framework maintains its own platform support matrix. By
|
||||
building on the open-source skills CLI ecosystem, BMAD offloads the highest-churn
|
||||
maintenance burden and focuses on what actually differentiates it: the methodology
|
||||
itself.
|
||||
```
|
||||
|
||||
**After** (distillate):
|
||||
```
|
||||
## Differentiation
|
||||
- Anti-fragmentation positioning: BMAD = cross-platform constant across 40+ fragmenting AI tools; no competitor provides shared methodology layer
|
||||
- Platform complexity delegated to Vercel skills CLI ecosystem (MIT); BMAD maintains methodology, not platform configs
|
||||
```
|
||||
|
||||
### Technical Details to Compressed Facts
|
||||
|
||||
**Before** (discovery notes excerpt):
|
||||
```
|
||||
## Competitive Landscape
|
||||
|
||||
- **Vercel Skills.sh**: 83K+ skills, 18 agents, largest curated leaderboard —
|
||||
but dev-only, skills trigger unreliably (20% without explicit prompting)
|
||||
- **SkillsMP**: 400K+ skills directory, pure aggregator with no curation or CLI
|
||||
- **ClawHub/OpenClaw**: ~3.2K curated skills with versioning/rollback, small ecosystem
|
||||
- **Lindy**: No-code AI agent builder for business automation — closed platform,
|
||||
no skill sharing
|
||||
- **Microsoft Copilot Studio**: Enterprise no-code agent builder — vendor-locked
|
||||
to Microsoft
|
||||
- **MindStudio**: No-code AI agent platform — siloed, no interoperability
|
||||
- **Make/Zapier AI**: Workflow automation adding AI agents — workflow-centric,
|
||||
not methodology-centric
|
||||
- **Key gap**: NO competitor combines structured methodology with plugin
|
||||
marketplace — this is BMAD's whitespace
|
||||
```
|
||||
|
||||
**After** (distillate):
|
||||
```
|
||||
## Competitive Landscape
|
||||
- No competitor combines structured methodology + plugin marketplace (whitespace)
|
||||
- Skills.sh (Vercel): 83K skills, 18 agents, dev-only, 20% trigger reliability
|
||||
- SkillsMP: 400K skills, aggregator only, no curation/CLI
|
||||
- ClawHub: 3.2K curated, versioning, small ecosystem
|
||||
- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only
|
||||
```
|
||||
|
||||
### Deduplication Across Documents
|
||||
|
||||
When the same fact appears in both a brief and discovery notes:
|
||||
|
||||
**Brief says:**
|
||||
```
|
||||
bmad-help must always be included as a base skill in every bundle
|
||||
```
|
||||
|
||||
**Discovery notes say:**
|
||||
```
|
||||
bmad-help must always be included as a base skill in every bundle/install
|
||||
(solves discoverability problem)
|
||||
```
|
||||
|
||||
**Distillate keeps the more contextual version:**
|
||||
```
|
||||
- bmad-help: always included as base skill in every bundle (solves discoverability)
|
||||
```
|
||||
|
||||
### Decision/Rationale Compression
|
||||
|
||||
**Before:**
|
||||
```
|
||||
We decided not to build our own platform support matrix going forward, instead
|
||||
delegating to the Vercel skills CLI ecosystem. The rationale is that maintaining
|
||||
20+ platform configs is the biggest maintenance burden and it's unsustainable
|
||||
at 40+ platforms.
|
||||
```
|
||||
|
||||
**After:**
|
||||
```
|
||||
- Rejected: own platform support matrix. Reason: unsustainable at 40+ platforms; delegate to Vercel CLI ecosystem
|
||||
```
|
||||
|
||||
## Full Example
|
||||
|
||||
A complete distillate produced from a product brief and its discovery notes, targeted at PRD creation:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: bmad-distillate
|
||||
sources:
|
||||
- "product-brief-bmad-next-gen-installer.md"
|
||||
- "product-brief-bmad-next-gen-installer-discovery-notes.md"
|
||||
downstream_consumer: "PRD creation"
|
||||
created: "2026-03-13"
|
||||
token_estimate: 1450
|
||||
parts: 1
|
||||
---
|
||||
|
||||
## Core Concept
|
||||
- BMAD Next-Gen Installer: replaces monolithic Node.js CLI with skill-based plugin architecture for distributing BMAD methodology across 40+ AI platforms
|
||||
- Three layers: self-describing plugins (bmad-manifest.json), cross-platform install via Vercel skills CLI (MIT), runtime registration via bmad-setup skill
|
||||
- Transforms BMAD from dev-only methodology into open platform for any domain (creative, therapeutic, educational, personal)
|
||||
|
||||
## Problem
|
||||
- Current installer maintains ~20 platform configs manually; each platform convention change requires installer update, test, release — largest maintenance burden on team
|
||||
- Node.js/npm required — blocks non-technical users on UI-based platforms (Claude Co-Work, etc.)
|
||||
- CSV manifests are static, generated once at install; no runtime scanning/registration
|
||||
- Unsustainable at 40+ platforms; new tools launching weekly
|
||||
|
||||
## Solution Architecture
|
||||
- Plugins: skill bundles with Anthropic plugin standard as base format + bmad-manifest.json extending for BMAD-specific metadata (installer options, capabilities, help integration, phase ordering, dependencies)
|
||||
- Existing manifest example: `{"module-code":"bmm","replaces-skill":"bmad-create-product-brief","capabilities":[{"name":"create-brief","menu-code":"CB","supports-headless":true,"phase-name":"1-analysis","preceded-by":["brainstorming"],"followed-by":["create-prd"],"is-required":true}]}`
|
||||
- Vercel skills CLI handles platform translation; integration pattern (wrap/fork/call) is PRD decision
|
||||
- bmad-setup: global skill scanning installed bmad-manifest.json files, registering capabilities, configuring project settings; always included as base skill in every bundle (solves bootstrapping)
|
||||
- bmad-update: plugin update path without full reinstall; technical approach (diff/replace/preserve customizations) is PRD decision
|
||||
- Distribution tiers: (1) NPX installer wrapping skills CLI for technical users, (2) zip bundle + platform-specific README for non-technical users, (3) future marketplace
|
||||
- Non-technical path has honest friction: "copy to right folder" requires knowing where; per-platform README instructions; improves over time as low-code space matures
|
||||
|
||||
## Differentiation
|
||||
- Anti-fragmentation: BMAD = cross-platform constant; no competitor provides shared methodology layer across AI tools
|
||||
- Curated quality: all submissions gated, human-reviewed by BMad + core team; 13.4% of community skills have critical vulnerabilities (Snyk 2026); quality gate value increases as ecosystem gets noisier
|
||||
- Domain-agnostic: no competitor builds beyond software dev workflows; same plugin system powers any domain via BMAD Builder (separate initiative)
|
||||
|
||||
## Users (ordered by v1 priority)
|
||||
- Module authors (primary v1): package/test/distribute plugins independently without installer changes
|
||||
- Developers: single-command install on any of 40+ platforms via NPX
|
||||
- Non-technical users: install without Node/Git/terminal; emerging segment including PMs, designers, educators
|
||||
- Future plugin creators: non-dev authors using BMAD Builder; need distribution without building own installer
|
||||
|
||||
## Success Criteria
|
||||
- Zero (or near-zero) custom platform directory code; delegated to skills CLI ecosystem
|
||||
- Installation verified on top platforms by volume; skills CLI handles long tail
|
||||
- Non-technical install path validated with non-developer users
|
||||
- bmad-setup discovers/registers all plugins from manifests; clear errors for malformed manifests
|
||||
- At least one external module author successfully publishes plugin using manifest system
|
||||
- bmad-update works without full reinstall
|
||||
- Existing CLI users have documented migration path
|
||||
|
||||
## Scope
|
||||
- In: manifest spec, bmad-setup, bmad-update, Vercel CLI integration, NPX installer, zip bundles, migration path
|
||||
- Out: BMAD Builder, marketplace web platform, skill conversion (prerequisite, separate), one-click install for all platforms, monetization, quality certification process (gated-submission principle is architectural requirement; process defined separately)
|
||||
- Deferred: CI/CD integration, telemetry for module authors, air-gapped enterprise install, zip bundle integrity verification (checksums/signing), deeper non-technical platform integrations
|
||||
|
||||
## Current Installer (migration context)
|
||||
- Entry: `tools/installer/bmad-cli.js` (Commander.js) → `tools/installer/core/installer.js`
|
||||
- Platforms: `platform-codes.yaml` (~20 platforms with target dirs, legacy dirs, template types, special flags)
|
||||
- Manifests: skill-manifest.csv is the current source of truth; agent essence lives in `_bmad/config.toml` (generated from each module.yaml's `agents:` block)
|
||||
- External modules: `external-official-modules.yaml` (CIS, GDS, TEA, WDS) from npm with semver
|
||||
- Dependencies: 4-pass resolver (collect → parse → resolve → transitive); YAML-declared only
|
||||
- Config: prompts for name, communication language, document output language, output folder
|
||||
- Skills already use directory-per-skill layout; bmad-manifest.json sidecars exist but are not source of truth
|
||||
- Key shift: CSV-based static manifests → JSON-based runtime scanning
|
||||
|
||||
## Vercel Skills CLI
|
||||
- `npx skills add <source>` — GitHub, GitLab, local paths, git URLs
|
||||
- 40+ agents; per-agent path mappings; symlinks (recommended) or copies
|
||||
- Scopes: project-level or global
|
||||
- Discovery: `skills/`, `.agents/skills/`, agent-specific paths, `.claude-plugin/marketplace.json`
|
||||
- Commands: add, list, find, remove, check, update, init
|
||||
- Non-interactive: `-y`, `--all` flags for CI/CD
|
||||
|
||||
## Competitive Landscape
|
||||
- No competitor combines structured methodology + plugin marketplace (whitespace)
|
||||
- Skills.sh (Vercel): 83K skills, dev-only, 20% trigger reliability without explicit prompting
|
||||
- SkillsMP: 400K skills, aggregator only, no curation
|
||||
- ClawHub: 3.2K curated, versioning, small
|
||||
- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only
|
||||
- Market: $7.84B (2025) → $52.62B (2030); Agent Skills spec ~4 months old, 351K+ skills; standards converging under Linux Foundation AAIF (MCP, AGENTS.md, A2A)
|
||||
|
||||
## Rejected Alternatives
|
||||
- Building own platform support matrix: unsustainable at 40+; delegate to Vercel ecosystem
|
||||
- One-click install for non-technical v1: emerging space; guidance-based, improve over time
|
||||
- Prior roadmap/brainstorming: clean start, unconstrained by previous planning
|
||||
|
||||
## Open Questions
|
||||
- Vercel CLI integration pattern: wrap/fork/call/peer dependency?
|
||||
- bmad-update mechanics: diff/replace? Preserve user customizations?
|
||||
- Migration story: command/manual reinstall/compatibility shim?
|
||||
- Cross-platform testing: CI matrix for top N? Community testing for rest?
|
||||
- bmad-manifest.json as open standard submission to Agent Skills governance?
|
||||
- Platforms NOT supported by Vercel skills CLI?
|
||||
- Manifest versioning strategy for backward compatibility?
|
||||
- Plugin author getting-started experience and tooling?
|
||||
|
||||
## Opportunities
|
||||
- Module authors as acquisition channel: each published plugin distributes BMAD to creator's audience
|
||||
- CI/CD integration: bmad-setup as pipeline one-liner increases stickiness
|
||||
- Educational institutions: structured methodology + non-technical install → university AI curriculum
|
||||
- Skill composability: mixing BMAD modules with third-party skills for custom methodology stacks
|
||||
|
||||
## Risks
|
||||
- Manifest format evolution creates versioning/compatibility burden once third-party authors publish
|
||||
- Quality gate needs defined process, not just claim — gated review model addresses
|
||||
- 40+ platform testing environments even with Vercel handling translation
|
||||
- Scope creep pressure from marketplace vision (explicitly excluded but primary long-term value)
|
||||
- Vercel dependency: minor supply-chain risk; MIT license allows fork if deprioritized
|
||||
```
|
||||
|
|
@ -1,78 +0,0 @@
|
|||
# Semantic Splitting Strategy
|
||||
|
||||
When the source content is large (exceeds ~15,000 tokens) or a token_budget requires it, split the distillate into semantically coherent sections rather than arbitrary size breaks.
|
||||
|
||||
## Why Semantic Over Size-Based
|
||||
|
||||
Arbitrary splits (every N tokens) break coherence. A downstream workflow loading "part 2 of 4" gets context fragments. Semantic splits produce self-contained topic clusters that a workflow can load selectively — "give me just the technical decisions section" — which is more useful and more token-efficient for the consumer.
|
||||
|
||||
## Splitting Process
|
||||
|
||||
### 1. Identify Natural Boundaries
|
||||
|
||||
After the initial extraction and deduplication (Steps 1-2 of the compression process), look for natural semantic boundaries:
|
||||
- Distinct problem domains or functional areas
|
||||
- Different stakeholder perspectives (users, technical, business)
|
||||
- Temporal boundaries (current state vs future vision)
|
||||
- Scope boundaries (in-scope vs out-of-scope vs deferred)
|
||||
- Phase boundaries (analysis, design, implementation)
|
||||
|
||||
Choose boundaries that produce sections a downstream workflow might load independently.
|
||||
|
||||
### 2. Assign Items to Sections
|
||||
|
||||
For each extracted item, assign it to the most relevant section. Items that span multiple sections go in the root distillate.
|
||||
|
||||
Cross-cutting items (items relevant to multiple sections):
|
||||
- Constraints that affect all areas → root distillate
|
||||
- Decisions with broad impact → root distillate
|
||||
- Section-specific decisions → section distillate
|
||||
|
||||
### 3. Produce Root Distillate
|
||||
|
||||
The root distillate contains:
|
||||
- **Orientation** (3-5 bullets): what was distilled, from what sources, for what consumer, how many sections
|
||||
- **Cross-references**: list of section distillates with 1-line descriptions
|
||||
- **Cross-cutting items**: facts, decisions, and constraints that span multiple sections
|
||||
- **Scope summary**: high-level in/out/deferred if applicable
|
||||
|
||||
### 4. Produce Section Distillates
|
||||
|
||||
Each section distillate must be self-sufficient — a reader loading only one section should understand it without the others.
|
||||
|
||||
Each section includes:
|
||||
- **Context header** (1 line): "This section covers [topic]. Part N of M from [source document names]."
|
||||
- **Section content**: thematically-grouped bullets following the same compression rules as a single distillate
|
||||
- **Cross-references** (if needed): pointers to other sections for related content
|
||||
|
||||
### 5. Output Structure
|
||||
|
||||
Create a folder `{base-name}-distillate/` containing:
|
||||
|
||||
```
|
||||
{base-name}-distillate/
|
||||
├── _index.md # Root distillate: orientation, cross-cutting items, section manifest
|
||||
├── 01-{topic-slug}.md # Self-contained section
|
||||
├── 02-{topic-slug}.md
|
||||
└── 03-{topic-slug}.md
|
||||
```
|
||||
|
||||
Example:
|
||||
```
|
||||
product-brief-distillate/
|
||||
├── _index.md
|
||||
├── 01-problem-solution.md
|
||||
├── 02-technical-decisions.md
|
||||
└── 03-users-market.md
|
||||
```
|
||||
|
||||
## Size Targets
|
||||
|
||||
When a token_budget is specified:
|
||||
- Root distillate: ~20% of budget (orientation + cross-cutting items)
|
||||
- Remaining budget split proportionally across sections based on content density
|
||||
- If a section exceeds its proportional share, compress more aggressively or sub-split
|
||||
|
||||
When no token_budget but splitting is needed:
|
||||
- Aim for sections of 3,000-5,000 tokens each
|
||||
- Root distillate as small as possible while remaining useful standalone
|
||||
|
|
@ -1,300 +0,0 @@
|
|||
# /// script
|
||||
# /// requires-python = ">=3.10"
|
||||
# /// dependencies = []
|
||||
# ///
|
||||
"""Analyze source documents for the distillation generator.
|
||||
|
||||
Enumerates files from paths/folders/globs, computes sizes and token estimates,
|
||||
detects document types from naming conventions, and suggests groupings for
|
||||
related documents (e.g., a brief paired with its discovery notes).
|
||||
|
||||
Accepts: file paths, folder paths (scans recursively for .md/.txt/.yaml/.yml/.json),
|
||||
or glob patterns. Skips node_modules, .git, __pycache__, .venv, _bmad-output.
|
||||
|
||||
Output JSON structure:
|
||||
status: "ok" | "error"
|
||||
files[]: path, filename, size_bytes, estimated_tokens, doc_type
|
||||
summary: total_files, total_size_bytes, total_estimated_tokens
|
||||
groups[]: group_key, files[] with role (primary/companion/standalone)
|
||||
- Groups related docs by naming convention (e.g., brief + discovery-notes)
|
||||
routing: recommendation ("single" | "fan-out"), reason
|
||||
- single: ≤3 files AND ≤15K estimated tokens
|
||||
- fan-out: >3 files OR >15K estimated tokens
|
||||
split_prediction: prediction ("likely" | "unlikely"), reason, estimated_distillate_tokens
|
||||
- Estimates distillate at ~1/3 source size; splits if >5K tokens
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import glob
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# Extensions to include when scanning folders
|
||||
INCLUDE_EXTENSIONS = {".md", ".txt", ".yaml", ".yml", ".json"}
|
||||
|
||||
# Directories to skip when scanning folders
|
||||
SKIP_DIRS = {
|
||||
"node_modules", ".git", "__pycache__", ".venv", "venv",
|
||||
".claude", "_bmad-output", ".cursor", ".vscode",
|
||||
}
|
||||
|
||||
# Approximate chars per token for estimation
|
||||
CHARS_PER_TOKEN = 4
|
||||
|
||||
# Thresholds
|
||||
SINGLE_COMPRESSOR_MAX_TOKENS = 15_000
|
||||
SINGLE_DISTILLATE_MAX_TOKENS = 5_000
|
||||
|
||||
# Naming patterns for document type detection
|
||||
DOC_TYPE_PATTERNS = [
|
||||
(r"discovery[_-]notes", "discovery-notes"),
|
||||
(r"product[_-]brief", "product-brief"),
|
||||
(r"research[_-]report", "research-report"),
|
||||
(r"architecture", "architecture-doc"),
|
||||
(r"prd", "prd"),
|
||||
(r"distillate", "distillate"),
|
||||
(r"changelog", "changelog"),
|
||||
(r"readme", "readme"),
|
||||
(r"spec", "specification"),
|
||||
(r"requirements", "requirements"),
|
||||
(r"design[_-]doc", "design-doc"),
|
||||
(r"meeting[_-]notes", "meeting-notes"),
|
||||
(r"brainstorm", "brainstorming"),
|
||||
(r"interview", "interview-notes"),
|
||||
]
|
||||
|
||||
# Patterns for grouping related documents
|
||||
GROUP_PATTERNS = [
|
||||
# base document + discovery notes
|
||||
(r"^(.+?)(?:-discovery-notes|-discovery_notes)\.(\w+)$", r"\1.\2"),
|
||||
# base document + appendix
|
||||
(r"^(.+?)(?:-appendix|-addendum)(?:-\w+)?\.(\w+)$", r"\1.\2"),
|
||||
# base document + review/feedback
|
||||
(r"^(.+?)(?:-review|-feedback)\.(\w+)$", r"\1.\2"),
|
||||
]
|
||||
|
||||
|
||||
def resolve_inputs(inputs: list[str]) -> list[Path]:
|
||||
"""Resolve input arguments to a flat list of file paths."""
|
||||
files: list[Path] = []
|
||||
for inp in inputs:
|
||||
path = Path(inp)
|
||||
if path.is_file():
|
||||
files.append(path.resolve())
|
||||
elif path.is_dir():
|
||||
for root, dirs, filenames in os.walk(path):
|
||||
dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
|
||||
for fn in sorted(filenames):
|
||||
fp = Path(root) / fn
|
||||
if fp.suffix.lower() in INCLUDE_EXTENSIONS:
|
||||
files.append(fp.resolve())
|
||||
else:
|
||||
# Try as glob
|
||||
matches = glob.glob(inp, recursive=True)
|
||||
for m in sorted(matches):
|
||||
mp = Path(m)
|
||||
if mp.is_file() and mp.suffix.lower() in INCLUDE_EXTENSIONS:
|
||||
files.append(mp.resolve())
|
||||
# Deduplicate while preserving order
|
||||
seen: set[Path] = set()
|
||||
deduped: list[Path] = []
|
||||
for f in files:
|
||||
if f not in seen:
|
||||
seen.add(f)
|
||||
deduped.append(f)
|
||||
return deduped
|
||||
|
||||
|
||||
def detect_doc_type(filename: str) -> str:
|
||||
"""Detect document type from filename."""
|
||||
name_lower = filename.lower()
|
||||
for pattern, doc_type in DOC_TYPE_PATTERNS:
|
||||
if re.search(pattern, name_lower):
|
||||
return doc_type
|
||||
return "unknown"
|
||||
|
||||
|
||||
def suggest_groups(files: list[Path]) -> list[dict]:
|
||||
"""Suggest document groupings based on naming conventions."""
|
||||
groups: dict[str, list[dict]] = {}
|
||||
ungrouped: list[dict] = []
|
||||
|
||||
file_map = {f.name: f for f in files}
|
||||
|
||||
assigned: set[str] = set()
|
||||
|
||||
for f in files:
|
||||
if f.name in assigned:
|
||||
continue
|
||||
|
||||
matched = False
|
||||
for pattern, base_pattern in GROUP_PATTERNS:
|
||||
m = re.match(pattern, f.name, re.IGNORECASE)
|
||||
if m:
|
||||
# This file is a companion — find its base
|
||||
base_name = re.sub(pattern, base_pattern, f.name, flags=re.IGNORECASE)
|
||||
group_key = base_name
|
||||
if group_key not in groups:
|
||||
groups[group_key] = []
|
||||
# Add the base file if it exists
|
||||
if base_name in file_map and base_name not in assigned:
|
||||
groups[group_key].append({
|
||||
"path": str(file_map[base_name]),
|
||||
"filename": base_name,
|
||||
"role": "primary",
|
||||
})
|
||||
assigned.add(base_name)
|
||||
groups[group_key].append({
|
||||
"path": str(f),
|
||||
"filename": f.name,
|
||||
"role": "companion",
|
||||
})
|
||||
assigned.add(f.name)
|
||||
matched = True
|
||||
break
|
||||
|
||||
if not matched:
|
||||
# Check if this file is a base that already has companions
|
||||
if f.name in groups:
|
||||
continue # Already added as primary
|
||||
ungrouped.append({
|
||||
"path": str(f),
|
||||
"filename": f.name,
|
||||
})
|
||||
|
||||
result = []
|
||||
for group_key, members in groups.items():
|
||||
result.append({
|
||||
"group_key": group_key,
|
||||
"files": members,
|
||||
})
|
||||
for ug in ungrouped:
|
||||
if ug["filename"] not in assigned:
|
||||
result.append({
|
||||
"group_key": ug["filename"],
|
||||
"files": [{"path": ug["path"], "filename": ug["filename"], "role": "standalone"}],
|
||||
})
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def analyze(inputs: list[str], output_path: str | None = None) -> None:
|
||||
"""Main analysis function."""
|
||||
files = resolve_inputs(inputs)
|
||||
|
||||
if not files:
|
||||
result = {
|
||||
"status": "error",
|
||||
"error": "No readable files found from provided inputs",
|
||||
"inputs": inputs,
|
||||
}
|
||||
output_json(result, output_path)
|
||||
return
|
||||
|
||||
# Analyze each file
|
||||
file_details = []
|
||||
total_chars = 0
|
||||
for f in files:
|
||||
size = f.stat().st_size
|
||||
total_chars += size
|
||||
file_details.append({
|
||||
"path": str(f),
|
||||
"filename": f.name,
|
||||
"size_bytes": size,
|
||||
"estimated_tokens": size // CHARS_PER_TOKEN,
|
||||
"doc_type": detect_doc_type(f.name),
|
||||
})
|
||||
|
||||
total_tokens = total_chars // CHARS_PER_TOKEN
|
||||
groups = suggest_groups(files)
|
||||
|
||||
# Routing recommendation
|
||||
if len(files) <= 3 and total_tokens <= SINGLE_COMPRESSOR_MAX_TOKENS:
|
||||
routing = "single"
|
||||
routing_reason = (
|
||||
f"{len(files)} file(s), ~{total_tokens:,} estimated tokens — "
|
||||
f"within single compressor threshold"
|
||||
)
|
||||
else:
|
||||
routing = "fan-out"
|
||||
routing_reason = (
|
||||
f"{len(files)} file(s), ~{total_tokens:,} estimated tokens — "
|
||||
f"exceeds single compressor threshold "
|
||||
f"({'>' + str(SINGLE_COMPRESSOR_MAX_TOKENS) + ' tokens' if total_tokens > SINGLE_COMPRESSOR_MAX_TOKENS else '> 3 files'})"
|
||||
)
|
||||
|
||||
# Split prediction
|
||||
estimated_distillate_tokens = total_tokens // 3 # rough: distillate is ~1/3 of source
|
||||
if estimated_distillate_tokens > SINGLE_DISTILLATE_MAX_TOKENS:
|
||||
split_prediction = "likely"
|
||||
split_reason = (
|
||||
f"Estimated distillate ~{estimated_distillate_tokens:,} tokens "
|
||||
f"exceeds {SINGLE_DISTILLATE_MAX_TOKENS:,} threshold"
|
||||
)
|
||||
else:
|
||||
split_prediction = "unlikely"
|
||||
split_reason = (
|
||||
f"Estimated distillate ~{estimated_distillate_tokens:,} tokens "
|
||||
f"within {SINGLE_DISTILLATE_MAX_TOKENS:,} threshold"
|
||||
)
|
||||
|
||||
result = {
|
||||
"status": "ok",
|
||||
"files": file_details,
|
||||
"summary": {
|
||||
"total_files": len(files),
|
||||
"total_size_bytes": total_chars,
|
||||
"total_estimated_tokens": total_tokens,
|
||||
},
|
||||
"groups": groups,
|
||||
"routing": {
|
||||
"recommendation": routing,
|
||||
"reason": routing_reason,
|
||||
},
|
||||
"split_prediction": {
|
||||
"prediction": split_prediction,
|
||||
"reason": split_reason,
|
||||
"estimated_distillate_tokens": estimated_distillate_tokens,
|
||||
},
|
||||
}
|
||||
|
||||
output_json(result, output_path)
|
||||
|
||||
|
||||
def output_json(data: dict, output_path: str | None) -> None:
|
||||
"""Write JSON to file or stdout."""
|
||||
json_str = json.dumps(data, indent=2)
|
||||
if output_path:
|
||||
Path(output_path).parent.mkdir(parents=True, exist_ok=True)
|
||||
Path(output_path).write_text(json_str + "\n")
|
||||
print(f"Results written to {output_path}", file=sys.stderr)
|
||||
else:
|
||||
print(json_str)
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(
|
||||
description=__doc__,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
parser.add_argument(
|
||||
"inputs",
|
||||
nargs="+",
|
||||
help="File paths, folder paths, or glob patterns to analyze",
|
||||
)
|
||||
parser.add_argument(
|
||||
"-o", "--output",
|
||||
help="Output JSON to file instead of stdout",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
analyze(args.inputs, args.output)
|
||||
sys.exit(0)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
|
|
@ -1,204 +0,0 @@
|
|||
"""Tests for analyze_sources.py"""
|
||||
|
||||
import json
|
||||
import os
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
from unittest.mock import patch
|
||||
|
||||
import pytest
|
||||
|
||||
# Add parent dir to path so we can import the script
|
||||
import sys
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent))
|
||||
|
||||
from analyze_sources import (
|
||||
resolve_inputs,
|
||||
detect_doc_type,
|
||||
suggest_groups,
|
||||
analyze,
|
||||
INCLUDE_EXTENSIONS,
|
||||
SKIP_DIRS,
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def temp_dir():
|
||||
"""Create a temp directory with sample files."""
|
||||
with tempfile.TemporaryDirectory() as d:
|
||||
# Create sample files
|
||||
(Path(d) / "product-brief-foo.md").write_text("# Product Brief\nContent here")
|
||||
(Path(d) / "product-brief-foo-discovery-notes.md").write_text("# Discovery\nNotes")
|
||||
(Path(d) / "architecture-doc.md").write_text("# Architecture\nDesign here")
|
||||
(Path(d) / "research-report.md").write_text("# Research\nFindings")
|
||||
(Path(d) / "random.txt").write_text("Some text content")
|
||||
(Path(d) / "image.png").write_bytes(b"\x89PNG")
|
||||
# Create a subdirectory with more files
|
||||
sub = Path(d) / "subdir"
|
||||
sub.mkdir()
|
||||
(sub / "prd-v2.md").write_text("# PRD\nRequirements")
|
||||
# Create a skip directory
|
||||
skip = Path(d) / "node_modules"
|
||||
skip.mkdir()
|
||||
(skip / "junk.md").write_text("Should be skipped")
|
||||
yield d
|
||||
|
||||
|
||||
class TestResolveInputs:
|
||||
def test_single_file(self, temp_dir):
|
||||
f = str(Path(temp_dir) / "product-brief-foo.md")
|
||||
result = resolve_inputs([f])
|
||||
assert len(result) == 1
|
||||
assert result[0].name == "product-brief-foo.md"
|
||||
|
||||
def test_folder_recursion(self, temp_dir):
|
||||
result = resolve_inputs([temp_dir])
|
||||
names = {f.name for f in result}
|
||||
assert "product-brief-foo.md" in names
|
||||
assert "prd-v2.md" in names
|
||||
assert "random.txt" in names
|
||||
|
||||
def test_folder_skips_excluded_dirs(self, temp_dir):
|
||||
result = resolve_inputs([temp_dir])
|
||||
names = {f.name for f in result}
|
||||
assert "junk.md" not in names
|
||||
|
||||
def test_folder_skips_non_text_files(self, temp_dir):
|
||||
result = resolve_inputs([temp_dir])
|
||||
names = {f.name for f in result}
|
||||
assert "image.png" not in names
|
||||
|
||||
def test_glob_pattern(self, temp_dir):
|
||||
pattern = str(Path(temp_dir) / "product-brief-*.md")
|
||||
result = resolve_inputs([pattern])
|
||||
assert len(result) == 2
|
||||
names = {f.name for f in result}
|
||||
assert "product-brief-foo.md" in names
|
||||
assert "product-brief-foo-discovery-notes.md" in names
|
||||
|
||||
def test_deduplication(self, temp_dir):
|
||||
f = str(Path(temp_dir) / "product-brief-foo.md")
|
||||
result = resolve_inputs([f, f, f])
|
||||
assert len(result) == 1
|
||||
|
||||
def test_mixed_inputs(self, temp_dir):
|
||||
file_path = str(Path(temp_dir) / "architecture-doc.md")
|
||||
folder_path = str(Path(temp_dir) / "subdir")
|
||||
result = resolve_inputs([file_path, folder_path])
|
||||
names = {f.name for f in result}
|
||||
assert "architecture-doc.md" in names
|
||||
assert "prd-v2.md" in names
|
||||
|
||||
def test_nonexistent_path(self):
|
||||
result = resolve_inputs(["/nonexistent/path/file.md"])
|
||||
assert len(result) == 0
|
||||
|
||||
|
||||
class TestDetectDocType:
|
||||
@pytest.mark.parametrize("filename,expected", [
|
||||
("product-brief-foo.md", "product-brief"),
|
||||
("product_brief_bar.md", "product-brief"),
|
||||
("foo-discovery-notes.md", "discovery-notes"),
|
||||
("foo-discovery_notes.md", "discovery-notes"),
|
||||
("architecture-overview.md", "architecture-doc"),
|
||||
("my-prd.md", "prd"),
|
||||
("research-report-q4.md", "research-report"),
|
||||
("foo-distillate.md", "distillate"),
|
||||
("changelog.md", "changelog"),
|
||||
("readme.md", "readme"),
|
||||
("api-spec.md", "specification"),
|
||||
("design-doc-v2.md", "design-doc"),
|
||||
("meeting-notes-2026.md", "meeting-notes"),
|
||||
("brainstorm-session.md", "brainstorming"),
|
||||
("user-interview-notes.md", "interview-notes"),
|
||||
("random-file.md", "unknown"),
|
||||
])
|
||||
def test_detection(self, filename, expected):
|
||||
assert detect_doc_type(filename) == expected
|
||||
|
||||
|
||||
class TestSuggestGroups:
|
||||
def test_groups_brief_with_discovery_notes(self, temp_dir):
|
||||
files = [
|
||||
Path(temp_dir) / "product-brief-foo.md",
|
||||
Path(temp_dir) / "product-brief-foo-discovery-notes.md",
|
||||
]
|
||||
groups = suggest_groups(files)
|
||||
# Should produce one group with both files
|
||||
paired = [g for g in groups if len(g["files"]) > 1]
|
||||
assert len(paired) == 1
|
||||
filenames = {f["filename"] for f in paired[0]["files"]}
|
||||
assert "product-brief-foo.md" in filenames
|
||||
assert "product-brief-foo-discovery-notes.md" in filenames
|
||||
|
||||
def test_standalone_files(self, temp_dir):
|
||||
files = [
|
||||
Path(temp_dir) / "architecture-doc.md",
|
||||
Path(temp_dir) / "research-report.md",
|
||||
]
|
||||
groups = suggest_groups(files)
|
||||
assert len(groups) == 2
|
||||
for g in groups:
|
||||
assert len(g["files"]) == 1
|
||||
|
||||
def test_mixed_grouped_and_standalone(self, temp_dir):
|
||||
files = [
|
||||
Path(temp_dir) / "product-brief-foo.md",
|
||||
Path(temp_dir) / "product-brief-foo-discovery-notes.md",
|
||||
Path(temp_dir) / "architecture-doc.md",
|
||||
]
|
||||
groups = suggest_groups(files)
|
||||
paired = [g for g in groups if len(g["files"]) > 1]
|
||||
standalone = [g for g in groups if len(g["files"]) == 1]
|
||||
assert len(paired) == 1
|
||||
assert len(standalone) == 1
|
||||
|
||||
|
||||
class TestAnalyze:
|
||||
def test_basic_analysis(self, temp_dir):
|
||||
f = str(Path(temp_dir) / "product-brief-foo.md")
|
||||
output_file = str(Path(temp_dir) / "output.json")
|
||||
analyze([f], output_file)
|
||||
result = json.loads(Path(output_file).read_text())
|
||||
assert result["status"] == "ok"
|
||||
assert result["summary"]["total_files"] == 1
|
||||
assert result["files"][0]["doc_type"] == "product-brief"
|
||||
assert result["files"][0]["estimated_tokens"] > 0
|
||||
|
||||
def test_routing_single_small_input(self, temp_dir):
|
||||
f = str(Path(temp_dir) / "product-brief-foo.md")
|
||||
output_file = str(Path(temp_dir) / "output.json")
|
||||
analyze([f], output_file)
|
||||
result = json.loads(Path(output_file).read_text())
|
||||
assert result["routing"]["recommendation"] == "single"
|
||||
|
||||
def test_routing_fanout_many_files(self, temp_dir):
|
||||
# Create enough files to trigger fan-out (> 3 files)
|
||||
for i in range(5):
|
||||
(Path(temp_dir) / f"doc-{i}.md").write_text("x" * 1000)
|
||||
output_file = str(Path(temp_dir) / "output.json")
|
||||
analyze([temp_dir], output_file)
|
||||
result = json.loads(Path(output_file).read_text())
|
||||
assert result["routing"]["recommendation"] == "fan-out"
|
||||
|
||||
def test_folder_analysis(self, temp_dir):
|
||||
output_file = str(Path(temp_dir) / "output.json")
|
||||
analyze([temp_dir], output_file)
|
||||
result = json.loads(Path(output_file).read_text())
|
||||
assert result["status"] == "ok"
|
||||
assert result["summary"]["total_files"] >= 4 # at least the base files
|
||||
assert len(result["groups"]) > 0
|
||||
|
||||
def test_no_files_found(self):
|
||||
output_file = "/tmp/test_analyze_empty.json"
|
||||
analyze(["/nonexistent/path"], output_file)
|
||||
result = json.loads(Path(output_file).read_text())
|
||||
assert result["status"] == "error"
|
||||
os.unlink(output_file)
|
||||
|
||||
def test_stdout_output(self, temp_dir, capsys):
|
||||
f = str(Path(temp_dir) / "product-brief-foo.md")
|
||||
analyze([f])
|
||||
captured = capsys.readouterr()
|
||||
result = json.loads(captured.out)
|
||||
assert result["status"] == "ok"
|
||||
|
|
@ -0,0 +1,126 @@
|
|||
---
|
||||
name: bmad-spec
|
||||
description: Distill any intent input into the SPEC kernel + companions — the canonical, preservation-validated machine contract for downstream work. Use when the user says "create a spec", "distill this into a spec", "validate this spec", or "update the spec".
|
||||
---
|
||||
|
||||
# BMad Spec
|
||||
## Overview
|
||||
|
||||
Canonical transformer for the BMad spec-kernel ecosystem. Takes any intent input — vague idea, brain dump, PRD, GDD, RFC, brief, Slack thread, customer email, meeting transcript, mockups, mixed multi-source — and produces **SPEC.md** carrying the five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for load-bearing content that does not fit or would bloat the kernel with expansive line-item detail. Together they are the machine contract every downstream BMad skill consumes.
|
||||
|
||||
Multiple skills may call to update the same spec over time.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Bare paths (e.g. `assets/spec-template.md`) resolve from the skill root.
|
||||
- `{skill-root}` is this skill's install dir; `{project-root}` is the working dir.
|
||||
- `{workflow.<name>}` resolves to fields in `customize.toml`.
|
||||
|
||||
## On Activation
|
||||
|
||||
1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly.
|
||||
2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (`file:` entries are loaded).
|
||||
3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present), root level and `bmm` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
|
||||
4. Detect mode. **Headless** when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. **Interactive** otherwise. In interactive mode, greet by `{user_name}` in `{communication_language}`, stay in that language, and mention that `bmad-party-mode` and `bmad-advanced-elicitation` are available for deeper exploration on any field.
|
||||
5. Run `{workflow.activation_steps_append}`.
|
||||
|
||||
## Workspace
|
||||
|
||||
The spec is **always a folder** named `{workflow.spec_output_path}/{workflow.run_folder_pattern}`, resolving by default to `{output_folder}/specs/spec-{slug}/`.
|
||||
|
||||
`{slug}` describes the thing being specced, not the input shape:
|
||||
|
||||
- Source artifact already carries a slug (e.g., `prd-foo-bar-2026-05-23/`): inherit (`foo-bar`).
|
||||
- Sparse, in-chat, or multi-source input: interactive asks; headless caller provides it as part of the input. If absent and underivable, headless blocks with `error_code: "missing_slug"`.
|
||||
- Same slug = same folder. A second invocation with the same `{slug}` lands at the existing spec folder and updates in place, preserving capability IDs.
|
||||
|
||||
**No input.** Interactive: ask the user to share a file path, paste content, explain the idea in detail, or point to a source. Headless: respond with JSON containing `error_code: "insufficient_intent"`.
|
||||
|
||||
Inside the spec folder:
|
||||
|
||||
```
|
||||
<spec-folder>/
|
||||
SPEC.md ← uppercase, the kernel
|
||||
<companion-1>.md ← optional, content-typed (e.g. glossary.md)
|
||||
<companion-2>.md
|
||||
.decision-log.md ← canonical memory for this spec
|
||||
```
|
||||
|
||||
## The Operation
|
||||
|
||||
Read the input and its ancillary linked materials. If there is no input, follow the no-input branch in **Workspace** (ask or block). If a prior `SPEC.md` exists at the target folder, read it too — the operation becomes an update. Preserve capability IDs; new capabilities get the next unused `CAP-N`; never reuse retired IDs. Otherwise this is a create.
|
||||
|
||||
When the input is structured and pre-sorted (a PRD with an addendum, a GDD, a brief produced by an upstream BMad skill), trust the authored separation: lift kernel-fitting content into SPEC.md, lift overflow into appropriately-named companions. When the input is mixed (a brain dump, a transcript, an RFC, a customer email), do the sorting yourself: walk each claim, apply the three-lens load-bearing test (Spec Law rule 7), and route to the kernel field or a companion.
|
||||
|
||||
Distill the input into the five-field kernel using `{workflow.spec_template}` as the skeleton. When input is rich, extract directly — no elicitation. When input is sparse, choose: **express** (best-effort distill, every gap becomes an `open_questions[]` entry) or **guided** (walk the five fields with the user one at a time). Headless defaults to express and logs the choice. Interactive asks.
|
||||
|
||||
Write lean from the first pass: every sentence must earn its place. Decoration costs tokens and dilutes downstream readers.
|
||||
|
||||
If the input is genuinely too thin to distill (e.g. "an app for hikers" with no surrounding context), stop and suggest `bmad-prd` (or sibling ceremony skill). This skill distills; it does not coach.
|
||||
|
||||
## Load-bearing
|
||||
|
||||
A claim is **load-bearing** if any consumer (downstream skill, implementing agent, verification pass) would change a decision without it.
|
||||
|
||||
## Companions
|
||||
|
||||
When load-bearing content does not fit the five-field kernel, it lives in a companion. The kernel cites it; the companion holds it. Companions are part of the contract; every consumer reads `companions:` in SPEC.md frontmatter to discover them. Companions follow the same lean discipline as SPEC.md (Spec Law rule 8).
|
||||
|
||||
**Spawn a companion when the content needs more than one kernel-shape line:** multi-item catalogs (per-entity matrices like archetypes, drinks, modes, routes), tables, diagrams (always), editorial voice rules, long-form reference material the kernel cites by name (glossary, brownfield notes, project conventions). Single-line decision-benders stay in Constraints; intent+success pairs stay in Capabilities. If a kernel field is starting to bullet into sub-bullets, the content has outgrown the kernel and wants a companion.
|
||||
|
||||
Companions are either:
|
||||
|
||||
- **Spec-authored** companions are written by bmad-spec and live as **siblings of SPEC.md** (e.g., `glossary.md`, `patron-archetypes.md`). bmad-spec owns them and may edit them on update operations.
|
||||
- **Adopted** companions are load-bearing artifacts written by an upstream skill that downstream still needs to read. bmad-spec references them into `companions:` by relative path but does NOT edit them (e.g., a `DESIGN.md` or `EXPERIENCE.md` from a UX run, an integration partner's API spec). The originating skill owns them.
|
||||
|
||||
Two rules govern companions:
|
||||
|
||||
1. **Name spec-authored companions for the content type they hold.** `glossary.md`, `<entity-class>.md` (e.g. `patron-archetypes.md`, `medication-routes.md`, `flight-modes.md`), `stack.md`, `conventions.md`, `brownfield.md`, `architecture-diagrams.md`, `state-machines.md`, `failure-modes.md`, `compliance-references.md`. The principle: "a reader should know what is inside before opening it." Adopted companions keep whatever name their originating skill gave them.
|
||||
2. **Diagrams always land in a companion**, regardless of size. SPEC.md kernel holds prose only. Mermaid blocks, ASCII diagrams, and image references all live in a companion (e.g. `architecture-diagrams.md`), with sibling image files referenced from there.
|
||||
|
||||
Pre-existing project-wide docs (e.g. `project-context.md`) that downstream needs are listed as **adopted companions**, never duplicated into SPEC.md or a spec-authored companion.
|
||||
|
||||
## Spec Law
|
||||
|
||||
Every spec must satisfy these eight rules. The operation aims for them; the self-validate sweep enforces them.
|
||||
|
||||
1. **Each capability has both `intent` and `success`.** Missing either = not a capability.
|
||||
2. **Intents describe WHAT, not HOW.** Implementation prescription belongs in a companion (stack, conventions).
|
||||
3. **Constraints actually bend design decisions.** A "constraint" that rules nothing out is decoration.
|
||||
4. **Non-goals are explicit.** At least one. Absence means downstream skills fill the vacuum.
|
||||
5. **Success signal is concrete enough to test or demonstrate against.** "Users love it" doesn't qualify.
|
||||
6. **Capability IDs are stable and unique.** Never reused, never renumbered.
|
||||
7. **Preservation.** Every load-bearing source claim lands in SPEC.md or a companion. Wrapper ceremony does not.
|
||||
8. **Lean prose.** Every sentence carries load-bearing content. Cut decoration, hedges, backstory, throat-clearing. Applies to SPEC.md, companions, and `.decision-log.md`.
|
||||
|
||||
## Self-Validate
|
||||
|
||||
After every create or update, sweep the resulting artifact in **two passes** before presenting.
|
||||
|
||||
**Pass 1 — Coherence.** Judge the spec against Spec Law rules 1–6 and 8. For anything that fails or feels weak, attempt to fix it without inventing content the input did not support. Calls made without direct confirmation become `assumptions[]`; gaps that could not be filled become `open_questions[]`.
|
||||
|
||||
**Pass 2 — Preservation.** Walk the source claim by claim. Confirm each load-bearing claim landed in SPEC.md or a companion. Wrapper-ceremony drops are logged under "Wrapper-only content" so the drop is on the record, not silent.
|
||||
|
||||
Append a one-paragraph verdict to `.decision-log.md` covering both passes. In interactive mode, review the verdict with the user. In headless mode, `.decision-log.md` is one of the files returned, so the caller (or its downstream LLM) reads the verdict there.
|
||||
|
||||
## Spec with no change signal
|
||||
|
||||
When the user points the skill at an existing spec folder (or its SPEC.md) with no change signal, offer to review assumptions or open questions, or determine what they want to do.
|
||||
|
||||
## Output
|
||||
|
||||
**Interactive** — share the spec folder path conversationally. Name the capability count, the companions produced, and the verdict in one or two sentences. If `assumptions[]` or `open_questions[]` are non-empty, list them (short — one line each) and invite the user to walk through them. Make clear that addressing them can update the source input (if it was a file), the spec, or both — whichever combination the user prefers. Do not dump JSON or present a wall of output.
|
||||
|
||||
**Headless** — return JSON per `assets/headless-schemas.md`.
|
||||
|
||||
Run `{workflow.on_complete}` if set.
|
||||
|
||||
## After Spec is Output
|
||||
|
||||
Any update to spec regarding assumptions, open questions, or other changes should be appended to that source's decision log also and offer to update the source.
|
||||
|
||||
## Frontmatter conventions
|
||||
|
||||
- `companions:` array of `.md` files downstream MUST read alongside SPEC.md to have the full contract. Paths may point inside the spec folder (spec-authored companions like `glossary.md`) or outside it (adopted companions like `../planning-artifacts/ux-designs/ux-foo-bar-2026-05-23/DESIGN.md`). The split between spec-authored and adopted is implicit by path; downstream treats both the same.
|
||||
- `sources:` array of paths to files that were **fully absorbed** into the SPEC, with no remaining downstream value (e.g., a PRD whose every load-bearing claim is now in the kernel). Listed for audit and for bmad-spec to re-read on update. Downstream does NOT read these. Files that downstream still needs to read belong in `companions:`, not here.
|
||||
- **Do not list** decision logs, README files, organizational artifacts, or any operational record of how upstream skills produced their artifacts. Those are not source content; they are process metadata that downstream consumers don't need.
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
# Headless JSON Response
|
||||
|
||||
The default invocation is headless: input goes in, JSON comes out. The contract is intentionally tiny — return the outcome and the files touched. Anything else a caller needs is inside those files (SPEC.md, companions, `.decision-log.md`).
|
||||
|
||||
## Success
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "complete",
|
||||
"files": [
|
||||
"_bmad-output/specs/spec-quarter-drop/SPEC.md",
|
||||
"_bmad-output/specs/spec-quarter-drop/glossary.md",
|
||||
"_bmad-output/specs/spec-quarter-drop/.decision-log.md"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`files` lists every file written or modified in this run, in any order. The spec folder, kernel filename, decision log location, capabilities, companions, and verdict are all readable from those files; no need to re-encode them in the response.
|
||||
|
||||
## Blocked
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "blocked",
|
||||
"error_code": "insufficient_intent",
|
||||
"reason": "Input was a one-line idea with no surrounding context; too thin to distill. Suggest bmad-prd to draw the vision out first."
|
||||
}
|
||||
```
|
||||
|
||||
Defined `error_code` values:
|
||||
|
||||
- `insufficient_intent` — input too thin to distill into a kernel.
|
||||
- `missing_slug` — input is sparse or multi-source and no slug was provided by the caller or derivable from a source path.
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
id: SPEC-{slug}
|
||||
companions: [] # files downstream MUST read alongside SPEC.md. Paths may point inside the spec folder (spec-authored) or outside it (adopted from an upstream skill).
|
||||
sources: [] # files fully absorbed into the SPEC (audit only; downstream does NOT read these). Never decision logs.
|
||||
---
|
||||
|
||||
> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability only — consult them only if you need narrative rationale or prose color this contract intentionally omits.
|
||||
|
||||
# {Spec Title}
|
||||
|
||||
## Why
|
||||
|
||||
{One paragraph naming the force behind this work. A spec can exist for any of:
|
||||
- **a pain to solve** — a user or operator is stuck on a specific gap;
|
||||
- **an opportunity to capture** — something newly possible we want to claim;
|
||||
- **a vision to realize** — a thing we want to make exist because we want it to exist;
|
||||
- **a mandate to meet** — a regulation, deprecation, deadline, or contractual obligation.
|
||||
|
||||
Name which (or which combination) applies, who is affected, and the backdrop that makes it matter now. This is the anchor every downstream trade-off resolves against.}
|
||||
|
||||
## Capabilities
|
||||
|
||||
- id: CAP-1
|
||||
intent: {One sentence. "User or system can do X to achieve Y." WHAT, not HOW.}
|
||||
success: {Testable or demonstrable criterion. Something a test or a real demonstration can decide.}
|
||||
|
||||
## Constraints
|
||||
|
||||
- {A non-negotiable that bends design. If it doesn't rule anything out, it doesn't belong.}
|
||||
|
||||
## Non-goals
|
||||
|
||||
- {Explicit out-of-scope item. At least one. Stops downstream from filling the vacuum.}
|
||||
|
||||
## Success signal
|
||||
|
||||
- {One or two sentences. World-change moment, not dashboard. Concrete enough to write a test or run a demonstration against.}
|
||||
|
||||
## Assumptions
|
||||
|
||||
<!-- Optional. Omit this section entirely if empty. Inferred calls made without direct confirmation from the input. -->
|
||||
|
||||
- {Statement of fact the Spec proceeded under, e.g. "Assumed mobile-first since input mentioned GPS but no platform."}
|
||||
|
||||
## Open Questions
|
||||
|
||||
<!-- Optional. Omit this section entirely if empty. Gaps the input did not resolve that need a human decision before downstream skills consume the Spec. -->
|
||||
|
||||
- {Question phrased so a human can answer it, e.g. "Is offline playback in scope for CAP-2?"}
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
# DO NOT EDIT -- overwritten on every update.
|
||||
#
|
||||
# Workflow customization surface for bmad-spec.
|
||||
#
|
||||
# Override files (not edited here):
|
||||
# {project-root}/_bmad/custom/bmad-spec.toml (team)
|
||||
# {project-root}/_bmad/custom/bmad-spec.user.toml (personal)
|
||||
|
||||
[workflow]
|
||||
|
||||
# --- Configurable below. Overrides merge per BMad structural rules: ---
|
||||
# scalars: override wins • arrays: append
|
||||
|
||||
# Steps to run before the standard activation (config load, greet).
|
||||
activation_steps_prepend = []
|
||||
|
||||
# Steps to run after greet but before the operation begins.
|
||||
activation_steps_append = []
|
||||
|
||||
# Persistent facts the workflow keeps in mind for the whole run.
|
||||
# Each entry is either a literal sentence, a skill prefixed with `skill:`,
|
||||
# or a `file:`-prefixed path/glob whose contents are loaded as facts.
|
||||
# Default points to a single top-level file; override in team/user TOML
|
||||
# to widen the scope (e.g. `_bmad/**/project-context.md`) if needed.
|
||||
persistent_facts = [
|
||||
"file:{project-root}/project-context.md",
|
||||
]
|
||||
|
||||
# Executed when the workflow completes. Scalar or array of instructions.
|
||||
on_complete = ""
|
||||
|
||||
# Spec template. The five-field kernel skeleton. Override the path in
|
||||
# team/user TOML to enforce a different shape (e.g. a hypothesis field
|
||||
# for research initiatives, or a mechanics field for games).
|
||||
spec_template = "assets/spec-template.md"
|
||||
|
||||
# Canonical filename for the kernel artifact inside the spec folder.
|
||||
# Uppercase by convention to signal "the central source of truth."
|
||||
spec_filename = "SPEC.md"
|
||||
|
||||
# Output path for spec folders. Lands directly under {output_folder}
|
||||
# so bmad-spec works in core-only installs and matches the
|
||||
# long-term BMad direction of grouping artifacts as siblings under
|
||||
# {output_folder}/<type>/ rather than nested inside planning vs
|
||||
# implementation folders.
|
||||
spec_output_path = "{output_folder}/specs"
|
||||
|
||||
# Run-folder pattern inside spec_output_path. Resolved against the
|
||||
# input-derived slug at activation. Same slug = same folder, so a
|
||||
# second invocation updates the existing spec in place (capability
|
||||
# IDs preserved). Override to add {date} or other components if a
|
||||
# fresh dated history is preferred.
|
||||
run_folder_pattern = "spec-{slug}"
|
||||
|
|
@ -9,5 +9,5 @@ Core,bmad-editorial-review-prose,Editorial Review - Prose,EP,Use after drafting
|
|||
Core,bmad-editorial-review-structure,Editorial Review - Structure,ES,Use when doc produced from multiple subprocesses or needs structural improvement.,,[path],anytime,,,false,report located with target document,
|
||||
Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assurance or before finalizing deliverables. Code Review in other modules runs this automatically, but also useful for document reviews.",,[path],anytime,,,false,,
|
||||
Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,,
|
||||
Core,bmad-distillator,Distillator,DG,Use when you need token-efficient distillates that preserve all information for downstream LLM consumption.,,[path],anytime,,,false,adjacent to source document or specified output_path,distillate markdown file(s)
|
||||
Core,bmad-spec,Spec,SP,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
|
||||
Core,bmad-customize,BMad Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _bmad/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_bmad/custom,TOML override files
|
||||
|
|
|
|||
|
|
|
@ -177,6 +177,14 @@ def extract_key(data, dotted_key: str):
|
|||
return current
|
||||
|
||||
|
||||
def write_json_stdout(output):
|
||||
"""Write JSON as UTF-8 so Windows cp1252 stdout can carry emoji icons."""
|
||||
reconfigure = getattr(sys.stdout, "reconfigure", None)
|
||||
if reconfigure is not None:
|
||||
reconfigure(encoding="utf-8")
|
||||
sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Resolve customization for a BMad skill using three-layer TOML merge.",
|
||||
|
|
@ -223,7 +231,7 @@ def main():
|
|||
else:
|
||||
output = merged
|
||||
|
||||
sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
|
||||
write_json_stdout(output)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
|
|
|||
|
|
@ -0,0 +1,50 @@
|
|||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
SCRIPT = Path(__file__).resolve().parents[1] / "resolve_customization.py"
|
||||
|
||||
|
||||
class ResolveCustomizationStdoutTests(unittest.TestCase):
|
||||
def test_writes_emoji_json_when_stdout_encoding_is_cp1252(self):
|
||||
with tempfile.TemporaryDirectory() as temp_dir:
|
||||
skill_dir = Path(temp_dir) / "emoji-agent"
|
||||
skill_dir.mkdir()
|
||||
(skill_dir / "customize.toml").write_text(
|
||||
'[agent]\nname = "Emoji Agent"\nicon = "🧭"\n',
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
env = os.environ.copy()
|
||||
env["PYTHONIOENCODING"] = "cp1252"
|
||||
result = subprocess.run(
|
||||
[
|
||||
sys.executable,
|
||||
str(SCRIPT),
|
||||
"--skill",
|
||||
str(skill_dir),
|
||||
"--key",
|
||||
"agent",
|
||||
],
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.PIPE,
|
||||
env=env,
|
||||
check=False,
|
||||
)
|
||||
|
||||
stderr = result.stderr.decode("utf-8", errors="replace")
|
||||
self.assertEqual(result.returncode, 0, msg=stderr)
|
||||
|
||||
output = result.stdout.decode("utf-8")
|
||||
self.assertIn("🧭", output)
|
||||
resolved = json.loads(output)
|
||||
self.assertEqual(resolved["agent"]["icon"], "🧭")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
|
@ -132,7 +132,7 @@
|
|||
<div class="header">
|
||||
<div class="header-badge">⚡ Carte des Workflows V6</div>
|
||||
<h1>Méthode BMad</h1>
|
||||
<p class="subtitle">Ingénierie du contexte pour le développement piloté par l'IA</p>
|
||||
<p class="subtitle">Ingénierie du contexte pour le développement piloté par l’IA</p>
|
||||
</div>
|
||||
|
||||
<div class="flow-legend">→ les flèches montrent le flux des artefacts entre les workflows</div>
|
||||
|
|
@ -206,7 +206,7 @@
|
|||
<span class="output">prd.md →</span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="decision">Interface utilisateur ?</div>
|
||||
<div class="decision">Interface utilisateur ?</div>
|
||||
<div class="workflow">
|
||||
<div class="workflow-header">
|
||||
<span class="workflow-name">create-ux-design</span>
|
||||
|
|
@ -329,7 +329,7 @@
|
|||
</div>
|
||||
<div class="workflow-meta">
|
||||
<div class="agent"><div class="agent-icon amelia">A</div><span class="agent-name">Amelia</span></div>
|
||||
<span class="output">rapport d'investigation</span>
|
||||
<span class="output">rapport d’investigation</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Reference in New Issue