convoke-agents 2.0.0

package/_bmad/bme/_vortex/guides/WADE-USER-GUIDE.md

@@ -0,0 +1,245 @@
+# Wade User Guide - Lean Experiments Specialist 🧪
+
+**Agent:** Wade (lean-experiments-specialist)
+**Version:** 1.6.4
+**Module:** Convoke (bme) - Vortex Pattern
+**Last Updated:** 2026-03-02
+
+---
+
+## Quick Start
+
+**Who is Wade?**
+Wade is a Validated Learning Expert and First Externalization Designer who helps teams create minimal, fast, inexpensive experiments to validate product direction. He guides you through the "Externalize" stream of the Vortex pattern — designing MVPs, running Build-Measure-Learn experiments, validating technical feasibility (proof-of-concept), and validating business value (proof-of-value). Every build Wade produces is an experiment for validated learning, not a feature to ship.
+
+**When to use Wade:**
+- Designing Minimum Viable Products that test the riskiest assumption
+- Running Build-Measure-Learn experiment cycles
+- Validating technical feasibility before investing in business case (proof-of-concept)
+- Validating business value and market demand (proof-of-value)
+- Reviewing experiment designs for rigor before execution
+- Producing experiment artifacts (HC4) that connect back to Liam's hypotheses (HC3)
+
+**Wade vs. Just Building — which do I need?**
+
+| | Wade 🧪 (Structured Experiments) | Just Building |
+|---|---|---|
+| **Process** | Hypothesis → MVP → Measure → Learn → Decide | Spec → Build → Ship → Hope |
+| **Output** | HC4 experiment context with validated learning | A product feature |
+| **Rigor** | Pre-defined success criteria, falsifiable hypothesis | "We'll know it when we see it" |
+| **Failure mode** | Fast learning from small bets | Expensive learning from big bets |
+| **Next step** | Noah interprets production signals, Max decides | Ship more features |
+
+**Decision aid:** If you need to validate assumptions before committing resources → **Wade**. If you already know what to build and just need to build it → BMAD Core development agents.
+
+**What you'll get:**
+MVP specifications, lean experiment designs with Build-Measure-Learn structure, proof-of-concept results for technical feasibility, proof-of-value validations for business case, and validated learning documentation — all as HC4 experiment context artifacts that feed into Noah's signal interpretation.
+
+---
+
+## How to Invoke Wade
+
+### Method 1: Direct Agent File Reading (Recommended)
+
+Read Wade's agent file to activate him. This works in any environment:
+
+**Claude Code:**
+```
+Read the file at _bmad/bme/_vortex/agents/lean-experiments-specialist.md
+```
+
+**Terminal:**
+```bash
+cat _bmad/bme/_vortex/agents/lean-experiments-specialist.md
+```
+
+**Claude.ai:** Copy the contents of `_bmad/bme/_vortex/agents/lean-experiments-specialist.md` and paste into the chat.
+
+---
+
+### Method 2: Slash Command (BMAD Environments Only)
+
+If your environment supports BMAD slash commands:
+
+```
+/bmad-agent-bme-lean-experiments-specialist
+```
+
+---
+
+## Wade's Menu Options
+
+Once Wade activates, you'll see menu options for his available workflows:
+
+```
+1. [MH] Redisplay Menu Help
+2. [CH] Chat with Wade about lean experiments, MVPs, validated learning, or Lean Startup
+3. [ME] Design MVP: Create Minimum Viable Product specification in 6 steps
+4. [LE] Run Lean Experiment: Execute Build-Measure-Learn cycle in 6 steps
+5. [PC] Create Proof of Concept: Validate technical feasibility in 6 steps
+6. [PV] Create Proof of Value: Validate business value in 6 steps
+7. [VE] Validate Experiment: Review experiment design for rigor
+8. [PM] Start Party Mode
+9. [DA] Dismiss Agent
+```
+
+### How to Select an Option
+
+1. **Number:** Type `3` to select option 3
+2. **Command Code:** Type `ME` to design an MVP
+3. **Fuzzy Match:** Type `mvp` or `experiment` or `proof` - Wade will match the command
+
+---
+
+## Workflows
+
+### [ME] Design MVP (6 steps)
+
+Design a Minimum Viable Product specification using Build-Measure-Learn methodology. An MVP is not a feature-light product — it's the smallest experiment that tests the riskiest assumption from Liam's hypothesis contracts (HC3).
+
+**Output:** `{output_folder}/vortex-artifacts/hc4-mvp-spec-{date}.md`
+**Time:** 60-120 minutes
+
+**When to use Design MVP:**
+You have validated hypotheses from Liam and need to design the smallest thing that tests the riskiest assumption. You want to move from "we think" to "we know" with minimal investment.
+
+---
+
+### [LE] Run Lean Experiment (6 steps)
+
+Execute a full Build-Measure-Learn cycle with structured hypothesis testing. Takes an HC3 hypothesis contract (from Liam) and walks through building the experiment, measuring results, and capturing validated learning.
+
+**Output:** `{output_folder}/vortex-artifacts/hc4-experiment-results-{date}.md`
+**Time:** 90-180 minutes (design + execution guidance)
+
+**When to use Lean Experiment:**
+You're ready to run a complete experiment cycle — build, measure, learn, decide. This is the core Build-Measure-Learn workflow that produces the HC4 experiment context Noah will interpret.
+
+---
+
+### [PC] Create Proof of Concept (6 steps)
+
+Validate technical feasibility before investing in the business case. Can you build this? A proof-of-concept answers "is this technically possible?" before asking "should we build this?"
+
+**Output:** `{output_folder}/vortex-artifacts/hc4-poc-results-{date}.md`
+**Time:** 60-120 minutes
+
+**When to use Proof of Concept:**
+The riskiest assumption is technical — "can we build this at all?" Run a PoC before investing in business validation. Technical feasibility must come before market feasibility.
+
+---
+
+### [PV] Create Proof of Value (6 steps)
+
+Validate business value and market demand. Should you build this? A proof-of-value answers "do users want this enough to pay/change behavior?" after technical feasibility is established.
+
+**Output:** `{output_folder}/vortex-artifacts/hc4-pov-results-{date}.md`
+**Time:** 60-120 minutes
+
+**When to use Proof of Value:**
+Technical feasibility is confirmed (via PoC or prior knowledge) and now you need to validate that users actually want this. Technical capability doesn't guarantee business success.
+
+---
+
+### [VE] Validate Experiment
+
+Review an experiment design for rigor before execution.
+
+**When to use Validate Experiment:**
+- You designed an experiment and want expert review before running it
+- You inherited experiment artifacts from another team
+- You want to check if success criteria are truly falsifiable
+- You're preparing to hand off to Noah for production signal interpretation
+
+**What Wade checks:**
+- Is the hypothesis falsifiable and specific?
+- Are success metrics actionable (not vanity metrics)?
+- Is the MVP truly minimal (smallest testable version)?
+- Are pre-defined success criteria in place before results come in?
+- Can this guide a pivot/patch/persevere decision?
+
+---
+
+## Wade's Philosophy: Externalization Over Speculation
+
+### The Externalize Stream (Vortex Pattern)
+
+Wade guides teams through the "Externalize" stream (Stream 5):
+- **Build the smallest thing that validates learning** — not the best thing
+- **Expose to real users early** — internal feedback isn't validation
+- **Treat everything as an experiment** — hypothesis → test → learn
+- **Outcomes over outputs** — focus on what we learn, not what we build
+- **Fast and cheap beats slow and perfect** — speed enables iteration
+- **MVP does not equal Minimum Viable Quality** — it must be functional enough to test the hypothesis
+
+---
+
+## Chatting with Wade (CH)
+
+Select **[CH] Chat** to discuss:
+- Lean Startup methodologies and Build-Measure-Learn cycles
+- MVP design and what "minimum" really means
+- Hypothesis testing and experiment methodology
+- Proof-of-concept vs. proof-of-value decisions
+- Actionable metrics vs. vanity metrics
+- When to pivot vs. persevere
+- Rapid prototyping and validated learning
+
+**Example questions:**
+- "How do I design an MVP that tests my riskiest assumption?"
+- "What's the difference between proof-of-concept and proof-of-value?"
+- "How do I write a falsifiable hypothesis for an experiment?"
+- "What metrics should I track in a lean experiment?"
+- "When should I pivot vs. persevere?"
+- "How do I know if my MVP is truly minimal?"
+- "What experiment methodology should I use for my hypothesis?"
+
+---
+
+## Troubleshooting
+
+### Error: "Configuration Error: Cannot load config file"
+
+**How to fix:**
+1. Check if `_bmad/bme/_vortex/config.yaml` exists
+2. If missing: `npx convoke-install-vortex`
+
+### Error: "Workflow Error: Cannot load lean experiment workflow"
+
+**How to fix:**
+1. Check workflow files exist in `_bmad/bme/_vortex/workflows/`
+2. Run `npx convoke-doctor` to diagnose
+3. If missing: `npx convoke-install-vortex`
+
+---
+
+## Tips from Wade
+
+### "Build the smallest thing that tests the riskiest assumption"
+Don't build a full product to test if users want it. Build the smallest experiment that answers your biggest question. Sometimes that's a landing page, not an app.
+
+### "Measure what matters"
+Vanity metrics look good but don't drive decisions. Actionable metrics tell you what to do next. Instead of "page views," track "% who signed up after viewing pricing."
+
+### "Learn fast, pivot faster"
+Every experiment teaches something, even failures. The goal isn't to validate your idea — it's to learn what's true. Be willing to pivot when evidence contradicts assumptions.
+
+### "Proof-of-concept before proof-of-value"
+Can you build it? Doesn't mean should you build it. Validate technical feasibility first, then validate business case. Don't waste money proving market demand for something you can't deliver.
+
+### "Fail fast is good, learn fast is better"
+Failure is only valuable if you learn from it. Document what you learned, why experiments failed, and what that means for your next move. Failure without learning is just waste.
+
+---
+
+## Credits
+
+**Agent:** Wade (lean-experiments-specialist)
+**Module:** Convoke (bme)
+**Submodule:** Vortex Pattern (`_vortex`)
+**Stream:** Externalize (Stream 5)
+**Version:** 1.6.4
+
+---
+
+**Questions?** Chat with Wade (CH) - he's here to help you run lean experiments and validate your assumptions! 🧪

package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/empathy-map.template.md

@@ -0,0 +1,143 @@
+---
+title: "Empathy Map: {user-name}"
+date: {date}
+created-by: {user-name} with Emma (contextualization-expert)
+research-sources: {research-sources}
+status: DRAFT
+---
+
+# Empathy Map: {user-name}
+
+## Executive Summary
+
+**Key Insights:**
+{key-insights}
+
+**Primary Pain Points:**
+{top-3-pain-points}
+
+**Top Desired Gains:**
+{top-3-gains}
+
+---
+
+## Target User Profile
+
+**Who:** {user-demographics}
+
+**Job-to-be-done:** {job-to-be-done}
+
+**Context:** {user-context}
+
+**Research Sources:**
+{research-sources-list}
+
+---
+
+## Says & Thinks
+
+### What They SAY (Direct Quotes)
+
+{says-list}
+
+### What They THINK (Inferred Thoughts)
+
+{thinks-list}
+
+---
+
+## Does & Feels
+
+### What They DO (Observable Actions)
+
+{does-list}
+
+### What They FEEL (Emotional States)
+
+{feels-list}
+
+---
+
+## Pain Points
+
+**Priority:** High = Critical | Medium = Important | Low = Nice-to-fix
+
+{pain-points-detailed}
+
+**Summary:**
+- **High Priority:** {count-high}
+- **Medium Priority:** {count-medium}
+- **Low Priority:** {count-low}
+
+---
+
+## Desired Gains
+
+**Priority:** High = Must-have | Medium = Important | Low = Nice-to-have
+
+{gains-detailed}
+
+**Summary:**
+- **High Priority:** {count-high-gains}
+- **Medium Priority:** {count-medium-gains}
+- **Low Priority:** {count-low-gains}
+
+---
+
+## Design Implications
+
+### What This Means for Design
+
+**Based on this empathy map, we should:**
+
+1. **Prioritize:** {priority-implications}
+
+2. **Avoid:** {avoid-implications}
+
+3. **Focus On:** {focus-implications}
+
+### Feature Prioritization Matrix
+
+| Pain Point | Desired Gain | Design Opportunity | Priority |
+|------------|--------------|-------------------|----------|
+{feature-matrix}
+
+---
+
+## Validation Checklist
+
+- [ ] Empathy map reviewed by users (shows it resonates)
+- [ ] Team alignment achieved (stakeholders understand user perspective)
+- [ ] Design decisions informed by insights (wireframes, features)
+- [ ] Success metrics defined (based on user gains)
+- [ ] Research sources documented (traceable insights)
+
+---
+
+## Next Steps
+
+**Recommended Actions:**
+
+1. **Validate:** Show this empathy map to 3-5 users and ask if it resonates
+2. **Share:** Present to team for alignment on user needs
+3. **Design:** Use insights to inform wireframes and feature decisions
+4. **Measure:** Track success using gain metrics
+5. **Iterate:** Update empathy map as new research emerges
+
+---
+
+## Research Sources
+
+{research-sources-detailed}
+
+---
+
+**Created by:** {creator-name}
+**Created with:** Emma (contextualization-expert) - Convoke v2.0.0
+**Date:** {creation-date}
+**Version:** 1.0
+**Status:** {status}
+
+---
+
+*This empathy map is a living document. Update it as you learn more about your users through ongoing research.*

package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/steps/step-01-define-user.md

@@ -0,0 +1,60 @@
+---
+step: 1
+workflow: empathy-map
+title: Define Target User
+---
+
+# Step 1: Define Target User
+
+Before we create an empathy map, we need to be crystal clear about WHO we're creating it for.
+
+## Why This Matters
+
+An empathy map is only as useful as its specificity. "Users" is too broad. "Mobile app users" is still too broad. "Busy parents managing multiple kids' schedules on mobile" - now we're getting somewhere.
+
+## Your Task
+
+Answer these questions to define your target user:
+
+### 1. Who is this user? (Demographics)
+- Age range?
+- Occupation/role?
+- Location/context?
+- Tech savvy level?
+
+### 2. What is their core job-to-be-done?
+What are they trying to accomplish when they interact with your product/service?
+
+### 3. What context are we focusing on?
+When and where are they using your product? What's happening around them?
+
+### 4. What user research informs this empathy map?
+- Interview transcripts?
+- Survey responses?
+- Observational studies?
+- Analytics data?
+
+## Example
+
+**Target User:** Sarah, a 34-year-old marketing manager at a mid-sized B2B SaaS company. She manages a team of 5 and is responsible for lead generation campaigns.
+
+**Job-to-be-done:** Plan and execute multi-channel marketing campaigns that generate qualified leads for the sales team.
+
+**Context:** Working from home office, juggling multiple campaigns simultaneously, under pressure to hit quarterly lead targets.
+
+**Research Sources:**
+- 3 user interviews (transcripts: INT-001, INT-002, INT-003)
+- Survey of 50 marketing managers
+- 2 hours of screen-recording observation
+
+---
+
+## Your Turn
+
+Please define your target user using the structure above.
+
+## Next Step
+
+When you've defined your target user and I've confirmed the definition is specific enough, I'll load:
+
+{project-root}/_bmad/bme/_designos/workflows/empathy-map/steps/step-02-says-thinks.md

package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/steps/step-02-says-thinks.md

@@ -0,0 +1,67 @@
+---
+step: 2
+workflow: empathy-map
+title: Says & Thinks
+---
+
+# Step 2: Says & Thinks
+
+Now let's capture what your target user **says out loud** and what they **think privately**.
+
+## Why This Matters
+
+There's often a gap between what people say and what they actually think. Understanding both helps us:
+- Identify unspoken needs
+- Spot contradictions that reveal pain points
+- Understand social pressures influencing their behavior
+
+## What vs. Why
+
+- **SAYS** - Direct quotes from user research ("I check my email first thing every morning")
+- **THINKS** - Inferred thoughts based on behavior and tone ("I'm worried I'll miss something important")
+
+## Your Task
+
+### What They SAY (3-5 direct quotes)
+
+Pull actual quotes from your user research. These should be things they said out loud in interviews, surveys, or conversations.
+
+**Example:**
+- "I don't have time to learn a new tool right now"
+- "My team needs better collaboration features"
+- "I wish I could see all my campaigns in one place"
+
+### What They THINK (3-5 inferred thoughts)
+
+Based on their behavior, tone, and context, what are they thinking but not saying?
+
+**Example:**
+- "If I adopt this tool and it fails, I'll look bad to my boss"
+- "I'm overwhelmed by the number of platforms I already use"
+- "My current process is inefficient but at least it's familiar"
+
+## Tips for Success
+
+**For SAYS:**
+- Use direct quotes (exact words when possible)
+- Include both positive and negative statements
+- Capture the language they use (jargon, metaphors, etc.)
+
+**For THINKS:**
+- Look for hesitation, tone shifts, or contradictions
+- Consider what they DON'T say (conspicuous absences)
+- Infer based on behavior, not speculation
+
+---
+
+## Your Turn
+
+Please provide:
+1. 3-5 things your target user SAYS (direct quotes)
+2. 3-5 things your target user THINKS (inferred thoughts)
+
+## Next Step
+
+When you've captured both SAYS and THINKS, I'll load:
+
+{project-root}/_bmad/bme/_designos/workflows/empathy-map/steps/step-03-does-feels.md

package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/steps/step-03-does-feels.md

@@ -0,0 +1,79 @@
+---
+step: 3
+workflow: empathy-map
+title: Does & Feels
+---
+
+# Step 3: Does & Feels
+
+Let's capture what your target user **does** (observable actions) and **feels** (emotional states).
+
+## Why This Matters
+
+Actions reveal priorities. Emotions drive decisions. Together, they show us:
+- What users actually do vs. what they say they do
+- Emotional triggers that influence behavior
+- Moments of delight or frustration
+
+## What vs. Why
+
+- **DOES** - Observable behaviors, actions, and habits
+- **FEELS** - Emotional states, reactions, and moods
+
+## Your Task
+
+### What They DO (3-5 observable actions)
+
+What specific behaviors did you observe or did they describe? These are concrete, observable actions.
+
+**Example:**
+- Opens email client before any other app every morning
+- Switches between 6 different tools to check campaign performance
+- Takes screenshots of data to create manual reports in PowerPoint
+- Sets reminders to follow up with leads but often misses them
+- Batch-processes tasks on Friday afternoons to "clear the deck" for Monday
+
+### What They FEEL (3-5 emotional states)
+
+What emotions did they express or did you infer from their tone, body language, or word choice?
+
+**Example:**
+- Frustrated when tools don't integrate with each other
+- Anxious about missing important lead notifications
+- Proud when a campaign performs well
+- Overwhelmed by the volume of data to analyze
+- Relieved when repetitive tasks are automated
+
+## Tips for Success
+
+**For DOES:**
+- Be specific (not "uses social media" but "checks LinkedIn 3x per day")
+- Include frequency/timing when relevant
+- Note workarounds or "hacks" they've created
+- Look for patterns across multiple users
+
+**For FEELS:**
+- Use emotion words (frustrated, anxious, excited, relieved)
+- Link emotions to specific moments or contexts
+- Note intensity (mildly annoyed vs. deeply frustrated)
+- Watch for contradictions (says "it's fine" but looks stressed)
+
+## Connecting Does & Feels
+
+Notice how actions and emotions influence each other:
+- DOES: Switches between 6 tools → FEELS: Frustrated, overwhelmed
+- FEELS: Anxious about missing notifications → DOES: Checks email obsessively
+
+---
+
+## Your Turn
+
+Please provide:
+1. 3-5 things your target user DOES (observable actions)
+2. 3-5 things your target user FEELS (emotional states)
+
+## Next Step
+
+When you've captured both DOES and FEELS, I'll load:
+
+{project-root}/_bmad/bme/_designos/workflows/empathy-map/steps/step-04-pain-points.md

package/_bmad/bme/_vortex/workflows/_deprecated/empathy-map/steps/step-04-pain-points.md

@@ -0,0 +1,87 @@
+---
+step: 4
+workflow: empathy-map
+title: Pain Points
+---
+
+# Step 4: Pain Points
+
+Now let's identify the **obstacles, frustrations, and challenges** your target user faces.
+
+## Why This Matters
+
+Pain points reveal opportunities. Every pain point is a potential solution waiting to happen. Understanding pain points helps us:
+- Prioritize features that solve real problems
+- Avoid building solutions for non-problems
+- Empathize with user struggles
+
+## Types of Pain Points
+
+**Process Pain Points** - Inefficient workflows, too many steps, repetitive tasks
+
+**Support Pain Points** - Lack of help, unclear documentation, slow response times
+
+**Integration Pain Points** - Tools don't talk to each other, data silos, manual data transfer
+
+**Learning Pain Points** - Steep learning curve, unclear UI, inconsistent patterns
+
+**Emotional Pain Points** - Stress, anxiety, fear of failure, overwhelm
+
+## Your Task
+
+### Identify 4-6 Pain Points
+
+For each pain point, capture:
+1. **The Pain** - What's the problem?
+2. **The Impact** - How does it affect them?
+3. **The Evidence** - What research supports this?
+
+**Example:**
+
+**Pain #1: Data Scattered Across 6 Tools**
+- **Impact:** Wastes 2 hours per day switching tools and manually consolidating data
+- **Evidence:** "I feel like I spend more time gathering data than analyzing it" (INT-002)
+
+**Pain #2: Can't See Campaign Performance in Real-Time**
+- **Impact:** Misses opportunities to optimize underperforming campaigns early
+- **Evidence:** Observed user checking analytics 8 times in a 30-minute session (OBS-001)
+
+**Pain #3: No Automated Lead Scoring**
+- **Impact:** Sales team complains about low-quality leads, creating tension between marketing and sales
+- **Evidence:** "Sales always says our leads are junk, but we don't have a good way to prioritize them" (INT-003)
+
+## Tips for Success
+
+**Be Specific:**
+- Not "Bad UX" but "Button to create campaign is hidden in nested menu"
+- Not "Slow" but "Report generation takes 45 seconds, blocking other work"
+
+**Quantify When Possible:**
+- Time wasted
+- Frequency of occurrence
+- Number of steps involved
+
+**Ground in Evidence:**
+- Direct quotes
+- Observed behavior
+- Usage analytics
+
+**Prioritize by Severity:**
+- Which pain points cause the most frustration?
+- Which ones waste the most time?
+- Which ones risk critical failures?
+
+---
+
+## Your Turn
+
+Please identify 4-6 pain points your target user faces. For each pain point, include:
+1. The pain itself
+2. The impact on the user
+3. Evidence from research
+
+## Next Step
+
+When you've documented the pain points, I'll load:
+
+{project-root}/_bmad/bme/_designos/workflows/empathy-map/steps/step-05-gains.md