bmalph 2.7.7 → 2.9.0

package/bmad/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 `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 `finalize.md`.

package/bmad/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 `draft-and-review.md`. Otherwise, exit.

package/bmad/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 `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 `draft-and-review.md`.

package/bmad/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.

package/bmad/bmm/workflows/1-analysis/research/bmad-domain-research/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-domain-research
+description: 'Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]"'
+---
+
+Follow the instructions in ./workflow.md.

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

@@ -0,0 +1 @@
+type: skill

package/bmad/bmm/workflows/1-analysis/research/{domain-steps → bmad-domain-research/domain-steps}/step-06-research-synthesis.md

@@ -373,6 +373,7 @@ _This comprehensive research document serves as an authoritative reference on {{
 
 #### 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 complete document to the research file
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
 - Complete the domain research workflow
@@ -380,7 +381,7 @@ _This comprehensive research document serves as an authoritative reference on {{
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the complete comprehensive research document using the full structure above.
+When user selects 'C', append the complete comprehensive research document using the full structure above. 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:
 

package/bmad/bmm/workflows/1-analysis/research/bmad-domain-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 -->

package/bmad/bmm/workflows/1-analysis/research/{workflow-domain-research.md → bmad-domain-research/workflow.md}

@@ -1,8 +1,3 @@
----
-name: domain-research
-description: Conduct domain research covering industry analysis, regulations, technology trends, and ecosystem dynamics using current web data and verified sources.
----
-
 # Domain Research Workflow
 
 **Goal:** Conduct comprehensive domain/industry research using current web data and verified sources to produce complete research documents with compelling narratives and proper citations.

package/bmad/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.

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

@@ -0,0 +1 @@
+type: skill

package/bmad/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 -->

package/bmad/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!