bmad-method 6.10.1-next.18 → 6.10.1-next.19

package/.claude-plugin/marketplace.json

@@ -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",

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.10.1-next.18",
+  "version": "6.10.1-next.19",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

package/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml

@@ -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

package/src/bmm-skills/2-plan-workflows/bmad-prd/customize.toml

@@ -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

package/src/bmm-skills/2-plan-workflows/bmad-ux/customize.toml

@@ -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

package/src/bmm-skills/3-solutioning/bmad-architecture/customize.toml

@@ -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

package/src/bmm-skills/v6-shims/README.md

@@ -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.

package/src/core-skills/bmad-review/SKILL.md

@@ -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.

package/src/core-skills/bmad-review/customize.toml

@@ -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."

package/src/core-skills/bmad-review/references/editorial-common.md

@@ -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}`.

package/src/core-skills/bmad-review/references/lens-prose.md

@@ -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`.

package/src/core-skills/bmad-review/references/lens-structure.md

@@ -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`.

package/src/core-skills/module-help.csv

@@ -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)

package/src/core-skills/v6-shims/README.md

@@ -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.

package/src/core-skills/v6-shims/bmad-editorial-review/SKILL.md

@@ -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.

package/src/core-skills/v6-shims/bmad-editorial-review/customize.toml

@@ -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 = ""

package/src/core-skills/v6-shims/bmad-editorial-review-prose/SKILL.md

@@ -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`.

package/src/core-skills/v6-shims/bmad-editorial-review-structure/SKILL.md

@@ -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`.

package/src/core-skills/bmad-editorial-review/SKILL.md

@@ -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.

package/src/core-skills/bmad-editorial-review/customize.toml

@@ -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 = []

package/src/core-skills/bmad-editorial-review-prose/SKILL.md

@@ -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`.

package/src/core-skills/bmad-editorial-review-structure/SKILL.md

@@ -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`.