Merge branch 'main' into docs/zh-cn-quick-dev-new-preview

fix: replace broken party-mode workflow refs with skill syntax

docs/how-to/get-answers-about-bmad.md

@@ -42,8 +42,6 @@ BMad-Help responds with:
 - What the first required task is
 - What the rest of the process looks like
 
----
-
 ## When to Use This Guide
 
 Use this section when:

docs/how-to/project-context.md

@@ -5,7 +5,7 @@ sidebar:
   order: 7
 ---
 
-Use the `project-context.md` file to ensure AI agents follow your project's technical preferences and implementation rules throughout all workflows.
+Use the `project-context.md` file to ensure AI agents follow your project's technical preferences and implementation rules throughout all workflows. To make sure this is always available, you can also add the line `Important project context and conventions are located in [path to project context]/project-context.md` to your tools context or always rules file (such as `AGENTS.md`)
 
 :::note[Prerequisites]
 - BMad Method installed
@@ -114,20 +114,11 @@ A `project-context.md` file that:
 
 ## Tips
 
-:::tip[Focus on the Unobvious]
+:::tip[Best Practices]
-Document patterns agents might miss such as "Use JSDoc style comments on every public class, function and variable", not universal practices like "use meaningful variable names" which LLMs know at this point.
+- **Focus on the unobvious** — Document patterns agents might miss (e.g., "Use JSDoc on every public class"), not universal practices like "use meaningful variable names."
-:::
+- **Keep it lean** — This file is loaded by every implementation workflow. Long files waste context. Exclude content that only applies to narrow scope or specific stories.
-
+- **Update as needed** — Edit manually when patterns change, or re-generate after significant architecture changes.
-:::tip[Keep It Lean]
+- Works for Quick Flow and full BMad Method projects alike.
-This file is loaded by every implementation workflow. Long files waste context. Do not include content that only applies to narrow scope or specific stories or features.
-:::
-
-:::tip[Update as Needed]
-Edit manually when patterns change, or re-generate after significant architecture changes.
-:::
-
-:::tip[Works for All Project Types]
-Just as useful for Quick Flow as for full BMad Method projects.
 :::
 
 ## Next Steps

docs/reference/commands.md

@@ -105,32 +105,21 @@ See [Workflow Map](./workflow-map.md) for the complete workflow reference organi
 
 Tasks and tools are standalone operations that do not require an agent or workflow context.
 
-#### BMad-Help: Your Intelligent Guide
+**BMad-Help: Your Intelligent Guide**
 
-**`bmad-help`** is your primary interface for discovering what to do next. It's not just a lookup tool — it's an intelligent assistant that:
+`bmad-help` is your primary interface for discovering what to do next. It inspects your project, understands natural language queries, and recommends the next required or optional step based on your installed modules.
-
-- **Inspects your project** to see what's already been done
-- **Understands natural language queries** — ask questions in plain English
-- **Varies by installed modules** — shows options based on what you have
-- **Auto-invokes after workflows** — every workflow ends with clear next steps
-- **Recommends the first required task** — no guessing where to start
-
-**Examples:**
 
+:::note[Example]
 ```
 bmad-help
 bmad-help I have a SaaS idea and know all the features. Where do I start?
 bmad-help What are my options for UX design?
-bmad-help I'm stuck on the PRD workflow
 ```
+:::
 
-#### Other Tasks and Tools
+**Other Core Tasks and Tools**
 
-| Example skill | Purpose |
+The core module includes 11 built-in tools — reviews, compression, brainstorming, document management, and more. See [Core Tools](./core-tools.md) for the complete reference.
-| --- | --- |
-| `bmad-shard-doc` | Split a large markdown file into smaller sections |
-| `bmad-index-docs` | Index project documentation |
-| `bmad-editorial-review-prose` | Review document prose quality |
 
 ## Naming Convention
 

docs/reference/core-tools.md

@@ -0,0 +1,293 @@
+---
+title: Core Tools
+description: Reference for all built-in tasks and workflows available in every BMad installation without additional modules.
+sidebar:
+  order: 2
+---
+
+Every BMad installation includes a set of core skills that can be used in conjunction with any anything you are doing — standalone tasks and workflows that work across all projects, all modules, and all phases. These are always available regardless of which optional modules you install.
+
+:::tip[Quick Path]
+Run any core tool by typing its skill name (e.g., `bmad-help`) in your IDE. No agent session required.
+:::
+
+## Overview
+
+| Tool | Type | Purpose |
+| --- | --- | --- |
+| [`bmad-help`](#bmad-help) | Task | Get context-aware guidance on what to do next |
+| [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Facilitate interactive brainstorming sessions |
+| [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrate multi-agent group discussions |
+| [`bmad-distillator`](#bmad-distillator) | Task | Lossless LLM-optimized compression of documents |
+| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | Push LLM output through iterative refinement methods |
+| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | Cynical review that finds what's missing and what's wrong |
+| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | Exhaustive branching-path analysis for unhandled edge cases |
+| [`bmad-editorial-review-prose`](#bmad-editorial-review-prose) | Task | Clinical copy-editing for communication clarity |
+| [`bmad-editorial-review-structure`](#bmad-editorial-review-structure) | Task | Structural editing — cuts, merges, and reorganization |
+| [`bmad-shard-doc`](#bmad-shard-doc) | Task | Split large markdown files into organized sections |
+| [`bmad-index-docs`](#bmad-index-docs) | Task | Generate or update an index of all docs in a folder |
+
+## bmad-help
+
+**Your intelligent guide to what comes next.** — Inspects your project state, detects what's been done, and recommends the next required or optional step.
+
+**Use it when:**
+
+- You finished a workflow and want to know what's next
+- You're new to BMad and need orientation
+- You're stuck and want context-aware advice
+- You installed new modules and want to see what's available
+
+**How it works:**
+
+1. Scans your project for existing artifacts (PRD, architecture, stories, etc.)
+2. Detects which modules are installed and their available workflows
+3. Recommends next steps in priority order — required steps first, then optional
+4. Presents each recommendation with the skill command and a brief description
+
+**Input:** Optional query in natural language (e.g., `bmad-help I have a SaaS idea, where do I start?`)
+
+**Output:** Prioritized list of recommended next steps with skill commands
+
+## bmad-brainstorming
+
+**Generate diverse ideas through interactive creative techniques.** — A facilitated brainstorming session that loads proven ideation methods from a technique library and guides you toward 100+ ideas before organizing.
+
+**Use it when:**
+
+- You're starting a new project and need to explore the problem space
+- You're stuck generating ideas and need structured creativity
+- You want to use proven ideation frameworks (SCAMPER, reverse brainstorming, etc.)
+
+**How it works:**
+
+1. Sets up a brainstorming session with your topic
+2. Loads creative techniques from a method library
+3. Guides you through technique after technique, generating ideas
+4. Applies anti-bias protocol — shifts creative domain every 10 ideas to prevent clustering
+5. Produces an append-only session document with all ideas organized by technique
+
+**Input:** Brainstorming topic or problem statement, optional context file
+
+**Output:** `brainstorming-session-{date}.md` with all generated ideas
+
+:::note[Quantity Target]
+The magic happens in ideas 50–100. The workflow encourages generating 100+ ideas before organization.
+:::
+
+## bmad-party-mode
+
+**Orchestrate multi-agent group discussions.** — Loads all installed BMad agents and facilitates a natural conversation where each agent contributes from their unique expertise and personality.
+
+**Use it when:**
+
+- You need multiple expert perspectives on a decision
+- You want agents to challenge each other's assumptions
+- You're exploring a complex topic that spans multiple domains
+
+**How it works:**
+
+1. Loads the agent manifest with all installed agent personalities
+2. Analyzes your topic to select 2–3 most relevant agents
+3. Agents take turns contributing, with natural cross-talk and disagreements
+4. Rotates agent participation to ensure diverse perspectives over time
+5. Exit with `goodbye`, `end party`, or `quit`
+
+**Input:** Discussion topic or question, along with specification of personas you would like to participate (optional)
+
+**Output:** Real-time multi-agent conversation with maintained agent personalities
+
+## bmad-distillator
+
+**Lossless LLM-optimized compression of source documents.** — Produces dense, token-efficient distillates that preserve all information for downstream LLM consumption. Verifiable through round-trip reconstruction.
+
+**Use it when:**
+
+- A document is too large for an LLM's context window
+- You need token-efficient versions of research, specs, or planning artifacts
+- You want to verify no information is lost during compression
+- Agents will need to frequently reference and find information in it
+
+**How it works:**
+
+1. **Analyze** — Reads source documents, identifies information density and structure
+2. **Compress** — Converts prose to dense bullet-point format, strips decorative formatting
+3. **Verify** — Checks completeness to ensure all original information is preserved
+4. **Validate** (optional) — Round-trip reconstruction test proves lossless compression
+
+**Input:**
+
+- `source_documents` (required) — File paths, folder paths, or glob patterns
+- `downstream_consumer` (optional) — What consumes this (e.g., "PRD creation")
+- `token_budget` (optional) — Approximate target size
+- `--validate` (flag) — Run round-trip reconstruction test
+
+**Output:** Distillate markdown file(s) with compression ratio report (e.g., "3.2:1")
+
+## bmad-advanced-elicitation
+
+**Push LLM output through iterative refinement methods.** — Selects from a library of elicitation techniques to systematically improve content through multiple passes.
+
+**Use it when:**
+
+- LLM output feels shallow or generic
+- You want to explore a topic from multiple analytical angles
+- You're refining a critical document and want deeper thinking
+
+**How it works:**
+
+1. Loads method registry with 5+ elicitation techniques
+2. Selects 5 best-fit methods based on content type and complexity
+3. Presents an interactive menu — pick a method, reshuffle, or list all
+4. Applies the selected method to enhance the content
+5. Re-presents options for iterative improvement until you select "Proceed"
+
+**Input:** Content section to enhance
+
+**Output:** Enhanced version of the content with improvements applied
+
+## bmad-review-adversarial-general
+
+**Cynical review that assumes problems exist and searches for them.** — Takes a skeptical, jaded reviewer perspective with zero patience for sloppy work. Looks for what's missing, not just what's wrong.
+
+**Use it when:**
+
+- You need quality assurance before finalizing a deliverable
+- You want to stress-test a spec, story, or document
+- You want to find gaps in coverage that optimistic reviews miss
+
+**How it works:**
+
+1. Reads the content with a cynical, critical perspective
+2. Identifies issues across completeness, correctness, and quality
+3. Searches specifically for what's missing — not just what's present and wrong
+4. Must find a minimum of 10 issues or re-analyzes deeper
+
+**Input:**
+
+- `content` (required) — Diff, spec, story, doc, or any artifact
+- `also_consider` (optional) — Additional areas to keep in mind
+
+**Output:** Markdown list of 10+ findings with descriptions
+
+## bmad-review-edge-case-hunter
+
+**Walk every branching path and boundary condition, report only unhandled cases.** — Pure path-tracing methodology that mechanically derives edge classes. Orthogonal to adversarial review — method-driven, not attitude-driven.
+
+**Use it when:**
+
+- You want exhaustive edge case coverage for code or logic
+- You need a complement to adversarial review (different methodology, different findings)
+- You're reviewing a diff or function for boundary conditions
+
+**How it works:**
+
+1. Enumerates all branching paths in the content
+2. Derives edge classes mechanically: missing else/default, unguarded inputs, off-by-one, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+3. Tests each path against existing guards
+4. Reports only unhandled paths — silently discards handled ones
+
+**Input:**
+
+- `content` (required) — Diff, full file, or function
+- `also_consider` (optional) — Additional areas to keep in mind
+
+**Output:** JSON array of findings, each with `location`, `trigger_condition`, `guard_snippet`, and `potential_consequence`
+
+:::note[Complementary Reviews]
+Run both `bmad-review-adversarial-general` and `bmad-review-edge-case-hunter` together for orthogonal coverage. The adversarial review catches quality and completeness issues; the edge case hunter catches unhandled paths.
+:::
+
+## bmad-editorial-review-prose
+
+**Clinical copy-editing focused on communication clarity.** — Reviews text for issues that impede comprehension. Applies Microsoft Writing Style Guide baseline. Preserves author voice.
+
+**Use it when:**
+
+- You've drafted a document and want to polish the writing
+- You need to ensure clarity for a specific audience
+- You want communication fixes without style opinion changes
+
+**How it works:**
+
+1. Reads the content, skipping code blocks and frontmatter
+2. Identifies communication issues (not style preferences)
+3. Deduplicates same issues across multiple locations
+4. Produces a three-column fix table
+
+**Input:**
+
+- `content` (required) — Markdown, plain text, or XML
+- `style_guide` (optional) — Project-specific style guide
+- `reader_type` (optional) — `humans` (default) for clarity/flow, or `llm` for precision/consistency
+
+**Output:** Three-column markdown table: Original Text | Revised Text | Changes
+
+## bmad-editorial-review-structure
+
+**Structural editing — proposes cuts, merges, moves, and condensing.** — Reviews document organization and proposes substantive changes to improve clarity and flow before copy editing.
+
+**Use it when:**
+
+- A document was produced from multiple subprocesses and needs structural coherence
+- You want to reduce document length while preserving comprehension
+- You need to identify scope violations or buried critical information
+
+**How it works:**
+
+1. Analyzes document against 5 structure models (Tutorial, Reference, Explanation, Prompt, Strategic)
+2. Identifies redundancies, scope violations, and buried information
+3. Produces prioritized recommendations: CUT, MERGE, MOVE, CONDENSE, QUESTION, PRESERVE
+4. Estimates total reduction in words and percentage
+
+**Input:**
+
+- `content` (required) — Document to review
+- `purpose` (optional) — Intended purpose (e.g., "quickstart tutorial")
+- `target_audience` (optional) — Who reads this
+- `reader_type` (optional) — `humans` or `llm`
+- `length_target` (optional) — Target reduction (e.g., "30% shorter")
+
+**Output:** Document summary, prioritized recommendation list, and estimated reduction
+
+## bmad-shard-doc
+
+**Split large markdown files into organized section files.** — Uses level-2 headers as split points to create a folder of self-contained section files with an index.
+
+**Use it when:**
+
+- A markdown document has grown too large to manage effectively (500+ lines)
+- You want to break a monolithic doc into navigable sections
+- You need separate files for parallel editing or LLM context management
+
+**How it works:**
+
+1. Validates the source file exists and is markdown
+2. Splits on level-2 (`##`) headers into numbered section files
+3. Creates an `index.md` with section manifest and links
+4. Prompts you to delete, archive, or keep the original
+
+**Input:** Source markdown file path, optional destination folder
+
+**Output:** Folder with `index.md` and `01-{section}.md`, `02-{section}.md`, etc.
+
+## bmad-index-docs
+
+**Generate or update an index of all documents in a folder.** — Scans a directory, reads each file to understand its purpose, and produces an organized `index.md` with links and descriptions.
+
+**Use it when:**
+
+- You need a lightweight index for quick LLM scanning of available docs
+- A documentation folder has grown and needs an organized table of contents
+- You want an auto-generated overview that stays current
+
+**How it works:**
+
+1. Scans the target directory for all non-hidden files
+2. Reads each file to understand its actual purpose
+3. Groups files by type, purpose, or subdirectory
+4. Generates concise descriptions (3–10 words each)
+
+**Input:** Target folder path
+
+**Output:** `index.md` with organized file listings, relative links, and brief descriptions

docs/zh-cn/explanation/quick-dev-new-preview.md

@@ -0,0 +1,73 @@
+---
+title: "快速开发新预览版"
+description: 减少人工介入的阻力，同时保留保护输出质量的检查点
+sidebar:
+  order: 2
+---
+
+`bmad-quick-dev-new-preview` 是对快速流程的一次实验性大改：输入意图即可直接输出代码变更——更少的流程开销、更少的人工介入，但不牺牲质量。
+
+它让模型在检查点之间跑得更久，只在任务没有人工判断就无法安全推进、或需要审查最终结果时，才把人拉回来。
+
+![快速开发新预览版工作流图](/diagrams/quick-dev-diagram.png)
+
+## 为什么需要它
+
+人工介入不可或缺，但代价不小。
+
+当前的大语言模型仍会以可预见的方式翻车：曲解意图、用看似靠谱的猜测填坑、跑偏到不相干的工作上、输出一堆噪音式的审查结果。但不停地人工干预同样拖慢开发节奏。人的注意力才是真正的瓶颈。
+
+这个实验版快速流程尝试重新找到平衡点：让模型在更长的时间段内自主运行，但前提是工作流已经建立了足够强的护栏。
+
+## 核心设计
+
+### 1. 先压缩意图
+
+工作流的第一步是让人和模型一起把请求压缩成一个清晰的目标。输入可以很粗糙，但在工作流开始自主运行之前，目标必须足够小、足够明确、没有自相矛盾的地方。
+
+意图的来源很灵活：几句话、一个 bug tracker 链接、Plan 模式的输出、聊天记录里复制的文本，甚至 BMAD 自身 `epics.md` 里的 story 编号。最后这种情况，工作流并不理解 BMAD 的 story 跟踪语义，但它可以拿到 story 内容直接跑起来。
+
+人工控制并没有被取消，而是集中到了少数高价值的节点上：
+
+- **意图澄清** — 把模糊的请求理清为一个连贯目标，排除隐含矛盾
+- **规格审批** — 确认锁定的理解就是要做的东西
+- **最终产品审查** — 核心检查点，人在最后拍板结果是否达标
+
+### 2. 路由到最小安全路径
+
+目标明确后，工作流判断这是不是真正能一步到位的变更。小改动、影响面为零的变更直接进实现。其余的先走规划，给模型更长自主运行之前加上更强的约束。
+
+### 3. 以更少的监督运行更长时间
+
+路由决策之后，模型可以自主承担更多工作。走完整路径时，已批准的规格本身就是模型在更少监督下执行的边界——这正是整个实验的核心。
+
+### 4. 在正确的层级诊断失败
+
+如果实现出错是因为意图本身就错了，那修代码就是修错了地方。如果代码出错是因为规格不够扎实，光改 diff 也于事无补。工作流的设计目标是找到问题从哪个环节引入，回到那一层重新来过。
+
+审查结果用来判断问题源自意图、规格生成还是局部实现。只有真正的局部问题才就地修补。
+
+### 5. 仅在需要时带回人类
+
+意图访谈需要人工参与，但它不同于反复弹出的检查点中断。工作流会尽可能压缩这类反复中断的次数。初始意图敲定之后，人主要在两个时机回来：工作流靠自己推进不下去的时候，以及最终审查结果的时候。
+
+- **意图缺口解决** — 审查表明工作流无法安全推断原始意图时，人重新介入
+
+其余环节都可以交给模型自主跑更久。这个取舍是有意为之的。老模式把更多人的注意力花在持续盯着上；快速开发新预览版选择更多地信任模型，把人的注意力省给人类判断最有价值的时刻。
+
+## 为什么审查系统很重要
+
+审查阶段不只是找 bug，更重要的是在不打断节奏的前提下把纠正路由到对的地方。
+
+工作流在能拉起子代理的平台上效果最好，至少也要能通过命令行调用另一个 LLM 并等结果返回。平台不原生支持的话，可以加一个 skill 来补。无上下文子代理是审查设计的基石。
+
+AI 代理审查常见两类问题：
+
+- 输出过多发现，逼人在噪音里大海捞针。
+- 顺带暴露了不相关的问题，让当前变更跑偏，每次运行都变成临时打扫卫生。
+
+快速开发新预览版的做法是把审查当分诊来处理。
+
+有些发现属于当前变更，有些不属于。如果一个发现只是顺带发现的、跟当前工作没有因果关系，工作流会把它推迟，而不是逼着人当场处理。这样运行才能保持专注，不会被随机的旁枝末节吃掉注意力。
+
+分诊偶尔会不准，这可以接受。漏判几个发现，远好过上千条低价值审查评论把人淹没。系统优化的是信号质量，不是穷举式召回。

src/bmm/agents/analyst.agent.yaml

@@ -23,7 +23,7 @@ agent:
       description: "[BP] Brainstorm Project: Expert Guided Facilitation through a single or multiple techniques with a final report"
 
     - trigger: MR or fuzzy match on market-research
-      exec: "{project-root}/_bmad/bmm/workflows/1-analysis/research/workflow-market-research.md"
+      exec: "skill:bmad-market-research"
       description: "[MR] Market Research: Market analysis, competitive landscape, customer needs and trends"
 
     - trigger: DR or fuzzy match on domain-research

src/bmm/module-help.csv

@@ -11,7 +11,7 @@ bmm,anytime,Mermaid Generate,MG,,_bmad/bmm/agents/tech-writer/tech-writer.agent.
 bmm,anytime,Validate Document,VD,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.",planning_artifacts,"validation report",
 bmm,anytime,Explain Concept,EC,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Create clear technical explanations with examples and diagrams for complex concepts. Breaks down into digestible sections using task-oriented approach.",project_knowledge,"explanation",
 bmm,1-analysis,Brainstorm Project,BP,10,skill:bmad-brainstorming,bmad-brainstorming,false,analyst,data=_bmad/bmm/data/project-context-template.md,"Expert Guided Facilitation through a single or multiple techniques",planning_artifacts,"brainstorming session",
-bmm,1-analysis,Market Research,MR,20,_bmad/bmm/workflows/1-analysis/research/workflow-market-research.md,bmad-bmm-market-research,false,analyst,Create Mode,"Market analysis competitive landscape customer needs and trends","planning_artifacts|project-knowledge","research documents",
+bmm,1-analysis,Market Research,MR,20,skill:bmad-market-research,bmad-bmm-market-research,false,analyst,Create Mode,"Market analysis competitive landscape customer needs and trends","planning_artifacts|project-knowledge","research documents",
 bmm,1-analysis,Domain Research,DR,21,skill:bmad-domain-research,bmad-bmm-domain-research,false,analyst,Create Mode,"Industry domain deep dive subject matter expertise and terminology","planning_artifacts|project_knowledge","research documents",
 bmm,1-analysis,Technical Research,TR,22,skill:bmad-technical-research,bmad-bmm-technical-research,false,analyst,Create Mode,"Technical feasibility architecture options and implementation approaches","planning_artifacts|project_knowledge","research documents",
 bmm,1-analysis,Create Brief,CB,30,skill:bmad-create-product-brief,bmad-bmm-create-product-brief,false,analyst,Create Mode,"A guided experience to nail down your product idea",planning_artifacts,"product brief",

src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md

@@ -4,7 +4,7 @@ outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 2: Product Vision Discovery

src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md

@@ -4,7 +4,7 @@ outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 3: Target Users Discovery

src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md

@@ -4,7 +4,7 @@ outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 4: Success Metrics Definition

src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.md

@@ -4,7 +4,7 @@ outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 5: MVP Scope Definition

src/bmm/workflows/1-analysis/bmad-product-brief-preview/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: bmad-product-brief-preview
+description: Create or update product briefs through guided or autonomous discovery. Use when the user requests to 'create a product brief', 'help me create a project brief', or 'update my product brief'.
+argument-hint: "[optional --create, --edit, --optimize, --distillate, --inputs, --headless] [brief idea]"
+---
+
+# Create Product Brief
+
+## Overview
+
+This skill helps you create compelling product briefs through collaborative discovery, intelligent artifact analysis, and web research. Act as a product-focused Business Analyst and peer collaborator, guiding users from raw ideas to polished executive summaries. Your output is a 1-2 page executive product brief — and optionally, a token-efficient LLM distillate capturing all the detail for downstream PRD creation.
+
+The user is the domain expert. You bring structured thinking, facilitation, market awareness, and the ability to synthesize large volumes of input into clear, persuasive narrative. Work together as equals.
+
+**Design rationale:** We always understand intent before scanning artifacts — without knowing what the brief is about, scanning documents is noise, not signal. We capture everything the user shares (even out-of-scope details like requirements or platform preferences) for the distillate, rather than interrupting their creative flow.
+
+## Activation Mode Detection
+
+Check activation context immediately:
+
+1. **Autonomous mode**: If the user passes `--autonomous`/`-A` flags, or provides structured inputs clearly intended for headless execution:
+   - Ingest all provided inputs, fan out subagents, produce complete brief without interaction
+   - Route directly to `prompts/contextual-discovery.md` with `{mode}=autonomous`
+
+2. **Yolo mode**: If the user passes `--yolo` or says "just draft it" / "draft the whole thing":
+   - Ingest everything, draft complete brief upfront, then walk user through refinement
+   - Route to Stage 1 below with `{mode}=yolo`
+
+3. **Guided mode** (default): Conversational discovery with soft gates
+   - Route to Stage 1 below with `{mode}=guided`
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Greet user** as `{user_name}`, speaking in `{communication_language}`. Be warm but efficient — dream builder energy.
+
+3. **Stage 1: Understand Intent** (handled here in SKILL.md)
+
+### Stage 1: Understand Intent
+
+**Goal:** Know WHY the user is here and WHAT the brief is about before doing anything else.
+
+**Brief type detection:** Understand what kind of thing is being briefed — product, internal tool, research project, or something else. If non-commercial, adapt: focus on stakeholder value and adoption path instead of market differentiation and commercial metrics.
+
+**Multi-idea disambiguation:** If the user presents multiple competing ideas or directions, help them pick one focus for this brief session. Note that others can be briefed separately.
+
+**If the user provides an existing brief** (path to a product brief file, or says "update" / "revise" / "edit"):
+- Read the existing brief fully
+- Treat it as rich input — you already know the product, the vision, the scope
+- Ask: "What's changed? What do you want to update or improve?"
+- The rest of the workflow proceeds normally — contextual discovery may pull in new research, elicitation focuses on gaps or changes, and draft-and-review produces an updated version
+
+**If the user already provided context** when launching the skill (description, docs, brain dump):
+- Acknowledge what you received — but **DO NOT read document files yet**. Note their paths for Stage 2's subagents to scan contextually. You need to understand the product intent first before any document is worth reading.
+- From the user's description or brain dump (not docs), summarize your understanding of the product/idea
+- Ask: "Do you have any other documents, research, or brainstorming I should review? Anything else to add before I dig in?"
+
+**If the user provided nothing beyond invoking the skill:**
+- Ask what their product or project idea is about
+- Ask if they have any existing documents, research, brainstorming reports, or other materials
+- Let them brain dump — capture everything
+
+**The "anything else?" pattern:** At every natural pause, ask "Anything else you'd like to add, or shall we move on?" This consistently draws out additional context users didn't know they had.
+
+**Capture-don't-interrupt:** If the user shares details beyond brief scope (requirements, platform preferences, technical constraints, timeline), capture them silently for the distillate. Don't redirect or stop their flow.
+
+**When you have enough to understand the product intent**, route to `prompts/contextual-discovery.md` with the current mode.
+
+## Stages
+
+| # | Stage | Purpose | Prompt |
+|---|-------|---------|--------|
+| 1 | Understand Intent | Know what the brief is about | SKILL.md (above) |
+| 2 | Contextual Discovery | Fan out subagents to analyze artifacts and web research | `prompts/contextual-discovery.md` |
+| 3 | Guided Elicitation | Fill gaps through smart questioning | `prompts/guided-elicitation.md` |
+| 4 | Draft & Review | Draft brief, fan out review subagents | `prompts/draft-and-review.md` |
+| 5 | Finalize | Polish, output, offer distillate | `prompts/finalize.md` |
+
+## External Skills
+
+This workflow uses:
+- `bmad-init` — Configuration loading (module: bmm)

src/bmm/workflows/1-analysis/bmad-product-brief-preview/agents/artifact-analyzer.md

@@ -0,0 +1,60 @@
+# Artifact Analyzer
+
+You are a research analyst. Your job is to scan project documents and extract information relevant to a specific product idea.
+
+## Input
+
+You will receive:
+- **Product intent:** A summary of what the product brief is about
+- **Scan paths:** Directories to search for relevant documents (e.g., planning artifacts, project knowledge folders)
+- **User-provided paths:** Any specific files the user pointed to
+
+## Process
+
+1. **Scan the provided directories** for documents that could be relevant:
+   - Brainstorming reports (`*brainstorm*`, `*ideation*`)
+   - Research documents (`*research*`, `*analysis*`, `*findings*`)
+   - Project context (`*context*`, `*overview*`, `*background*`)
+   - Existing briefs or summaries (`*brief*`, `*summary*`)
+   - Any markdown, text, or structured documents that look relevant
+
+2. **For sharded documents** (a folder with `index.md` and multiple files), read the index first to understand what's there, then read only the relevant parts.
+
+3. **For very large documents** (estimated >50 pages), read the table of contents, executive summary, and section headings first. Read only sections directly relevant to the stated product intent. Note which sections were skimmed vs read fully.
+
+4. **Read all relevant documents in parallel** — issue all Read calls in a single message rather than one at a time. Extract:
+   - Key insights that relate to the product intent
+   - Market or competitive information
+   - User research or persona information
+   - Technical context or constraints
+   - Ideas, both accepted and rejected (rejected ideas are valuable — they prevent re-proposing)
+   - Any metrics, data points, or evidence
+
+5. **Ignore documents that aren't relevant** to the stated product intent. Don't waste tokens on unrelated content.
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Maximum 8 bullets per section.
+
+```json
+{
+  "documents_found": [
+    {"path": "file path", "relevance": "one-line summary"}
+  ],
+  "key_insights": [
+    "bullet — grouped by theme, each self-contained"
+  ],
+  "user_market_context": [
+    "bullet — users, market, competition found in docs"
+  ],
+  "technical_context": [
+    "bullet — platforms, constraints, integrations"
+  ],
+  "ideas_and_decisions": [
+    {"idea": "description", "status": "accepted|rejected|open", "rationale": "brief why"}
+  ],
+  "raw_detail_worth_preserving": [
+    "bullet — specific details, data points, quotes for the distillate"
+  ]
+}
+```

src/bmm/workflows/1-analysis/bmad-product-brief-preview/agents/opportunity-reviewer.md

@@ -0,0 +1,44 @@
+# Opportunity Reviewer
+
+You are a strategic advisor reviewing a product brief draft. Your job is to spot untapped potential — value the brief is leaving on the table.
+
+## Input
+
+You will receive the complete draft product brief.
+
+## Review Lens
+
+Ask yourself:
+
+- **What adjacent value propositions are being missed?** Are there related problems this solution naturally addresses?
+- **What market angles are underemphasized?** Is the positioning leaving opportunities unexplored?
+- **What partnerships or integrations could multiply impact?** Who would benefit from aligning with this product?
+- **What's the network effect or viral potential?** Is there a growth flywheel the brief doesn't describe?
+- **What's underemphasized?** Which strengths deserve more spotlight?
+- **What user segments are overlooked?** Could this serve audiences not yet mentioned?
+- **What's the bigger story?** If you zoom out, is there a more compelling narrative?
+- **What would an investor want to hear more about?** What would make someone lean forward?
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Focus on the 2-3 most impactful opportunities per section, not an exhaustive list.
+
+```json
+{
+  "untapped_value": [
+    {"opportunity": "adjacent problem or value prop", "rationale": "why it matters"}
+  ],
+  "positioning_opportunities": [
+    {"angle": "market angle or narrative", "impact": "how it strengthens the brief"}
+  ],
+  "growth_and_scale": [
+    "bullet — network effects, viral loops, expansion paths"
+  ],
+  "strategic_partnerships": [
+    {"partner_type": "who", "value": "why this alliance matters"}
+  ],
+  "underemphasized_strengths": [
+    {"strength": "what's underplayed", "suggestion": "how to elevate it"}
+  ]
+}
+```

src/bmm/workflows/1-analysis/bmad-product-brief-preview/agents/skeptic-reviewer.md

@@ -0,0 +1,44 @@
+# Skeptic Reviewer
+
+You are a critical analyst reviewing a product brief draft. Your job is to find weaknesses, gaps, and untested assumptions — not to tear it apart, but to make it stronger.
+
+## Input
+
+You will receive the complete draft product brief.
+
+## Review Lens
+
+Ask yourself:
+
+- **What's missing?** Are there sections that feel thin or glossed over?
+- **What assumptions are untested?** Where does the brief assert things without evidence?
+- **What could go wrong?** What risks aren't acknowledged?
+- **Where is it vague?** Which claims need more specificity?
+- **Does the problem statement hold up?** Is this a real, significant problem or a nice-to-have?
+- **Are the differentiators actually defensible?** Could a competitor replicate them easily?
+- **Do the success metrics make sense?** Are they measurable and meaningful?
+- **Is the MVP scope realistic?** Too ambitious? Too timid?
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Maximum 5 items per section. Prioritize — lead with the most impactful issues.
+
+```json
+{
+  "critical_gaps": [
+    {"issue": "what's missing", "impact": "why it matters", "suggestion": "how to fix"}
+  ],
+  "untested_assumptions": [
+    {"assumption": "what's asserted", "risk": "what could go wrong"}
+  ],
+  "unacknowledged_risks": [
+    {"risk": "potential failure mode", "severity": "high|medium|low"}
+  ],
+  "vague_areas": [
+    {"section": "where", "issue": "what's vague", "suggestion": "how to sharpen"}
+  ],
+  "suggested_improvements": [
+    "actionable suggestion"
+  ]
+}
+```

src/bmm/workflows/1-analysis/bmad-product-brief-preview/agents/web-researcher.md

@@ -0,0 +1,49 @@
+# Web Researcher
+
+You are a market research analyst. Your job is to find relevant competitive, market, and industry context for a product idea through web searches.
+
+## Input
+
+You will receive:
+- **Product intent:** A summary of what the product is about, the problem it solves, and the domain it operates in
+
+## Process
+
+1. **Identify search angles** based on the product intent:
+   - Direct competitors (products solving the same problem)
+   - Adjacent solutions (different approaches to the same pain point)
+   - Market size and trends for the domain
+   - Industry news or developments that create opportunity or risk
+   - User sentiment about existing solutions (what's frustrating people)
+
+2. **Execute 3-5 targeted web searches** — quality over quantity. Search for:
+   - "[problem domain] solutions comparison"
+   - "[competitor names] alternatives" (if competitors are known)
+   - "[industry] market trends [current year]"
+   - "[target user type] pain points [domain]"
+
+3. **Synthesize findings** — don't just list links. Extract the signal.
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Maximum 5 bullets per section.
+
+```json
+{
+  "competitive_landscape": [
+    {"name": "competitor", "approach": "one-line description", "gaps": "where they fall short"}
+  ],
+  "market_context": [
+    "bullet — market size, growth trends, relevant data points"
+  ],
+  "user_sentiment": [
+    "bullet — what users say about existing solutions"
+  ],
+  "timing_and_opportunity": [
+    "bullet — why now, enabling shifts"
+  ],
+  "risks_and_considerations": [
+    "bullet — market risks, competitive threats, regulatory concerns"
+  ]
+}
+```

src/bmm/workflows/1-analysis/bmad-product-brief-preview/bmad-manifest.json

@@ -0,0 +1,17 @@
+{
+  "module-code": "bmm",
+  "replaces-skill": "bmad-create-product-brief",
+  "capabilities": [
+    {
+      "name": "create-brief",
+      "menu-code": "CB",
+      "description": "Produces executive product brief and optional LLM distillate for PRD input.",
+      "supports-headless": true,
+      "phase-name": "1-analysis",
+      "after": ["brainstorming, perform-research"],
+      "before": ["create-prd"],
+      "is-required": true,
+      "output-location": "{planning_artifacts}"
+    }
+  ]
+}

src/bmm/workflows/1-analysis/bmad-product-brief-preview/prompts/contextual-discovery.md

@@ -0,0 +1,57 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+
+# Stage 2: Contextual Discovery
+
+**Goal:** Armed with the user's stated intent, intelligently gather and synthesize all available context — documents, project knowledge, and web research — so later stages work from a rich, relevant foundation.
+
+## Subagent Fan-Out
+
+Now that you know what the brief is about, fan out subagents in parallel to gather context. Each subagent receives the product intent summary so it knows what's relevant.
+
+**Launch in parallel:**
+
+1. **Artifact Analyzer** (`agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents. Also scans any specific paths the user provided. Returns structured synthesis of what it found.
+
+2. **Web Researcher** (`agents/web-researcher.md`) — Searches for competitive landscape, market context, trends, and relevant industry data. Returns structured findings scoped to the product domain.
+
+### Graceful Degradation
+
+If subagents are unavailable or fail:
+- Read only the most relevant 1-2 documents in the main context and summarize (don't full-read everything — limit context impact in degraded mode)
+- Do a few targeted web searches inline
+- Never block the workflow because a subagent feature is unavailable
+
+## Synthesis
+
+Once subagent results return (or inline scanning completes):
+
+1. **Merge findings** with what the user already told you
+2. **Identify gaps** — what do you still need to know to write a solid brief?
+3. **Note surprises** — anything from research that contradicts or enriches the user's assumptions?
+
+## Mode-Specific Behavior
+
+**Guided mode:**
+- Present a concise summary of what you found: "Here's what I learned from your documents and web research..."
+- Highlight anything surprising or worth discussing
+- Share the gaps you've identified
+- Ask: "Anything else you'd like to add, or shall we move on to filling in the details?"
+- Route to `prompts/guided-elicitation.md`
+
+**Yolo mode:**
+- Absorb all findings silently
+- Skip directly to `prompts/draft-and-review.md` — you have enough to draft
+- The user will refine later
+
+**Headless mode:**
+- Absorb all findings
+- Skip directly to `prompts/draft-and-review.md`
+- No interaction
+
+## Stage Complete
+
+This stage is complete when subagent results (or inline scanning fallback) have returned and findings are merged with user context. Route per mode:
+- **Guided** → `prompts/guided-elicitation.md`
+- **Yolo / Headless** → `prompts/draft-and-review.md`

src/bmm/workflows/1-analysis/bmad-product-brief-preview/prompts/draft-and-review.md

@@ -0,0 +1,86 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+
+# Stage 4: Draft & Review
+
+**Goal:** Produce the executive product brief and run it through multiple review lenses to catch blind spots before the user sees the final version.
+
+## Step 1: Draft the Executive Brief
+
+Use `resources/brief-template.md` as a guide — adapt structure to fit the product's story.
+
+**Writing principles:**
+- **Executive audience** — persuasive, clear, concise. 1-2 pages.
+- **Lead with the problem** — make the reader feel the pain before presenting the solution
+- **Concrete over abstract** — specific examples, real scenarios, measurable outcomes
+- **Confident voice** — this is a pitch, not a hedge
+- Write in `{document_output_language}`
+
+**Create the output document at:** `{planning_artifacts}/product-brief-{project_name}.md`
+
+Include YAML frontmatter:
+```yaml
+---
+title: "Product Brief: {project_name}"
+status: "draft"
+created: "{timestamp}"
+updated: "{timestamp}"
+inputs: [list of input files used]
+---
+```
+
+## Step 2: Fan Out Review Subagents
+
+Before showing the draft to the user, run it through multiple review lenses in parallel.
+
+**Launch in parallel:**
+
+1. **Skeptic Reviewer** (`agents/skeptic-reviewer.md`) — "What's missing? What assumptions are untested? What could go wrong? Where is the brief vague or hand-wavy?"
+
+2. **Opportunity Reviewer** (`agents/opportunity-reviewer.md`) — "What adjacent value propositions are being missed? What market angles or partnerships could strengthen this? What's underemphasized?"
+
+3. **Contextual Reviewer** — You (the main agent) pick the most useful third lens based on THIS specific product. Choose the lens that addresses the SINGLE BIGGEST RISK that the skeptic and opportunity reviewers won't naturally catch. Examples:
+   - For healthtech: "Regulatory and compliance risk reviewer"
+   - For devtools: "Developer experience and adoption friction critic"
+   - For marketplace: "Network effects and chicken-and-egg problem analyst"
+   - For enterprise: "Procurement and organizational change management reviewer"
+   - **When domain is unclear, default to:** "Go-to-market and launch risk reviewer" — examines distribution, pricing, and first-customer acquisition. Almost always valuable, frequently missed.
+   Describe the lens, run the review yourself inline.
+
+### Graceful Degradation
+
+If subagents are unavailable:
+- Perform all three review passes yourself, sequentially
+- Apply each lens deliberately — don't blend them into one generic review
+- The quality of review matters more than the parallelism
+
+## Step 3: Integrate Review Insights
+
+After all reviews complete:
+
+1. **Triage findings** — group by theme, remove duplicates
+2. **Apply non-controversial improvements** directly to the draft (obvious gaps, unclear language, missing specifics)
+3. **Flag substantive suggestions** that need user input (strategic choices, scope questions, market positioning decisions)
+
+## Step 4: Present to User
+
+**Headless mode:** Skip to `prompts/finalize.md` — no user interaction. Save the improved draft directly.
+
+**Yolo and Guided modes:**
+
+Present the draft brief to the user. Then share the reviewer insights:
+
+"Here's your product brief draft. Before we finalize, my review panel surfaced some things worth considering:
+
+**[Grouped reviewer findings — only the substantive ones that need user input]**
+
+What do you think? Any changes you'd like to make?"
+
+Present reviewer findings with brief rationale, then offer: "Want me to dig into any of these, or are you ready to make your revisions?"
+
+**Iterate** as long as the user wants to refine. Use the "anything else, or are we happy with this?" soft gate.
+
+## Stage Complete
+
+This stage is complete when: (a) the draft has been reviewed by all three lenses and improvements integrated, AND either (autonomous) save and route directly, or (guided/yolo) the user is satisfied. Route to `prompts/finalize.md`.

src/bmm/workflows/1-analysis/bmad-product-brief-preview/prompts/finalize.md

@@ -0,0 +1,75 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+
+# Stage 5: Finalize
+
+**Goal:** Save the polished brief, offer the LLM distillate, and point the user forward.
+
+## Step 1: Polish and Save
+
+Update the product brief document at `{planning_artifacts}/product-brief-{project_name}.md`:
+- Update frontmatter `status` to `"complete"`
+- Update `updated` timestamp
+- Ensure formatting is clean and consistent
+- Confirm the document reads well as a standalone 1-2 page executive summary
+
+## Step 2: Offer the Distillate
+
+Throughout the discovery process, you likely captured detail that doesn't belong in a 1-2 page executive summary but is valuable for downstream work — requirements hints, platform preferences, rejected ideas, technical constraints, detailed user scenarios, competitive deep-dives, etc.
+
+**Ask the user:**
+"Your product brief is complete. During our conversation, I captured additional detail that goes beyond the executive summary — things like [mention 2-3 specific examples of overflow you captured]. Would you like me to create a detail pack for PRD creation? It distills all that extra context into a concise, structured format optimized for the next phase."
+
+**If yes, create the distillate** at `{planning_artifacts}/product-brief-{project_name}-distillate.md`:
+
+```yaml
+---
+title: "Product Brief Distillate: {project_name}"
+type: llm-distillate
+source: "product-brief-{project_name}.md"
+created: "{timestamp}"
+purpose: "Token-efficient context for downstream PRD creation"
+---
+```
+
+**Distillate content principles:**
+- Dense bullet points, not prose
+- Each bullet carries enough context to be understood standalone (don't assume the reader has the full brief loaded)
+- Group by theme, not by when it was mentioned
+- Include:
+  - **Rejected ideas** — so downstream workflows don't re-propose them, with brief rationale
+  - **Requirements hints** — anything the user mentioned that sounds like a requirement
+  - **Technical context** — platforms, integrations, constraints, preferences
+  - **Detailed user scenarios** — richer than what fits in the exec summary
+  - **Competitive intelligence** — specifics from web research worth preserving
+  - **Open questions** — things surfaced but not resolved during discovery
+  - **Scope signals** — what the user indicated is in/out/maybe for MVP
+- Token-conscious: be concise, but give enough context per bullet so an LLM reading this later understands WHY each point matters
+
+**Headless mode:** Always create the distillate automatically — unless the session was too brief to capture meaningful overflow (in that case, note this in the completion output instead of creating an empty file).
+
+## Step 3: Present Completion
+
+"Your product brief for {project_name} is complete!
+
+**Executive Brief:** `{planning_artifacts}/product-brief-{project_name}.md`
+[If distillate created:] **Detail Pack:** `{planning_artifacts}/product-brief-{project_name}-distillate.md`
+
+**Recommended next step:** Use the product brief (and detail pack) as input for PRD creation — tell your assistant 'create a PRD' and point it to these files."
+[If distillate created:] "The detail pack contains all the overflow context (requirements hints, rejected ideas, technical constraints) specifically structured for the PRD workflow to consume."
+
+**Headless mode:** Output the file paths as structured JSON and exit:
+```json
+{
+  "status": "complete",
+  "brief": "{planning_artifacts}/product-brief-{project_name}.md",
+  "distillate": "{path or null}",
+  "confidence": "high|medium|low",
+  "open_questions": ["any unresolved items"]
+}
+```
+
+## Stage Complete
+
+This is the terminal stage. After delivering the completion message and file paths, the workflow is done. If the user requests further revisions, loop back to `prompts/draft-and-review.md`. Otherwise, exit.

src/bmm/workflows/1-analysis/bmad-product-brief-preview/prompts/guided-elicitation.md

@@ -0,0 +1,70 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+
+# Stage 3: Guided Elicitation
+
+**Goal:** Fill the gaps in what you know. By now you have the user's brain dump, artifact analysis, and web research. This stage is about smart, targeted questioning — not rote section-by-section interrogation.
+
+**Skip this stage entirely in Yolo and Autonomous modes** — go directly to `prompts/draft-and-review.md`.
+
+## Approach
+
+You are NOT walking through a rigid questionnaire. You're having a conversation that covers the substance of a great product brief. The topics below are your mental checklist, not a script. Adapt to:
+- What you already know (don't re-ask what's been covered)
+- What the user is excited about (follow their energy)
+- What's genuinely unclear (focus questions where they matter)
+
+## Topics to Cover (flexibly, conversationally)
+
+### Vision & Problem
+- What core problem does this solve? For whom?
+- How do people solve this today? What's frustrating about current approaches?
+- What would success look like for the people this helps?
+- What's the insight or angle that makes this approach different?
+
+### Users & Value
+- Who experiences this problem most acutely?
+- Are there different user types with different needs?
+- What's the "aha moment" — when does a user realize this is what they needed?
+- How does this fit into their existing workflow or life?
+
+### Market & Differentiation
+- What competitive or alternative solutions exist? (Leverage web research findings)
+- What's the unfair advantage or defensible moat?
+- Why is now the right time for this?
+
+### Success & Scope
+- How will you know this is working? What metrics matter?
+- What's the minimum viable version that creates real value?
+- What's explicitly NOT in scope for the first version?
+- If this is wildly successful, what does it become in 2-3 years?
+
+## The Flow
+
+For each topic area where you have gaps:
+
+1. **Lead with what you know** — "Based on your input and my research, it sounds like [X]. Is that right?"
+2. **Ask the gap question** — targeted, specific, not generic
+3. **Reflect and confirm** — paraphrase what you heard
+4. **"Anything else on this, or shall we move on?"** — the soft gate
+
+If the user is giving you detail beyond brief scope (requirements, architecture, platform details, timelines), **capture it silently** for the distillate. Acknowledge it briefly ("Good detail, I'll capture that") but don't derail the conversation.
+
+## When to Move On
+
+When you have enough substance to draft a compelling 1-2 page executive brief covering:
+- Clear problem and who it affects
+- Proposed solution and what makes it different
+- Target users (at least primary)
+- Some sense of success criteria or business objectives
+- MVP-level scope thinking
+
+You don't need perfection — you need enough to draft well. Missing details can be surfaced during the review stage.
+
+If the user is providing complete, confident answers and you have solid coverage across all four topic areas after fewer than 3-4 exchanges, proactively offer to draft early.
+
+**Transition:** "I think I have a solid picture. Ready for me to draft the brief, or is there anything else you'd like to add?"
+
+## Stage Complete
+
+This stage is complete when sufficient substance exists to draft a compelling brief and the user confirms readiness. Route to `prompts/draft-and-review.md`.

src/bmm/workflows/1-analysis/bmad-product-brief-preview/resources/brief-template.md

@@ -0,0 +1,60 @@
+# Product Brief Template
+
+This is a flexible guide for the executive product brief — adapt it to serve the product's story. Merge sections, add new ones, reorder as needed. The product determines the structure, not the template.
+
+## Sensible Default Structure
+
+```markdown
+# Product Brief: {Product Name}
+
+## Executive Summary
+
+[2-3 paragraph narrative: What is this? What problem does it solve? Why does it matter? Why now?
+This should be compelling enough to stand alone — if someone reads only this section, they should understand the vision.]
+
+## The Problem
+
+[What pain exists? Who feels it? How are they coping today? What's the cost of the status quo?
+Be specific — real scenarios, real frustrations, real consequences.]
+
+## The Solution
+
+[What are we building? How does it solve the problem?
+Focus on the experience and outcome, not the implementation.]
+
+## What Makes This Different
+
+[Key differentiators. Why this approach vs alternatives? What's the unfair advantage?
+Be honest — if the moat is execution speed, say so. Don't fabricate technical moats.]
+
+## Who This Serves
+
+[Primary users — vivid but brief. Who are they, what do they need, what does success look like for them?
+Secondary users if relevant.]
+
+## Success Criteria
+
+[How do we know this is working? What metrics matter?
+Mix of user success signals and business objectives. Be measurable.]
+
+## Scope
+
+[What's in for the first version? What's explicitly out?
+Keep this tight — it's a boundary document, not a feature list.]
+
+## Vision
+
+[Where does this go if it succeeds? What does it become in 2-3 years?
+Inspiring but grounded.]
+```
+
+## Adaptation Guidelines
+
+- **For B2B products:** Consider adding a "Buyer vs User" section if they're different people
+- **For platforms/marketplaces:** Consider a "Network Effects" or "Ecosystem" section
+- **For technical products:** May need a brief "Technical Approach" section (keep it high-level)
+- **For regulated industries:** Consider a "Compliance & Regulatory" section
+- **If scope is well-defined:** Merge "Scope" and "Vision" into "Roadmap Thinking"
+- **If the problem is well-known:** Shorten "The Problem" and expand "What Makes This Different"
+
+The brief should be 1-2 pages. If it's longer, you're putting in too much detail — that's what the distillate is for.

src/bmm/workflows/1-analysis/research/bmad-market-research/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-market-research
+description: 'Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/1-analysis/research/bmad-market-research/research.template.md

@@ -0,0 +1,29 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'research'
+lastStep: 1
+research_type: '{{research_type}}'
+research_topic: '{{research_topic}}'
+research_goals: '{{research_goals}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+web_research_enabled: true
+source_verification: true
+---
+
+# Research Report: {{research_type}}
+
+**Date:** {{date}}
+**Author:** {{user_name}}
+**Research Type:** {{research_type}}
+
+---
+
+## Research Overview
+
+[Research overview and methodology will be appended here]
+
+---
+
+<!-- Content will be appended sequentially through research workflow steps -->

src/bmm/workflows/1-analysis/research/bmad-market-research/steps/step-01-init.md

@@ -0,0 +1,184 @@
+# Market Research Step 1: Market Research Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate research content in init step
+- ✅ ALWAYS confirm understanding of user's research goals
+- 📋 YOU ARE A MARKET RESEARCH FACILITATOR, not content generator
+- 💬 FOCUS on clarifying scope and approach
+- 🔍 NO WEB RESEARCH in init - that's for later steps
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete research
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Confirm research understanding before proceeding
+- ⚠️ Present [C] continue option after scope clarification
+- 💾 Write initial scope document immediately
+- 📖 Update frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from main workflow discovery are available
+- Research type = "market" is already set
+- **Research topic = "{{research_topic}}"** - discovered from initial discussion
+- **Research goals = "{{research_goals}}"** - captured from initial discussion
+- Focus on market research scope clarification
+- Web search capabilities are enabled for later steps
+
+## YOUR TASK:
+
+Initialize market research by confirming understanding of {{research_topic}} and establishing clear research scope.
+
+## MARKET RESEARCH INITIALIZATION:
+
+### 1. Confirm Research Understanding
+
+**INITIALIZE - DO NOT RESEARCH YET**
+
+Start with research confirmation:
+"I understand you want to conduct **market research** for **{{research_topic}}** with these goals: {{research_goals}}
+
+**My Understanding of Your Research Needs:**
+
+- **Research Topic**: {{research_topic}}
+- **Research Goals**: {{research_goals}}
+- **Research Type**: Market Research
+- **Approach**: Comprehensive market analysis with source verification
+
+**Market Research Areas We'll Cover:**
+
+- Market size, growth dynamics, and trends
+- Customer insights and behavior analysis
+- Competitive landscape and positioning
+- Strategic recommendations and implementation guidance
+
+**Does this accurately capture what you're looking for?**"
+
+### 2. Refine Research Scope
+
+Gather any clarifications needed:
+
+#### Scope Clarification Questions:
+
+- "Are there specific customer segments or aspects of {{research_topic}} we should prioritize?"
+- "Should we focus on specific geographic regions or global market?"
+- "Is this for market entry, expansion, product development, or other business purpose?"
+- "Any competitors or market segments you specifically want us to analyze?"
+
+### 3. Document Initial Scope
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Write initial research scope to document:
+
+```markdown
+# Market Research: {{research_topic}}
+
+## Research Initialization
+
+### Research Understanding Confirmed
+
+**Topic**: {{research_topic}}
+**Goals**: {{research_goals}}
+**Research Type**: Market Research
+**Date**: {{date}}
+
+### Research Scope
+
+**Market Analysis Focus Areas:**
+
+- Market size, growth projections, and dynamics
+- Customer segments, behavior patterns, and insights
+- Competitive landscape and positioning analysis
+- Strategic recommendations and implementation guidance
+
+**Research Methodology:**
+
+- Current web data with source verification
+- Multiple independent sources for critical claims
+- Confidence level assessment for uncertain data
+- Comprehensive coverage with no critical gaps
+
+### Next Steps
+
+**Research Workflow:**
+
+1. ✅ Initialization and scope setting (current step)
+2. Customer Insights and Behavior Analysis
+3. Competitive Landscape Analysis
+4. Strategic Synthesis and Recommendations
+
+**Research Status**: Scope confirmed, ready to proceed with detailed market analysis
+```
+
+### 4. Present Confirmation and Continue Option
+
+Show initial scope document and present continue option:
+"I've documented our understanding and initial scope for **{{research_topic}}** market research.
+
+**What I've established:**
+
+- Research topic and goals confirmed
+- Market analysis focus areas defined
+- Research methodology verification
+- Clear workflow progression
+
+**Document Status:** Initial scope written to research file for your review
+
+**Ready to begin detailed market research?**
+[C] Continue - Confirm scope and proceed to customer insights analysis
+[Modify] Suggest changes to research scope before proceeding
+
+**HALT — wait for user response before proceeding.**
+
+### 5. Handle User Response
+
+#### If 'C' (Continue):
+
+- Update frontmatter: `stepsCompleted: [1]`
+- Add confirmation note to document: "Scope confirmed by user on {{date}}"
+- Load: `./step-02-customer-behavior.md`
+
+#### If 'Modify':
+
+- Gather user changes to scope
+- Update document with modifications
+- Re-present updated scope for confirmation
+
+## SUCCESS METRICS:
+
+✅ Research topic and goals accurately understood
+✅ Market research scope clearly defined
+✅ Initial scope document written immediately
+✅ User opportunity to review and modify scope
+✅ [C] continue option presented and handled correctly
+✅ Document properly updated with scope confirmation
+
+## FAILURE MODES:
+
+❌ Not confirming understanding of research topic and goals
+❌ Generating research content instead of just scope clarification
+❌ Not writing initial scope document to file
+❌ Not providing opportunity for user to modify scope
+❌ Proceeding to next step without user confirmation
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor research decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## INITIALIZATION PRINCIPLES:
+
+This step ensures:
+
+- Clear mutual understanding of research objectives
+- Well-defined research scope and approach
+- Immediate documentation for user review
+- User control over research direction before detailed work begins
+
+## NEXT STEP:
+
+After user confirmation and scope finalization, load `./step-02-customer-behavior.md` to begin detailed market research with customer insights analysis.
+
+Remember: Init steps confirm understanding and scope, not generate research content!

src/bmm/workflows/1-analysis/research/bmad-market-research/steps/step-02-customer-behavior.md

@@ -0,0 +1,239 @@
+# Market Research Step 2: Customer Behavior and Segments
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A CUSTOMER BEHAVIOR ANALYST, not content generator
+- 💬 FOCUS on customer behavior patterns and demographic analysis
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete research
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after customer behavior content generation
+- 📝 WRITE CUSTOMER BEHAVIOR ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from step-01 are available
+- Focus on customer behavior patterns and demographic analysis
+- Web search capabilities with source verification are enabled
+- Previous step confirmed research scope and goals
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+
+## YOUR TASK:
+
+Conduct customer behavior and segment analysis with emphasis on patterns and demographics.
+
+## CUSTOMER BEHAVIOR ANALYSIS SEQUENCE:
+
+### 1. Begin Customer Behavior Analysis
+
+**UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different customer behavior areas simultaneously and thoroughly.
+
+Start with customer behavior research approach:
+"Now I'll conduct **customer behavior analysis** for **{{research_topic}}** to understand customer patterns.
+
+**Customer Behavior Focus:**
+
+- Customer behavior patterns and preferences
+- Demographic profiles and segmentation
+- Psychographic characteristics and values
+- Behavior drivers and influences
+- Customer interaction patterns and engagement
+
+**Let me search for current customer behavior insights.**"
+
+### 2. Parallel Customer Behavior Research Execution
+
+**Execute multiple web searches simultaneously:**
+
+Search the web: "{{research_topic}} customer behavior patterns"
+Search the web: "{{research_topic}} customer demographics"
+Search the web: "{{research_topic}} psychographic profiles"
+Search the web: "{{research_topic}} customer behavior drivers"
+
+**Analysis approach:**
+
+- Look for customer behavior studies and research reports
+- Search for demographic segmentation and analysis
+- Research psychographic profiling and value systems
+- Analyze behavior drivers and influencing factors
+- Study customer interaction and engagement patterns
+
+### 3. Analyze and Aggregate Results
+
+**Collect and analyze findings from all parallel searches:**
+
+"After executing comprehensive parallel web searches, let me analyze and aggregate customer behavior findings:
+
+**Research Coverage:**
+
+- Customer behavior patterns and preferences
+- Demographic profiles and segmentation
+- Psychographic characteristics and values
+- Behavior drivers and influences
+- Customer interaction patterns and engagement
+
+**Cross-Behavior Analysis:**
+[Identify patterns connecting demographics, psychographics, and behaviors]
+
+**Quality Assessment:**
+[Overall confidence levels and research gaps identified]"
+
+### 4. Generate Customer Behavior Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare customer behavior analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Customer Behavior and Segments
+
+### Customer Behavior Patterns
+
+[Customer behavior patterns analysis with source citations]
+_Behavior Drivers: [Key motivations and patterns from web search]_
+_Interaction Preferences: [Customer engagement and interaction patterns]_
+_Decision Habits: [How customers typically make decisions]_
+_Source: [URL]_
+
+### Demographic Segmentation
+
+[Demographic analysis with source citations]
+_Age Demographics: [Age groups and preferences]_
+_Income Levels: [Income segments and purchasing behavior]_
+_Geographic Distribution: [Regional/city differences]_
+_Education Levels: [Education impact on behavior]_
+_Source: [URL]_
+
+### Psychographic Profiles
+
+[Psychographic analysis with source citations]
+_Values and Beliefs: [Core values driving customer behavior]_
+_Lifestyle Preferences: [Lifestyle choices and behaviors]_
+_Attitudes and Opinions: [Customer attitudes toward products/services]_
+_Personality Traits: [Personality influences on behavior]_
+_Source: [URL]_
+
+### Customer Segment Profiles
+
+[Detailed customer segment profiles with source citations]
+_Segment 1: [Detailed profile including demographics, psychographics, behavior]_
+_Segment 2: [Detailed profile including demographics, psychographics, behavior]_
+_Segment 3: [Detailed profile including demographics, psychographics, behavior]_
+_Source: [URL]_
+
+### Behavior Drivers and Influences
+
+[Behavior drivers analysis with source citations]
+_Emotional Drivers: [Emotional factors influencing behavior]_
+_Rational Drivers: [Logical decision factors]_
+_Social Influences: [Social and peer influences]_
+_Economic Influences: [Economic factors affecting behavior]_
+_Source: [URL]_
+
+### Customer Interaction Patterns
+
+[Customer interaction analysis with source citations]
+_Research and Discovery: [How customers find and research options]_
+_Purchase Decision Process: [Steps in purchase decision making]_
+_Post-Purchase Behavior: [After-purchase engagement patterns]_
+_Loyalty and Retention: [Factors driving customer loyalty]_
+_Source: [URL]_
+```
+
+### 5. Present Analysis and Continue Option
+
+**Show analysis and present continue option:**
+
+"I've completed **customer behavior analysis** for {{research_topic}}, focusing on customer patterns.
+
+**Key Customer Behavior Findings:**
+
+- Customer behavior patterns clearly identified with drivers
+- Demographic segmentation thoroughly analyzed
+- Psychographic profiles mapped and documented
+- Customer interaction patterns captured
+- Multiple sources verified for critical insights
+
+**Ready to proceed to customer pain points?**
+[C] Continue - Save this to document and proceed to pain points analysis
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2]`
+- Load: `./step-03-customer-pain-points.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 4. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Customer behavior patterns identified with current citations
+✅ Demographic segmentation thoroughly analyzed
+✅ Psychographic profiles clearly documented
+✅ Customer interaction patterns captured
+✅ Multiple sources verified for critical insights
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (customer pain points)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical customer behavior patterns
+❌ Incomplete demographic segmentation analysis
+❌ Missing psychographic profile documentation
+❌ Not writing content immediately to document
+❌ Not presenting [C] continue option after content generation
+❌ Not routing to customer pain points analysis step
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor research decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## CUSTOMER BEHAVIOR RESEARCH PROTOCOLS:
+
+- Research customer behavior studies and market research
+- Use demographic data from authoritative sources
+- Research psychographic profiling and value systems
+- Analyze customer interaction and engagement patterns
+- Focus on current behavior data and trends
+- Present conflicting information when sources disagree
+- Apply confidence levels appropriately
+
+## BEHAVIOR ANALYSIS STANDARDS:
+
+- Always cite URLs for web search results
+- Use authoritative customer research sources
+- Note data currency and potential limitations
+- Present multiple perspectives when sources conflict
+- Apply confidence levels to uncertain data
+- Focus on actionable customer insights
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-03-customer-pain-points.md` to analyze customer pain points, challenges, and unmet needs for {{research_topic}}.
+
+Remember: Always write research content to document immediately and emphasize current customer data with rigorous source verification!

src/bmm/workflows/1-analysis/research/bmad-market-research/steps/step-03-customer-pain-points.md

@@ -0,0 +1,251 @@
+# Market Research Step 3: Customer Pain Points and Needs
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A CUSTOMER NEEDS ANALYST, not content generator
+- 💬 FOCUS on customer pain points, challenges, and unmet needs
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after pain points content generation
+- 📝 WRITE CUSTOMER PAIN POINTS ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Customer behavior analysis completed in previous step
+- Focus on customer pain points, challenges, and unmet needs
+- Web search capabilities with source verification are enabled
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+
+## YOUR TASK:
+
+Conduct customer pain points and needs analysis with emphasis on challenges and frustrations.
+
+## CUSTOMER PAIN POINTS ANALYSIS SEQUENCE:
+
+### 1. Begin Customer Pain Points Analysis
+
+**UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different customer pain point areas simultaneously and thoroughly.
+
+Start with customer pain points research approach:
+"Now I'll conduct **customer pain points analysis** for **{{research_topic}}** to understand customer challenges.
+
+**Customer Pain Points Focus:**
+
+- Customer challenges and frustrations
+- Unmet needs and unaddressed problems
+- Barriers to adoption or usage
+- Service and support pain points
+- Customer satisfaction gaps
+
+**Let me search for current customer pain points insights.**"
+
+### 2. Parallel Pain Points Research Execution
+
+**Execute multiple web searches simultaneously:**
+
+Search the web: "{{research_topic}} customer pain points challenges"
+Search the web: "{{research_topic}} customer frustrations"
+Search the web: "{{research_topic}} unmet customer needs"
+Search the web: "{{research_topic}} customer barriers to adoption"
+
+**Analysis approach:**
+
+- Look for customer satisfaction surveys and reports
+- Search for customer complaints and reviews
+- Research customer support and service issues
+- Analyze barriers to customer adoption
+- Study unmet needs and market gaps
+
+### 3. Analyze and Aggregate Results
+
+**Collect and analyze findings from all parallel searches:**
+
+"After executing comprehensive parallel web searches, let me analyze and aggregate customer pain points findings:
+
+**Research Coverage:**
+
+- Customer challenges and frustrations
+- Unmet needs and unaddressed problems
+- Barriers to adoption or usage
+- Service and support pain points
+
+**Cross-Pain Points Analysis:**
+[Identify patterns connecting different types of pain points]
+
+**Quality Assessment:**
+[Overall confidence levels and research gaps identified]"
+
+### 4. Generate Customer Pain Points Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare customer pain points analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Customer Pain Points and Needs
+
+### Customer Challenges and Frustrations
+
+[Customer challenges analysis with source citations]
+_Primary Frustrations: [Major customer frustrations identified]_
+_Usage Barriers: [Barriers preventing effective usage]_
+_Service Pain Points: [Customer service and support issues]_
+_Frequency Analysis: [How often these challenges occur]_
+_Source: [URL]_
+
+### Unmet Customer Needs
+
+[Unmet needs analysis with source citations]
+_Critical Unmet Needs: [Most important unaddressed needs]_
+_Solution Gaps: [Opportunities to address unmet needs]_
+_Market Gaps: [Market opportunities from unmet needs]_
+_Priority Analysis: [Which needs are most critical]_
+_Source: [URL]_
+
+### Barriers to Adoption
+
+[Adoption barriers analysis with source citations]
+_Price Barriers: [Cost-related barriers to adoption]_
+_Technical Barriers: [Complexity or technical barriers]_
+_Trust Barriers: [Trust and credibility issues]_
+_Convenience Barriers: [Ease of use or accessibility issues]_
+_Source: [URL]_
+
+### Service and Support Pain Points
+
+[Service pain points analysis with source citations]
+_Customer Service Issues: [Common customer service problems]_
+_Support Gaps: [Areas where customer support is lacking]_
+_Communication Issues: [Communication breakdowns and frustrations]_
+_Response Time Issues: [Slow response and resolution problems]_
+_Source: [URL]_
+
+### Customer Satisfaction Gaps
+
+[Satisfaction gap analysis with source citations]
+_Expectation Gaps: [Differences between expectations and reality]_
+_Quality Gaps: [Areas where quality expectations aren't met]_
+_Value Perception Gaps: [Perceived value vs actual value]_
+_Trust and Credibility Gaps: [Trust issues affecting satisfaction]_
+_Source: [URL]_
+
+### Emotional Impact Assessment
+
+[Emotional impact analysis with source citations]
+_Frustration Levels: [Customer frustration severity assessment]_
+_Loyalty Risks: [How pain points affect customer loyalty]_
+_Reputation Impact: [Impact on brand or product reputation]_
+_Customer Retention Risks: [Risk of customer loss from pain points]_
+_Source: [URL]_
+
+### Pain Point Prioritization
+
+[Pain point prioritization with source citations]
+_High Priority Pain Points: [Most critical pain points to address]_
+_Medium Priority Pain Points: [Important but less critical pain points]_
+_Low Priority Pain Points: [Minor pain points with lower impact]_
+_Opportunity Mapping: [Pain points with highest solution opportunity]_
+_Source: [URL]_
+```
+
+### 5. Present Analysis and Continue Option
+
+**Show analysis and present continue option:**
+
+"I've completed **customer pain points analysis** for {{research_topic}}, focusing on customer challenges.
+
+**Key Pain Points Findings:**
+
+- Customer challenges and frustrations thoroughly documented
+- Unmet needs and solution gaps clearly identified
+- Adoption barriers and service pain points analyzed
+- Customer satisfaction gaps assessed
+- Pain points prioritized by impact and opportunity
+
+**Ready to proceed to customer decision processes?**
+[C] Continue - Save this to document and proceed to decision processes analysis
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2, 3]`
+- Load: `./step-04-customer-decisions.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 4. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Customer challenges and frustrations clearly documented
+✅ Unmet needs and solution gaps identified
+✅ Adoption barriers and service pain points analyzed
+✅ Customer satisfaction gaps assessed
+✅ Pain points prioritized by impact and opportunity
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (customer decisions)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical customer challenges or frustrations
+❌ Not identifying unmet needs or solution gaps
+❌ Incomplete adoption barriers analysis
+❌ Not writing content immediately to document
+❌ Not presenting [C] continue option after content generation
+❌ Not routing to customer decisions analysis step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## CUSTOMER PAIN POINTS RESEARCH PROTOCOLS:
+
+- Research customer satisfaction surveys and reviews
+- Use customer feedback and complaint data
+- Analyze customer support and service issues
+- Study barriers to customer adoption
+- Focus on current pain point data
+- Present conflicting information when sources disagree
+- Apply confidence levels appropriately
+
+## PAIN POINTS ANALYSIS STANDARDS:
+
+- Always cite URLs for web search results
+- Use authoritative customer research sources
+- Note data currency and potential limitations
+- Present multiple perspectives when sources conflict
+- Apply confidence levels to uncertain data
+- Focus on actionable pain point insights
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-04-customer-decisions.md` to analyze customer decision processes, journey mapping, and decision factors for {{research_topic}}.
+
+Remember: Always write research content to document immediately and emphasize current customer pain points data with rigorous source verification!

src/bmm/workflows/1-analysis/research/bmad-market-research/steps/step-04-customer-decisions.md

@@ -0,0 +1,261 @@
+# Market Research Step 4: Customer Decisions and Journey
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A CUSTOMER DECISION ANALYST, not content generator
+- 💬 FOCUS on customer decision processes and journey mapping
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after decision processes content generation
+- 📝 WRITE CUSTOMER DECISIONS ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Customer behavior and pain points analysis completed in previous steps
+- Focus on customer decision processes and journey mapping
+- Web search capabilities with source verification are enabled
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+
+## YOUR TASK:
+
+Conduct customer decision processes and journey analysis with emphasis on decision factors and journey mapping.
+
+## CUSTOMER DECISIONS ANALYSIS SEQUENCE:
+
+### 1. Begin Customer Decisions Analysis
+
+**UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different customer decision areas simultaneously and thoroughly.
+
+Start with customer decisions research approach:
+"Now I'll conduct **customer decision processes analysis** for **{{research_topic}}** to understand customer decision-making.
+
+**Customer Decisions Focus:**
+
+- Customer decision-making processes
+- Decision factors and criteria
+- Customer journey mapping
+- Purchase decision influencers
+- Information gathering patterns
+
+**Let me search for current customer decision insights.**"
+
+### 2. Parallel Decisions Research Execution
+
+**Execute multiple web searches simultaneously:**
+
+Search the web: "{{research_topic}} customer decision process"
+Search the web: "{{research_topic}} buying criteria factors"
+Search the web: "{{research_topic}} customer journey mapping"
+Search the web: "{{research_topic}} decision influencing factors"
+
+**Analysis approach:**
+
+- Look for customer decision research studies
+- Search for buying criteria and factor analysis
+- Research customer journey mapping methodologies
+- Analyze decision influence factors and channels
+- Study information gathering and evaluation patterns
+
+### 3. Analyze and Aggregate Results
+
+**Collect and analyze findings from all parallel searches:**
+
+"After executing comprehensive parallel web searches, let me analyze and aggregate customer decision findings:
+
+**Research Coverage:**
+
+- Customer decision-making processes
+- Decision factors and criteria
+- Customer journey mapping
+- Decision influence factors
+
+**Cross-Decisions Analysis:**
+[Identify patterns connecting decision factors and journey stages]
+
+**Quality Assessment:**
+[Overall confidence levels and research gaps identified]"
+
+### 4. Generate Customer Decisions Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare customer decisions analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Customer Decision Processes and Journey
+
+### Customer Decision-Making Processes
+
+[Decision processes analysis with source citations]
+_Decision Stages: [Key stages in customer decision making]_
+_Decision Timelines: [Timeframes for different decisions]_
+_Complexity Levels: [Decision complexity assessment]_
+_Evaluation Methods: [How customers evaluate options]_
+_Source: [URL]_
+
+### Decision Factors and Criteria
+
+[Decision factors analysis with source citations]
+_Primary Decision Factors: [Most important factors in decisions]_
+_Secondary Decision Factors: [Supporting factors influencing decisions]_
+_Weighing Analysis: [How different factors are weighed]_
+_Evoluton Patterns: [How factors change over time]_
+_Source: [URL]_
+
+### Customer Journey Mapping
+
+[Journey mapping analysis with source citations]
+_Awareness Stage: [How customers become aware of {{research_topic}}]_
+_Consideration Stage: [Evaluation and comparison process]_
+_Decision Stage: [Final decision-making process]_
+_Purchase Stage: [Purchase execution and completion]_
+_Post-Purchase Stage: [Post-decision evaluation and behavior]_
+_Source: [URL]_
+
+### Touchpoint Analysis
+
+[Touchpoint analysis with source citations]
+_Digital Touchpoints: [Online and digital interaction points]_
+_Offline Touchpoints: [Physical and in-person interaction points]_
+_Information Sources: [Where customers get information]_
+_Influence Channels: [What influences customer decisions]_
+_Source: [URL]_
+
+### Information Gathering Patterns
+
+[Information patterns analysis with source citations]
+_Research Methods: [How customers research options]_
+_Information Sources Trusted: [Most trusted information sources]_
+_Research Duration: [Time spent gathering information]_
+_Evaluation Criteria: [How customers evaluate information]_
+_Source: [URL]_
+
+### Decision Influencers
+
+[Decision influencer analysis with source citations]
+_Peer Influence: [How friends and family influence decisions]_
+_Expert Influence: [How expert opinions affect decisions]_
+_Media Influence: [How media and marketing affect decisions]_
+_Social Proof Influence: [How reviews and testimonials affect decisions]_
+_Source: [URL]_
+
+### Purchase Decision Factors
+
+[Purchase decision factors analysis with source citations]
+_Immediate Purchase Drivers: [Factors triggering immediate purchase]_
+_Delayed Purchase Drivers: [Factors causing purchase delays]_
+_Brand Loyalty Factors: [Factors driving repeat purchases]_
+_Price Sensitivity: [How price affects purchase decisions]_
+_Source: [URL]_
+
+### Customer Decision Optimizations
+
+[Decision optimization analysis with source citations]
+_Friction Reduction: [Ways to make decisions easier]_
+_Trust Building: [Building customer trust in decisions]_
+_Conversion Optimization: [Optimizing decision-to-purchase rates]_
+_Loyalty Building: [Building long-term customer relationships]_
+_Source: [URL]_
+```
+
+### 5. Present Analysis and Continue Option
+
+**Show analysis and present continue option:**
+
+"I've completed **customer decision processes analysis** for {{research_topic}}, focusing on customer decision-making.
+
+**Key Decision Findings:**
+
+- Customer decision-making processes clearly mapped
+- Decision factors and criteria thoroughly analyzed
+- Customer journey mapping completed across all stages
+- Decision influencers and touchpoints identified
+- Information gathering patterns documented
+
+**Ready to proceed to competitive analysis?**
+[C] Continue - Save this to document and proceed to competitive analysis
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
+- Load: `./step-05-competitive-analysis.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 4. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Customer decision-making processes clearly mapped
+✅ Decision factors and criteria thoroughly analyzed
+✅ Customer journey mapping completed across all stages
+✅ Decision influencers and touchpoints identified
+✅ Information gathering patterns documented
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (competitive analysis)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical decision-making process stages
+❌ Not identifying key decision factors
+❌ Incomplete customer journey mapping
+❌ Not writing content immediately to document
+❌ Not presenting [C] continue option after content generation
+❌ Not routing to competitive analysis step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## CUSTOMER DECISIONS RESEARCH PROTOCOLS:
+
+- Research customer decision studies and psychology
+- Use customer journey mapping methodologies
+- Analyze buying criteria and decision factors
+- Study decision influence and touchpoint analysis
+- Focus on current decision data
+- Present conflicting information when sources disagree
+- Apply confidence levels appropriately
+
+## DECISION ANALYSIS STANDARDS:
+
+- Always cite URLs for web search results
+- Use authoritative customer decision research sources
+- Note data currency and potential limitations
+- Present multiple perspectives when sources conflict
+- Apply confidence levels to uncertain data
+- Focus on actionable decision insights
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-05-competitive-analysis.md` to analyze competitive landscape, market positioning, and competitive strategies for {{research_topic}}.
+
+Remember: Always write research content to document immediately and emphasize current customer decision data with rigorous source verification!

src/bmm/workflows/1-analysis/research/bmad-market-research/steps/step-05-competitive-analysis.md

@@ -0,0 +1,173 @@
+# Market Research Step 5: Competitive Analysis
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A COMPETITIVE ANALYST, not content generator
+- 💬 FOCUS on competitive landscape and market positioning
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] complete option after competitive analysis content generation
+- 💾 ONLY save when user chooses C (Complete)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before completing workflow
+- 🚫 FORBIDDEN to complete workflow until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Focus on competitive landscape and market positioning analysis
+- Web search capabilities with source verification are enabled
+- May need to search for specific competitor information
+
+## YOUR TASK:
+
+Conduct comprehensive competitive analysis with emphasis on market positioning.
+
+## COMPETITIVE ANALYSIS SEQUENCE:
+
+### 1. Begin Competitive Analysis
+
+Start with competitive research approach:
+"Now I'll conduct **competitive analysis** to understand the competitive landscape.
+
+**Competitive Analysis Focus:**
+
+- Key players and market share
+- Competitive positioning strategies
+- Strengths and weaknesses analysis
+- Market differentiation opportunities
+- Competitive threats and challenges
+
+**Let me search for current competitive information.**"
+
+### 2. Generate Competitive Analysis Content
+
+Prepare competitive analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Competitive Landscape
+
+### Key Market Players
+
+[Key players analysis with market share data]
+_Source: [URL]_
+
+### Market Share Analysis
+
+[Market share analysis with source citations]
+_Source: [URL]_
+
+### Competitive Positioning
+
+[Positioning analysis with source citations]
+_Source: [URL]_
+
+### Strengths and Weaknesses
+
+[SWOT analysis with source citations]
+_Source: [URL]_
+
+### Market Differentiation
+
+[Differentiation analysis with source citations]
+_Source: [URL]_
+
+### Competitive Threats
+
+[Threats analysis with source citations]
+_Source: [URL]_
+
+### Opportunities
+
+[Competitive opportunities analysis with source citations]
+_Source: [URL]_
+```
+
+### 3. Present Analysis and Complete Option
+
+Show the generated competitive analysis and present complete option:
+"I've completed the **competitive analysis** for the competitive landscape.
+
+**Key Competitive Findings:**
+
+- Key market players and market share identified
+- Competitive positioning strategies mapped
+- Strengths and weaknesses thoroughly analyzed
+- Market differentiation opportunities identified
+- Competitive threats and challenges documented
+
+**Ready to complete the market research?**
+[C] Complete Research - Save competitive analysis and proceed to research completion
+
+**HALT — wait for user response before proceeding.**
+
+### 4. Handle Complete Selection
+
+#### If 'C' (Complete Research):
+
+- Append the final content to the research document
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
+- Load: `./step-06-research-completion.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the research document using the structure from step 2.
+
+## SUCCESS METRICS:
+
+✅ Key market players identified
+✅ Market share analysis completed with source verification
+✅ Competitive positioning strategies clearly mapped
+✅ Strengths and weaknesses thoroughly analyzed
+✅ Market differentiation opportunities identified
+✅ [C] complete option presented and handled correctly
+✅ Content properly appended to document when C selected
+✅ Market research workflow completed successfully
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing key market players or market share data
+❌ Incomplete competitive positioning analysis
+❌ Not identifying market differentiation opportunities
+❌ Not presenting completion option for research workflow
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## COMPETITIVE RESEARCH PROTOCOLS:
+
+- Search for industry reports and competitive intelligence
+- Use competitor company websites and annual reports
+- Research market research firm competitive analyses
+- Note competitive advantages and disadvantages
+- Search for recent market developments and disruptions
+
+## MARKET RESEARCH COMPLETION:
+
+When 'C' is selected:
+
+- All market research steps completed
+- Comprehensive market research document generated
+- All sections appended with source citations
+- Market research workflow status updated
+- Final recommendations provided to user
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-06-research-completion.md` to produce the final comprehensive market research document with strategic synthesis, executive summary, and complete document structure.

src/bmm/workflows/1-analysis/research/bmad-market-research/steps/step-06-research-completion.md

@@ -0,0 +1,478 @@
+# Market Research Step 6: Research Completion
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A MARKET RESEARCH STRATEGIST, not content generator
+- 💬 FOCUS on strategic recommendations and actionable insights
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] complete option after completion content generation
+- 💾 ONLY save when user chooses C (Complete)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` before completing workflow
+- 🚫 FORBIDDEN to complete workflow until C is selected
+- 📚 GENERATE COMPLETE DOCUMENT STRUCTURE with intro, TOC, and summary
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- **Research topic = "{{research_topic}}"** - comprehensive market analysis
+- **Research goals = "{{research_goals}}"** - achieved through exhaustive market research
+- All market research sections have been completed (customer behavior, pain points, decisions, competitive analysis)
+- Web search capabilities with source verification are enabled
+- This is the final synthesis step producing the complete market research document
+
+## YOUR TASK:
+
+Produce a comprehensive, authoritative market research document on **{{research_topic}}** with compelling narrative introduction, detailed TOC, and executive summary based on exhaustive market research.
+
+## MARKET RESEARCH COMPLETION SEQUENCE:
+
+### 1. Begin Strategic Synthesis
+
+Start with strategic synthesis approach:
+"Now I'll complete our market research with **strategic synthesis and recommendations** .
+
+**Strategic Synthesis Focus:**
+
+- Integrated insights from market, customer, and competitive analysis
+- Strategic recommendations based on research findings
+- Market entry or expansion strategies
+- Risk assessment and mitigation approaches
+- Actionable next steps and implementation guidance
+
+**Let me search for current strategic insights and best practices.**"
+
+### 2. Web Search for Market Entry Strategies
+
+Search for current market strategies:
+Search the web: "market entry strategies best practices"
+
+**Strategy focus:**
+
+- Market entry timing and approaches
+- Go-to-market strategies and frameworks
+- Market positioning and differentiation tactics
+- Customer acquisition and growth strategies
+
+### 3. Web Search for Risk Assessment
+
+Search for current risk approaches:
+Search the web: "market research risk assessment frameworks"
+
+**Risk focus:**
+
+- Market risks and uncertainty management
+- Competitive threats and mitigation strategies
+- Regulatory and compliance risks
+- Economic and market volatility considerations
+
+### 4. Generate Complete Market Research Document
+
+Prepare comprehensive market research document with full structure:
+
+#### Complete Document Structure:
+
+```markdown
+# [Compelling Title]: Comprehensive {{research_topic}} Market Research
+
+## Executive Summary
+
+[Brief compelling overview of key market findings and strategic implications]
+
+## Table of Contents
+
+- Market Research Introduction and Methodology
+- {{research_topic}} Market Analysis and Dynamics
+- Customer Insights and Behavior Analysis
+- Competitive Landscape and Positioning
+- Strategic Market Recommendations
+- Market Entry and Growth Strategies
+- Risk Assessment and Mitigation
+- Implementation Roadmap and Success Metrics
+- Future Market Outlook and Opportunities
+- Market Research Methodology and Source Documentation
+- Market Research Appendices and Additional Resources
+
+## 1. Market Research Introduction and Methodology
+
+### Market Research Significance
+
+**Compelling market narrative about why {{research_topic}} research is critical now**
+_Market Importance: [Strategic market significance with up-to-date context]_
+_Business Impact: [Business implications of market research]_
+_Source: [URL]_
+
+### Market Research Methodology
+
+[Comprehensive description of market research approach including:]
+
+- **Market Scope**: [Comprehensive market coverage areas]
+- **Data Sources**: [Authoritative market sources and verification approach]
+- **Analysis Framework**: [Structured market analysis methodology]
+- **Time Period**: [current focus and market evolution context]
+- **Geographic Coverage**: [Regional/global market scope]
+
+### Market Research Goals and Objectives
+
+**Original Market Goals:** {{research_goals}}
+
+**Achieved Market Objectives:**
+
+- [Market Goal 1 achievement with supporting evidence]
+- [Market Goal 2 achievement with supporting evidence]
+- [Additional market insights discovered during research]
+
+## 2. {{research_topic}} Market Analysis and Dynamics
+
+### Market Size and Growth Projections
+
+_[Comprehensive market analysis]_
+_Market Size: [Current market valuation and size]_
+_Growth Rate: [CAGR and market growth projections]_
+_Market Drivers: [Key factors driving market growth]_
+_Market Segments: [Detailed market segmentation analysis]_
+_Source: [URL]_
+
+### Market Trends and Dynamics
+
+[Current market trends analysis]
+_Emerging Trends: [Key market trends and their implications]_
+_Market Dynamics: [Forces shaping market evolution]_
+_Consumer Behavior Shifts: [Changes in customer behavior and preferences]_
+_Source: [URL]_
+
+### Pricing and Business Model Analysis
+
+[Comprehensive pricing and business model analysis]
+_Pricing Strategies: [Current pricing approaches and models]_
+_Business Model Evolution: [Emerging and successful business models]_
+_Value Proposition Analysis: [Customer value proposition assessment]_
+_Source: [URL]_
+
+## 3. Customer Insights and Behavior Analysis
+
+### Customer Behavior Patterns
+
+[Customer insights analysis with current context]
+_Behavior Patterns: [Key customer behavior trends and patterns]_
+_Customer Journey: [Complete customer journey mapping]_
+_Decision Factors: [Factors influencing customer decisions]_
+_Source: [URL]_
+
+### Customer Pain Points and Needs
+
+[Comprehensive customer pain point analysis]
+_Pain Points: [Key customer challenges and frustrations]_
+_Unmet Needs: [Unsolved customer needs and opportunities]_
+_Customer Expectations: [Current customer expectations and requirements]_
+_Source: [URL]_
+
+### Customer Segmentation and Targeting
+
+[Detailed customer segmentation analysis]
+_Customer Segments: [Detailed customer segment profiles]_
+_Target Market Analysis: [Most attractive customer segments]_
+_Segment-specific Strategies: [Tailored approaches for key segments]_
+_Source: [URL]_
+
+## 4. Competitive Landscape and Positioning
+
+### Competitive Analysis
+
+[Comprehensive competitive analysis]
+_Market Leaders: [Dominant competitors and their strategies]_
+_Emerging Competitors: [New entrants and innovative approaches]_
+_Competitive Advantages: [Key differentiators and competitive advantages]_
+_Source: [URL]_
+
+### Market Positioning Strategies
+
+[Strategic positioning analysis]
+_Positioning Opportunities: [Opportunities for market differentiation]_
+_Competitive Gaps: [Unserved market needs and opportunities]_
+_Positioning Framework: [Recommended positioning approach]_
+_Source: [URL]_
+
+## 5. Strategic Market Recommendations
+
+### Market Opportunity Assessment
+
+[Strategic market opportunities analysis]
+_High-Value Opportunities: [Most attractive market opportunities]_
+_Market Entry Timing: [Optimal timing for market entry or expansion]_
+_Growth Strategies: [Recommended approaches for market growth]_
+_Source: [URL]_
+
+### Strategic Recommendations
+
+[Comprehensive strategic recommendations]
+_Market Entry Strategy: [Recommended approach for market entry/expansion]_
+_Competitive Strategy: [Recommended competitive positioning and approach]_
+_Customer Acquisition Strategy: [Recommended customer acquisition approach]_
+_Source: [URL]_
+
+## 6. Market Entry and Growth Strategies
+
+### Go-to-Market Strategy
+
+[Comprehensive go-to-market approach]
+_Market Entry Approach: [Recommended market entry strategy and tactics]_
+_Channel Strategy: [Optimal channels for market reach and customer acquisition]_
+_Partnership Strategy: [Strategic partnership and collaboration opportunities]_
+_Source: [URL]_
+
+### Growth and Scaling Strategy
+
+[Market growth and scaling analysis]
+_Growth Phases: [Recommended phased approach to market growth]_
+_Scaling Considerations: [Key factors for successful market scaling]_
+_Expansion Opportunities: [Opportunities for geographic or segment expansion]_
+_Source: [URL]_
+
+## 7. Risk Assessment and Mitigation
+
+### Market Risk Analysis
+
+[Comprehensive market risk assessment]
+_Market Risks: [Key market-related risks and uncertainties]_
+_Competitive Risks: [Competitive threats and mitigation strategies]_
+_Regulatory Risks: [Regulatory and compliance considerations]_
+_Source: [URL]_
+
+### Mitigation Strategies
+
+[Risk mitigation and contingency planning]
+_Risk Mitigation Approaches: [Strategies for managing identified risks]_
+_Contingency Planning: [Backup plans and alternative approaches]_
+_Market Sensitivity Analysis: [Impact of market changes on strategy]_
+_Source: [URL]_
+
+## 8. Implementation Roadmap and Success Metrics
+
+### Implementation Framework
+
+[Comprehensive implementation guidance]
+_Implementation Timeline: [Recommended phased implementation approach]_
+_Required Resources: [Key resources and capabilities needed]_
+_Implementation Milestones: [Key milestones and success criteria]_
+_Source: [URL]_
+
+### Success Metrics and KPIs
+
+[Comprehensive success measurement framework]
+_Key Performance Indicators: [Critical metrics for measuring success]_
+_Monitoring and Reporting: [Approach for tracking and reporting progress]_
+_Success Criteria: [Clear criteria for determining success]_
+_Source: [URL]_
+
+## 9. Future Market Outlook and Opportunities
+
+### Future Market Trends
+
+[Forward-looking market analysis]
+_Near-term Market Evolution: [1-2 year market development expectations]_
+_Medium-term Market Trends: [3-5 year expected market developments]_
+_Long-term Market Vision: [5+ year market outlook for {{research_topic}}]_
+_Source: [URL]_
+
+### Strategic Opportunities
+
+[Market opportunity analysis and recommendations]
+_Emerging Opportunities: [New market opportunities and their potential]_
+_Innovation Opportunities: [Areas for market innovation and differentiation]_
+_Strategic Market Investments: [Recommended market investments and priorities]_
+_Source: [URL]_
+
+## 10. Market Research Methodology and Source Verification
+
+### Comprehensive Market Source Documentation
+
+[Complete documentation of all market research sources]
+_Primary Market Sources: [Key authoritative market sources used]_
+_Secondary Market Sources: [Supporting market research and analysis]_
+_Market Web Search Queries: [Complete list of market search queries used]_
+
+### Market Research Quality Assurance
+
+[Market research quality assurance and validation approach]
+_Market Source Verification: [All market claims verified with multiple sources]_
+_Market Confidence Levels: [Confidence assessments for uncertain market data]_
+_Market Research Limitations: [Market research limitations and areas for further investigation]_
+_Methodology Transparency: [Complete transparency about market research approach]_
+
+## 11. Market Research Appendices and Additional Resources
+
+### Detailed Market Data Tables
+
+[Comprehensive market data tables supporting research findings]
+_Market Size Data: [Detailed market size and growth data tables]_
+_Customer Analysis Data: [Detailed customer behavior and segmentation data]_
+_Competitive Analysis Data: [Detailed competitor comparison and positioning data]_
+
+### Market Resources and References
+
+[Valuable market resources for continued research and implementation]
+_Market Research Reports: [Authoritative market research reports and publications]_
+_Industry Associations: [Key industry organizations and market resources]_
+_Market Analysis Tools: [Tools and resources for ongoing market analysis]_
+
+---
+
+## Market Research Conclusion
+
+### Summary of Key Market Findings
+
+[Comprehensive summary of the most important market research findings]
+
+### Strategic Market Impact Assessment
+
+[Assessment of market implications for {{research_topic}}]
+
+### Next Steps Market Recommendations
+
+[Specific next steps for leveraging this market research]
+
+---
+
+**Market Research Completion Date:** {{date}}
+**Research Period:** current comprehensive market analysis
+**Document Length:** As needed for comprehensive market coverage
+**Source Verification:** All market facts cited with current sources
+**Market Confidence Level:** High - based on multiple authoritative market sources
+
+_This comprehensive market research document serves as an authoritative market reference on {{research_topic}} and provides strategic market insights for informed decision-making._
+```
+
+### 5. Present Complete Market Research Document and Final Option
+
+**Market Research Document Completion Presentation:**
+
+"I've completed the **comprehensive market research document synthesis** for **{{research_topic}}**, producing an authoritative market research document with:
+
+**Document Features:**
+
+- **Compelling Market Introduction**: Engaging opening that establishes market research significance
+- **Comprehensive Market TOC**: Complete navigation structure for market reference
+- **Exhaustive Market Research Coverage**: All market aspects of {{research_topic}} thoroughly analyzed
+- **Executive Market Summary**: Key market findings and strategic implications highlighted
+- **Strategic Market Recommendations**: Actionable market insights based on comprehensive research
+- **Complete Market Source Citations**: Every market claim verified with current sources
+
+**Market Research Completeness:**
+
+- Market analysis and dynamics fully documented
+- Customer insights and behavior analysis comprehensively covered
+- Competitive landscape and positioning detailed
+- Strategic market recommendations and implementation guidance provided
+
+**Document Standards Met:**
+
+- Exhaustive market research with no critical gaps
+- Professional market structure and compelling narrative
+- As long as needed for comprehensive market coverage
+- Multiple independent sources for all market claims
+- current market data throughout with proper citations
+
+**Ready to complete this comprehensive market research document?**
+[C] Complete Research - Save final comprehensive market research document
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Complete Selection
+
+#### If 'C' (Complete Research):
+
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
+- Append the final content to the research document
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
+- Complete the market research workflow
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the research document using the structure from step 4. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
+
+## SUCCESS METRICS:
+
+✅ Compelling market introduction with research significance
+✅ Comprehensive market table of contents with complete document structure
+✅ Exhaustive market research coverage across all market aspects
+✅ Executive market summary with key findings and strategic implications
+✅ Strategic market recommendations grounded in comprehensive research
+✅ Complete market source verification with current citations
+✅ Professional market document structure and compelling narrative
+✅ [C] complete option presented and handled correctly
+✅ Market research workflow completed with comprehensive document
+
+## FAILURE MODES:
+
+❌ Not producing compelling market introduction
+❌ Missing comprehensive market table of contents
+❌ Incomplete market research coverage across market aspects
+❌ Not providing executive market summary with key findings
+❌ Missing strategic market recommendations based on research
+❌ Relying solely on training data without web verification for current facts
+❌ Producing market document without professional structure
+❌ Not presenting completion option for final market document
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## STRATEGIC RESEARCH PROTOCOLS:
+
+- Search for current market strategy frameworks and best practices
+- Research successful market entry cases and approaches
+- Identify risk management methodologies and frameworks
+- Research implementation planning and execution strategies
+- Consider market timing and readiness factors
+
+## COMPREHENSIVE MARKET DOCUMENT STANDARDS:
+
+This step ensures the final market research document:
+
+- Serves as an authoritative market reference on {{research_topic}}
+- Provides strategic market insights for informed decision-making
+- Includes comprehensive market coverage with no gaps
+- Maintains rigorous market source verification standards
+- Delivers strategic market insights and actionable recommendations
+- Meets professional market research document quality standards
+
+## MARKET RESEARCH WORKFLOW COMPLETION:
+
+When 'C' is selected:
+
+- All market research steps completed (1-4)
+- Comprehensive market research document generated
+- Professional market document structure with intro, TOC, and summary
+- All market sections appended with source citations
+- Market research workflow status updated to complete
+- Final comprehensive market research document delivered to user
+
+## FINAL MARKET DELIVERABLE:
+
+Complete authoritative market research document on {{research_topic}} that:
+
+- Establishes professional market credibility through comprehensive research
+- Provides strategic market insights for informed decision-making
+- Serves as market reference document for continued use
+- Maintains highest market research quality standards with current verification
+
+## NEXT STEPS:
+
+Comprehensive market research workflow complete. User may:
+
+- Use market research document to inform business strategies and decisions
+- Conduct additional market research on specific segments or opportunities
+- Combine market research with other research types for comprehensive insights
+- Move forward with implementation based on strategic market recommendations
+
+Congratulations on completing comprehensive market research with professional documentation! 🎉

src/bmm/workflows/1-analysis/research/bmad-market-research/workflow.md

@@ -1,8 +1,3 @@
----
-name: market-research
-description: 'Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".'
----
-
 # Market Research Workflow
 
 **Goal:** Conduct comprehensive market research using current web data and verified sources to produce complete research documents with compelling narratives and proper citations.
@@ -47,7 +42,7 @@ After gathering the topic and goals:
 2. Set `research_topic = [discovered topic from discussion]`
 3. Set `research_goals = [discovered goals from discussion]`
 4. Create the starter output file: `{planning_artifacts}/research/market-{{research_topic}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents
-5. Load: `./market-steps/step-01-init.md` with topic context
+5. Load: `./steps/step-01-init.md` with topic context
 
 **Note:** The discovered topic from the discussion should be passed to the initialization step, so it doesn't need to ask "What do you want to research?" again - it can focus on refining the scope for market research.
 

src/bmm/workflows/1-analysis/research/bmad-skill-manifest.yaml

@@ -1,4 +0,0 @@
-workflow-market-research.md:
-  canonicalId: bmad-market-research
-  type: workflow
-  description: "Conduct market research on competition and customers. Use when the user says 'create a market research report about [business idea]'"

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-02-discovery.md

@@ -30,8 +30,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-03-core-experience.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -162,7 +162,7 @@ Show the generated core experience content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current core experience content
+- Invoke the `bmad-advanced-elicitation` skill with the current core experience content
 - Process the enhanced experience insights that come back
 - Ask user: "Accept these improvements to the core experience definition? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -170,7 +170,7 @@ Show the generated core experience content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current core experience definition
+- Invoke the `bmad-party-mode` skill with the current core experience definition
 - Process the collaborative experience improvements that come back
 - Ask user: "Accept these changes to the core experience definition? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-04-emotional-response.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -165,7 +165,7 @@ Show the generated emotional response content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current emotional response content
+- Invoke the `bmad-advanced-elicitation` skill with the current emotional response content
 - Process the enhanced emotional insights that come back
 - Ask user: "Accept these improvements to the emotional response definition? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -173,7 +173,7 @@ Show the generated emotional response content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current emotional response definition
+- Invoke the `bmad-party-mode` skill with the current emotional response definition
 - Process the collaborative emotional insights that come back
 - Ask user: "Accept these changes to the emotional response definition? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-05-inspiration.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -180,7 +180,7 @@ Show the generated inspiration analysis content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current inspiration analysis content
+- Invoke the `bmad-advanced-elicitation` skill with the current inspiration analysis content
 - Process the enhanced pattern insights that come back
 - Ask user: "Accept these improvements to the inspiration analysis? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -188,7 +188,7 @@ Show the generated inspiration analysis content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current inspiration analysis
+- Invoke the `bmad-party-mode` skill with the current inspiration analysis
 - Process the collaborative pattern insights that come back
 - Ask user: "Accept these changes to the inspiration analysis? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-06-design-system.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -198,7 +198,7 @@ Show the generated design system content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current design system content
+- Invoke the `bmad-advanced-elicitation` skill with the current design system content
 - Process the enhanced design system insights that come back
 - Ask user: "Accept these improvements to the design system decision? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -206,7 +206,7 @@ Show the generated design system content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current design system choice
+- Invoke the `bmad-party-mode` skill with the current design system choice
 - Process the collaborative design system insights that come back
 - Ask user: "Accept these changes to the design system decision? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-07-defining-experience.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -200,7 +200,7 @@ Show the generated defining experience content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current defining experience content
+- Invoke the `bmad-advanced-elicitation` skill with the current defining experience content
 - Process the enhanced experience insights that come back
 - Ask user: "Accept these improvements to the defining experience? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -208,7 +208,7 @@ Show the generated defining experience content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current defining experience
+- Invoke the `bmad-party-mode` skill with the current defining experience
 - Process the collaborative experience insights that come back
 - Ask user: "Accept these changes to the defining experience? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-08-visual-foundation.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -170,7 +170,7 @@ Show the generated visual foundation content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current visual foundation content
+- Invoke the `bmad-advanced-elicitation` skill with the current visual foundation content
 - Process the enhanced visual insights that come back
 - Ask user: "Accept these improvements to the visual foundation? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -178,7 +178,7 @@ Show the generated visual foundation content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current visual foundation
+- Invoke the `bmad-party-mode` skill with the current visual foundation
 - Process the collaborative visual insights that come back
 - Ask user: "Accept these changes to the visual foundation? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-09-design-directions.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -170,7 +170,7 @@ Show the generated design direction content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current design direction content
+- Invoke the `bmad-advanced-elicitation` skill with the current design direction content
 - Process the enhanced design insights that come back
 - Ask user: "Accept these improvements to the design direction? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -178,7 +178,7 @@ Show the generated design direction content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current design direction
+- Invoke the `bmad-party-mode` skill with the current design direction
 - Process the collaborative design insights that come back
 - Ask user: "Accept these changes to the design direction? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-10-user-journeys.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -188,7 +188,7 @@ Show the generated user journey content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current user journey content
+- Invoke the `bmad-advanced-elicitation` skill with the current user journey content
 - Process the enhanced journey insights that come back
 - Ask user: "Accept these improvements to the user journeys? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -196,7 +196,7 @@ Show the generated user journey content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current user journeys
+- Invoke the `bmad-party-mode` skill with the current user journeys
 - Process the collaborative journey insights that come back
 - Ask user: "Accept these changes to the user journeys? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-11-component-strategy.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -194,7 +194,7 @@ Show the generated component strategy content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current component strategy content
+- Invoke the `bmad-advanced-elicitation` skill with the current component strategy content
 - Process the enhanced component insights that come back
 - Ask user: "Accept these improvements to the component strategy? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -202,7 +202,7 @@ Show the generated component strategy content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current component strategy
+- Invoke the `bmad-party-mode` skill with the current component strategy
 - Process the collaborative component insights that come back
 - Ask user: "Accept these changes to the component strategy? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-12-ux-patterns.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -183,7 +183,7 @@ Show the generated UX patterns content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current UX patterns content
+- Invoke the `bmad-advanced-elicitation` skill with the current UX patterns content
 - Process the enhanced pattern insights that come back
 - Ask user: "Accept these improvements to the UX patterns? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -191,7 +191,7 @@ Show the generated UX patterns content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current UX patterns
+- Invoke the `bmad-party-mode` skill with the current UX patterns
 - Process the collaborative pattern insights that come back
 - Ask user: "Accept these changes to the UX patterns? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-create-ux-design/steps/step-13-responsive-accessibility.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -210,7 +210,7 @@ Show the generated responsive and accessibility content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with the current responsive/accessibility content
+- Invoke the `bmad-advanced-elicitation` skill with the current responsive/accessibility content
 - Process the enhanced insights that come back
 - Ask user: "Accept these improvements to the responsive/accessibility strategy? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
@@ -218,7 +218,7 @@ Show the generated responsive and accessibility content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current responsive/accessibility strategy
+- Invoke the `bmad-party-mode` skill with the current responsive/accessibility strategy
 - Process the collaborative insights that come back
 - Ask user: "Accept these changes to the responsive/accessibility strategy? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md

@@ -6,7 +6,7 @@ description: 'Discovery & Understanding - Understand what user wants to edit and
 altStepFile: './step-e-01b-legacy-conversion.md'
 prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step E-1: Discovery & Understanding

src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-01-discovery.md

@@ -5,7 +5,7 @@ description: 'Document Discovery & Confirmation - Handle fresh context validatio
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-02-format-detection.md'
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 prdPurpose: '../data/prd-purpose.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md

@@ -5,7 +5,7 @@ description: 'Document Discovery & Confirmation - Handle fresh context validatio
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-02-format-detection.md'
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 prdPurpose: '../data/prd-purpose.md'
 ---
 

src/bmm/workflows/3-solutioning/bmad-create-architecture/steps/step-02-context.md

@@ -32,7 +32,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -178,7 +178,7 @@ Show the generated content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current project context
+- Invoke the `bmad-party-mode` skill with the current project context
 - Process the collaborative improvements to architectural understanding
 - Ask user: "Accept these changes to the project context analysis? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/3-solutioning/bmad-create-architecture/steps/step-03-starter.md

@@ -31,8 +31,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -276,7 +276,7 @@ Show the generated content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with current starter analysis
+- Invoke the `bmad-advanced-elicitation` skill with current starter analysis
 - Process enhanced insights about starter options or custom approaches
 - Ask user: "Accept these changes to the starter template evaluation? (y/n)"
 - If yes: Update content, then return to A/P/C menu
@@ -284,7 +284,7 @@ Show the generated content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with starter evaluation context
+- Invoke the `bmad-party-mode` skill with starter evaluation context
 - Process collaborative insights about starter trade-offs
 - Ask user: "Accept these changes to the starter template evaluation? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/bmad-create-architecture/steps/step-04-decisions.md

@@ -32,8 +32,8 @@ This step will generate content and present choices for each decision category:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -264,7 +264,7 @@ Show the generated decisions content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with specific decision categories
+- Invoke the `bmad-advanced-elicitation` skill with specific decision categories
 - Process enhanced insights about particular decisions
 - Ask user: "Accept these enhancements to the architectural decisions? (y/n)"
 - If yes: Update content, then return to A/P/C menu
@@ -272,7 +272,7 @@ Show the generated decisions content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with architectural decisions context
+- Invoke the `bmad-party-mode` skill with architectural decisions context
 - Process collaborative insights about decision trade-offs
 - Ask user: "Accept these changes to the architectural decisions? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/bmad-create-architecture/steps/step-05-patterns.md

@@ -32,8 +32,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -305,7 +305,7 @@ Show the generated patterns content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with current patterns
+- Invoke the `bmad-advanced-elicitation` skill with current patterns
 - Process enhanced consistency rules that come back
 - Ask user: "Accept these additional pattern refinements? (y/n)"
 - If yes: Update content, then return to A/P/C menu
@@ -313,7 +313,7 @@ Show the generated patterns content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with implementation patterns context
+- Invoke the `bmad-party-mode` skill with implementation patterns context
 - Process collaborative insights about potential conflicts
 - Ask user: "Accept these changes to the implementation patterns? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/bmad-create-architecture/steps/step-06-structure.md

@@ -32,8 +32,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -325,7 +325,7 @@ Show the generated project structure content and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with current project structure
+- Invoke the `bmad-advanced-elicitation` skill with current project structure
 - Process enhanced organizational insights that come back
 - Ask user: "Accept these changes to the project structure? (y/n)"
 - If yes: Update content, then return to A/P/C menu
@@ -333,7 +333,7 @@ Show the generated project structure content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with project structure context
+- Invoke the `bmad-party-mode` skill with project structure context
 - Process collaborative insights about organization trade-offs
 - Ask user: "Accept these changes to the project structure? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/bmad-create-architecture/steps/step-07-validation.md

@@ -32,8 +32,8 @@ This step will generate content and present choices:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Invoke the `bmad-party-mode` skill
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -305,7 +305,7 @@ Show the validation results and present choices:
 
 #### If 'A' (Advanced Elicitation):
 
-- Read fully and follow: skill:bmad-advanced-elicitation with validation issues
+- Invoke the `bmad-advanced-elicitation` skill with validation issues
 - Process enhanced solutions for complex concerns
 - Ask user: "Accept these architectural improvements? (y/n)"
 - If yes: Update content, then return to A/P/C menu
@@ -313,7 +313,7 @@ Show the validation results and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with validation context
+- Invoke the `bmad-party-mode` skill with validation context
 - Process collaborative insights on implementation readiness
 - Ask user: "Accept these changes to the validation results? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/bmad-generate-project-context/steps/step-02-generate.md

@@ -31,7 +31,7 @@ This step will generate content and present choices for each rule category:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Execute skill:bmad-advanced-elicitation
-- When 'P' selected: Execute {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Execute skill:bmad-party-mode
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -276,7 +276,7 @@ After each category, show the generated rules and present choices:
 
 #### If 'P' (Party Mode):
 
-- Execute party-mode workflow with category rules context
+- Execute skill:bmad-party-mode with category rules context
 - Process collaborative insights on implementation patterns
 - Ask user: "Accept these changes to {{category}} rules? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/workflow.md

@@ -34,7 +34,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 ### Related Workflows
 
 - `quick_spec_workflow` = `skill:bmad-quick-spec`
-- `party_mode_exec` = `{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md`
+- `party_mode_exec` = `skill:bmad-party-mode`
 - `advanced_elicitation` = `skill:bmad-advanced-elicitation`
 
 ---

src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/workflow.md

@@ -3,7 +3,7 @@ main_config: '{project-root}/_bmad/bmm/config.yaml'
 
 # Checkpoint handler references
 advanced_elicitation: 'skill:bmad-advanced-elicitation'
-party_mode_exec: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+party_mode_exec: 'skill:bmad-party-mode'
 ---
 
 # Quick-Spec Workflow

src/core/agents/bmad-master.agent.yaml

@@ -1,30 +0,0 @@
-# BMad Master Task Executor Agent
-# Core system agent for task execution and resource management
-
-agent:
-  metadata:
-    id: "_bmad/core/agents/bmad-master.md"
-    name: "BMad Master"
-    title: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator"
-    icon: "🧙"
-    capabilities: "runtime resource management, workflow orchestration, task execution, knowledge custodian"
-    hasSidecar: false
-
-  persona:
-    role: "Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator"
-    identity: "Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations."
-    communication_style: "Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability."
-    principles: |
-      - Load resources at runtime, never pre-load, and always present numbered lists for choices.
-
-  critical_actions:
-    - 'Always greet the user and let them know they can invoke the `bmad-help` skill at any time to get advice on what to do next, and they can combine it with what they need help with <example>Invoke the `bmad-help` skill with a question like "where should I start with an idea I have that does XYZ?"</example>'
-
-  menu:
-    - trigger: "LT or fuzzy match on list-tasks"
-      action: "list all tasks from {project-root}/_bmad/_config/task-manifest.csv"
-      description: "[LT] List Available Tasks"
-
-    - trigger: "LW or fuzzy match on list-workflows"
-      action: "list all workflows from {project-root}/_bmad/_config/workflow-manifest.csv"
-      description: "[LW] List Workflows"

src/core/agents/bmad-skill-manifest.yaml

@@ -1,3 +0,0 @@
-canonicalId: bmad-master
-type: agent
-description: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator"

src/core/module-help.csv

@@ -8,3 +8,4 @@ core,anytime,Editorial Review - Prose,EP,,skill:bmad-editorial-review-prose,bmad
 core,anytime,Editorial Review - Structure,ES,,skill:bmad-editorial-review-structure,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
 core,anytime,Adversarial Review (General),AR,,skill:bmad-review-adversarial-general,bmad-review-adversarial-general,false,,,"Review content critically to find issues and weaknesses. Use for quality assurance or before finalizing deliverables. Code Review in other modules run this automatically, but its useful also for document reviews",,
 core,anytime,Edge Case Hunter Review,ECH,,skill:bmad-review-edge-case-hunter,bmad-review-edge-case-hunter,false,,,"Walk every branching path and boundary condition in code, report only unhandled edge cases. Use alongside adversarial review for orthogonal coverage - method-driven not attitude-driven.",,
+core,anytime,Distillator,DG,,skill:bmad-distillator,bmad-distillator,false,,,"Lossless LLM-optimized compression of source documents. Use when you need token-efficient distillates that preserve all information for downstream LLM consumption.",adjacent to source document or specified output_path,distillate markdown file(s)

src/core/skills/bmad-distillator/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: bmad-distillator
+description: Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'.
+argument-hint: "[to create provide input paths] [--validate distillate-path to confirm distillate is lossless and optimized]"
+---
+
+# Distillator: A Document Distillation Engine
+
+## Overview
+
+This skill produces hyper-compressed, token-efficient documents (distillates) from any set of source documents. A distillate preserves every fact, decision, constraint, and relationship from the sources while stripping all overhead that humans need and LLMs don't. Act as an information extraction and compression specialist. The output is a single dense document (or semantically-split set) that a downstream LLM workflow can consume as sole context input without information loss.
+
+This is a compression task, not a summarization task. Summaries are lossy. Distillates are lossless compression optimized for LLM consumption.
+
+## On Activation
+
+1. **Validate inputs.** The caller must provide:
+   - **source_documents** (required) — One or more file paths, folder paths, or glob patterns to distill
+   - **downstream_consumer** (optional) — What workflow/agent consumes this distillate (e.g., "PRD creation", "architecture design"). When provided, use it to judge signal vs noise. When omitted, preserve everything.
+   - **token_budget** (optional) — Approximate target size. When provided and the distillate would exceed it, trigger semantic splitting.
+   - **output_path** (optional) — Where to save. When omitted, save adjacent to the primary source document with `-distillate.md` suffix.
+   - **--validate** (flag) — Run round-trip reconstruction test after producing the distillate.
+
+2. **Route** — proceed to Stage 1.
+
+## Stages
+
+| # | Stage | Purpose |
+|---|-------|---------|
+| 1 | Analyze | Run analysis script, determine routing and splitting |
+| 2 | Compress | Spawn compressor agent(s) to produce the distillate |
+| 3 | Verify & Output | Completeness check, format check, save output |
+| 4 | Round-Trip Validate | (--validate only) Reconstruct and diff against originals |
+
+### Stage 1: Analyze
+
+Run `scripts/analyze_sources.py --help` then run it with the source paths. Use its routing recommendation and grouping output to drive Stage 2. Do NOT read the source documents yourself.
+
+### Stage 2: Compress
+
+**Single mode** (routing = `"single"`, ≤3 files, ≤15K estimated tokens):
+
+Spawn one subagent using `agents/distillate-compressor.md` with all source file paths.
+
+**Fan-out mode** (routing = `"fan-out"`):
+
+1. Spawn one compressor subagent per group from the analysis output. Each compressor receives only its group's file paths and produces an intermediate distillate.
+
+2. After all compressors return, spawn one final **merge compressor** subagent using `agents/distillate-compressor.md`. Pass it the intermediate distillate contents as its input (not the original files). Its job is cross-group deduplication, thematic regrouping, and final compression.
+
+3. Clean up intermediate distillate content (it exists only in memory, not saved to disk).
+
+**Graceful degradation:** If subagent spawning is unavailable, read the source documents and perform the compression work directly using the same instructions from `agents/distillate-compressor.md`. For fan-out, process groups sequentially then merge.
+
+The compressor returns a structured JSON result containing the distillate content, source headings, named entities, and token estimate.
+
+### Stage 3: Verify & Output
+
+After the compressor (or merge compressor) returns:
+
+1. **Completeness check.** Using the headings and named entities list returned by the compressor, verify each appears in the distillate content. If gaps are found, send them back to the compressor for a targeted fix pass — not a full recompression. Limit to 2 fix passes maximum.
+
+2. **Format check.** Verify the output follows distillate format rules:
+   - No prose paragraphs (only bullets)
+   - No decorative formatting
+   - No repeated information
+   - Each bullet is self-contained
+   - Themes are clearly delineated with `##` headings
+
+3. **Determine output format.** Using the split prediction from Stage 1 and actual distillate size:
+
+   **Single distillate** (≤~5,000 tokens or token_budget not exceeded):
+
+   Save as a single file with frontmatter:
+
+   ```yaml
+   ---
+   type: bmad-distillate
+   sources:
+     - "{relative path to source file 1}"
+     - "{relative path to source file 2}"
+   downstream_consumer: "{consumer or 'general'}"
+   created: "{date}"
+   token_estimate: {approximate token count}
+   parts: 1
+   ---
+   ```
+
+   **Split distillate** (>~5,000 tokens, or token_budget requires it):
+
+   Create a folder `{base-name}-distillate/` containing:
+
+   ```
+   {base-name}-distillate/
+   ├── _index.md           # Orientation, cross-cutting items, section manifest
+   ├── 01-{topic-slug}.md  # Self-contained section
+   ├── 02-{topic-slug}.md
+   └── 03-{topic-slug}.md
+   ```
+
+   The `_index.md` contains:
+   - Frontmatter with sources (relative paths from the distillate folder to the originals)
+   - 3-5 bullet orientation (what was distilled, from what)
+   - Section manifest: each section's filename + 1-line description
+   - Cross-cutting items that span multiple sections
+
+   Each section file is self-contained — loadable independently. Include a 1-line context header: "This section covers [topic]. Part N of M."
+
+   Source paths in frontmatter must be relative to the distillate's location.
+
+4. **Measure distillate.** Run `scripts/analyze_sources.py` on the final distillate file(s) to get accurate token counts for the output. Use the `total_estimated_tokens` from this analysis as `distillate_total_tokens`.
+
+5. **Report results.** Always return structured JSON output:
+
+   ```json
+   {
+     "status": "complete",
+     "distillate": "{path or folder path}",
+     "section_distillates": ["{path1}", "{path2}"] or null,
+     "source_total_tokens": N,
+     "distillate_total_tokens": N,
+     "compression_ratio": "X:1",
+     "source_documents": ["{path1}", "{path2}"],
+     "completeness_check": "pass" or "pass_with_additions"
+   }
+   ```
+
+   Where `source_total_tokens` is from the Stage 1 analysis and `distillate_total_tokens` is from step 4. The `compression_ratio` is `source_total_tokens / distillate_total_tokens` formatted as "X:1" (e.g., "3.2:1").
+
+6. If `--validate` flag was set, proceed to Stage 4. Otherwise, done.
+
+### Stage 4: Round-Trip Validation (--validate only)
+
+This stage proves the distillate is lossless by reconstructing source documents from the distillate alone. Use for critical documents where information loss is unacceptable, or as a quality gate for high-stakes downstream workflows. Not for routine use — it adds significant token cost.
+
+1. **Spawn the reconstructor agent** using `agents/round-trip-reconstructor.md`. Pass it ONLY the distillate file path (or `_index.md` path for split distillates) — it must NOT have access to the original source documents.
+
+   For split distillates, spawn one reconstructor per section in parallel. Each receives its section file plus the `_index.md` for cross-cutting context.
+
+   **Graceful degradation:** If subagent spawning is unavailable, this stage cannot be performed by the main agent (it has already seen the originals). Report that round-trip validation requires subagent support and skip.
+
+2. **Receive reconstructions.** The reconstructor returns reconstruction file paths saved adjacent to the distillate.
+
+3. **Perform semantic diff.** Read both the original source documents and the reconstructions. For each section of the original, assess:
+   - Is the core information present in the reconstruction?
+   - Are specific details preserved (numbers, names, decisions)?
+   - Are relationships and rationale intact?
+   - Did the reconstruction add anything not in the original? (indicates hallucination filling gaps)
+
+4. **Produce validation report** saved adjacent to the distillate as `-validation-report.md`:
+
+   ```markdown
+   ---
+   type: distillate-validation
+   distillate: "{distillate path}"
+   sources: ["{source paths}"]
+   created: "{date}"
+   ---
+
+   ## Validation Summary
+   - Status: PASS | PASS_WITH_WARNINGS | FAIL
+   - Information preserved: {percentage estimate}
+   - Gaps found: {count}
+   - Hallucinations detected: {count}
+
+   ## Gaps (information in originals but missing from reconstruction)
+   - {gap description} — Source: {which original}, Section: {where}
+
+   ## Hallucinations (information in reconstruction not traceable to originals)
+   - {hallucination description} — appears to fill gap in: {section}
+
+   ## Possible Gap Markers (flagged by reconstructor)
+   - {marker description}
+   ```
+
+5. **If gaps are found**, offer to run a targeted fix pass on the distillate — adding the missing information without full recompression. Limit to 2 fix passes maximum.
+
+6. **Clean up** — delete the temporary reconstruction files after the report is generated.

src/core/skills/bmad-distillator/agents/distillate-compressor.md

@@ -0,0 +1,116 @@
+# Distillate Compressor Agent
+
+Act as an information extraction and compression specialist. Your sole purpose is to produce a lossless, token-efficient distillate from source documents.
+
+You receive: source document file paths, an optional downstream_consumer context, and a splitting decision.
+
+You must load and apply `resources/compression-rules.md` before producing output. Reference `resources/distillate-format-reference.md` for the expected output format.
+
+## Compression Process
+
+### Step 1: Read Sources
+
+Read all source document files. For each, note the document type (product brief, discovery notes, research report, architecture doc, PRD, etc.) based on content and naming.
+
+### Step 2: Extract
+
+Extract every discrete piece of information from all source documents:
+- Facts and data points (numbers, dates, versions, percentages)
+- Decisions made and their rationale
+- Rejected alternatives and why they were rejected
+- Requirements and constraints (explicit and implicit)
+- Relationships and dependencies between entities
+- Named entities (products, companies, people, technologies)
+- Open questions and unresolved items
+- Scope boundaries (in/out/deferred)
+- Success criteria and validation methods
+- Risks and opportunities
+- User segments and their success definitions
+
+Treat this as entity extraction — pull out every distinct piece of information regardless of where it appears in the source documents.
+
+### Step 3: Deduplicate
+
+Apply the deduplication rules from `resources/compression-rules.md`.
+
+### Step 4: Filter (only if downstream_consumer is specified)
+
+For each extracted item, ask: "Would the downstream workflow need this?"
+- Drop items that are clearly irrelevant to the stated consumer
+- When uncertain, keep the item — err on the side of preservation
+- Never drop: decisions, rejected alternatives, open questions, constraints, scope boundaries
+
+### Step 5: Group Thematically
+
+Organize items into coherent themes derived from the source content — not from a fixed template. The themes should reflect what the documents are actually about.
+
+Common groupings (use what fits, omit what doesn't, add what's needed):
+- Core concept / problem / motivation
+- Solution / approach / architecture
+- Users / segments
+- Technical decisions / constraints
+- Scope boundaries (in/out/deferred)
+- Competitive context
+- Success criteria
+- Rejected alternatives
+- Open questions
+- Risks and opportunities
+
+### Step 6: Compress Language
+
+For each item, apply the compression rules from `resources/compression-rules.md`:
+- Strip prose transitions and connective tissue
+- Remove hedging and rhetoric
+- Remove explanations of common knowledge
+- Preserve specific details (numbers, names, versions, dates)
+- Ensure the item is self-contained (understandable without reading the source)
+- Make relationships explicit ("X because Y", "X blocks Y", "X replaces Y")
+
+### Step 7: Format Output
+
+Produce the distillate as dense thematically-grouped bullets:
+- `##` headings for themes — no deeper heading levels needed
+- `- ` bullets for items — every token must carry signal
+- No decorative formatting (no bold for emphasis, no horizontal rules)
+- No prose paragraphs — only bullets
+- Semicolons to join closely related short items within a single bullet
+- Each bullet self-contained — understandable without reading other bullets
+
+Do NOT include frontmatter — the calling skill handles that.
+
+## Semantic Splitting
+
+If the splitting decision indicates splitting is needed, load `resources/splitting-strategy.md` and follow it.
+
+When splitting:
+
+1. Identify natural semantic boundaries in the content — coherent topic clusters, not arbitrary size breaks.
+
+2. Produce a **root distillate** containing:
+   - 3-5 bullet orientation (what was distilled, for whom, how many parts)
+   - Cross-references to section distillates
+   - Items that span multiple sections
+
+3. Produce **section distillates**, each self-sufficient. Include a 1-line context header: "This section covers [topic]. Part N of M from [source document names]."
+
+## Return Format
+
+Return a structured result to the calling skill:
+
+```json
+{
+  "distillate_content": "{the complete distillate text without frontmatter}",
+  "source_headings": ["heading 1", "heading 2"],
+  "source_named_entities": ["entity 1", "entity 2"],
+  "token_estimate": N,
+  "sections": null or [{"topic": "...", "content": "..."}]
+}
+```
+
+- **distillate_content**: The full distillate text
+- **source_headings**: All Level 2+ headings found across source documents (for completeness verification)
+- **source_named_entities**: Key named entities (products, companies, people, technologies, decisions) found in sources
+- **token_estimate**: Approximate token count of the distillate
+- **sections**: null for single distillates; array of section objects if semantically split
+
+Do not include conversational text, status updates, or preamble — return only the structured result.

src/core/skills/bmad-distillator/agents/round-trip-reconstructor.md

@@ -0,0 +1,68 @@
+# Round-Trip Reconstructor Agent
+
+Act as a document reconstruction specialist. Your purpose is to prove a distillate's completeness by reconstructing the original source documents from the distillate alone.
+
+**Critical constraint:** You receive ONLY the distillate file path. You must NOT have access to the original source documents. If you can see the originals, the test is meaningless.
+
+## Process
+
+### Step 1: Analyze the Distillate
+
+Read the distillate file. Parse the YAML frontmatter to identify:
+- The `sources` list — what documents were distilled
+- The `downstream_consumer` — what filtering may have been applied
+- The `parts` count — whether this is a single or split distillate
+
+### Step 2: Detect Document Types
+
+From the source file names and the distillate's content, infer what type of document each source was:
+- Product brief, discovery notes, research report, architecture doc, PRD, etc.
+- Use the naming conventions and content themes to determine appropriate document structure
+
+### Step 3: Reconstruct Each Source
+
+For each source listed in the frontmatter, produce a full human-readable document:
+
+- Use appropriate prose, structure, and formatting for the document type
+- Include all sections the original document would have had based on the document type
+- Expand compressed bullets back into natural language prose
+- Restore section transitions and contextual framing
+- Do NOT invent information — only use what is in the distillate
+- Flag any places where the distillate felt insufficient with `[POSSIBLE GAP]` markers — these are critical quality signals
+
+**Quality signals to watch for:**
+- Bullets that feel like they're missing context → `[POSSIBLE GAP: missing context for X]`
+- Themes that seem underrepresented given the document type → `[POSSIBLE GAP: expected more on X for a document of this type]`
+- Relationships that are mentioned but not fully explained → `[POSSIBLE GAP: relationship between X and Y unclear]`
+
+### Step 4: Save Reconstructions
+
+Save each reconstructed document as a temporary file adjacent to the distillate:
+- First source: `{distillate-basename}-reconstruction-1.md`
+- Second source: `{distillate-basename}-reconstruction-2.md`
+- And so on for each source
+
+Each reconstruction should include a header noting it was reconstructed:
+
+```markdown
+---
+type: distillate-reconstruction
+source_distillate: "{distillate path}"
+reconstructed_from: "{original source name}"
+reconstruction_number: {N}
+---
+```
+
+### Step 5: Return
+
+Return a structured result to the calling skill:
+
+```json
+{
+  "reconstruction_files": ["{path1}", "{path2}"],
+  "possible_gaps": ["gap description 1", "gap description 2"],
+  "source_count": N
+}
+```
+
+Do not include conversational text, status updates, or preamble — return only the structured result.

src/core/skills/bmad-distillator/bmad-skill-manifest.yaml

@@ -0,0 +1,15 @@
+type: skill
+module: core
+capabilities:
+  - name: bmad-distillator
+    menu-code: DSTL
+    description: "Produces lossless LLM-optimized distillate from source documents. Use after producing large human presentable documents that will be consumed later by LLMs"
+    supports-headless: true
+    input: source documents
+    args: output, validate
+    output: single distillate or folder of distillates next to source input
+    config-vars-used: null
+    phase: anytime
+    before: []
+    after: []
+    is-required: false

src/core/skills/bmad-distillator/resources/compression-rules.md

@@ -0,0 +1,51 @@
+# Compression Rules
+
+These rules govern how source text is compressed into distillate format. Apply as a final pass over all output.
+
+## Strip — Remove entirely
+
+- Prose transitions: "As mentioned earlier", "It's worth noting", "In addition to this"
+- Rhetoric and persuasion: "This is a game-changer", "The exciting thing is"
+- Hedging: "We believe", "It's likely that", "Perhaps", "It seems"
+- Self-reference: "This document describes", "As outlined above"
+- Common knowledge explanations: "Vercel is a cloud platform company", "MIT is an open-source license", "JSON is a data interchange format"
+- Repeated introductions of the same concept
+- Section transition paragraphs
+- Formatting-only elements (decorative bold/italic for emphasis, horizontal rules for visual breaks)
+- Filler phrases: "In order to", "It should be noted that", "The fact that"
+
+## Preserve — Keep always
+
+- Specific numbers, dates, versions, percentages
+- Named entities (products, companies, people, technologies)
+- Decisions made and their rationale (compressed: "Decision: X. Reason: Y")
+- Rejected alternatives and why (compressed: "Rejected: X. Reason: Y")
+- Explicit constraints and non-negotiables
+- Dependencies and ordering relationships
+- Open questions and unresolved items
+- Scope boundaries (in/out/deferred)
+- Success criteria and how they're validated
+- User segments and what success means for each
+- Risks with their severity signals
+- Conflicts between source documents
+
+## Transform — Change form for efficiency
+
+- Long prose paragraphs → single dense bullet capturing the same information
+- "We decided to use X because Y and Z" → "X (rationale: Y, Z)"
+- Repeated category labels → group under a single heading, no per-item labels
+- "Risk: ... Severity: high" → "HIGH RISK: ..."
+- Conditional statements → "If X → Y" form
+- Multi-sentence explanations → semicolon-separated compressed form
+- Lists of related short items → single bullet with semicolons
+- "X is used for Y" → "X: Y" when context is clear
+- Verbose enumerations → parenthetical lists: "platforms (Cursor, Claude Code, Windsurf, Copilot)"
+
+## Deduplication Rules
+
+- Same fact in multiple documents → keep the version with most context
+- Same concept at different detail levels → keep the detailed version
+- Overlapping lists → merge into single list, no duplicates
+- When source documents disagree → note the conflict explicitly: "Brief says X; discovery notes say Y — unresolved"
+- Executive summary points that are expanded elsewhere → keep only the expanded version
+- Introductory framing repeated across sections → capture once under the most relevant theme

src/core/skills/bmad-distillator/resources/distillate-format-reference.md

@@ -0,0 +1,227 @@
+# Distillate Format Reference
+
+Examples showing the transformation from human-readable source content to distillate format.
+
+## Frontmatter
+
+Every distillate includes YAML frontmatter. Source paths are relative to the distillate's location so the distillate remains portable:
+
+```yaml
+---
+type: bmad-distillate
+sources:
+  - "product-brief-example.md"
+  - "product-brief-example-discovery-notes.md"
+downstream_consumer: "PRD creation"
+created: "2026-03-13"
+token_estimate: 1200
+parts: 1
+---
+```
+
+## Before/After Examples
+
+### Prose Paragraph to Dense Bullet
+
+**Before** (human-readable brief excerpt):
+```
+## What Makes This Different
+
+**The anti-fragmentation layer.** The AI tooling space is fracturing across 40+
+platforms with no shared methodology layer. BMAD is uniquely positioned to be the
+cross-platform constant — the structured approach that works the same in Cursor,
+Claude Code, Windsurf, Copilot, and whatever launches next month. Every other
+methodology or skill framework maintains its own platform support matrix. By
+building on the open-source skills CLI ecosystem, BMAD offloads the highest-churn
+maintenance burden and focuses on what actually differentiates it: the methodology
+itself.
+```
+
+**After** (distillate):
+```
+## Differentiation
+- Anti-fragmentation positioning: BMAD = cross-platform constant across 40+ fragmenting AI tools; no competitor provides shared methodology layer
+- Platform complexity delegated to Vercel skills CLI ecosystem (MIT); BMAD maintains methodology, not platform configs
+```
+
+### Technical Details to Compressed Facts
+
+**Before** (discovery notes excerpt):
+```
+## Competitive Landscape
+
+- **Vercel Skills.sh**: 83K+ skills, 18 agents, largest curated leaderboard —
+  but dev-only, skills trigger unreliably (20% without explicit prompting)
+- **SkillsMP**: 400K+ skills directory, pure aggregator with no curation or CLI
+- **ClawHub/OpenClaw**: ~3.2K curated skills with versioning/rollback, small ecosystem
+- **Lindy**: No-code AI agent builder for business automation — closed platform,
+  no skill sharing
+- **Microsoft Copilot Studio**: Enterprise no-code agent builder — vendor-locked
+  to Microsoft
+- **MindStudio**: No-code AI agent platform — siloed, no interoperability
+- **Make/Zapier AI**: Workflow automation adding AI agents — workflow-centric,
+  not methodology-centric
+- **Key gap**: NO competitor combines structured methodology with plugin
+  marketplace — this is BMAD's whitespace
+```
+
+**After** (distillate):
+```
+## Competitive Landscape
+- No competitor combines structured methodology + plugin marketplace (whitespace)
+- Skills.sh (Vercel): 83K skills, 18 agents, dev-only, 20% trigger reliability
+- SkillsMP: 400K skills, aggregator only, no curation/CLI
+- ClawHub: 3.2K curated, versioning, small ecosystem
+- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only
+```
+
+### Deduplication Across Documents
+
+When the same fact appears in both a brief and discovery notes:
+
+**Brief says:**
+```
+bmad-init must always be included as a base skill in every bundle
+```
+
+**Discovery notes say:**
+```
+bmad-init must always be included as a base skill in every bundle/install
+(solves bootstrapping problem)
+```
+
+**Distillate keeps the more contextual version:**
+```
+- bmad-init: always included as base skill in every bundle (solves bootstrapping)
+```
+
+### Decision/Rationale Compression
+
+**Before:**
+```
+We decided not to build our own platform support matrix going forward, instead
+delegating to the Vercel skills CLI ecosystem. The rationale is that maintaining
+20+ platform configs is the biggest maintenance burden and it's unsustainable
+at 40+ platforms.
+```
+
+**After:**
+```
+- Rejected: own platform support matrix. Reason: unsustainable at 40+ platforms; delegate to Vercel CLI ecosystem
+```
+
+## Full Example
+
+A complete distillate produced from a product brief and its discovery notes, targeted at PRD creation:
+
+```markdown
+---
+type: bmad-distillate
+sources:
+  - "product-brief-bmad-next-gen-installer.md"
+  - "product-brief-bmad-next-gen-installer-discovery-notes.md"
+downstream_consumer: "PRD creation"
+created: "2026-03-13"
+token_estimate: 1450
+parts: 1
+---
+
+## Core Concept
+- BMAD Next-Gen Installer: replaces monolithic Node.js CLI with skill-based plugin architecture for distributing BMAD methodology across 40+ AI platforms
+- Three layers: self-describing plugins (bmad-manifest.json), cross-platform install via Vercel skills CLI (MIT), runtime registration via bmad-init skill
+- Transforms BMAD from dev-only methodology into open platform for any domain (creative, therapeutic, educational, personal)
+
+## Problem
+- Current installer maintains ~20 platform configs manually; each platform convention change requires installer update, test, release — largest maintenance burden on team
+- Node.js/npm required — blocks non-technical users on UI-based platforms (Claude Co-Work, etc.)
+- CSV manifests are static, generated once at install; no runtime scanning/registration
+- Unsustainable at 40+ platforms; new tools launching weekly
+
+## Solution Architecture
+- Plugins: skill bundles with Anthropic plugin standard as base format + bmad-manifest.json extending for BMAD-specific metadata (installer options, capabilities, help integration, phase ordering, dependencies)
+- Existing manifest example: `{"module-code":"bmm","replaces-skill":"bmad-create-product-brief","capabilities":[{"name":"create-brief","menu-code":"CB","supports-headless":true,"phase-name":"1-analysis","after":["brainstorming"],"before":["create-prd"],"is-required":true}]}`
+- Vercel skills CLI handles platform translation; integration pattern (wrap/fork/call) is PRD decision
+- bmad-init: global skill scanning installed bmad-manifest.json files, registering capabilities, configuring project settings; always included as base skill in every bundle (solves bootstrapping)
+- bmad-update: plugin update path without full reinstall; technical approach (diff/replace/preserve customizations) is PRD decision
+- Distribution tiers: (1) NPX installer wrapping skills CLI for technical users, (2) zip bundle + platform-specific README for non-technical users, (3) future marketplace
+- Non-technical path has honest friction: "copy to right folder" requires knowing where; per-platform README instructions; improves over time as low-code space matures
+
+## Differentiation
+- Anti-fragmentation: BMAD = cross-platform constant; no competitor provides shared methodology layer across AI tools
+- Curated quality: all submissions gated, human-reviewed by BMad + core team; 13.4% of community skills have critical vulnerabilities (Snyk 2026); quality gate value increases as ecosystem gets noisier
+- Domain-agnostic: no competitor builds beyond software dev workflows; same plugin system powers any domain via BMAD Builder (separate initiative)
+
+## Users (ordered by v1 priority)
+- Module authors (primary v1): package/test/distribute plugins independently without installer changes
+- Developers: single-command install on any of 40+ platforms via NPX
+- Non-technical users: install without Node/Git/terminal; emerging segment including PMs, designers, educators
+- Future plugin creators: non-dev authors using BMAD Builder; need distribution without building own installer
+
+## Success Criteria
+- Zero (or near-zero) custom platform directory code; delegated to skills CLI ecosystem
+- Installation verified on top platforms by volume; skills CLI handles long tail
+- Non-technical install path validated with non-developer users
+- bmad-init discovers/registers all plugins from manifests; clear errors for malformed manifests
+- At least one external module author successfully publishes plugin using manifest system
+- bmad-update works without full reinstall
+- Existing CLI users have documented migration path
+
+## Scope
+- In: manifest spec, bmad-init, bmad-update, Vercel CLI integration, NPX installer, zip bundles, migration path
+- Out: BMAD Builder, marketplace web platform, skill conversion (prerequisite, separate), one-click install for all platforms, monetization, quality certification process (gated-submission principle is architectural requirement; process defined separately)
+- Deferred: CI/CD integration, telemetry for module authors, air-gapped enterprise install, zip bundle integrity verification (checksums/signing), deeper non-technical platform integrations
+
+## Current Installer (migration context)
+- Entry: `tools/cli/bmad-cli.js` (Commander.js) → `tools/cli/installers/lib/core/installer.js`
+- Platforms: `platform-codes.yaml` (~20 platforms with target dirs, legacy dirs, template types, special flags)
+- Manifests: CSV files (skill/workflow/agent-manifest.csv) are current source of truth, not JSON
+- External modules: `external-official-modules.yaml` (CIS, GDS, TEA, WDS) from npm with semver
+- Dependencies: 4-pass resolver (collect → parse → resolve → transitive); YAML-declared only
+- Config: prompts for name, communication language, document output language, output folder
+- Skills already use directory-per-skill layout; bmad-manifest.json sidecars exist but are not source of truth
+- Key shift: CSV-based static manifests → JSON-based runtime scanning
+
+## Vercel Skills CLI
+- `npx skills add <source>` — GitHub, GitLab, local paths, git URLs
+- 40+ agents; per-agent path mappings; symlinks (recommended) or copies
+- Scopes: project-level or global
+- Discovery: `skills/`, `.agents/skills/`, agent-specific paths, `.claude-plugin/marketplace.json`
+- Commands: add, list, find, remove, check, update, init
+- Non-interactive: `-y`, `--all` flags for CI/CD
+
+## Competitive Landscape
+- No competitor combines structured methodology + plugin marketplace (whitespace)
+- Skills.sh (Vercel): 83K skills, dev-only, 20% trigger reliability without explicit prompting
+- SkillsMP: 400K skills, aggregator only, no curation
+- ClawHub: 3.2K curated, versioning, small
+- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only
+- Market: $7.84B (2025) → $52.62B (2030); Agent Skills spec ~4 months old, 351K+ skills; standards converging under Linux Foundation AAIF (MCP, AGENTS.md, A2A)
+
+## Rejected Alternatives
+- Building own platform support matrix: unsustainable at 40+; delegate to Vercel ecosystem
+- One-click install for non-technical v1: emerging space; guidance-based, improve over time
+- Prior roadmap/brainstorming: clean start, unconstrained by previous planning
+
+## Open Questions
+- Vercel CLI integration pattern: wrap/fork/call/peer dependency?
+- bmad-update mechanics: diff/replace? Preserve user customizations?
+- Migration story: command/manual reinstall/compatibility shim?
+- Cross-platform testing: CI matrix for top N? Community testing for rest?
+- bmad-manifest.json as open standard submission to Agent Skills governance?
+- Platforms NOT supported by Vercel skills CLI?
+- Manifest versioning strategy for backward compatibility?
+- Plugin author getting-started experience and tooling?
+
+## Opportunities
+- Module authors as acquisition channel: each published plugin distributes BMAD to creator's audience
+- CI/CD integration: bmad-init as pipeline one-liner increases stickiness
+- Educational institutions: structured methodology + non-technical install → university AI curriculum
+- Skill composability: mixing BMAD modules with third-party skills for custom methodology stacks
+
+## Risks
+- Manifest format evolution creates versioning/compatibility burden once third-party authors publish
+- Quality gate needs defined process, not just claim — gated review model addresses
+- 40+ platform testing environments even with Vercel handling translation
+- Scope creep pressure from marketplace vision (explicitly excluded but primary long-term value)
+- Vercel dependency: minor supply-chain risk; MIT license allows fork if deprioritized
+```

src/core/skills/bmad-distillator/resources/splitting-strategy.md

@@ -0,0 +1,78 @@
+# Semantic Splitting Strategy
+
+When the source content is large (exceeds ~15,000 tokens) or a token_budget requires it, split the distillate into semantically coherent sections rather than arbitrary size breaks.
+
+## Why Semantic Over Size-Based
+
+Arbitrary splits (every N tokens) break coherence. A downstream workflow loading "part 2 of 4" gets context fragments. Semantic splits produce self-contained topic clusters that a workflow can load selectively — "give me just the technical decisions section" — which is more useful and more token-efficient for the consumer.
+
+## Splitting Process
+
+### 1. Identify Natural Boundaries
+
+After the initial extraction and deduplication (Steps 1-2 of the compression process), look for natural semantic boundaries:
+- Distinct problem domains or functional areas
+- Different stakeholder perspectives (users, technical, business)
+- Temporal boundaries (current state vs future vision)
+- Scope boundaries (in-scope vs out-of-scope vs deferred)
+- Phase boundaries (analysis, design, implementation)
+
+Choose boundaries that produce sections a downstream workflow might load independently.
+
+### 2. Assign Items to Sections
+
+For each extracted item, assign it to the most relevant section. Items that span multiple sections go in the root distillate.
+
+Cross-cutting items (items relevant to multiple sections):
+- Constraints that affect all areas → root distillate
+- Decisions with broad impact → root distillate
+- Section-specific decisions → section distillate
+
+### 3. Produce Root Distillate
+
+The root distillate contains:
+- **Orientation** (3-5 bullets): what was distilled, from what sources, for what consumer, how many sections
+- **Cross-references**: list of section distillates with 1-line descriptions
+- **Cross-cutting items**: facts, decisions, and constraints that span multiple sections
+- **Scope summary**: high-level in/out/deferred if applicable
+
+### 4. Produce Section Distillates
+
+Each section distillate must be self-sufficient — a reader loading only one section should understand it without the others.
+
+Each section includes:
+- **Context header** (1 line): "This section covers [topic]. Part N of M from [source document names]."
+- **Section content**: thematically-grouped bullets following the same compression rules as a single distillate
+- **Cross-references** (if needed): pointers to other sections for related content
+
+### 5. Output Structure
+
+Create a folder `{base-name}-distillate/` containing:
+
+```
+{base-name}-distillate/
+├── _index.md           # Root distillate: orientation, cross-cutting items, section manifest
+├── 01-{topic-slug}.md  # Self-contained section
+├── 02-{topic-slug}.md
+└── 03-{topic-slug}.md
+```
+
+Example:
+```
+product-brief-distillate/
+├── _index.md
+├── 01-problem-solution.md
+├── 02-technical-decisions.md
+└── 03-users-market.md
+```
+
+## Size Targets
+
+When a token_budget is specified:
+- Root distillate: ~20% of budget (orientation + cross-cutting items)
+- Remaining budget split proportionally across sections based on content density
+- If a section exceeds its proportional share, compress more aggressively or sub-split
+
+When no token_budget but splitting is needed:
+- Aim for sections of 3,000-5,000 tokens each
+- Root distillate as small as possible while remaining useful standalone

src/core/skills/bmad-distillator/scripts/analyze_sources.py

@@ -0,0 +1,300 @@
+# /// script
+# /// requires-python = ">=3.10"
+# /// dependencies = []
+# ///
+"""Analyze source documents for the distillation generator.
+
+Enumerates files from paths/folders/globs, computes sizes and token estimates,
+detects document types from naming conventions, and suggests groupings for
+related documents (e.g., a brief paired with its discovery notes).
+
+Accepts: file paths, folder paths (scans recursively for .md/.txt/.yaml/.yml/.json),
+or glob patterns. Skips node_modules, .git, __pycache__, .venv, _bmad-output.
+
+Output JSON structure:
+  status: "ok" | "error"
+  files[]: path, filename, size_bytes, estimated_tokens, doc_type
+  summary: total_files, total_size_bytes, total_estimated_tokens
+  groups[]: group_key, files[] with role (primary/companion/standalone)
+    - Groups related docs by naming convention (e.g., brief + discovery-notes)
+  routing: recommendation ("single" | "fan-out"), reason
+    - single: ≤3 files AND ≤15K estimated tokens
+    - fan-out: >3 files OR >15K estimated tokens
+  split_prediction: prediction ("likely" | "unlikely"), reason, estimated_distillate_tokens
+    - Estimates distillate at ~1/3 source size; splits if >5K tokens
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+# Extensions to include when scanning folders
+INCLUDE_EXTENSIONS = {".md", ".txt", ".yaml", ".yml", ".json"}
+
+# Directories to skip when scanning folders
+SKIP_DIRS = {
+    "node_modules", ".git", "__pycache__", ".venv", "venv",
+    ".claude", "_bmad-output", ".cursor", ".vscode",
+}
+
+# Approximate chars per token for estimation
+CHARS_PER_TOKEN = 4
+
+# Thresholds
+SINGLE_COMPRESSOR_MAX_TOKENS = 15_000
+SINGLE_DISTILLATE_MAX_TOKENS = 5_000
+
+# Naming patterns for document type detection
+DOC_TYPE_PATTERNS = [
+    (r"discovery[_-]notes", "discovery-notes"),
+    (r"product[_-]brief", "product-brief"),
+    (r"research[_-]report", "research-report"),
+    (r"architecture", "architecture-doc"),
+    (r"prd", "prd"),
+    (r"distillate", "distillate"),
+    (r"changelog", "changelog"),
+    (r"readme", "readme"),
+    (r"spec", "specification"),
+    (r"requirements", "requirements"),
+    (r"design[_-]doc", "design-doc"),
+    (r"meeting[_-]notes", "meeting-notes"),
+    (r"brainstorm", "brainstorming"),
+    (r"interview", "interview-notes"),
+]
+
+# Patterns for grouping related documents
+GROUP_PATTERNS = [
+    # base document + discovery notes
+    (r"^(.+?)(?:-discovery-notes|-discovery_notes)\.(\w+)$", r"\1.\2"),
+    # base document + appendix
+    (r"^(.+?)(?:-appendix|-addendum)(?:-\w+)?\.(\w+)$", r"\1.\2"),
+    # base document + review/feedback
+    (r"^(.+?)(?:-review|-feedback)\.(\w+)$", r"\1.\2"),
+]
+
+
+def resolve_inputs(inputs: list[str]) -> list[Path]:
+    """Resolve input arguments to a flat list of file paths."""
+    files: list[Path] = []
+    for inp in inputs:
+        path = Path(inp)
+        if path.is_file():
+            files.append(path.resolve())
+        elif path.is_dir():
+            for root, dirs, filenames in os.walk(path):
+                dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+                for fn in sorted(filenames):
+                    fp = Path(root) / fn
+                    if fp.suffix.lower() in INCLUDE_EXTENSIONS:
+                        files.append(fp.resolve())
+        else:
+            # Try as glob
+            matches = glob.glob(inp, recursive=True)
+            for m in sorted(matches):
+                mp = Path(m)
+                if mp.is_file() and mp.suffix.lower() in INCLUDE_EXTENSIONS:
+                    files.append(mp.resolve())
+    # Deduplicate while preserving order
+    seen: set[Path] = set()
+    deduped: list[Path] = []
+    for f in files:
+        if f not in seen:
+            seen.add(f)
+            deduped.append(f)
+    return deduped
+
+
+def detect_doc_type(filename: str) -> str:
+    """Detect document type from filename."""
+    name_lower = filename.lower()
+    for pattern, doc_type in DOC_TYPE_PATTERNS:
+        if re.search(pattern, name_lower):
+            return doc_type
+    return "unknown"
+
+
+def suggest_groups(files: list[Path]) -> list[dict]:
+    """Suggest document groupings based on naming conventions."""
+    groups: dict[str, list[dict]] = {}
+    ungrouped: list[dict] = []
+
+    file_map = {f.name: f for f in files}
+
+    assigned: set[str] = set()
+
+    for f in files:
+        if f.name in assigned:
+            continue
+
+        matched = False
+        for pattern, base_pattern in GROUP_PATTERNS:
+            m = re.match(pattern, f.name, re.IGNORECASE)
+            if m:
+                # This file is a companion — find its base
+                base_name = re.sub(pattern, base_pattern, f.name, flags=re.IGNORECASE)
+                group_key = base_name
+                if group_key not in groups:
+                    groups[group_key] = []
+                    # Add the base file if it exists
+                    if base_name in file_map and base_name not in assigned:
+                        groups[group_key].append({
+                            "path": str(file_map[base_name]),
+                            "filename": base_name,
+                            "role": "primary",
+                        })
+                        assigned.add(base_name)
+                groups[group_key].append({
+                    "path": str(f),
+                    "filename": f.name,
+                    "role": "companion",
+                })
+                assigned.add(f.name)
+                matched = True
+                break
+
+        if not matched:
+            # Check if this file is a base that already has companions
+            if f.name in groups:
+                continue  # Already added as primary
+            ungrouped.append({
+                "path": str(f),
+                "filename": f.name,
+            })
+
+    result = []
+    for group_key, members in groups.items():
+        result.append({
+            "group_key": group_key,
+            "files": members,
+        })
+    for ug in ungrouped:
+        if ug["filename"] not in assigned:
+            result.append({
+                "group_key": ug["filename"],
+                "files": [{"path": ug["path"], "filename": ug["filename"], "role": "standalone"}],
+            })
+
+    return result
+
+
+def analyze(inputs: list[str], output_path: str | None = None) -> None:
+    """Main analysis function."""
+    files = resolve_inputs(inputs)
+
+    if not files:
+        result = {
+            "status": "error",
+            "error": "No readable files found from provided inputs",
+            "inputs": inputs,
+        }
+        output_json(result, output_path)
+        return
+
+    # Analyze each file
+    file_details = []
+    total_chars = 0
+    for f in files:
+        size = f.stat().st_size
+        total_chars += size
+        file_details.append({
+            "path": str(f),
+            "filename": f.name,
+            "size_bytes": size,
+            "estimated_tokens": size // CHARS_PER_TOKEN,
+            "doc_type": detect_doc_type(f.name),
+        })
+
+    total_tokens = total_chars // CHARS_PER_TOKEN
+    groups = suggest_groups(files)
+
+    # Routing recommendation
+    if len(files) <= 3 and total_tokens <= SINGLE_COMPRESSOR_MAX_TOKENS:
+        routing = "single"
+        routing_reason = (
+            f"{len(files)} file(s), ~{total_tokens:,} estimated tokens — "
+            f"within single compressor threshold"
+        )
+    else:
+        routing = "fan-out"
+        routing_reason = (
+            f"{len(files)} file(s), ~{total_tokens:,} estimated tokens — "
+            f"exceeds single compressor threshold "
+            f"({'>' + str(SINGLE_COMPRESSOR_MAX_TOKENS) + ' tokens' if total_tokens > SINGLE_COMPRESSOR_MAX_TOKENS else '> 3 files'})"
+        )
+
+    # Split prediction
+    estimated_distillate_tokens = total_tokens // 3  # rough: distillate is ~1/3 of source
+    if estimated_distillate_tokens > SINGLE_DISTILLATE_MAX_TOKENS:
+        split_prediction = "likely"
+        split_reason = (
+            f"Estimated distillate ~{estimated_distillate_tokens:,} tokens "
+            f"exceeds {SINGLE_DISTILLATE_MAX_TOKENS:,} threshold"
+        )
+    else:
+        split_prediction = "unlikely"
+        split_reason = (
+            f"Estimated distillate ~{estimated_distillate_tokens:,} tokens "
+            f"within {SINGLE_DISTILLATE_MAX_TOKENS:,} threshold"
+        )
+
+    result = {
+        "status": "ok",
+        "files": file_details,
+        "summary": {
+            "total_files": len(files),
+            "total_size_bytes": total_chars,
+            "total_estimated_tokens": total_tokens,
+        },
+        "groups": groups,
+        "routing": {
+            "recommendation": routing,
+            "reason": routing_reason,
+        },
+        "split_prediction": {
+            "prediction": split_prediction,
+            "reason": split_reason,
+            "estimated_distillate_tokens": estimated_distillate_tokens,
+        },
+    }
+
+    output_json(result, output_path)
+
+
+def output_json(data: dict, output_path: str | None) -> None:
+    """Write JSON to file or stdout."""
+    json_str = json.dumps(data, indent=2)
+    if output_path:
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+        Path(output_path).write_text(json_str + "\n")
+        print(f"Results written to {output_path}", file=sys.stderr)
+    else:
+        print(json_str)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "inputs",
+        nargs="+",
+        help="File paths, folder paths, or glob patterns to analyze",
+    )
+    parser.add_argument(
+        "-o", "--output",
+        help="Output JSON to file instead of stdout",
+    )
+    args = parser.parse_args()
+    analyze(args.inputs, args.output)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

src/core/skills/bmad-distillator/scripts/tests/test_analyze_sources.py

@@ -0,0 +1,204 @@
+"""Tests for analyze_sources.py"""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+# Add parent dir to path so we can import the script
+import sys
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from analyze_sources import (
+    resolve_inputs,
+    detect_doc_type,
+    suggest_groups,
+    analyze,
+    INCLUDE_EXTENSIONS,
+    SKIP_DIRS,
+)
+
+
+@pytest.fixture
+def temp_dir():
+    """Create a temp directory with sample files."""
+    with tempfile.TemporaryDirectory() as d:
+        # Create sample files
+        (Path(d) / "product-brief-foo.md").write_text("# Product Brief\nContent here")
+        (Path(d) / "product-brief-foo-discovery-notes.md").write_text("# Discovery\nNotes")
+        (Path(d) / "architecture-doc.md").write_text("# Architecture\nDesign here")
+        (Path(d) / "research-report.md").write_text("# Research\nFindings")
+        (Path(d) / "random.txt").write_text("Some text content")
+        (Path(d) / "image.png").write_bytes(b"\x89PNG")
+        # Create a subdirectory with more files
+        sub = Path(d) / "subdir"
+        sub.mkdir()
+        (sub / "prd-v2.md").write_text("# PRD\nRequirements")
+        # Create a skip directory
+        skip = Path(d) / "node_modules"
+        skip.mkdir()
+        (skip / "junk.md").write_text("Should be skipped")
+        yield d
+
+
+class TestResolveInputs:
+    def test_single_file(self, temp_dir):
+        f = str(Path(temp_dir) / "product-brief-foo.md")
+        result = resolve_inputs([f])
+        assert len(result) == 1
+        assert result[0].name == "product-brief-foo.md"
+
+    def test_folder_recursion(self, temp_dir):
+        result = resolve_inputs([temp_dir])
+        names = {f.name for f in result}
+        assert "product-brief-foo.md" in names
+        assert "prd-v2.md" in names
+        assert "random.txt" in names
+
+    def test_folder_skips_excluded_dirs(self, temp_dir):
+        result = resolve_inputs([temp_dir])
+        names = {f.name for f in result}
+        assert "junk.md" not in names
+
+    def test_folder_skips_non_text_files(self, temp_dir):
+        result = resolve_inputs([temp_dir])
+        names = {f.name for f in result}
+        assert "image.png" not in names
+
+    def test_glob_pattern(self, temp_dir):
+        pattern = str(Path(temp_dir) / "product-brief-*.md")
+        result = resolve_inputs([pattern])
+        assert len(result) == 2
+        names = {f.name for f in result}
+        assert "product-brief-foo.md" in names
+        assert "product-brief-foo-discovery-notes.md" in names
+
+    def test_deduplication(self, temp_dir):
+        f = str(Path(temp_dir) / "product-brief-foo.md")
+        result = resolve_inputs([f, f, f])
+        assert len(result) == 1
+
+    def test_mixed_inputs(self, temp_dir):
+        file_path = str(Path(temp_dir) / "architecture-doc.md")
+        folder_path = str(Path(temp_dir) / "subdir")
+        result = resolve_inputs([file_path, folder_path])
+        names = {f.name for f in result}
+        assert "architecture-doc.md" in names
+        assert "prd-v2.md" in names
+
+    def test_nonexistent_path(self):
+        result = resolve_inputs(["/nonexistent/path/file.md"])
+        assert len(result) == 0
+
+
+class TestDetectDocType:
+    @pytest.mark.parametrize("filename,expected", [
+        ("product-brief-foo.md", "product-brief"),
+        ("product_brief_bar.md", "product-brief"),
+        ("foo-discovery-notes.md", "discovery-notes"),
+        ("foo-discovery_notes.md", "discovery-notes"),
+        ("architecture-overview.md", "architecture-doc"),
+        ("my-prd.md", "prd"),
+        ("research-report-q4.md", "research-report"),
+        ("foo-distillate.md", "distillate"),
+        ("changelog.md", "changelog"),
+        ("readme.md", "readme"),
+        ("api-spec.md", "specification"),
+        ("design-doc-v2.md", "design-doc"),
+        ("meeting-notes-2026.md", "meeting-notes"),
+        ("brainstorm-session.md", "brainstorming"),
+        ("user-interview-notes.md", "interview-notes"),
+        ("random-file.md", "unknown"),
+    ])
+    def test_detection(self, filename, expected):
+        assert detect_doc_type(filename) == expected
+
+
+class TestSuggestGroups:
+    def test_groups_brief_with_discovery_notes(self, temp_dir):
+        files = [
+            Path(temp_dir) / "product-brief-foo.md",
+            Path(temp_dir) / "product-brief-foo-discovery-notes.md",
+        ]
+        groups = suggest_groups(files)
+        # Should produce one group with both files
+        paired = [g for g in groups if len(g["files"]) > 1]
+        assert len(paired) == 1
+        filenames = {f["filename"] for f in paired[0]["files"]}
+        assert "product-brief-foo.md" in filenames
+        assert "product-brief-foo-discovery-notes.md" in filenames
+
+    def test_standalone_files(self, temp_dir):
+        files = [
+            Path(temp_dir) / "architecture-doc.md",
+            Path(temp_dir) / "research-report.md",
+        ]
+        groups = suggest_groups(files)
+        assert len(groups) == 2
+        for g in groups:
+            assert len(g["files"]) == 1
+
+    def test_mixed_grouped_and_standalone(self, temp_dir):
+        files = [
+            Path(temp_dir) / "product-brief-foo.md",
+            Path(temp_dir) / "product-brief-foo-discovery-notes.md",
+            Path(temp_dir) / "architecture-doc.md",
+        ]
+        groups = suggest_groups(files)
+        paired = [g for g in groups if len(g["files"]) > 1]
+        standalone = [g for g in groups if len(g["files"]) == 1]
+        assert len(paired) == 1
+        assert len(standalone) == 1
+
+
+class TestAnalyze:
+    def test_basic_analysis(self, temp_dir):
+        f = str(Path(temp_dir) / "product-brief-foo.md")
+        output_file = str(Path(temp_dir) / "output.json")
+        analyze([f], output_file)
+        result = json.loads(Path(output_file).read_text())
+        assert result["status"] == "ok"
+        assert result["summary"]["total_files"] == 1
+        assert result["files"][0]["doc_type"] == "product-brief"
+        assert result["files"][0]["estimated_tokens"] > 0
+
+    def test_routing_single_small_input(self, temp_dir):
+        f = str(Path(temp_dir) / "product-brief-foo.md")
+        output_file = str(Path(temp_dir) / "output.json")
+        analyze([f], output_file)
+        result = json.loads(Path(output_file).read_text())
+        assert result["routing"]["recommendation"] == "single"
+
+    def test_routing_fanout_many_files(self, temp_dir):
+        # Create enough files to trigger fan-out (> 3 files)
+        for i in range(5):
+            (Path(temp_dir) / f"doc-{i}.md").write_text("x" * 1000)
+        output_file = str(Path(temp_dir) / "output.json")
+        analyze([temp_dir], output_file)
+        result = json.loads(Path(output_file).read_text())
+        assert result["routing"]["recommendation"] == "fan-out"
+
+    def test_folder_analysis(self, temp_dir):
+        output_file = str(Path(temp_dir) / "output.json")
+        analyze([temp_dir], output_file)
+        result = json.loads(Path(output_file).read_text())
+        assert result["status"] == "ok"
+        assert result["summary"]["total_files"] >= 4  # at least the base files
+        assert len(result["groups"]) > 0
+
+    def test_no_files_found(self):
+        output_file = "/tmp/test_analyze_empty.json"
+        analyze(["/nonexistent/path"], output_file)
+        result = json.loads(Path(output_file).read_text())
+        assert result["status"] == "error"
+        os.unlink(output_file)
+
+    def test_stdout_output(self, temp_dir, capsys):
+        f = str(Path(temp_dir) / "product-brief-foo.md")
+        analyze([f])
+        captured = capsys.readouterr()
+        result = json.loads(captured.out)
+        assert result["status"] == "ok"