Merge branch 'main' into feat/editorial-review-task

Prose task was using 'target_audience' for the humans/llm optimization
flag while structure task correctly separates 'target_audience' (who
reads) from 'reader_type' (optimization mode). Aligns to reader_type.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

package-lock.json

@@ -47,7 +47,7 @@
         "jest": "^30.0.4",
         "lint-staged": "^16.1.1",
         "markdownlint-cli2": "^0.19.1",
-        "prettier": "^3.5.3",
+        "prettier": "^3.7.4",
         "prettier-plugin-packagejson": "^2.5.19",
         "sharp": "^0.33.5",
         "yaml-eslint-parser": "^1.2.3",
@@ -244,6 +244,7 @@
       "integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.27.1",
         "@babel/generator": "^7.28.5",
@@ -3642,6 +3643,7 @@
       "integrity": "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA==",
       "devOptional": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~7.16.0"
       }
@@ -3981,6 +3983,7 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -4287,6 +4290,7 @@
       "integrity": "sha512-6mF/YrvwwRxLTu+aMEa5pwzKUNl5ZetWbTyZCs9Um0F12HUmxUiF5UHiZPy4rifzU3gtpM3xP2DfdmkNX9eZRg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@astrojs/compiler": "^2.13.0",
         "@astrojs/internal-helpers": "0.7.5",
@@ -5354,6 +5358,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.9.0",
         "caniuse-lite": "^1.0.30001759",
@@ -6684,6 +6689,7 @@
       "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.1",
@@ -10298,6 +10304,7 @@
       "integrity": "sha512-p3JTemJJbkiMjXEMiFwgm0v6ym5g8K+b2oDny+6xdl300tUKySxvilJQLSea48C6OaYNmO30kH9KxpiAg5bWJw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "globby": "15.0.0",
         "js-yaml": "4.1.1",
@@ -12371,6 +12378,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.11",
         "picocolors": "^1.1.1",
@@ -12436,6 +12444,7 @@
       "integrity": "sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "prettier": "bin/prettier.cjs"
       },
@@ -13264,6 +13273,7 @@
       "integrity": "sha512-3nk8Y3a9Ea8szgKhinMlGMhGMw89mqule3KWczxhIzqudyHdCIOHw8WJlj/r329fACjKLEh13ZSk7oE22kyeIw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@types/estree": "1.0.8"
       },
@@ -14827,6 +14837,7 @@
       "integrity": "sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "esbuild": "^0.25.0",
         "fdir": "^6.4.4",
@@ -15100,6 +15111,7 @@
       "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz",
       "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==",
       "license": "ISC",
+      "peer": true,
       "bin": {
         "yaml": "bin.mjs"
       },
@@ -15291,6 +15303,7 @@
       "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }

package.json

@@ -101,7 +101,7 @@
     "jest": "^30.0.4",
     "lint-staged": "^16.1.1",
     "markdownlint-cli2": "^0.19.1",
-    "prettier": "^3.5.3",
+    "prettier": "^3.7.4",
     "prettier-plugin-packagejson": "^2.5.19",
     "sharp": "^0.33.5",
     "yaml-eslint-parser": "^1.2.3",

src/core/tasks/editorial-review-prose.xml

@@ -1,5 +1,5 @@
-<task id="_bmad/core/tasks/editorial-review.xml"
+<task id="_bmad/core/tasks/editorial-review-prose.xml"
-  name="Editorial Review"
+  name="Editorial Review - Prose"
   description="Clinical copy-editor that reviews text for communication issues"
   standalone="false">
 
@@ -7,7 +7,7 @@
 
   <inputs>
     <input name="content" required="true" desc="Cohesive unit of text to review (markdown, plain text, or text-heavy XML)" />
-    <input name="target_audience" required="false" default="humans" desc="Target audience: 'humans' (default) for standard editorial, 'llm' for precision focus" />
+    <input name="reader_type" required="false" default="humans" desc="'humans' (default) for standard editorial, 'llm' for precision focus" />
   </inputs>
 
   <llm critical="true">
@@ -21,6 +21,8 @@
     <i>Focus on communication issues that impede comprehension - not style preferences</i>
     <i>NEVER rewrite for preference - only fix genuine issues</i>
 
+    <i critical="true">CONTENT IS SACROSANCT: Never challenge ideas—only clarify how they're expressed.</i>
+
     <principles>
       <i>Minimal intervention: Apply the smallest fix that achieves clarity</i>
       <i>Preserve structure: Fix prose within existing structure, never restructure</i>
@@ -37,8 +39,8 @@
     <step n="1" title="Validate Input">
       <action>Check if content is empty or contains fewer than 3 words</action>
       <action if="empty or fewer than 3 words">HALT with error: "Content too short for editorial review (minimum 3 words required)"</action>
-      <action>Validate target_audience is "humans" or "llm" (or not provided, defaulting to "humans")</action>
+      <action>Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")</action>
-      <action if="target_audience is invalid">HALT with error: "Invalid target_audience. Must be 'humans' or 'llm'"</action>
+      <action if="reader_type is invalid">HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"</action>
       <action>Identify content type (markdown, plain text, XML with text)</action>
       <action>Note any code blocks, frontmatter, or structural markup to skip</action>
     </step>
@@ -46,9 +48,9 @@
     <step n="2" title="Analyze Style">
       <action>Analyze the style, tone, and voice of the input text</action>
       <action>Note any intentional stylistic choices to preserve (informal tone, technical jargon, rhetorical patterns)</action>
-      <action>Calibrate review approach based on target_audience parameter</action>
+      <action>Calibrate review approach based on reader_type parameter</action>
-      <action if="target_audience='llm'">Prioritize: unambiguous references, consistent terminology, explicit structure, no hedging</action>
+      <action if="reader_type='llm'">Prioritize: unambiguous references, consistent terminology, explicit structure, no hedging</action>
-      <action if="target_audience='humans'">Prioritize: clarity, flow, readability, natural progression</action>
+      <action if="reader_type='humans'">Prioritize: clarity, flow, readability, natural progression</action>
     </step>
 
     <step n="3" title="Editorial Review" critical="true">
@@ -82,7 +84,7 @@
 
   <halt-conditions>
     <condition>HALT with error if content is empty or fewer than 3 words</condition>
-    <condition>HALT with error if target_audience is not "humans" or "llm"</condition>
+    <condition>HALT with error if reader_type is not "humans" or "llm"</condition>
     <condition>If no issues found after thorough review, output "No editorial issues identified" (this is valid completion, not an error)</condition>
   </halt-conditions>
 

src/core/tasks/editorial-review-structure.xml

@@ -0,0 +1,198 @@
+<?xml version="1.0"?>
+<!-- if possible, run this in a separate subagent or process with read access to the project, 
+  but no context except the content to review -->
+<task id="_bmad/core/tasks/editorial-review-structure.xml"
+  name="Editorial Review - Structure"
+  description="Structural editor that proposes cuts, reorganization,
+    and simplification while preserving comprehension"
+  standalone="false">
+  <objective>Review document structure and propose substantive changes
+    to improve clarity and flow-run this BEFORE copy editing</objective>
+  <inputs>
+    <input name="content" required="true"
+      desc="Document to review (markdown, plain text, or structured content)"/>
+    <input name="purpose" required="false"
+      desc="Document's intended purpose (e.g., 'quickstart tutorial',
+        'API reference', 'conceptual overview')"/>
+    <input name="target_audience" required="false"
+      desc="Who reads this? (e.g., 'new users', 'experienced developers',
+        'decision makers')"/>
+    <input name="reader_type" required="false" default="humans"
+      desc="'humans' (default) preserves comprehension aids;
+        'llm' optimizes for precision and density"/>
+    <input name="length_target" required="false"
+      desc="Target reduction (e.g., '30% shorter', 'half the length',
+        'no limit')"/>
+  </inputs>
+  <llm critical="true">
+    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>DO NOT skip steps or change the sequence</i>
+    <i>HALT immediately when halt-conditions are met</i>
+    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
+    <i>You are a structural editor focused on HIGH-VALUE DENSITY</i>
+    <i>Brevity IS clarity: Concise writing respects limited attention spans and enables effective scanning</i>
+    <i>Every section must justify its existence-cut anything that delays understanding</i>
+    <i>True redundancy is failure</i>
+    <principles>
+      <i>Comprehension through calibration: Optimize for the minimum words needed to maintain understanding</i>
+      <i>Front-load value: Critical information comes first; nice-to-know comes last (or goes)</i>
+      <i>One source of truth: If information appears identically twice, consolidate</i>
+      <i>Scope discipline: Content that belongs in a different document should be cut or linked</i>
+      <i>Propose, don't execute: Output recommendations-user decides what to accept</i>
+      <i critical="true">CONTENT IS SACROSANCT: Never challenge ideas—only optimize how they're organized.</i>
+    </principles>
+    <human-reader-principles>
+      <i>These elements serve human comprehension and engagement-preserve unless clearly wasteful:</i>
+      <i>Visual aids: Diagrams, images, and flowcharts anchor understanding</i>
+      <i>Expectation-setting: "What You'll Learn" helps readers confirm they're in the right place</i>
+      <i>Reader's Journey: Organize content biologically (linear progression), not logically (database)</i>
+      <i>Mental models: Overview before details prevents cognitive overload</i>
+      <i>Warmth: Encouraging tone reduces anxiety for new users</i>
+      <i>Whitespace: Admonitions and callouts provide visual breathing room</i>
+      <i>Summaries: Recaps help retention; they're reinforcement, not redundancy</i>
+      <i>Examples: Concrete illustrations make abstract concepts accessible</i>
+      <i>Engagement: "Flow" techniques (transitions, variety) are functional, not "fluff"-they maintain attention</i>
+    </human-reader-principles>
+    <llm-reader-principles>
+      <i>When reader_type='llm', optimize for PRECISION and UNAMBIGUITY:</i>
+      <i>Dependency-first: Define concepts before usage to minimize hallucination risk</i>
+      <i>Cut emotional language, encouragement, and orientation sections</i>
+      <i>
+        IF concept is well-known from training (e.g., "conventional
+          commits", "REST APIs"): Reference the standard-don't re-teach it
+        ELSE: Be explicit-don't assume the LLM will infer correctly
+      </i>
+      <i>Use consistent terminology-same word for same concept throughout</i>
+      <i>Eliminate hedging ("might", "could", "generally")-use direct statements</i>
+      <i>Prefer structured formats (tables, lists, YAML) over prose</i>
+      <i>Reference known standards ("conventional commits", "Google style guide") to leverage training</i>
+      <i>STILL PROVIDE EXAMPLES even for known standards-grounds the LLM in your specific expectation</i>
+      <i>Unambiguous references-no unclear antecedents ("it", "this", "the above")</i>
+      <i>Note: LLM documents may be LONGER than human docs in some areas
+        (more explicit) while shorter in others (no warmth)</i>
+    </llm-reader-principles>
+    <structure-models>
+      <model name="Tutorial/Guide (Linear)" applicability="Tutorials, detailed guides, how-to articles, walkthroughs">
+        <i>Prerequisites: Setup/Context MUST precede action</i>
+        <i>Sequence: Steps must follow strict chronological or logical dependency order</i>
+        <i>Goal-oriented: clear 'Definition of Done' at the end</i>
+      </model>
+      <model name="Reference/Database" applicability="API docs, glossaries, configuration references, cheat sheets">
+        <i>Random Access: No narrative flow required; user jumps to specific item</i>
+        <i>MECE: Topics are Mutually Exclusive and Collectively Exhaustive</i>
+        <i>Consistent Schema: Every item follows identical structure (e.g., Signature to Params to Returns)</i>
+      </model>
+      <model name="Explanation (Conceptual)"
+        applicability="Deep dives, architecture overviews, conceptual guides,
+          whitepapers, project context">
+        <i>Abstract to Concrete: Definition to Context to Implementation/Example</i>
+        <i>Scaffolding: Complex ideas built on established foundations</i>
+      </model>
+      <model name="Prompt/Task Definition (Functional)"
+        applicability="BMAD tasks, prompts, system instructions, XML definitions">
+        <i>Meta-first: Inputs, usage constraints, and context defined before instructions</i>
+        <i>Separation of Concerns: Instructions (logic) separate from Data (content)</i>
+        <i>Step-by-step: Execution flow must be explicit and ordered</i>
+      </model>
+      <model name="Strategic/Context (Pyramid)" applicability="PRDs, research reports, proposals, decision records">
+        <i>Top-down: Conclusion/Status/Recommendation starts the document</i>
+        <i>Grouping: Supporting context grouped logically below the headline</i>
+        <i>Ordering: Most critical information first</i>
+        <i>MECE: Arguments/Groups are Mutually Exclusive and Collectively Exhaustive</i>
+        <i>Evidence: Data supports arguments, never leads</i>
+      </model>
+    </structure-models>
+  </llm>
+  <flow>
+    <step n="1" title="Validate Input">
+      <action>Check if content is empty or contains fewer than 3 words</action>
+      <action if="empty or fewer than 3 words">HALT with error: "Content
+        too short for substantive review (minimum 3 words required)"</action>
+      <action>Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")</action>
+      <action if="reader_type is invalid">HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"</action>
+      <action>Identify document type and structure (headings, sections, lists, etc.)</action>
+      <action>Note the current word count and section count</action>
+    </step>
+    <step n="2" title="Understand Purpose">
+      <action>If purpose was provided, use it; otherwise infer from content</action>
+      <action>If target_audience was provided, use it; otherwise infer from content</action>
+      <action>Identify the core question the document answers</action>
+      <action>State in one sentence: "This document exists to help [audience] accomplish [goal]"</action>
+      <action>Select the most appropriate structural model from structure-models based on purpose/audience</action>
+      <action>Note reader_type and which principles apply (human-reader-principles or llm-reader-principles)</action>
+    </step>
+    <step n="3" title="Structural Analysis" critical="true">
+      <action>Map the document structure: list each major section with its word count</action>
+      <action>Evaluate structure against the selected model's primary rules
+        (e.g., 'Does recommendation come first?' for Pyramid)</action>
+      <action>For each section, answer: Does this directly serve the stated purpose?</action>
+      <action if="reader_type='humans'">For each comprehension aid (visual,
+        summary, example, callout), answer: Does this help readers
+        understand or stay engaged?</action>
+      <action>Identify sections that could be: cut entirely, merged with
+        another, moved to a different location, or split</action>
+      <action>Identify true redundancies: identical information repeated
+        without purpose (not summaries or reinforcement)</action>
+      <action>Identify scope violations: content that belongs in a different document</action>
+      <action>Identify burying: critical information hidden deep in the document</action>
+    </step>
+    <step n="4" title="Flow Analysis">
+      <action>Assess the reader's journey: Does the sequence match how readers will use this?</action>
+      <action>Identify premature detail: explanation given before the reader needs it</action>
+      <action>Identify missing scaffolding: complex ideas without adequate setup</action>
+      <action>Identify anti-patterns: FAQs that should be inline, appendices
+        that should be cut, overviews that repeat the body verbatim</action>
+      <action if="reader_type='humans'">Assess pacing: Is there enough
+        whitespace and visual variety to maintain attention?</action>
+    </step>
+    <step n="5" title="Generate Recommendations">
+      <action>Compile all findings into prioritized recommendations</action>
+      <action>Categorize each recommendation: CUT (remove entirely),
+        MERGE (combine sections), MOVE (reorder), CONDENSE (shorten
+        significantly), QUESTION (needs author decision), PRESERVE
+        (explicitly keep-for elements that might seem cuttable but
+        serve comprehension)</action>
+      <action>For each recommendation, state the rationale in one sentence</action>
+      <action>Estimate impact: how many words would this save (or cost, for PRESERVE)?</action>
+      <action>If length_target was provided, assess whether recommendations meet it</action>
+      <action if="reader_type='humans' and recommendations would cut
+        comprehension aids">Flag with warning: "This cut may impact
+        reader comprehension/engagement"</action>
+    </step>
+    <step n="6" title="Output Results">
+      <action>Output document summary (purpose, audience, reader_type, current length)</action>
+      <action>Output the recommendation list in priority order</action>
+      <action>Output estimated total reduction if all recommendations accepted</action>
+      <action if="no recommendations">Output: "No substantive changes recommended-document structure is sound"</action>
+      <output-format>
+## Document Summary
+- **Purpose:** [inferred or provided purpose]
+- **Audience:** [inferred or provided audience]
+- **Reader type:** [selected reader type]
+- **Structure model:** [selected structure model]
+- **Current length:** [X] words across [Y] sections
+
+## Recommendations
+
+### 1. [CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE] - [Section or element name]
+**Rationale:** [One sentence explanation]
+**Impact:** ~[X] words
+**Comprehension note:** [If applicable, note impact on reader understanding]
+
+### 2. ...
+
+## Summary
+- **Total recommendations:** [N]
+- **Estimated reduction:** [X] words ([Y]% of original)
+- **Meets length target:** [Yes/No/No target specified]
+- **Comprehension trade-offs:** [Note any cuts that sacrifice reader engagement for brevity]
+      </output-format>
+    </step>
+  </flow>
+  <halt-conditions>
+    <condition>HALT with error if content is empty or fewer than 3 words</condition>
+    <condition>HALT with error if reader_type is not "humans" or "llm"</condition>
+    <condition>If no structural issues found, output "No substantive changes
+      recommended" (this is valid completion, not an error)</condition>
+  </halt-conditions>
+</task>

src/modules/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md

@@ -39,9 +39,27 @@ wipFile: '{implementation_artifacts}/tech-spec-wip.md'
 
 - {task_count} tasks to implement
 - {ac_count} acceptance criteria to verify
-- {files_count} files to modify
+- {files_count} files to modify"
 
-Does this capture your intent? Any changes needed?"
+**Present review menu:**
+
+```
+[y] Approve - finalize the spec
+[c] Changes - request modifications
+[q] Questions - ask about any section
+[a] Advanced Elicitation - dig deeper before approving
+[p] Party Mode - get expert feedback before approving
+```
+
+**HALT and wait for user selection.**
+
+#### Menu Handling:
+
+- **[y]**: Proceed to Section 3 (Finalize the Spec)
+- **[c]**: Proceed to Section 2 (Handle Review Feedback), then return here and redisplay menu
+- **[q]**: Answer questions, then redisplay this menu
+- **[a]**: Load and execute `{advanced_elicitation}`, then return here and redisplay menu
+- **[p]**: Load and execute `{party_mode_exec}`, then return here and redisplay menu
 
 ### 2. Handle Review Feedback