opensource/BMAD-METHOD
3
0
Fork 0
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-08-28 19:20:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor(core): group v6 shims and merge editorial review into bmad-review as lenses (#2608)

Browse Source 
* refactor: group v6 deprecation shims into v6-shims folders

Move the nine backward-compatibility forwarders into dedicated v6-shims/
folders so the deprecation set is visible in one place and can later be
made an install-time include/exclude option before removal at the v7 cut.

core-skills/v6-shims/: the five review and editorial husks
bmm-skills/v6-shims/: the four PRD and architecture husks

Grouping only — no content changes. The installer discovers skills by a
recursive walk and installs each under its own name, so installed paths
and skill IDs are unchanged. Verified by diffing a full headless install
against main: identical .claude/skills listing and file content, and an
identical _bmad tree. The only delta is the path column in
skill-manifest.csv, which now records the new source location.

External module repos (gds, loop, tea, bmb, os-utils) and enterprise
users still invoke these IDs, so they continue to ship by default.

* refactor(core): merge editorial review into bmad-review as lenses

All reviews are reviews. bmad-editorial-review's two passes become two
more bmad-review lenses, leaving one lens runtime instead of two skills
with overlapping trigger descriptions — "review this document" matched
both before, so which one ran was close to arbitrary.

Lenses now declare what they apply to. applies_to is "code", "docs", or
"any", and is the first filter on a default review; `when` still refines
it in prose. adversarial stays "any" — it is a stance, not a subject-
matter method, and is the lens a code/doc skill split could not have
placed. edge-case-hunter's `when` was "always", which is why it would
have fired on prose; it now gates on having a behavioral surface.

A lens may also declare `after`, naming a lens it builds on: prose runs
on top of the structure findings, as it always has. The runner announces
the plan, runs the independent lenses (in parallel via subagents when
available), then the dependent ones on their results.

Lens wording is unchanged. The three code lens files are byte-identical;
the editorial passes moved verbatim into references/lens-structure.md,
references/lens-prose.md, and references/editorial-common.md, which
carries what both share — the content-sacrosanct rule, style guide
handling, reader calibration, and the findings table. That material used
to load unconditionally; as lenses it loads just-in-time, so a code
review no longer pays for it.

bmad-editorial-review becomes the sixth v6 shim, forwarding with the
structure and prose lenses named. It keeps its customize.toml so existing
team and user overrides still resolve, and forwards them as pre-resolved
values. The four other husks now name bmad-review and their lens
explicitly. Each still pins its own legacy output contract.

bmm's four document skills point doc_standards at the merged skill with
named lenses. Docs updated across all five locales.

Core is 7 skills. A headless install produces the same 47-skill set as
main, with all six shims resolving.

* fix(core): honor forwarded customization and de-hardcode the lens set

Follow-up to the editorial/review merge, from review of #2608.

Contract fixes:
- bmad-review gains a Forwarded activation clause matching bmad-prd and
  bmad-architecture, so the bmad-editorial-review shim's pre-resolved fields
  are honored instead of being silently overwritten by the skill's own
  customize.toml. Existing bmad-editorial-review overrides resolve again.
- The announce step is skipped when a caller pinned an exact output contract,
  and a forwarder's contract now governs everything emitted rather than the
  findings block alone. The edge-case (raw JSON) and verification-gap (one
  exact line) forwarders no longer get a prose line prepended.

Lens set is no longer hardcoded:
- The description and body intro present the shipped lenses as examples and
  point at whatever {workflow.lenses} resolves to. Docs carry a matching note
  in all five locales.

Also:
- Document the `lenses=` directive form in Inputs and in the four bmm
  doc_standards comments that use it.
- module-help.csv review row rewritten to the house "Use to..." convention,
  naming the reviewable content types and the situations that should trigger
  a suggestion.
- Shim customize.toml trimmed to a lean legacy-key surface with empty
  defaults, so unset keys fall through to bmad-review and project-context.md
  is no longer loaded twice.
- Redundant `when` clauses dropped where applies_to already encodes the rule.
- Core skill count corrected to seven/four and the edge-case applies_to cell
  fixed to match its actual value, across all five locales.
This commit is contained in:
Brian
2026-07-19 18:40:47 -05:00
committed by GitHub
parent c23f23400d
commit 8b4da79161
40 changed files with 478 additions and 448 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude-plugin/marketplace.json
-1
View File
@@ -62,7 +62,6 @@
"./src/core-skills/bmad-customize",
"./src/core-skills/bmad-advanced-elicitation",
"./src/core-skills/bmad-review",
"./src/core-skills/bmad-editorial-review",
"./src/bmm-skills/1-analysis/bmad-product-brief",
"./src/bmm-skills/1-analysis/bmad-prfaq",
"./src/bmm-skills/1-analysis/bmad-agent-analyst",
docs/cs/reference/core-tools.md
+33 -52
View File
@@ -5,7 +5,7 @@ sidebar:
order: 3
---
Každá instalace BMad zahrnuje **základní modul** — malou sadu skills, které fungují napříč všemi projekty, všemi moduly a všemi fázemi. Tato stránka pokrývá těchto osm základních skills: pět jádrových nástrojů plus tři **myšlenkové skills** (brainstorming, forge idea, party mode).
Každá instalace BMad zahrnuje **základní modul** — malou sadu skills, které fungují napříč všemi projekty, všemi moduly a všemi fázemi. Tato stránka pokrývá těchto sedm základních skills: čtyři jádrové nástroje plus tři **myšlenkové skills** (brainstorming, forge idea, party mode).
:::tip[Rychlá cesta]
Spusťte jakýkoli nástroj zadáním jeho názvu skillu (např. `bmad-help`) ve vašem IDE. Nevyžaduje relaci agenta.
@@ -15,24 +15,23 @@ Spusťte jakýkoli nástroj zadáním jeho názvu skillu (např. `bmad-help`) ve
**Základní modul (vždy nainstalován):**
| Nástroj | Účel |
| --- | --- |
| [`bmad-help`](#bmad-help) | Kontextové poradenství, co dělat dál |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Iterativní zdokonalování LLM výstupu |
| [`bmad-editorial-review`](#bmad-editorial-review) | Dvoufázová redakční revize — nejprve struktura, pak text |
| [`bmad-review`](#bmad-review) | Kritická revize z více perspektiv — adversariální, hraniční případy a mezery ve verifikaci |
| [`bmad-customize`](#bmad-customize) | Vytváření a ověřování přizpůsobení BMad |
| Nástroj | Účel |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [`bmad-help`](#bmad-help) | Kontextové poradenství, co dělat dál |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Iterativní zdokonalování LLM výstupu |
| [`bmad-review`](#bmad-review) | Revize z více perspektiv — adversariální, hraniční případy a mezery ve verifikaci pro kód; struktura a text pro dokumenty |
| [`bmad-customize`](#bmad-customize) | Vytváření a ověřování přizpůsobení BMad |
**Myšlenkové skills:**
| Nástroj | Účel |
| --- | --- |
| [`bmad-brainstorming`](#bmad-brainstorming) | Facilitace interaktivních brainstormingových sezení |
| [`bmad-forge-idea`](#bmad-forge-idea) | Zátěžový test nápadu, dokud se nezpevní, nepotvrdí, nebo levně nezemře |
| [`bmad-party-mode`](#bmad-party-mode) | Orchestrace skupinových diskuzí více agentů |
| Nástroj | Účel |
| ------------------------------------------- | ---------------------------------------------------------------------- |
| [`bmad-brainstorming`](#bmad-brainstorming) | Facilitace interaktivních brainstormingových sezení |
| [`bmad-forge-idea`](#bmad-forge-idea) | Zátěžový test nápadu, dokud se nezpevní, nepotvrdí, nebo levně nezemře |
| [`bmad-party-mode`](#bmad-party-mode) | Orchestrace skupinových diskuzí více agentů |
:::note[Přesunuto a odstraněno]
`bmad-spec` se nyní dodává s modulem BMM jako plánovací workflow Fáze 2 — viz [Mapa workflow](./workflow-map.md). Utility `bmad-shard-doc` a `bmad-index-docs` byly odstraněny. Dřívější skills `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter` a `bmad-review-verification-gap` jsou sloučeny do `bmad-editorial-review` a `bmad-review`; staré identifikátory se stále rozliší přes skryté přesměrování kvůli kompatibilitě.
`bmad-spec` se nyní dodává s modulem BMM jako plánovací workflow Fáze 2 — viz [Mapa workflow](./workflow-map.md). Utility `bmad-shard-doc` a `bmad-index-docs` byly odstraněny. Dřívější skills `bmad-editorial-review`, `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter` a `bmad-review-verification-gap` jsou všechny sloučeny do `bmad-review`, jehož redakční perspektivy nahrazují samostatný redakční skill; staré identifikátory se stále rozliší přes přesměrování kvůli kompatibilitě.
:::
## bmad-help
@@ -79,64 +78,46 @@ Spusťte jakýkoli nástroj zadáním jeho názvu skillu (např. `bmad-help`) ve
**Výstup:** Vylepšená verze obsahu s aplikovanými zlepšeními
## bmad-editorial-review
**Dvoufázová redakční revize — nejprve struktura, pak text.** — Klinický editor, který reviduje tvar dokumentu i jeho věty a vrací navrhované opravy, jež řádek po řádku přijímáte nebo odmítáte. Obsah je nedotknutelný: nikdy nezpochybňuje vaše myšlenky, jen jejich organizaci a vyjádření.
**Použijte když:**
- Napsali jste dokument a chcete jej zpřísnit a vyladit
- Dokument vznikl z více podprocesů a potřebuje strukturální soudržnost
- Chcete zkrátit délku při zachování srozumitelnosti
- Potřebujete opravy srozumitelnosti bez stylistických zásahů
**Jak to funguje:**
1. **Strukturální fáze** — navrhuje škrty, sloučení, přesuny a zhuštění; ptá se, zda tvar dokumentu slouží jeho účelu
2. **Textová fáze** — koriguje komunikační problémy bránící porozumění, s Microsoft Writing Style Guide jako výchozí baseline (dodaný průvodce stylem má přednost)
3. Ve výchozím stavu běží obě fáze, nejprve struktura; požádejte o revizi jen struktury nebo jen textu, chcete-li spustit jednu
4. Navrhuje, nikdy neprovádí — o přijetí rozhoduje autor
**Vstup:**
- `content` (povinné) — Dokument k revizi
- `style_guide` (volitelné) — Projektově specifický průvodce stylem
- `reader_type` (volitelné) — `humans` (výchozí) pro srozumitelnost/plynulost, nebo `llm` pro přesnost/konzistenci
- `purpose` / `target_audience` / `length_target` (volitelné) — kalibrují strukturální fázi
**Výstup:** Tabulka nálezů s navrhovanými opravami, plus odhad zkrácení při navržených strukturálních změnách
## bmad-review
**Kritická revize z více perspektiv nad jakýmkoli diffem, dokumentem nebo artefaktem.** — Spouští nezávislé revizní perspektivy — každou s vlastní metodou a postojem — a hlásí každý nález v jednom kanonickém tvaru. Nula nálezů je platný výsledek; nikdy nedoplňuje, aby vypadal důkladně.
**Revize z více perspektiv nad jakýmkoli diffem, dokumentem nebo artefaktem.** — Spouští revizní perspektivy — každou s vlastní metodou a postojem — a hlásí každý nález v jednom kanonickém tvaru. Nula nálezů je platný výsledek; nikdy nedoplňuje, aby vypadal důkladně. Každá perspektiva deklaruje, na co se vztahuje: diff vyvolá perspektivy pro kód, dokument ty redakční.
**Dodávané perspektivy:**
| Perspektiva | Metoda |
| --- | --- |
| **Adversariální** | Skeptická revize předpokládající existenci problémů — hledá, co chybí, ne jen co je špatně |
| **Hraniční případy** | Projde každou větvící se cestu a hraniční podmínku, hlásí pouze neošetřené cesty |
| **Mezery ve verifikaci** | Hledá změněné chování, které by mohlo regredovat, aniž by to spolehlivá verifikace zachytila |
| Perspektiva | Vztahuje se na | Metoda |
| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- |
| **Adversariální** | Jakýkoli obsah | Skeptická revize předpokládající existenci problémů — hledá, co chybí, ne jen co je špatně |
| **Hraniční případy** | Jakýkoli obsah | Projde každou větvící se cestu a hraniční podmínku v obsahu, který definuje chování |
| **Mezery ve verifikaci** | Kód | Hledá změněné chování, které by mohlo regredovat, aniž by to spolehlivá verifikace zachytila |
| **Struktura** | Dokumenty | Navrhuje škrty, sloučení, přesuny a zhuštění — slouží tvar dokumentu jeho účelu? |
| **Text** | Dokumenty | Redakčně upravuje komunikační problémy, které brání porozumění |
Obě redakční perspektivy považují obsah za nedotknutelný: nikdy nezpochybňují vaše myšlenky, pouze jejich uspořádání a vyjádření, a navrhují místo toho, aby zasahovaly. Je-li vybráno obojí, textová perspektiva běží nad nálezy strukturní.
Sada není pevná: přepis v `customize.toml` může perspektivy přidat nebo nahradit dodávané a revize spustí ty, které se skutečně vyhodnotí.
**Použijte když:**
- Potřebujete zajištění kvality před finalizací výstupu
- Chcete vyčerpávající pokrytí hraničních případů kódu nebo logiky
- Chcete vědět, zda je změna dostatečně ověřena
- Chcete všechny tři perspektivy najednou (výchozí chování)
- Napsali jste dokument a chcete jej zpřesnit a vyladit
- Chcete zkrátit délku při zachování srozumitelnosti
**Jak to funguje:**
1. Načte obsah a identifikuje jeho typ — diff, soubor, funkce nebo dokument
2. Vybere perspektivy: ty, které pojmenujete, nebo každou povolenou perspektivu odpovídající obsahu
3. Spustí každou perspektivu nezávisle — paralelně přes subagenty, pokud to platforma podporuje
4. Sestaví jeden seznam nálezů; překryv mezi perspektivami je signál, ne duplikace
1. Načte obsah, identifikuje jeho typ — diff, soubor, funkce nebo dokument — a zda jde o kód či dokumentaci
2. Vybere perspektivy: ty, které pojmenujete, nebo každou povolenou perspektivu, jejíž použitelnost a podmínky obsahu odpovídají
3. Oznámí plán — které perspektivy poběží a které staví na nálezech jiné
4. Spustí nezávislé perspektivy — paralelně přes subagenty, pokud to platforma podporuje — a poté ty závislé
5. Sestaví jeden seznam nálezů; překryv mezi perspektivami je signál, ne duplikace
**Vstup:**
- `content` (povinné) — Diff, větev, nezakomitované změny, soubor, specifikace, story nebo jakýkoli dokument
- `lenses` (volitelné) — jeden nebo více kódů či názvů perspektiv; výchozí je plná revize
- `also_consider` (volitelné) — Další oblasti k zvážení
- `style_guide` / `reader_type` (volitelné, redakční perspektivy) — projektový průvodce stylem a `humans` (výchozí) nebo `llm`
**Výstup:** JSON pole nálezů a/nebo markdown report seskupený podle perspektiv. Vlastní perspektivy lze přidat — a dodávané doladit či vypnout — přes `customize.toml` skillu
docs/fr/reference/core-tools.md
+34 -53
View File
@@ -5,7 +5,7 @@ sidebar:
order: 3
---
Chaque installation BMad comprend le **module principal** — un petit ensemble de compétences qui fonctionnent dans tous les projets, tous les modules et toutes les phases. Cette page couvre ces huit compétences principales : les cinq outils du noyau plus les trois **compétences de réflexion** (brainstorming, forge idea, party mode).
Chaque installation BMad comprend le **module principal** — un petit ensemble de compétences qui fonctionnent dans tous les projets, tous les modules et toutes les phases. Cette page couvre ces sept compétences principales : les quatre outils du noyau plus les trois **compétences de réflexion** (brainstorming, forge idea, party mode).
:::tip[Raccourci Rapide]
Exécutez n’importe quel outil en tapant son nom de compétence (par ex., `bmad-help`) dans votre IDE. Aucune session d’agent requise.
@@ -15,24 +15,23 @@ Exécutez n’importe quel outil en tapant son nom de compétence (par ex., `bma
**Module principal (toujours installé) :**
| Outil | Objectif |
| --- | --- |
| [`bmad-help`](#bmad-help) | Obtenir des conseils contextuels sur la prochaine étape |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Soumettre la sortie LLM à des méthodes de raffinement itératives |
| [`bmad-editorial-review`](#bmad-editorial-review) | Revue éditoriale en deux passes — structure, puis prose |
| [`bmad-review`](#bmad-review) | Revue critique multi-perspectives — contradictoire, cas limites et lacunes de vérification |
| [`bmad-customize`](#bmad-customize) | Créer et vérifier des personnalisations BMad |
| Outil | Objectif |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| [`bmad-help`](#bmad-help) | Obtenir des conseils contextuels sur la prochaine étape |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Soumettre la sortie LLM à des méthodes de raffinement itératives |
| [`bmad-review`](#bmad-review) | Revue multi-perspectives — contradictoire, cas limites et lacunes de vérification pour le code ; structure et prose pour les documents |
| [`bmad-customize`](#bmad-customize) | Créer et vérifier des personnalisations BMad |
**Compétences de réflexion :**
| Outil | Objectif |
| --- | --- |
| [`bmad-brainstorming`](#bmad-brainstorming) | Faciliter des sessions de brainstorming interactives |
| [`bmad-forge-idea`](#bmad-forge-idea) | Éprouver une idée jusqu’à ce qu’elle se consolide, se confirme ou meure à moindre coût |
| [`bmad-party-mode`](#bmad-party-mode) | Orchestrer des discussions de groupe multi-agents |
| Outil | Objectif |
| ------------------------------------------- | -------------------------------------------------------------------------------------- |
| [`bmad-brainstorming`](#bmad-brainstorming) | Faciliter des sessions de brainstorming interactives |
| [`bmad-forge-idea`](#bmad-forge-idea) | Éprouver une idée jusqu’à ce qu’elle se consolide, se confirme ou meure à moindre coût |
| [`bmad-party-mode`](#bmad-party-mode) | Orchestrer des discussions de groupe multi-agents |
:::note[Déplacés et supprimés]
`bmad-spec` fait désormais partie du module BMM comme workflow de planification de Phase 2 — voir la [Carte des Workflows](./workflow-map.md). Les utilitaires `bmad-shard-doc` et `bmad-index-docs` ont été supprimés. Les anciennes compétences `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter` et `bmad-review-verification-gap` sont fusionnées dans `bmad-editorial-review` et `bmad-review` ; les anciens identifiants restent résolus via des redirections masquées pour la compatibilité.
`bmad-spec` fait désormais partie du module BMM comme workflow de planification de Phase 2 — voir la [Carte des Workflows](./workflow-map.md). Les utilitaires `bmad-shard-doc` et `bmad-index-docs` ont été supprimés. Les anciennes compétences `bmad-editorial-review`, `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter` et `bmad-review-verification-gap` sont toutes fusionnées dans `bmad-review`, dont les perspectives éditoriales remplacent la compétence éditoriale séparée ; les anciens identifiants restent résolus via des redirections pour la compatibilité.
:::
## bmad-help
@@ -79,69 +78,51 @@ Exécutez n’importe quel outil en tapant son nom de compétence (par ex., `bma
**Sortie :** Version améliorée du contenu avec les améliorations appliquées
## bmad-editorial-review
**Revue éditoriale en deux passes — structure, puis prose.** — Un éditeur clinique qui examine la forme d’un document et ses phrases, et propose des corrections que vous acceptez ou refusez ligne par ligne. Le contenu est sacré : il ne remet jamais en question vos idées, seulement leur organisation et leur expression.
**À utiliser quand :**
- Vous avez rédigé un document et voulez le resserrer et le polir
- Un document issu de plusieurs sous-processus a besoin de cohérence structurelle
- Vous voulez réduire la longueur tout en préservant la compréhension
- Vous voulez des corrections de clarté sans modifier les choix stylistiques
**Fonctionnement :**
1. **Passe structure** — propose des coupes, fusions, déplacements et condensations ; interroge si la forme du document sert son objectif
2. **Passe prose** — corrige les problèmes de communication qui nuisent à la compréhension, avec le Microsoft Writing Style Guide comme référence (un guide de style fourni prévaut)
3. Exécute les deux passes, structure d’abord, par défaut ; demandez une revue structure seule ou prose seule pour n’en exécuter qu’une
4. Propose, n’exécute jamais — l’auteur décide de ce qu’il accepte
**Entrée :**
- `content` (requis) — Document à réviser
- `style_guide` (optionnel) — Guide de style spécifique au projet
- `reader_type` (optionnel) — `humans` (par défaut) pour clarté/fluidité, ou `llm` pour précision/consistance
- `purpose` / `target_audience` / `length_target` (optionnel) — calibrent la passe structure
**Sortie :** Tableau de constatations avec corrections suggérées, plus une estimation de réduction lorsque des changements structurels sont proposés
## bmad-review
**Revue critique multi-perspectives sur tout diff, document ou artefact.** — Exécute des perspectives de revue indépendantes — chacune avec sa méthode et sa posture propres — et rapporte chaque constatation dans un format canonique unique. Zéro constatation est un résultat valide ; il ne remplit jamais pour paraître exhaustif.
**Revue multi-perspectives sur tout diff, document ou artefact.** — Exécute des perspectives de revue — chacune avec sa méthode et sa posture propres — et rapporte chaque constatation dans un format canonique unique. Zéro constatation est un résultat valide ; il ne remplit jamais pour paraître exhaustif. Chaque perspective déclare ce à quoi elle s’applique : un diff appelle les perspectives de code, un document les perspectives éditoriales.
**Les perspectives livrées :**
| Perspective | Méthode |
| --- | --- |
| **Contradictoire** | Revue sceptique qui part du principe que des problèmes existent — traque ce qui manque, pas seulement ce qui ne va pas |
| **Cas limites** | Parcourt chaque chemin de branchement et condition aux limites, ne rapporte que les chemins non gérés |
| **Lacunes de vérification** | Trouve les comportements modifiés qui pourraient régresser sans qu’une vérification fiable ne le détecte |
| Perspective | S’applique à | Méthode |
| --------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Contradictoire** | Tout contenu | Revue sceptique qui part du principe que des problèmes existent — traque ce qui manque, pas seulement ce qui ne va pas |
| **Cas limites** | Tout contenu | Parcourt chaque chemin de branchement et condition aux limites d’un contenu qui définit un comportement |
| **Lacunes de vérification** | Code | Trouve les comportements modifiés qui pourraient régresser sans qu’une vérification fiable ne le détecte |
| **Structure** | Documents | Propose coupes, fusions, déplacements et condensations — la forme du document sert-elle son objectif ? |
| **Prose** | Documents | Corrige les problèmes de communication qui nuisent à la compréhension |
Les deux perspectives éditoriales tiennent le contenu pour sacro-saint : elles ne remettent jamais en cause vos idées, seulement leur organisation et leur expression, et elles proposent sans exécuter. La perspective prose s’exécute sur les constatations de la perspective structure lorsque les deux sont sélectionnées.
L’ensemble n’est pas figé : une surcharge dans `customize.toml` peut ajouter des perspectives ou remplacer celles fournies, et une revue exécute celles qui sont effectivement résolues.
**À utiliser quand :**
- Vous avez besoin d’assurance qualité avant de finaliser un livrable
- Vous voulez une couverture exhaustive des cas limites d’un code ou d’une logique
- Vous voulez savoir si un changement est correctement vérifié
- Vous voulez les trois perspectives à la fois (le comportement par défaut)
- Vous avez rédigé un document et voulez le resserrer et le polir
- Vous voulez réduire la longueur en préservant la compréhension
**Fonctionnement :**
1. Charge le contenu et identifie son type — diff, fichier, fonction ou document
2. Sélectionne les perspectives : celles que vous nommez, ou toutes les perspectives activées adaptées au contenu
3. Exécute chaque perspective indépendamment — en parallèle via des sous-agents lorsque la plateforme le permet
4. Assemble une liste unique de constatations ; le chevauchement entre perspectives est un signal, pas une duplication
1. Charge le contenu, identifie son type — diff, fichier, fonction ou document — et s’il s’agit de code ou de documentation
2. Sélectionne les perspectives : celles que vous nommez, ou toutes les perspectives activées dont l’applicabilité et les conditions correspondent au contenu
3. Annonce le plan — quelles perspectives vont s’exécuter, et lesquelles s’appuient sur les constatations d’une autre
4. Exécute les perspectives indépendantes — en parallèle via des sous-agents lorsque la plateforme le permet — puis celles qui en dépendent
5. Assemble une liste unique de constatations ; le chevauchement entre perspectives est un signal, pas une duplication
**Entrée :**
- `content` (requis) — Diff, branche, changements non commités, fichier, spécification, story ou tout document
- `lenses` (optionnel) — un ou plusieurs codes ou noms de perspectives ; par défaut, revue complète
- `also_consider` (optionnel) — Domaines supplémentaires à garder à l’esprit
- `style_guide` / `reader_type` (optionnel, perspectives éditoriales) — un guide de style projet, et `humans` (défaut) ou `llm`
**Sortie :** Liste de constatations JSON (chaque constatation porte `lens`, `location`, `trigger_condition`, `guard_snippet`, `potential_consequence`) et/ou rapport markdown groupé par perspective
:::note[Utilisé par d’autres workflows]
Les workflows de Code Review d’autres modules exécutent ces perspectives automatiquement. Des perspectives personnalisées peuvent être ajoutées — et celles livrées ajustées ou désactivées — via le `customize.toml` de la compétence.
Les workflows de Code Review d’autres modules exécutent les perspectives de code automatiquement, et les workflows documentaires (PRD, UX, architecture, brief produit) exécutent les perspectives éditoriales à l’étape de finalisation. Des perspectives personnalisées peuvent être ajoutées — et celles livrées ajustées ou désactivées — via le `customize.toml` de la compétence.
:::
## bmad-customize
docs/reference/core-tools.md
+36 -55
View File
@@ -5,7 +5,7 @@ sidebar:
order: 3
---
Every BMad installation includes the **core module** — a small set of skills that work across all projects, all modules, and all phases. This page covers those eight core skills: the five kernel tools plus the three **thinking skills** (brainstorming, forge idea, party mode).
Every BMad installation includes the **core module** — a small set of skills that work across all projects, all modules, and all phases. This page covers those seven core skills: the four kernel tools plus the three **thinking skills** (brainstorming, forge idea, party mode).
:::tip[Quick Path]
Run any tool by typing its skill name (e.g., `bmad-help`) in your IDE. No agent session required.
@@ -15,24 +15,23 @@ Run any tool by typing its skill name (e.g., `bmad-help`) in your IDE. No agent
**Core module (always installed):**
| Tool | Purpose |
| --- | --- |
| [`bmad-help`](#bmad-help) | Get context-aware guidance on what to do next |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Push LLM output through iterative refinement methods |
| [`bmad-editorial-review`](#bmad-editorial-review) | Two-pass editorial review — structure, then prose |
| [`bmad-review`](#bmad-review) | Multi-lens critical review — adversarial, edge-case, and verification-gap |
| [`bmad-customize`](#bmad-customize) | Create and verify BMad customization overrides |
| Tool | Purpose |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| [`bmad-help`](#bmad-help) | Get context-aware guidance on what to do next |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Push LLM output through iterative refinement methods |
| [`bmad-review`](#bmad-review) | Multi-lens review — adversarial, edge-case, and verification-gap for code; structure and prose for documents |
| [`bmad-customize`](#bmad-customize) | Create and verify BMad customization overrides |
**Thinking skills:**
| Tool | Purpose |
| --- | --- |
| [`bmad-brainstorming`](#bmad-brainstorming) | Facilitate interactive brainstorming sessions |
| [`bmad-forge-idea`](#bmad-forge-idea) | Pressure-test an idea until it hardens, proves out, or dies cheaply |
| [`bmad-party-mode`](#bmad-party-mode) | Orchestrate multi-agent group discussions |
| Tool | Purpose |
| ------------------------------------------- | ------------------------------------------------------------------- |
| [`bmad-brainstorming`](#bmad-brainstorming) | Facilitate interactive brainstorming sessions |
| [`bmad-forge-idea`](#bmad-forge-idea) | Pressure-test an idea until it hardens, proves out, or dies cheaply |
| [`bmad-party-mode`](#bmad-party-mode) | Orchestrate multi-agent group discussions |
:::note[Moved and removed]
`bmad-spec` now ships with the BMM module as a Phase 2 planning workflow — see the [Workflow Map](./workflow-map.md#phase-2-planning). The `bmad-shard-doc` and `bmad-index-docs` utilities have been removed. The former `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter`, and `bmad-review-verification-gap` skills are merged into `bmad-editorial-review` and `bmad-review`; the old IDs still resolve via hidden forwarders for compatibility.
`bmad-spec` now ships with the BMM module as a Phase 2 planning workflow — see the [Workflow Map](./workflow-map.md#phase-2-planning). The `bmad-shard-doc` and `bmad-index-docs` utilities have been removed. The former `bmad-editorial-review`, `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter`, and `bmad-review-verification-gap` skills are all merged into `bmad-review`, whose editorial lenses replace the separate editorial skill; the old IDs still resolve via forwarders for compatibility.
:::
## bmad-help
@@ -79,69 +78,51 @@ Run any tool by typing its skill name (e.g., `bmad-help`) in your IDE. No agent
**Output:** Enhanced version of the content with improvements applied
## bmad-editorial-review
**Two-pass editorial review — structure, then prose.** — A clinical editor that reviews a document's shape and its sentences, returning suggested fixes you accept or reject row by row. Content is sacrosanct: it never challenges your ideas, only how they're organized and expressed.
**Use it when:**
- You've drafted a document and want it tightened and polished
- A document was produced from multiple subprocesses and needs structural coherence
- You want to reduce length while preserving comprehension
- You need clarity fixes without style-opinion changes
**How it works:**
1. **Structure pass** — proposes cuts, merges, moves, and condensing; asks whether the document's shape serves its purpose
2. **Prose pass** — copy-edits for communication issues that impede comprehension, using the Microsoft Writing Style Guide as the baseline (a provided style guide overrides it)
3. Runs both passes, structure first, by default; ask for a structure-only or prose-only review to run one
4. Proposes, never executes — the author decides what to accept
**Input:**
- `content` (required) — Document to review
- `style_guide` (optional) — Project-specific style guide
- `reader_type` (optional) — `humans` (default) for clarity/flow, or `llm` for precision/consistency
- `purpose` / `target_audience` / `length_target` (optional) — calibrate the structure pass
**Output:** Findings table with suggested fixes, plus estimated reduction when structural changes are proposed
## bmad-review
**Multi-lens critical review over any diff, doc, or artifact.** — Runs independent review lenses — each a distinct method and stance — and reports every finding in one canonical shape. Zero findings is a valid outcome; it never pads to look thorough.
**Multi-lens review over any diff, doc, or artifact.** — Runs review lenses — each a distinct method and stance — and reports every finding in one canonical shape. Zero findings is a valid outcome; it never pads to look thorough. Each lens declares what it applies to, so a diff draws the code lenses and a document draws the editorial ones.
**The shipped lenses:**
| Lens | Method |
| --- | --- |
| **Adversarial** | Skeptical review that assumes problems exist — hunts what's missing, not just what's wrong |
| **Edge case** | Walks every branching path and boundary condition, reports only unhandled paths |
| **Verification gap** | Finds changed behavior that could regress without reliable verification catching it |
| Lens | Applies to | Method |
| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------- |
| **Adversarial** | Anything | Skeptical review that assumes problems exist — hunts what's missing, not just what's wrong |
| **Edge case** | Anything | Walks every branching path and boundary condition in content that defines behavior |
| **Verification gap** | Code | Finds changed behavior that could regress without reliable verification catching it |
| **Structure** | Documents | Proposes cuts, merges, moves, and condensing — does the document's shape serve its purpose? |
| **Prose** | Documents | Copy-edits for communication issues that impede comprehension |
The two editorial lenses hold content sacrosanct: they never challenge your ideas, only how they're organized and expressed, and they propose rather than execute. Prose runs on top of the structure findings when both are selected.
The set isn't fixed: a `customize.toml` override can add lenses or replace shipped ones, and a review runs whatever resolves.
**Use it when:**
- You need quality assurance before finalizing a deliverable
- You want exhaustive edge-case coverage of code or logic
- You want to know whether a change is adequately verified
- You want all three perspectives at once (the default)
- You've drafted a document and want it tightened and polished
- You want to reduce length while preserving comprehension
**How it works:**
1. Loads the content and identifies its type — diff, file, function, or document
2. Selects lenses: the ones you name, or every enabled lens that fits the content
3. Runs each lens independently — in parallel via subagents when the platform supports it
4. Assembles one findings array; overlap between lenses is signal, not duplication
1. Loads the content, identifies its type — diff, file, function, or document — and whether it is code or docs
2. Selects lenses: the ones you name, or every enabled lens whose applicability and conditions fit the content
3. Announces the plan — which lenses will run, and which run on top of another's findings
4. Runs the independent lenses — in parallel via subagents when the platform supports it — then the dependent ones on top of their results
5. Assembles one findings array; overlap between lenses is signal, not duplication
**Input:**
- `content` (required) — Diff, branch, uncommitted changes, file, spec, story, or any document
- `lenses` (optional) — one or more lens codes or names; default is a full review
- `lenses` (optional) — one or more lens codes or names; default is every lens that fits the content
- `also_consider` (optional) — Additional areas to keep in mind
- `style_guide` / `reader_type` (optional, editorial lenses) — a project style guide, and `humans` (default) for clarity/flow or `llm` for precision/consistency
**Output:** JSON findings array (each finding carries `lens`, `location`, `trigger_condition`, `guard_snippet`, `potential_consequence`) and/or a markdown report grouped by lens
**Output:** JSON findings array (each finding carries `lens`, `location`, `trigger_condition`, `guard_snippet`, `potential_consequence`) and/or a markdown report grouped by lens. The editorial lenses render a findings table you accept or reject row by row, plus an estimated reduction when structural changes are proposed.
:::note[Used by other workflows]
Code Review workflows in other modules run these lenses automatically. Custom lenses can be added — and shipped ones tuned or disabled — through the skill's `customize.toml`.
Code Review workflows in other modules run the code lenses automatically, and the document workflows (PRD, UX, architecture, product brief) run the editorial lenses as their finalize step. Custom lenses can be added — and shipped ones tuned or disabled — through the skill's `customize.toml`.
:::
## bmad-customize
docs/vi-vn/reference/core-tools.md
+36 -55
View File
@@ -5,7 +5,7 @@ sidebar:
order: 3
---
Mọi bản cài BMad đều bao gồm **module lõi** — một tập nhỏ các skill hoạt động xuyên suốt mọi dự án, mọi module và mọi giai đoạn. Trang này bao quát 8 skill lõi đó: 5 công cụ nhân lõi cùng 3 **skill tư duy** (brainstorming, forge idea, party mode).
Mọi bản cài BMad đều bao gồm **module lõi** — một tập nhỏ các skill hoạt động xuyên suốt mọi dự án, mọi module và mọi giai đoạn. Trang này bao quát 7 skill lõi đó: 4 công cụ nhân lõi cùng 3 **skill tư duy** (brainstorming, forge idea, party mode).
:::tip[Lối đi nhanh]
Chạy bất kỳ công cụ nào bằng cách gõ tên skill của nó, ví dụ `bmad-help`, trong IDE của bạn. Không cần mở phiên agent trước.
@@ -15,24 +15,23 @@ Chạy bất kỳ công cụ nào bằng cách gõ tên skill của nó, ví d
**Module lõi (luôn được cài):**
| Công cụ | Mục đích |
| --- | --- |
| [`bmad-help`](#bmad-help) | Nhận hướng dẫn có ngữ cảnh về việc nên làm gì tiếp theo |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Đẩy đầu ra của LLM qua các vòng tinh luyện lặp |
| [`bmad-editorial-review`](#bmad-editorial-review) | Review biên tập hai lượt — cấu trúc trước, câu chữ sau |
| [`bmad-review`](#bmad-review) | Review phản biện đa lăng kính — hoài nghi, ca biên và lỗ hổng kiểm chứng |
| [`bmad-customize`](#bmad-customize) | Tạo và kiểm tra các tùy biến BMad |
| Công cụ | Mục đích |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [`bmad-help`](#bmad-help) | Nhận hướng dẫn có ngữ cảnh về việc nên làm gì tiếp theo |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Đẩy đầu ra của LLM qua các vòng tinh luyện lặp |
| [`bmad-review`](#bmad-review) | Review đa lăng kính — hoài nghi, ca biên, lỗ hổng kiểm chứng cho code; cấu trúc và câu chữ cho tài liệu |
| [`bmad-customize`](#bmad-customize) | Tạo và kiểm tra các tùy biến BMad |
**Skill tư duy:**
| Công cụ | Mục đích |
| --- | --- |
| [`bmad-brainstorming`](#bmad-brainstorming) | Tổ chức các phiên brainstorming có tương tác |
| [`bmad-forge-idea`](#bmad-forge-idea) | Thử lửa một ý tưởng cho đến khi nó cứng cáp, được chứng thực hoặc chết với chi phí thấp |
| [`bmad-party-mode`](#bmad-party-mode) | Điều phối thảo luận nhóm nhiều agent |
| Công cụ | Mục đích |
| ------------------------------------------- | --------------------------------------------------------------------------------------- |
| [`bmad-brainstorming`](#bmad-brainstorming) | Tổ chức các phiên brainstorming có tương tác |
| [`bmad-forge-idea`](#bmad-forge-idea) | Thử lửa một ý tưởng cho đến khi nó cứng cáp, được chứng thực hoặc chết với chi phí thấp |
| [`bmad-party-mode`](#bmad-party-mode) | Điều phối thảo luận nhóm nhiều agent |
:::note[Đã chuyển và đã gỡ]
`bmad-spec` giờ đi kèm module BMM như một workflow lập kế hoạch Giai đoạn 2 — xem [Bản đồ Workflow](./workflow-map.md). Các tiện ích `bmad-shard-doc` và `bmad-index-docs` đã bị gỡ bỏ. Các skill cũ `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter` và `bmad-review-verification-gap` đã được gộp vào `bmad-editorial-review` và `bmad-review`; các ID cũ vẫn hoạt động qua cơ chế chuyển tiếp ẩn để giữ tương thích.
`bmad-spec` giờ đi kèm module BMM như một workflow lập kế hoạch Giai đoạn 2 — xem [Bản đồ Workflow](./workflow-map.md). Các tiện ích `bmad-shard-doc` và `bmad-index-docs` đã bị gỡ bỏ. Các skill cũ `bmad-editorial-review`, `bmad-editorial-review-prose`, `bmad-editorial-review-structure`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter` và `bmad-review-verification-gap` đều đã được gộp vào `bmad-review`, với các lăng kính biên tập thay thế skill biên tập riêng lẻ; các ID cũ vẫn hoạt động qua cơ chế chuyển tiếp để giữ tương thích.
:::
## bmad-help
@@ -79,64 +78,46 @@ Chạy bất kỳ công cụ nào bằng cách gõ tên skill của nó, ví d
**Đầu ra:** Phiên bản nội dung đã được nâng cấp
## bmad-editorial-review
**Review biên tập hai lượt — cấu trúc trước, câu chữ sau.** Một biên tập viên lâm sàng review cả hình khối của tài liệu lẫn từng câu chữ, trả về các đề xuất sửa để bạn chấp nhận hoặc từ chối theo từng dòng. Nội dung là bất khả xâm phạm: nó không bao giờ chất vấn ý tưởng của bạn, chỉ cách tổ chức và diễn đạt.
**Dùng khi:**
- Bạn đã có bản nháp và muốn siết chặt, trau chuốt nó
- Tài liệu được ghép từ nhiều quy trình con và cần sự mạch lạc về cấu trúc
- Bạn muốn giảm độ dài mà vẫn giữ được khả năng hiểu
- Bạn muốn sửa cho rõ nghĩa mà không áp đặt gu phong cách
**Cách hoạt động:**
1. **Lượt cấu trúc** — đề xuất cắt, gộp, di chuyển và cô đọng; đặt câu hỏi liệu hình khối tài liệu có phục vụ mục đích của nó
2. **Lượt câu chữ** — biên tập các vấn đề giao tiếp cản trở việc hiểu, dùng Microsoft Writing Style Guide làm nền (style guide bạn cung cấp sẽ được ưu tiên)
3. Mặc định chạy cả hai lượt, cấu trúc trước; yêu cầu review chỉ cấu trúc hoặc chỉ câu chữ nếu muốn chạy một lượt
4. Chỉ đề xuất, không bao giờ tự sửa — tác giả quyết định chấp nhận gì
**Đầu vào:**
- `content` *(bắt buộc)* — Tài liệu cần review
- `style_guide` *(tùy chọn)* — Style guide riêng của dự án
- `reader_type` *(tùy chọn)* — `humans` mặc định cho độ rõ và nhịp đọc, hoặc `llm` cho độ chính xác và nhất quán
- `purpose` / `target_audience` / `length_target` *(tùy chọn)* — hiệu chỉnh lượt cấu trúc
**Đầu ra:** Bảng phát hiện kèm đề xuất sửa, cộng ước tính mức rút gọn khi có đề xuất thay đổi cấu trúc
## bmad-review
**Review phản biện đa lăng kính trên bất kỳ diff, tài liệu hay artifact nào.** Chạy các lăng kính review độc lập — mỗi lăng kính một phương pháp và lập trường riêng — và báo cáo mọi phát hiện theo một định dạng chuẩn duy nhất. Không phát hiện gì cũng là kết quả hợp lệ; nó không bao giờ độn thêm cho có vẻ kỹ lưỡng.
**Review đa lăng kính trên bất kỳ diff, tài liệu hay artifact nào.** Chạy các lăng kính review — mỗi lăng kính một phương pháp và lập trường riêng — và báo cáo mọi phát hiện theo một định dạng chuẩn duy nhất. Không phát hiện gì cũng là kết quả hợp lệ; nó không bao giờ độn thêm cho có vẻ kỹ lưỡng. Mỗi lăng kính khai báo phạm vi áp dụng: diff kéo theo các lăng kính code, tài liệu kéo theo các lăng kính biên tập.
**Các lăng kính đi kèm:**
| Lăng kính | Phương pháp |
| --- | --- |
| **Hoài nghi (Adversarial)** | Review hoài nghi mặc định vấn đề luôn tồn tại — săn phần còn thiếu, không chỉ phần sai |
| **Ca biên (Edge case)** | Đi qua mọi nhánh rẽ và điều kiện biên, chỉ báo cáo các đường chưa được xử lý |
| **Lỗ hổng kiểm chứng (Verification gap)** | Tìm hành vi đã thay đổi có thể hồi quy mà không có kiểm chứng đáng tin cậy nào bắt được |
| Lăng kính | Áp dụng cho | Phương pháp |
| ----------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------- |
| **Hoài nghi (Adversarial)** | Mọi nội dung | Review hoài nghi mặc định vấn đề luôn tồn tại — săn phần còn thiếu, không chỉ phần sai |
| **Ca biên (Edge case)** | Mọi nội dung | Đi qua mọi nhánh rẽ và điều kiện biên trong nội dung có định nghĩa hành vi |
| **Lỗ hổng kiểm chứng (Verification gap)** | Code | Tìm hành vi đã thay đổi có thể hồi quy mà không có kiểm chứng đáng tin cậy nào bắt được |
| **Cấu trúc (Structure)** | Tài liệu | Đề xuất cắt, gộp, di chuyển và cô đọng — hình hài tài liệu có phục vụ mục đích của nó không? |
| **Câu chữ (Prose)** | Tài liệu | Biên tập các vấn đề diễn đạt gây cản trở việc hiểu |
Hai lăng kính biên tập coi nội dung là bất khả xâm phạm: không bao giờ chất vấn ý tưởng của bạn, chỉ xét cách tổ chức và diễn đạt, và chỉ đề xuất chứ không tự sửa. Khi chọn cả hai, lăng kính câu chữ chạy trên các phát hiện của lăng kính cấu trúc.
Tập lăng kính không cố định: một override trong `customize.toml` có thể thêm lăng kính hoặc thay thế lăng kính có sẵn, và mỗi lần rà soát sẽ chạy những gì thực sự được phân giải.
**Dùng khi:**
- Bạn cần bảo đảm chất lượng trước khi chốt một deliverable
- Bạn muốn phủ kín các ca biên của code hoặc logic
- Bạn muốn biết một thay đổi đã được kiểm chứng đầy đủ chưa
- Bạn muốn cả ba góc nhìn cùng lúc (mặc định)
- Bạn đã viết xong một tài liệu và muốn siết lại cho gọn và mượt
- Bạn muốn rút ngắn độ dài mà vẫn giữ được khả năng hiểu
**Cách hoạt động:**
1. Nạp nội dung và nhận diện loại — diff, file, hàm hoặc tài liệu
2. Chọn lăng kính: những cái bạn nêu tên, hoặc mọi lăng kính đang bật phù hợp với nội dung
3. Chạy từng lăng kính độc lập — song song qua subagent khi nền tảng hỗ trợ
4. Gom về một danh sách phát hiện duy nhất; trùng lặp giữa các lăng kính là tín hiệu, không phải lặp thừa
1. Nạp nội dung, nhận diện loại — diff, file, hàm hoặc tài liệu — và thuộc về code hay tài liệu
2. Chọn lăng kính: những cái bạn nêu tên, hoặc mọi lăng kính đang bật có phạm vi áp dụng và điều kiện khớp với nội dung
3. Công bố kế hoạch — những lăng kính nào sẽ chạy, và lăng kính nào chạy trên phát hiện của lăng kính khác
4. Chạy các lăng kính độc lập — song song qua subagent khi nền tảng hỗ trợ — rồi tới các lăng kính phụ thuộc
5. Gom về một danh sách phát hiện duy nhất; trùng lặp giữa các lăng kính là tín hiệu, không phải lặp thừa
**Đầu vào:**
- `content` *(bắt buộc)* — Diff, branch, thay đổi chưa commit, file, spec, story hoặc bất kỳ tài liệu nào
- `lenses` *(tùy chọn)* — một hoặc nhiều mã/tên lăng kính; mặc định là review đầy đủ
- `also_consider` *(tùy chọn)* — Các vùng bổ sung cần để ý
- `content` _(bắt buộc)_ — Diff, branch, thay đổi chưa commit, file, spec, story hoặc bất kỳ tài liệu nào
- `lenses` _(tùy chọn)_ — một hoặc nhiều mã/tên lăng kính; mặc định là review đầy đủ
- `also_consider` _(tùy chọn)_ — Các vùng bổ sung cần để ý
- `style_guide` / `reader_type` _(tùy chọn, cho lăng kính biên tập)_ — style guide của dự án, và `humans` (mặc định) hoặc `llm`
**Đầu ra:** Mảng phát hiện JSON và/hoặc báo cáo markdown nhóm theo lăng kính. Có thể thêm lăng kính tùy biến — và tinh chỉnh hoặc tắt các lăng kính đi kèm — qua `customize.toml` của skill
docs/zh-cn/reference/core-tools.md
+43 -44
View File
@@ -1,11 +1,11 @@
---
title: "核心工具"
title: '核心工具'
description: 核心模块内置 skills 参考。
sidebar:
order: 3
---
每个 BMad 安装都包含 **核心模块** —— 一小组跨项目、跨模块、跨阶段通用的 skills。本页覆盖这 8 个核心 skills：5 个内核工具，加上 3 个 **思考类 skills**（brainstorming、forge idea、party mode）。
每个 BMad 安装都包含 **核心模块** —— 一小组跨项目、跨模块、跨阶段通用的 skills。本页覆盖这 7 个核心 skills：4 个内核工具，加上 3 个 **思考类 skills**（brainstorming、forge idea、party mode）。
:::tip[快速入口]
在 IDE 中直接输入工具 skill 名（例如 `bmad-help`）即可调用，无需先加载智能体。
@@ -15,24 +15,23 @@ sidebar:
**核心模块（始终安装）：**
| 工具 | 主要用途 |
| --- | --- |
| [`bmad-help`](#bmad-help) | 基于项目上下文推荐下一步 |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | 通过多轮技法增强 LLM 输出 |
| [`bmad-editorial-review`](#bmad-editorial-review) | 两阶段编辑审查 —— 先结构、后文字 |
| [`bmad-review`](#bmad-review) | 多视角批判性审查 —— 对抗、边界条件与验证缺口 |
| [`bmad-customize`](#bmad-customize) | 创建并验证 BMad 自定义覆盖 |
| 工具 | 主要用途 |
| --------------------------------------------------------- | -------------------------------------------- |
| [`bmad-help`](#bmad-help) | 基于项目上下文推荐下一步 |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | 通过多轮技法增强 LLM 输出 |
| [`bmad-review`](#bmad-review) | 多视角批判性审查 —— 对抗、边界条件与验证缺口 |
| [`bmad-customize`](#bmad-customize) | 创建并验证 BMad 自定义覆盖 |
**思考类 skills：**
| 工具 | 主要用途 |
| --- | --- |
| [`bmad-brainstorming`](#bmad-brainstorming) | 引导式头脑风暴与想法扩展 |
| [`bmad-forge-idea`](#bmad-forge-idea) | 压力测试一个想法，直到它站得住、被证实或低成本地淘汰 |
| [`bmad-party-mode`](#bmad-party-mode) | 多智能体协作讨论 |
| 工具 | 主要用途 |
| ------------------------------------------- | ---------------------------------------------------- |
| [`bmad-brainstorming`](#bmad-brainstorming) | 引导式头脑风暴与想法扩展 |
| [`bmad-forge-idea`](#bmad-forge-idea) | 压力测试一个想法，直到它站得住、被证实或低成本地淘汰 |
| [`bmad-party-mode`](#bmad-party-mode) | 多智能体协作讨论 |
:::note[迁移与移除]
`bmad-spec` 现随 BMM 模块作为第 2 阶段规划 workflow 发布 —— 见[工作流地图](./workflow-map.md)。`bmad-shard-doc` 与 `bmad-index-docs` 已移除。原 `bmad-editorial-review-prose`、`bmad-editorial-review-structure`、`bmad-review-adversarial-general`、`bmad-review-edge-case-hunter`、`bmad-review-verification-gap` 已合并进 `bmad-editorial-review` 与 `bmad-review`；旧 ID 仍可通过隐藏转发器解析，保持兼容。
`bmad-spec` 现随 BMM 模块作为第 2 阶段规划 workflow 发布 —— 见[工作流地图](./workflow-map.md)。`bmad-shard-doc` 与 `bmad-index-docs` 已移除。原 `bmad-editorial-review`、`bmad-editorial-review-prose`、`bmad-editorial-review-structure`、`bmad-review-adversarial-general`、`bmad-review-edge-case-hunter`、`bmad-review-verification-gap` 已全部合并进 `bmad-review`，其编辑视角取代了原独立的编辑审查 skill；旧 ID 仍可通过转发器解析，保持兼容。
:::
## bmad-help
@@ -40,11 +39,13 @@ sidebar:
**定位：** 你的默认导航入口，告诉你“下一步该做什么”。
**适用场景：**
- 刚完成一个 workflow，不确定如何衔接
- 新接触项目，需要先看当前进度
- 变更模块后，想知道可用能力和推荐顺序
**工作机制：**
1. 扫描已存在产物（PRD、architecture、stories 等）
2. 检测已安装模块及其可用 workflow
3. 按优先级输出“必需步骤 + 可选步骤”
@@ -57,11 +58,13 @@ sidebar:
**定位：** 对已有 LLM 输出做第二轮深挖与改写强化。
**适用场景：**
- 结果“看起来对”，但深度不够
- 想从多个思维框架交叉审视同一内容
- 想按名字调用已知方法 —— 苏格拉底式、第一性原理、事前验尸、红队
**工作机制：**
1. 默认针对会话中最近一次输出，也可指向其他内容
2. 给出与内容匹配的候选技法短菜单
3. 应用所选技法进行强化
@@ -70,43 +73,33 @@ sidebar:
**输入：** 待增强内容（默认最近输出），可选指定方法名
**输出：** 增强后的内容版本
## bmad-editorial-review
**定位：** 两阶段编辑审查 —— 先审结构，再审文字；只改表达，不动观点。
**适用场景：**
- 文档已成稿，想要收紧和打磨
- 多个子流程拼出的文档需要结构上的连贯性
- 想在保留可理解性的前提下缩减篇幅
**工作机制：**
1. **结构阶段** —— 提出删减、合并、移动与压缩建议，检验文档形态是否服务于其目的
2. **文字阶段** —— 以 Microsoft Writing Style Guide 为基线（提供的风格指南优先），修复影响理解的表达问题
3. 默认两阶段依次执行；可只要求结构或文字单项审查
4. 只提建议、不直接改写 —— 是否采纳由作者决定
**输入：** `content`（必填），`style_guide` / `reader_type` / `purpose` / `target_audience` / `length_target`（可选）
**输出：** 修订建议表；提出结构性修改时附预计压缩幅度
## bmad-review
**定位：** 面向任意 diff、文档或产物的多视角批判性审查。各视角独立运行，统一输出。零发现是合法结果，绝不为“看起来彻底”而凑数。
**定位：** 面向任意 diff、文档或产物的多视角审查。统一输出。零发现是合法结果，绝不为“看起来彻底”而凑数。每个视角声明其适用对象：diff 触发代码视角，文档触发编辑视角。
**内置视角：**
| 视角 | 方法 |
| --- | --- |
| **对抗（Adversarial）** | 假设问题存在的怀疑式审查 —— 主动找缺失，而非只纠错 |
| **边界条件（Edge case）** | 走遍每条分支路径与边界条件，只报告未处理的路径 |
| **验证缺口（Verification gap）** | 找出可能回归且缺乏可靠验证兜底的行为变更 |
| 视角 | 适用于 | 方法 |
| -------------------------------- | ---------------- | ---------------------------------------------------------- |
| **对抗（Adversarial）** | 任意内容 | 假设问题存在的怀疑式审查 —— 主动找缺失，而非只纠错 |
| **边界条件（Edge case）** | 任意内容 | 走遍定义了行为的内容中的每条分支路径与边界条件 |
| **验证缺口（Verification gap）** | 代码 | 找出可能回归且缺乏可靠验证兜底的行为变更 |
| **结构（Structure）** | 文档 | 提出删减、合并、移动与精简 —— 文档的结构是否服务于其目的？ |
| **文字（Prose）** | 文档 | 针对妨碍理解的表达问题做文字编辑 |
两个编辑视角视内容为不可侵犯：只审组织与表达，从不质疑观点；只提建议，不直接改写。两者同时选中时，文字视角在结构视角的发现之上运行。
这套视角并非固定：`customize.toml` 覆盖可以新增视角或替换内置视角，审查会运行解析后实际生效的那些。
**工作机制：**
1. 加载内容并识别类型 —— diff、文件、函数或文档
2. 选择视角：你指定的，或所有适配内容的已启用视角
3. 各视角独立运行 —— 平台支持时通过子代理并行
4. 汇总为一个 findings 列表；视角间重叠是信号而非重复
**输入：** `content`（必填），`lenses`（可选，默认全量审查），`also_consider`（可选）
1. 加载内容，识别类型（diff、文件、函数或文档）以及属于代码还是文档
2. 选择视角：你指定的，或所有适用性与条件匹配的已启用视角
3. announce 执行计划 —— 将运行哪些视角，以及哪些视角在其他视角的发现之上运行
4. 独立视角先运行 —— 平台支持时通过子代理并行 —— 随后运行依赖它们的视角
5. 汇总为一个 findings 列表；视角间重叠是信号而非重复
**输入：** `content`（必填），`lenses`（可选，默认运行所有适配内容的视角），`also_consider`（可选），`style_guide` / `reader_type`（可选，供编辑视角使用）
**输出：** JSON findings 数组和/或按视角分组的 markdown 报告。可通过 skill 的 `customize.toml` 增加自定义视角，或调整/停用内置视角
## bmad-customize
@@ -114,6 +107,7 @@ sidebar:
**定位：** 无需手写 TOML，即可修改已安装 BMad 智能体或 workflow 的行为。
**工作机制：**
1. 扫描已安装 BMad skills 的可自定义面
2. 为你的变更选择合适的覆盖范围
3. 在 `_bmad/custom/` 下写入覆盖文件
@@ -131,11 +125,13 @@ sidebar:
**定位：** 用结构化创意技法快速扩展想法池。
**适用场景：**
- 启动新主题，想先打开问题空间
- 团队卡在同一思路，需要外部技法打破惯性
- 需要把“模糊方向”变成可讨论候选方案
**工作机制：**
1. 建立主题会话
2. 从方法库选择创意技法
3. 逐轮引导产出并记录想法
@@ -149,6 +145,7 @@ sidebar:
**定位：** 压力测试一个想法，直到它站得住、被证实或低成本地淘汰。
**工作机制：**
1. 先确立目标，并据此调整提问方向
2. 按依赖顺序一次一个问题，先摆出推荐答案供你反驳
3. 每个分支引入两个角色声音 —— 一个来自已安装的角色阵容，一个由话题临时召唤
@@ -163,11 +160,13 @@ sidebar:
**定位：** 让多个智能体围绕同一议题协作讨论。
**适用场景：**
- 决策涉及产品、架构、实现、质量等多视角
- 希望不同角色显式冲突并暴露假设差异
- 需要在短时间内收集多方案观点
**工作机制：**
1. 读取已安装智能体清单
2. 选取最相关的 2-3 个角色先发言
3. 轮换角色、持续交叉讨论
src/bmm-skills/1-analysis/bmad-product-brief/customize.toml
+5 -3
View File
@@ -53,7 +53,7 @@ run_folder_pattern = "brief-{project_name}-{date}"
# findings before the user sees the draft. Encodes standards, not options.
#
# Examples:
# "skill:bmad-editorial-review"
# "skill:bmad-review lenses=structure,prose"
# "file:{project-root}/_bmad/style-guides/company-voice.md"
# "Convert all dates to ISO 8601 format."
#
@@ -64,9 +64,11 @@ run_folder_pattern = "brief-{project_name}-{date}"
#
# Override the array in team/user TOML to add additional standards. Append-only:
# base entries cannot be removed or replaced (resolver has no removal mechanism).
# The default entry runs both editorial passes in order: structure, then prose.
# The default entry runs bmad-review's two editorial lenses in order:
# structure, then prose on top of the structure findings. The `lenses=` suffix
# names them; drop it to let bmad-review pick what fits the content.
doc_standards = [
"skill:bmad-editorial-review",
"skill:bmad-review lenses=structure,prose",
]
# External-source registry. Natural-language directives describing knowledge
src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml
+5 -3
View File
@@ -71,7 +71,7 @@ run_folder_pattern = "prd-{project_name}-{date}"
# findings before the user sees the draft. Encodes standards, not options.
#
# Examples:
# "skill:bmad-editorial-review"
# "skill:bmad-review lenses=structure,prose"
# "file:{project-root}/_bmad/style-guides/company-voice.md"
# "Convert all dates to ISO 8601 format."
#
@@ -82,9 +82,11 @@ run_folder_pattern = "prd-{project_name}-{date}"
#
# Override the array in team/user TOML to add additional standards. Append-only:
# base entries cannot be removed or replaced (resolver has no removal mechanism).
# The default entry runs both editorial passes in order: structure, then prose.
# The default entry runs bmad-review's two editorial lenses in order:
# structure, then prose on top of the structure findings. The `lenses=` suffix
# names them; drop it to let bmad-review pick what fits the content.
doc_standards = [
"skill:bmad-editorial-review",
"skill:bmad-review lenses=structure,prose",
]
# External-source registry. Natural-language directives describing knowledge
src/bmm-skills/2-plan-workflows/bmad-ux/customize.toml
+4 -2
View File
@@ -78,9 +78,11 @@ creative_tools = [
# Polish passes applied to DESIGN.md and EXPERIENCE.md at finalize.
# Entries: `skill:NAME`, `file:PATH`, or plain text directive.
# Suggested order: structural → content/voice → prose mechanics.
# The default entry runs both editorial passes in order: structure, then prose.
# The default entry runs bmad-review's two editorial lenses in order:
# structure, then prose on top of the structure findings. The `lenses=` suffix
# names them; drop it to let bmad-review pick what fits the content.
doc_standards = [
"skill:bmad-editorial-review",
"skill:bmad-review lenses=structure,prose",
]
# Information retrieval registry. Consulted on demand when the conversation
src/bmm-skills/3-solutioning/bmad-architecture/customize.toml
+4 -2
View File
@@ -59,9 +59,11 @@ run_folder_pattern = "architecture-{project_name}-{date}"
# short, structured outputs, which are terse and carry decisions in AD-n blocks and diagrams by
# design. Each entry is a `skill:`, `file:`, or plain-text directive applied before the user sees
# the polished draft. Suggested order: structural passes first, prose mechanics last. Append-only.
# The default entry runs both editorial passes in order: structure, then prose.
# The default entry runs bmad-review's two editorial lenses in order:
# structure, then prose on top of the structure findings. The `lenses=` suffix
# names them; drop it to let bmad-review pick what fits the content.
doc_standards = [
"skill:bmad-editorial-review",
"skill:bmad-review lenses=structure,prose",
]
# External-source registry. Natural-language directives describing knowledge bases, MCP tools, or
src/bmm-skills/v6-shims/README.md
+21
View File
@@ -0,0 +1,21 @@
# v6 Deprecation Shims
Skills in this folder are forwarders kept for backward compatibility with v6 skill IDs.
Each one holds no logic of its own — it forwards to the skill that replaced it, passing a
stated intent and pre-resolved customization fields so the target skips its own intent
inference.
| Shim | Forwards to |
| -------------------------- | ----------------------------------- |
| `bmad-create-prd` | `bmad-prd` (create intent) |
| `bmad-edit-prd` | `bmad-prd` (update intent) |
| `bmad-validate-prd` | `bmad-prd` (validate intent) |
| `bmad-create-architecture` | `bmad-architecture` (create intent) |
Enterprise users may still depend on these IDs, so they ship by default. Removal rides the
v7 cut — never a 6.x minor.
The folder is grouping only: the installer discovers skills recursively and installs each
one under its own `name`, so nesting here does not change any installed path or skill ID.
A future install option will let users include or exclude this folder before it is removed
outright.
src/bmm-skills/3-solutioning/bmad-create-architecture/SKILL.md → src/bmm-skills/v6-shims/bmad-create-architecture/SKILL.md
View File
src/bmm-skills/3-solutioning/bmad-create-architecture/customize.toml → src/bmm-skills/v6-shims/bmad-create-architecture/customize.toml
View File
src/bmm-skills/2-plan-workflows/bmad-create-prd/SKILL.md → src/bmm-skills/v6-shims/bmad-create-prd/SKILL.md
View File
src/bmm-skills/2-plan-workflows/bmad-create-prd/customize.toml → src/bmm-skills/v6-shims/bmad-create-prd/customize.toml
View File
src/bmm-skills/2-plan-workflows/bmad-edit-prd/SKILL.md → src/bmm-skills/v6-shims/bmad-edit-prd/SKILL.md
View File
src/bmm-skills/2-plan-workflows/bmad-edit-prd/customize.toml → src/bmm-skills/v6-shims/bmad-edit-prd/customize.toml
View File
src/bmm-skills/2-plan-workflows/bmad-validate-prd/SKILL.md → src/bmm-skills/v6-shims/bmad-validate-prd/SKILL.md
View File
src/bmm-skills/2-plan-workflows/bmad-validate-prd/customize.toml → src/bmm-skills/v6-shims/bmad-validate-prd/customize.toml
View File
src/core-skills/bmad-editorial-review-prose/SKILL.md
-6
View File
@@ -1,6 +0,0 @@
---
name: bmad-editorial-review-prose
description: 'Deprecated — forwards to bmad-editorial-review.'
---
Invoke `bmad-editorial-review` in prose-only mode with the same target and inputs. Present the findings in the legacy shape: a three-column markdown table `| Original Text | Revised Text | Changes |` — no Pass column, no preamble above the table. If no issues are found, output exactly: `No editorial issues identified`.
src/core-skills/bmad-editorial-review-structure/SKILL.md
-6
View File
@@ -1,6 +0,0 @@
---
name: bmad-editorial-review-structure
description: 'Deprecated — forwards to bmad-editorial-review.'
---
Invoke `bmad-editorial-review` in structure-only mode with the same target and inputs. Present the findings in the legacy report shape: a `## Document Summary` block (purpose, audience, reader type, structure model, current length), a `## Recommendations` list of numbered `[CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE]` entries each with rationale and word impact, and a closing `## Summary` (total recommendations, estimated reduction) — not the findings table. If no structural issues are found, output exactly: `No substantive changes recommended`.
src/core-skills/bmad-editorial-review/SKILL.md
-77
View File
@@ -1,77 +0,0 @@
---
name: bmad-editorial-review
description: 'Two-pass editorial review of a document — structure then prose. Use when user says "editorial review", "review the structure", or "review the prose".'
---
# Editorial Review
## Overview
Review a document as a clinical editor and return suggested fixes the author can accept or reject row by row. Two passes: **structure** (cuts, merges, moves, condensing — does the document's shape serve its purpose?) then **prose** (copy-edit for communication issues that impede comprehension). Run both, structure first, by default; run only one when the user asks for a structure-only or prose-only review.
**Content is sacrosanct.** Never challenge ideas — only how they're organized and expressed. Propose, don't execute: the author decides what to accept.
The baseline style guide is `{workflow.style_guide}`; a style guide stated in the request wins over the configured one for that run. Where the style guide in effect conflicts with a generic principle here — including the reader calibration — the style guide wins. Nothing overrides content being sacrosanct.
## Conventions
- Bare paths and `{skill-root}` resolve from this skill's installed directory; `{project-root}` is the project working directory.
- `{workflow.<name>}` resolves to fields in `customize.toml`'s `[workflow]` table (overrides win per BMad merge rules).
- In `style_guide`, `review_guidance`, and `persistent_facts`, a value prefixed `file:` is a path or glob — load that file's contents. If a `file:` value cannot be read, name the failed file in the output header and continue: the shipped baseline for `style_guide`, the remaining entries otherwise.
## On Activation
1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. Execute each `{workflow.activation_steps_prepend}` entry in order, and hold `{workflow.persistent_facts}` as standing context for the session.
2. Gather inputs: the content (required — a path or pasted text), plus whatever the request states: purpose, target audience, length target, reader type, style guide. If no reviewable content was provided, say so and stop. Request-level values win; `{workflow.reader_type}` and `{workflow.style_guide}` fill what the request leaves unstated. Treat `{workflow.review_guidance}` entries as standing review directives.
3. When the content is a file, get exact word counts — document total and per heading section — via `uv run {skill-root}/scripts/word_metrics.py <path>` (`--help` documents the output), and ground every word-impact estimate and the reduction summary in those numbers. If the content was pasted or the script cannot run, estimate and mark the numbers as estimates.
4. Infer purpose and audience from the content and standing context when not provided, and open the output with your one-sentence read — "this document exists to help [audience] accomplish [goal]" — so the author can correct a wrong premise before acting on the findings.
5. Execute each `{workflow.activation_steps_append}` entry in order.
## Reader calibration
Calibrate every finding to the reader type — stated in the request, else `{workflow.reader_type}`.
**humans** (default) — optimize for clarity, flow, and natural progression. These elements serve comprehension and engagement; preserve them unless clearly wasteful, and flag any recommendation that would cut one:
- Visual aids: diagrams, images, and flowcharts anchor understanding
- Expectation-setting: "What You'll Learn" helps readers confirm they're in the right place
- Reader's journey: organize content as a linear progression, not a database
- Mental models: overview before details prevents cognitive overload
- Warmth: encouraging tone reduces anxiety for new users
- Whitespace: admonitions and callouts provide visual breathing room
- Summaries: recaps help retention; they're reinforcement, not redundancy
- Examples: concrete illustrations make abstract concepts accessible
- Engagement: flow techniques (transitions, variety) are functional, not fluff — they maintain attention
**llm** — optimize for precision and unambiguity. An LLM-targeted document may run longer where explicitness pays and shorter where warmth was cut:
- Dependency-first: define concepts before usage to minimize hallucination risk
- Cut emotional language, encouragement, and orientation sections
- Reference well-known standards ("conventional commits", "REST APIs") instead of re-teaching them; be explicit where a concept is not well-known — and either way, ground the expectation with an example
- Consistent terminology: same word for same concept throughout
- No hedging ("might", "could", "generally") — direct statements
- Prefer structured formats (tables, lists, YAML) over prose
- Unambiguous references: no unclear antecedents ("it", "this", "the above")
## Structure pass
You are a structural editor focused on high-value density. Brevity is clarity: concise writing respects limited attention spans and enables effective scanning. Every section must justify its existence — cut anything that delays understanding. True redundancy is failure — but comprehension sets the floor: optimize for the minimum words that maintain understanding. Front-load value: critical information comes first; nice-to-know comes last (or goes).
Load `references/structure-models.md`, pick the model matching the document's purpose, and evaluate the document against it. Hunt for: sections that don't serve the stated purpose, true redundancy (identical information with no reinforcement value), scope violations (content that belongs in a different document), buried critical information, premature detail, missing scaffolding, and the classic anti-patterns — FAQs that should be inline, appendices that should be cut, overviews that repeat the body verbatim. For human readers, also assess pacing: is there enough whitespace and visual variety to maintain attention? Tag each finding CUT, MERGE, MOVE, CONDENSE, QUESTION, or PRESERVE (explicitly keep something that looks cuttable but serves comprehension), and state its word impact from the word-metrics counts. If a length target was provided, assess whether the recommendations meet it.
## Prose pass
You are a clinical copy-editor: precise, professional, neither warm nor cynical. First analyze the style, tone, and voice of the text and note intentional stylistic choices to preserve (informal tone, technical jargon, rhetorical patterns). Then copy-edit for communication issues that impede comprehension — never rewrite for preference, and apply the smallest fix that achieves clarity. Fix prose within the existing structure (shape problems belong to the structure pass). Skip code blocks, frontmatter, and structural markup. Preserve the author's voice and the stylistic choices you noted. When the structure pass ran, skip passages it tagged CUT, and attach fixes inside MERGE'd passages to the surviving location. Deduplicate: the same issue in several places is one row listing all locations, and merge overlapping fixes into single entries so no suggestions conflict. Phrase uncertain fixes as "Consider: …?" rather than definitive changes.
## Output
One findings table serves both passes:
| Pass | Original Text | Revised Text | Changes |
|------|---------------|---------------|---------|
| structure | §Setup — full section (~180 words) | MERGE into §Installation | Duplicates the install steps; one source of truth (saves ~150 words) |
| prose | The system will processes data and it handles errors. | The system processes data and handles errors. | Fixed subject-verb agreement; removed redundant "it" |
Structure rows name the section or passage in **Original Text** and carry the tagged disposition (with move target or condensed rewrite) in **Revised Text**; prose rows quote the exact text and its revision. Order rows by comprehension impact; when a long document would produce more rows than an author can realistically act on, present the highest-impact rows and roll the rest into one closing line — "N further minor fixes; ask to expand." Above the table, give the purpose/audience read plus — when the structure pass ran — the chosen structure model. When the structure pass ran, close with a summary: total recommendations, estimated reduction (words and % of original, computed from the word-metrics counts) if all are accepted, whether a provided length target is met, and any comprehension trade-offs (cuts that sacrifice reader engagement for brevity). A pass that finds nothing is a valid result; say so.
Findings land in `{workflow.review_output_path}` when set (default: this table in chat), shaped by `{workflow.output_preferences}`. After the findings are delivered, execute `{workflow.on_complete}` if set.
src/core-skills/bmad-editorial-review/customize.toml
-68
View File
@@ -1,68 +0,0 @@
# DO NOT EDIT -- overwritten on every update.
#
# Workflow customization surface for bmad-editorial-review.
#
# Override files (not edited here):
# {project-root}/_bmad/custom/bmad-editorial-review.toml (team)
# {project-root}/_bmad/custom/bmad-editorial-review.user.toml (personal)
[workflow]
# --- Configurable below. Overrides merge per BMad structural rules: ---
# scalars: override wins • arrays: append
# Steps executed on activation: prepend runs before the skill's own
# activation flow, append runs after it. Each entry is a literal instruction.
activation_steps_prepend = []
activation_steps_append = []
# Standing context held for every review. Entries prefixed `file:` are paths
# or globs whose contents load as facts; all others are literal facts.
persistent_facts = ["file:{project-root}/**/project-context.md"]
# Executed after the findings are delivered. Freeform directive; empty = the
# review ends with the findings.
#
# Example:
# on_complete = "Append a one-line review summary to {project-root}/docs/review-log.md"
on_complete = ""
# Default reader the review calibrates for when the request doesn't say:
# "humans" clarity, flow, comprehension aids preserved
# "llm" precision, consistent terminology, no hedging
# A reader type stated in the request wins for that run.
reader_type = "humans"
# The baseline style guide for every review: the name of a guide the model
# knows well, a `file:`-prefixed path to a style guide document, or the rules
# inline as text. A style guide stated in the request wins for that run.
# Where the guide in effect conflicts with the skill's generic principles,
# the guide wins — except content is sacrosanct.
#
# Examples (set in team/user override TOML):
# style_guide = "file:{project-root}/_bmad/style-guides/company-voice.md"
# style_guide = "Sentence-case headings. No Oxford comma. Address the reader as 'you'."
style_guide = "Microsoft Writing Style Guide"
# Where the findings table lands. A path or path directive; empty = chat.
#
# Example:
# review_output_path = "Write the findings table to <target>-review.md beside the reviewed document."
review_output_path = ""
# How findings are presented — shaping, not destination. Freeform directive;
# empty = the default table ordering and long-tail rollup.
#
# Example:
# output_preferences = "Cap output at the 20 highest-impact findings."
output_preferences = ""
# Standing review directives applied on every run alongside the skill's own
# principles. Each entry is a literal sentence or a `file:`-prefixed path/glob
# whose contents load as directives.
#
# Examples:
# "Flag passive voice in headings."
# "Second-person imperative is the house voice; never suggest changing it."
# "file:{project-root}/docs/terminology.md"
review_guidance = []
src/core-skills/bmad-review/SKILL.md
+17 -11
View File
@@ -1,30 +1,36 @@
---
name: bmad-review
description: 'Multi-lens critical review — adversarial, edge-case, and verification-gap passes over any diff, doc, or artifact, run singly or together. Use when the user says "review this", "critical review", "hunt edge cases", or "check verification gaps".'
description: 'Multi-lens review over any diff, doc, spec, or artifact — whichever installed lenses fit the content, run singly or together. Shipped lenses include adversarial, edge-case, verification-gap, structure, and prose. Use when the user says "review this", "critical review", "editorial review", "hunt edge cases", "review the structure", or "review the prose".'
---
# BMad Review
Review content through independent lenses — each a distinct method and stance — and report findings in one canonical shape. Report what is real — never pad to look thorough. Each lens sets its own stance toward zero findings: for most an empty result is valid; the adversarial lens treats it as suspicious.
Review content through lenses — each a distinct method and stance — and report findings in one canonical shape. Report what is real — never pad to look thorough. Each lens sets its own stance toward the content and toward zero findings: for most an empty result is valid; the adversarial lens treats it as suspicious; the editorial lenses hold content sacrosanct and critique only how it is organized and expressed.
The lens set is whatever `{workflow.lenses}` resolves to, not a fixed list — overrides add lenses and replace shipped ones. Never claim a capability from this file; read the resolved lenses and work from those.
## Inputs
- **content** — what to review: a diff, branch, uncommitted changes, file, spec, story, or any document. Args: `[path]`.
- **lenses** (optional) — one or more lens codes or names. Default: every applicable lens (a full review).
- **lenses** (optional) — one or more lens codes or names, however the caller expresses them: a spoken request, or a directive of the form `skill:bmad-review lenses=<code>[,<code>...]` (the form bmm's `doc_standards` uses). Default: every applicable lens (a full review).
- **also_consider** (optional) — areas to keep in mind alongside each lens's normal analysis.
- **pre-resolved customization** (optional) — `[workflow]` field values supplied by a forwarding caller. See Execution step 1.
## Conventions
- Bare paths (e.g. `references/lens-edge-case-hunter.md`) resolve from `{skill-root}` — this skill's installed directory, where `customize.toml` lives. `{project-root}` resolves to the project working directory.
- `{workflow.<name>}` values come from the resolved customization.
- `{workflow.<name>}` resolves to fields in `customize.toml`'s `[workflow]` table (overrides win per BMad merge rules).
- In `style_guide`, `review_guidance`, and `persistent_facts`, a value prefixed `file:` is a path or glob — load that file's contents. If a `file:` value cannot be read, name the failed file in the output header and continue: the shipped baseline for `style_guide`, the remaining entries otherwise.
## Execution
1. **Resolve customization:** `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
2. **Load the content.** If it is empty or cannot be decoded as text: when the caller expects the raw findings JSON array (e.g. the legacy edge-case forwarder), return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` (no `lens` field) and stop; otherwise say what's wrong and ask for reviewable content. Identify the content type — diff, file, function, document — since scope rules and lens applicability depend on it.
3. **Select lenses** from `{workflow.lenses}`. A lens with an empty `instruction` is disabled. If the user or caller named lenses, run exactly those only. Otherwise run every enabled lens whose `when` applies.
4. **Run each selected lens independently** — each sees the content and `also_consider`, never another lens's findings. Follow each lens's `instruction`; the shipped lenses load their reference file just-in-time, so load only what runs. When subagents are available, spawn one per lens in parallel: give it the lens `instruction` with `{skill-root}` and paths resolved absolute, the content or where to read it, any `also_consider` areas, and the constraint "Return ONLY the findings JSON array — no other output." Otherwise run the lenses sequentially yourself, completing one before starting the next.
5. **Assemble and present** per Output below. Keep every lens's findings — overlap between lenses is signal, not duplication; note it in the markdown report rather than deduping.
1. **Resolve customization:** `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults. **Forwarded activation:** if a caller invoked you with pre-resolved customization fields (e.g. the `bmad-editorial-review` shim), honor them verbatim for those named fields — they already carry the user's overrides — and resolve only the remaining fields from your own `customize.toml`. Then execute each `{workflow.activation_steps_prepend}` entry in order, hold `{workflow.persistent_facts}` as standing context for the session, and treat `{workflow.review_guidance}` entries as standing review directives for every lens.
2. **Load the content.** If it is empty or cannot be decoded as text: when the caller expects the raw findings JSON array (e.g. the legacy edge-case forwarder), return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` (no `lens` field) and stop; otherwise say what's wrong and ask for reviewable content. Classify the content — diff, source file, function, or document — and whether it is **code** or **docs**; scope rules and lens applicability both depend on it. A document that defines behavior (spec, requirements, plan, story) is `docs` that a behavioral lens may still apply to; judge by `when`.
3. **Select lenses** from `{workflow.lenses}`. A lens with an empty `instruction` is disabled. If the user or caller named lenses, run exactly those only — `applies_to` and `when` do not filter an explicit request. Otherwise run every enabled lens whose `applies_to` covers the content class (`any` always covers) and whose `when` applies.
4. **Announce the plan** in one line before running anything: the content class, the lenses about to run, and — when any lens has `after` set — that it runs on top of the named lens's findings. Skip the announcement entirely when the caller pinned an exact output contract (the legacy forwarders that demand raw JSON or one exact line) — their contract covers everything you emit, not just the findings block. Then execute each `{workflow.activation_steps_append}` entry in order.
5. **Run the independent lenses** — every selected lens without `after`. Each sees the content and `also_consider`, never another lens's findings. Follow each lens's `instruction`; the shipped lenses load their reference file just-in-time, so load only what runs. When subagents are available, spawn one per lens in parallel: give it the lens `instruction` with `{skill-root}` and paths resolved absolute, the content or where to read it, any `also_consider` areas, the standing review directives, and the constraint "Return ONLY your findings — no other output." Otherwise run the lenses sequentially yourself, completing one before starting the next.
6. **Run the dependent lenses** — every selected lens with `after`, once the lens it names has completed, passing that lens's findings in. A lens whose `after` target was not selected or produced nothing still runs, with no prior findings. Dependent lenses that name different targets are independent of each other and may run in parallel.
7. **Assemble and present** per Output below. Keep every lens's findings — overlap between lenses is signal, not duplication; note it in the markdown report rather than deduping. Execute `{workflow.on_complete}` if set.
## Output
@@ -36,8 +42,8 @@ One JSON array holding every finding from every lens. Each finding carries:
- `guard_snippet` — the concrete fix, guard, or missing check
- `potential_consequence` — what goes wrong if it ships as-is
Each lens file refines these semantics for its findings and may add lens-specific fields (e.g. `kind`/`confidence` on deletion findings, `gap_shape`/`consumer`/`evidence` on verification-gap findings). `[]` is valid when nothing is found. No severity, priority, or ranking anywhere.
Each lens file refines these semantics for its findings and may add lens-specific fields (e.g. `kind`/`confidence` on deletion findings, `gap_shape`/`consumer`/`evidence` on verification-gap findings). A lens file may instead declare its own findings shape and rendering — the editorial lenses render a findings table — and that shape wins for that lens's findings. `[]` is valid when nothing is found. No severity, priority, or ranking anywhere.
Present per `{workflow.output_format}` — `"json"` (the raw array in a fenced json block), `"markdown"`, or `"both"` — unless the caller requested a specific shape; a legacy forwarder's output contract always wins. The markdown report groups findings by lens: a short block per finding rendering the fields plus any extras worth surfacing, one line for a lens that found nothing, and a plain clean statement when the whole review is clean.
Present per `{workflow.output_format}` — `"json"` (the raw array in a fenced json block), `"markdown"`, or `"both"` — unless the caller requested a specific shape; a legacy forwarder's output contract always wins, and governs everything you emit rather than the findings block alone. The markdown report groups findings by lens, each rendered in its declared shape: a short block per finding rendering the fields plus any extras worth surfacing, one line for a lens that found nothing, and a plain clean statement when the whole review is clean. Shape the report per `{workflow.output_preferences}`.
When `{workflow.report_path}` is set, write the report there; otherwise present it in chat.
src/core-skills/bmad-review/customize.toml
+93 -8
View File
@@ -10,22 +10,88 @@
# --- Configurable below. Overrides merge per BMad structural rules: ---
# scalars: override wins
# arrays (persistent_facts, activation_steps_*, review_guidance): append
# arrays of tables keyed by `code`: matching key replaces, new keys append
# Steps executed on activation: prepend runs before the skill's own
# activation flow, append runs after the lens plan is settled and before the
# lenses run. Each entry is a literal instruction.
activation_steps_prepend = []
activation_steps_append = []
# Standing context held for every review, code and document alike. Entries
# prefixed `file:` are paths or globs whose contents load as facts; all others
# are literal facts. The shipped entry is a project-wide glob — set it to []
# if you don't want every review scanning for it.
persistent_facts = ["file:{project-root}/**/project-context.md"]
# Standing review directives applied on every run alongside each lens's own
# method. Each entry is a literal sentence or a `file:`-prefixed path/glob
# whose contents load as directives.
#
# Examples:
# "Flag passive voice in headings."
# "Second-person imperative is the house voice; never suggest changing it."
# "file:{project-root}/docs/terminology.md"
review_guidance = []
# Executed after the findings are delivered. Freeform directive; empty = the
# review ends with the findings.
#
# Example:
# on_complete = "Append a one-line review summary to {project-root}/docs/review-log.md"
on_complete = ""
# How findings are presented when the caller doesn't say: "json" (the raw
# findings array only), "markdown" (the human report only), or "both".
# findings array only), "markdown" (the human report only), or "both". A lens
# that declares its own rendering keeps it for its own findings.
output_format = "both"
# Where to write the review report. Empty = present in chat only. Accepts
# {project-root}-prefixed paths.
report_path = ""
# How findings are presented — shaping, not destination. Freeform directive;
# empty = each lens's default ordering and rollup.
#
# Example:
# output_preferences = "Cap output at the 20 highest-impact findings."
output_preferences = ""
# --- Editorial lens settings (used by the structure and prose lenses) ---
# Default reader the editorial lenses calibrate for when the request doesn't
# say:
# "humans" clarity, flow, comprehension aids preserved
# "llm" precision, consistent terminology, no hedging
# A reader type stated in the request wins for that run.
reader_type = "humans"
# The baseline style guide for every editorial review: the name of a guide the
# model knows well, a `file:`-prefixed path to a style guide document, or the
# rules inline as text. A style guide stated in the request wins for that run.
# Where the guide in effect conflicts with the lens's generic principles, the
# guide wins — except content is sacrosanct.
#
# Examples (set in team/user override TOML):
# style_guide = "file:{project-root}/_bmad/style-guides/company-voice.md"
# style_guide = "Sentence-case headings. No Oxford comma. Address the reader as 'you'."
style_guide = "Microsoft Writing Style Guide"
# ---------------------------------------------------------------------------
# Review lenses. Each lens is an independent pass over the content with its
# own method and stance. `instruction` is the lens's whole execution recipe —
# the shipped lenses load a reference file from the skill root, but an
# override may inline any prompt. `when` (optional) gates whether the lens
# joins a default full review; an explicitly requested lens always runs.
# Review lenses. Each lens is a pass over the content with its own method and
# stance. `instruction` is the lens's whole execution recipe — the shipped
# lenses load a reference file from the skill root, but an override may inline
# any prompt.
#
# `applies_to` is the content this lens can review: "code", "docs", or "any".
# It is the first filter — a lens never joins a default review for content it
# does not apply to. `when` (optional) refines that judgement in prose. An
# explicitly requested lens always runs, whatever both say.
#
# `after` (optional) names a lens this one builds on: it runs once that lens
# has completed and receives its findings, instead of running independently.
#
# Empty `instruction` disables a lens. Keyed by `code`: an override with a
# matching code replaces the shipped lens, a new code appends.
#
@@ -33,6 +99,7 @@ report_path = ""
# [[workflow.lenses]]
# code = "accessibility"
# name = "Accessibility"
# applies_to = "any"
# when = "UI code or user-facing documents."
# instruction = "Review against WCAG 2.2 AA. Emit findings in the canonical fields."
# ---------------------------------------------------------------------------
@@ -40,17 +107,35 @@ report_path = ""
[[workflow.lenses]]
code = "adversarial"
name = "Adversarial"
applies_to = "any"
when = "always"
instruction = "Load `references/lens-adversarial.md` from the skill root and follow it."
[[workflow.lenses]]
code = "edge-case-hunter"
name = "Edge-Case Hunter"
when = "always"
applies_to = "any"
when = "Content with behavior to trace: code, diffs, and the specs, requirements, plans, and stories that define behavior. Skip for prose documents with no behavioral surface."
instruction = "Load `references/lens-edge-case-hunter.md` from the skill root and follow it."
[[workflow.lenses]]
code = "verification-gap"
name = "Verification Gap"
when = "Code changes reviewed inside a repo where tests can be searched and read. Skip for prose documents or content with no verification surface."
applies_to = "code"
when = "Reviewed inside a repo where tests can be searched and read."
instruction = "Load `references/lens-verification-gap.md` from the skill root and follow it."
[[workflow.lenses]]
code = "structure"
name = "Editorial Structure"
applies_to = "docs"
when = "Documents whose shape is the author's to change."
instruction = "Load `references/lens-structure.md` from the skill root and follow it."
[[workflow.lenses]]
code = "prose"
name = "Editorial Prose"
applies_to = "docs"
after = "structure"
when = "Documents being copy-edited."
instruction = "Load `references/lens-prose.md` from the skill root and follow it."
src/core-skills/bmad-review/references/editorial-common.md
+56
View File
@@ -0,0 +1,56 @@
# Editorial Lenses — Common Ground
Shared by the `structure` and `prose` lenses. Load this once; when both lenses run, the setup below is done once and serves both.
## Stance
Review a document as a clinical editor and return suggested fixes the author can accept or reject row by row. Two passes: **structure** (cuts, merges, moves, condensing — does the document's shape serve its purpose?) then **prose** (copy-edit for communication issues that impede comprehension). Which of the two run, and in what order, is decided by lens selection — see the skill's Execution section.
**Content is sacrosanct.** Never challenge ideas — only how they're organized and expressed. Propose, don't execute: the author decides what to accept.
The baseline style guide is `{workflow.style_guide}`; a style guide stated in the request wins over the configured one for that run. Where the style guide in effect conflicts with a generic principle here — including the reader calibration — the style guide wins. Nothing overrides content being sacrosanct.
## Setup
1. Gather inputs: the content (required — a path or pasted text), plus whatever the request states: purpose, target audience, length target, reader type, style guide. If no reviewable content was provided, say so and stop. Request-level values win; `{workflow.reader_type}` and `{workflow.style_guide}` fill what the request leaves unstated. Treat `{workflow.review_guidance}` entries as standing review directives.
2. When the content is a file, get exact word counts — document total and per heading section — via `uv run {skill-root}/scripts/word_metrics.py <path>` (`--help` documents the output), and ground every word-impact estimate and the reduction summary in those numbers. If the content was pasted or the script cannot run, estimate and mark the numbers as estimates.
3. Infer purpose and audience from the content and standing context when not provided, and open the output with your one-sentence read — "this document exists to help [audience] accomplish [goal]" — so the author can correct a wrong premise before acting on the findings.
## Reader calibration
Calibrate every finding to the reader type — stated in the request, else `{workflow.reader_type}`.
**humans** (default) — optimize for clarity, flow, and natural progression. These elements serve comprehension and engagement; preserve them unless clearly wasteful, and flag any recommendation that would cut one:
- Visual aids: diagrams, images, and flowcharts anchor understanding
- Expectation-setting: "What You'll Learn" helps readers confirm they're in the right place
- Reader's journey: organize content as a linear progression, not a database
- Mental models: overview before details prevents cognitive overload
- Warmth: encouraging tone reduces anxiety for new users
- Whitespace: admonitions and callouts provide visual breathing room
- Summaries: recaps help retention; they're reinforcement, not redundancy
- Examples: concrete illustrations make abstract concepts accessible
- Engagement: flow techniques (transitions, variety) are functional, not fluff — they maintain attention
**llm** — optimize for precision and unambiguity. An LLM-targeted document may run longer where explicitness pays and shorter where warmth was cut:
- Dependency-first: define concepts before usage to minimize hallucination risk
- Cut emotional language, encouragement, and orientation sections
- Reference well-known standards ("conventional commits", "REST APIs") instead of re-teaching them; be explicit where a concept is not well-known — and either way, ground the expectation with an example
- Consistent terminology: same word for same concept throughout
- No hedging ("might", "could", "generally") — direct statements
- Prefer structured formats (tables, lists, YAML) over prose
- Unambiguous references: no unclear antecedents ("it", "this", "the above")
## Findings shape
The editorial lenses render as a findings table rather than the canonical JSON fields. One findings table serves both passes:
| Pass | Original Text | Revised Text | Changes |
| --------- | ----------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------- |
| structure | §Setup — full section (~180 words) | MERGE into §Installation | Duplicates the install steps; one source of truth (saves ~150 words) |
| prose | The system will processes data and it handles errors. | The system processes data and handles errors. | Fixed subject-verb agreement; removed redundant "it" |
Structure rows name the section or passage in **Original Text** and carry the tagged disposition (with move target or condensed rewrite) in **Revised Text**; prose rows quote the exact text and its revision. Order rows by comprehension impact; when a long document would produce more rows than an author can realistically act on, present the highest-impact rows and roll the rest into one closing line — "N further minor fixes; ask to expand." Above the table, give the purpose/audience read plus — when the structure pass ran — the chosen structure model. When the structure pass ran, close with a summary: total recommendations, estimated reduction (words and % of original, computed from the word-metrics counts) if all are accepted, whether a provided length target is met, and any comprehension trade-offs (cuts that sacrifice reader engagement for brevity). A pass that finds nothing is a valid result; say so.
Shape the table per `{workflow.output_preferences}`.
src/core-skills/bmad-review/references/lens-prose.md
+7
View File
@@ -0,0 +1,7 @@
# Prose Lens
Load `references/editorial-common.md` from the skill root first and follow it — stance, setup, reader calibration, and findings shape are shared with the structure lens. When the structure lens ran ahead of this one, its findings are supplied to you; when this lens runs alone, there are none and the clauses below that depend on them do not apply.
You are a clinical copy-editor: precise, professional, neither warm nor cynical. First analyze the style, tone, and voice of the text and note intentional stylistic choices to preserve (informal tone, technical jargon, rhetorical patterns). Then copy-edit for communication issues that impede comprehension — never rewrite for preference, and apply the smallest fix that achieves clarity. Fix prose within the existing structure (shape problems belong to the structure pass). Skip code blocks, frontmatter, and structural markup. Preserve the author's voice and the stylistic choices you noted. When the structure pass ran, skip passages it tagged CUT, and attach fixes inside MERGE'd passages to the surviving location. Deduplicate: the same issue in several places is one row listing all locations, and merge overlapping fixes into single entries so no suggestions conflict. Phrase uncertain fixes as "Consider: …?" rather than definitive changes.
Emit rows with `Pass` = `prose`.
src/core-skills/bmad-review/references/lens-structure.md
+9
View File
@@ -0,0 +1,9 @@
# Structure Lens
Load `references/editorial-common.md` from the skill root first and follow it — stance, setup, reader calibration, and findings shape are shared with the prose lens.
You are a structural editor focused on high-value density. Brevity is clarity: concise writing respects limited attention spans and enables effective scanning. Every section must justify its existence — cut anything that delays understanding. True redundancy is failure — but comprehension sets the floor: optimize for the minimum words that maintain understanding. Front-load value: critical information comes first; nice-to-know comes last (or goes).
Load `references/structure-models.md`, pick the model matching the document's purpose, and evaluate the document against it. Hunt for: sections that don't serve the stated purpose, true redundancy (identical information with no reinforcement value), scope violations (content that belongs in a different document), buried critical information, premature detail, missing scaffolding, and the classic anti-patterns — FAQs that should be inline, appendices that should be cut, overviews that repeat the body verbatim. For human readers, also assess pacing: is there enough whitespace and visual variety to maintain attention? Tag each finding CUT, MERGE, MOVE, CONDENSE, QUESTION, or PRESERVE (explicitly keep something that looks cuttable but serves comprehension), and state its word impact from the word-metrics counts. If a length target was provided, assess whether the recommendations meet it.
Emit rows with `Pass` = `structure`.
src/core-skills/bmad-editorial-review/references/structure-models.md → src/core-skills/bmad-review/references/structure-models.md
View File
src/core-skills/bmad-editorial-review/scripts/tests/test_word_metrics.py → src/core-skills/bmad-review/scripts/tests/test_word_metrics.py
View File
src/core-skills/bmad-editorial-review/scripts/word_metrics.py → src/core-skills/bmad-review/scripts/word_metrics.py
View File
src/core-skills/module-help.csv
+1 -2
View File
@@ -5,6 +5,5 @@ Core,bmad-party-mode,Party Mode,PM,Orchestrate multi-agent discussions when you
Core,bmad-help,BMad Help,BH,,,,anytime,,,false,,
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
Core,bmad-advanced-elicitation,Advanced Elicitation,AE,"Use at any checkpoint to push a just-produced draft, section, or plan past its first version — pick from a menu of elicitation methods (pre-mortem, first principles, red team, socratic) and apply the improvements.",,,anytime,,,false,,
Core,bmad-editorial-review,Editorial Review,ED,"Two-pass editorial review — structure (cuts, merges, moves) then prose copy-edit. Runs both passes by default; ask for either alone. Use after drafting to tighten and polish any document.",,[path],anytime,,,false,,findings table with suggested fixes
Core,bmad-review,Review,RV,"Multi-lens critical review — adversarial, edge-case, and verification-gap lenses over any diff, doc, or artifact; run one lens, several, or all. Code Review in other modules runs the lenses automatically; also useful for document and spec reviews.",,[path],anytime,,,false,,findings JSON array + markdown report
Core,bmad-review,Review,RV,"Use to review anything before it ships — a diff, branch, or uncommitted changes; a PRD, spec, story, or architecture doc; any prose document. Runs whichever installed lenses fit the content and reports findings in one shape: shipped lenses cover adversarial critique, edge cases, verification gaps, document structure (cuts, merges, moves), and prose copy-edit, and installs may add more. Reach for it to tighten a bloated or LLM-slop draft, pressure-test a plan before building, or check a change is adequately tested. Run every applicable lens or name the ones you want. Code Review in other modules calls it automatically.",,[path],anytime,,,false,,findings JSON array + markdown report
Core,bmad-forge-idea,Forge Idea,FI,"Use to pressure-test and harden an idea — software, business, creative, research, or life — until it proves out, hardens into something buildable, or dies cheaply. Persona-driven interrogation; optional handoff to bmad-spec or bmad-quick-dev.",,,anytime,,,false,{output_folder}/forge,refined-idea brief (optional)
1 module skill display-name menu-code description action args phase preceded-by followed-by required output-location outputs
5 Core bmad-help BMad Help BH anytime false
6 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
7 Core bmad-advanced-elicitation Advanced Elicitation AE Use at any checkpoint to push a just-produced draft, section, or plan past its first version — pick from a menu of elicitation methods (pre-mortem, first principles, red team, socratic) and apply the improvements. anytime false
8 Core bmad-editorial-review bmad-review Editorial Review Review ED RV Two-pass editorial review — structure (cuts, merges, moves) then prose copy-edit. Runs both passes by default; ask for either alone. Use after drafting to tighten and polish any document. Use to review anything before it ships — a diff, branch, or uncommitted changes; a PRD, spec, story, or architecture doc; any prose document. Runs whichever installed lenses fit the content and reports findings in one shape: shipped lenses cover adversarial critique, edge cases, verification gaps, document structure (cuts, merges, moves), and prose copy-edit, and installs may add more. Reach for it to tighten a bloated or LLM-slop draft, pressure-test a plan before building, or check a change is adequately tested. Run every applicable lens or name the ones you want. Code Review in other modules calls it automatically. [path] anytime false findings table with suggested fixes findings JSON array + markdown report
Core bmad-review Review RV Multi-lens critical review — adversarial, edge-case, and verification-gap lenses over any diff, doc, or artifact; run one lens, several, or all. Code Review in other modules runs the lenses automatically; also useful for document and spec reviews. [path] anytime false findings JSON array + markdown report
9 Core bmad-forge-idea Forge Idea FI Use to pressure-test and harden an idea — software, business, creative, research, or life — until it proves out, hardens into something buildable, or dies cheaply. Persona-driven interrogation; optional handoff to bmad-spec or bmad-quick-dev. anytime false {output_folder}/forge refined-idea brief (optional)
src/core-skills/v6-shims/README.md
+25
View File
@@ -0,0 +1,25 @@
# v6 Deprecation Shims
Skills in this folder are forwarders kept for backward compatibility with v6 skill IDs.
Each one holds no logic of its own — it forwards to the skill that replaced it, pinning
the legacy output contract so existing callers keep working.
| Shim | Forwards to |
| --------------------------------- | ---------------------------------------- |
| `bmad-editorial-review` | `bmad-review` (structure + prose lenses) |
| `bmad-editorial-review-prose` | `bmad-review` (prose lens) |
| `bmad-editorial-review-structure` | `bmad-review` (structure lens) |
| `bmad-review-adversarial-general` | `bmad-review` (adversarial lens) |
| `bmad-review-edge-case-hunter` | `bmad-review` (edge-case lens) |
| `bmad-review-verification-gap` | `bmad-review` (verification-gap lens) |
`bmad-editorial-review` keeps its `customize.toml` so existing team and user
overrides still resolve; the shim forwards those resolved values to `bmad-review`.
External module repos (gds, loop, tea, bmb, os-utils) still invoke these IDs, so they
ship by default. Removal rides the v7 cut — never a 6.x minor.
The folder is grouping only: the installer discovers skills recursively and installs each
one under its own `name`, so nesting here does not change any installed path or skill ID.
A future install option will let users include or exclude this folder before it is removed
outright.
src/core-skills/v6-shims/bmad-editorial-review-prose/SKILL.md
+6
View File
@@ -0,0 +1,6 @@
---
name: bmad-editorial-review-prose
description: 'Deprecated — forwards to bmad-review.'
---
Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `prose` lens, passing through the same inputs and any `also_consider` areas. Present the findings in the legacy shape: a three-column markdown table `| Original Text | Revised Text | Changes |` — no Pass column, no preamble above the table. If no issues are found, output exactly: `No editorial issues identified`.
src/core-skills/v6-shims/bmad-editorial-review-structure/SKILL.md
+6
View File
@@ -0,0 +1,6 @@
---
name: bmad-editorial-review-structure
description: 'Deprecated — forwards to bmad-review.'
---
Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `structure` lens, passing through the same inputs and any `also_consider` areas. Present the findings in the legacy report shape: a `## Document Summary` block (purpose, audience, reader type, structure model, current length), a `## Recommendations` list of numbered `[CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE]` entries each with rationale and word impact, and a closing `## Summary` (total recommendations, estimated reduction) — not the findings table. If no structural issues are found, output exactly: `No substantive changes recommended`.
src/core-skills/v6-shims/bmad-editorial-review/SKILL.md
+6
View File
@@ -0,0 +1,6 @@
---
name: bmad-editorial-review
description: 'Deprecated — forwards to bmad-review.'
---
Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with the `structure` and `prose` lenses — both, structure first, so prose runs on top of the structure findings — unless the caller asked for a structure-only or prose-only review, in which case pass only that lens. Pass through any `also_consider` areas, and forward this skill's resolved `[workflow]` fields as pre-resolved values — but only those that resolved to something, since an empty value here means no legacy override exists and bmad-review's own default should stand: `reader_type`, `style_guide`, `review_guidance`, `output_preferences`, `persistent_facts`, `activation_steps_prepend`, `activation_steps_append`, `on_complete`, and `review_output_path` as the report path. Present the findings in the legacy shape: the two-pass findings table `| Pass | Original Text | Revised Text | Changes |` with the purpose/audience read above it and, when the structure pass ran, the reduction summary below it — and no other lens's output.
src/core-skills/v6-shims/bmad-editorial-review/customize.toml
+31
View File
@@ -0,0 +1,31 @@
# DO NOT EDIT -- overwritten on every update.
#
# Legacy override surface for bmad-editorial-review, which is deprecated and
# forwards to bmad-review's `structure` and `prose` lenses. These keys exist
# only so overrides written against the old skill keep resolving: the shim
# resolves them here and passes them to bmad-review as pre-resolved values,
# which bmad-review honors verbatim over its own.
#
# Every field is documented in bmad-review's customize.toml, which is where
# new customization belongs. Defaults are empty here so the shim contributes
# nothing of its own — an unset key falls through to bmad-review's default.
#
# Override files (not edited here):
# {project-root}/_bmad/custom/bmad-editorial-review.toml (team)
# {project-root}/_bmad/custom/bmad-editorial-review.user.toml (personal)
#
# Overrides merge per BMad structural rules: scalars win, arrays append.
[workflow]
activation_steps_prepend = []
activation_steps_append = []
persistent_facts = []
review_guidance = []
on_complete = ""
output_preferences = ""
reader_type = ""
style_guide = ""
# Where the findings table lands; forwarded as bmad-review's report path.
review_output_path = ""
src/core-skills/bmad-review-adversarial-general/SKILL.md → src/core-skills/v6-shims/bmad-review-adversarial-general/SKILL.md
View File
src/core-skills/bmad-review-edge-case-hunter/SKILL.md → src/core-skills/v6-shims/bmad-review-edge-case-hunter/SKILL.md
View File
src/core-skills/bmad-review-verification-gap/SKILL.md → src/core-skills/v6-shims/bmad-review-verification-gap/SKILL.md
View File