convoke-agents 2.0.0

package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-03-metrics.md

@@ -0,0 +1,73 @@
+---
+step: 3
+workflow: lean-experiment
+title: Define Success Metrics
+---
+
+# Step 3: Define Success Metrics
+
+Before you run the experiment, define what success and failure look like. Not after. Before. This is the most important discipline in lean experimentation — pre-defined success criteria prevent you from moving the goalposts after you see the data.
+
+## Why This Matters
+
+Without pre-defined metrics, every experiment "succeeds" — you'll always find something positive in the data if you look hard enough. That's not learning, it's confirmation bias. Pre-defined success criteria force an honest conversation: "If the number is below X, we were wrong." That's the conversation most teams avoid. That's the conversation that saves you from building the wrong thing.
+
+## Your Task
+
+### 1. Define Primary Success Metric
+
+Your primary metric directly tests the riskiest assumption. One metric. Not three. Not five. One metric that, if it fails, tells you the hypothesis is wrong.
+
+| Field | Your Answer |
+|-------|-------------|
+| **Metric Name** | What are you measuring? (e.g., "Action rate on dinner suggestions") |
+| **Target Threshold** | What number means success? Be specific. (e.g., ">=60% of participants act on the suggestion") |
+| **Failure Threshold** | What number means failure? (e.g., "<40% action rate") |
+| **Measurement Method** | How will you collect this data? (e.g., "Track text replies vs. no-reply within 30 min") |
+| **Why This Metric** | How does it connect to the riskiest assumption? |
+
+### 2. Define Secondary Metrics (1-3)
+
+Secondary metrics provide context but don't determine pass/fail. They help you understand *why* the primary metric succeeded or failed.
+
+For each secondary metric:
+
+| Field | Your Answer |
+|-------|-------------|
+| **Metric Name** | What are you measuring? |
+| **Expected Range** | What range would you expect if the hypothesis is correct? |
+| **What It Tells You** | What insight does this metric provide beyond the primary? |
+
+### 3. Define Guardrail Metrics (Optional)
+
+Guardrail metrics detect unintended negative consequences — the "surgery was successful but the patient died" scenarios.
+
+| Field | Your Answer |
+|-------|-------------|
+| **Guardrail Metric** | What negative effect could this experiment cause? |
+| **Red Line** | At what threshold would you stop the experiment? |
+
+### 4. Validate Your Metrics
+
+- [ ] **Actionable?** Does each metric drive a specific decision? (If action rate < 40%, pivot. If > 60%, proceed.) If a metric doesn't drive a decision, remove it.
+- [ ] **Measurable?** Can you actually collect this data with your experiment design? If not, simplify the metric or change the design.
+- [ ] **Pre-defined?** Are thresholds set BEFORE seeing data? Write them down now. You can't move goalposts you've published.
+- [ ] **Connected?** Does the primary metric directly test the riskiest assumption, not a proxy?
+
+---
+
+## Your Turn
+
+Define your primary success metric, 1-3 secondary metrics, and any guardrail metrics. Share them and I'll help you sharpen the thresholds.
+
+---
+
+**[a]** Advanced Elicitation — Deep dive into metric selection and statistical significance
+**[p]** Party Mode — Bring in other Vortex agents for metric critique
+**[c]** Continue — Proceed to running the experiment
+
+## Next Step
+
+When your success metrics are defined and locked, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-04-run.md

package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-04-run.md

@@ -0,0 +1,75 @@
+---
+step: 4
+workflow: lean-experiment
+title: Run Experiment & Collect Data
+---
+
+# Step 4: Run Experiment & Collect Data
+
+Time to execute. You've defined the hypothesis, designed the experiment, and locked the success metrics. Now run it and collect the data — honestly, completely, and without cherry-picking.
+
+## Why This Matters
+
+The discipline of lean experimentation isn't in the design — it's in the execution. Most experiments fail not because the hypothesis was wrong, but because the execution was sloppy: inconsistent delivery, incomplete data collection, or mid-experiment changes that invalidate the results. Run the experiment exactly as designed. If you discover flaws mid-run, document them — don't fix them by changing the experiment. A clean experiment with a negative result is more valuable than a messy experiment with a positive one.
+
+## Your Task
+
+### 1. Pre-Launch Checklist
+
+Before you start, confirm everything is ready:
+
+- [ ] **Hypothesis is documented** — you know exactly what you're testing
+- [ ] **Success metrics are locked** — thresholds set before data arrives
+- [ ] **Experiment design is final** — no changes after launch
+- [ ] **Data collection is set up** — you can actually capture the metrics you defined
+- [ ] **Participants are recruited** — your sample is ready
+- [ ] **Timeline is set** — start date, end date, check-in points
+
+### 2. Execute the Experiment
+
+Run the experiment according to your design. During execution, track:
+
+**Execution Log:**
+
+| Date | What Happened | Data Collected | Issues / Anomalies |
+|------|---------------|----------------|---------------------|
+| Day 1 | | | |
+| Day 2 | | | |
+| ... | | | |
+
+**Key disciplines during execution:**
+- **Don't change the experiment mid-run.** If you discover a flaw, document it and decide after whether to re-run.
+- **Collect all data, not just positive signals.** Non-responses, dropouts, and complaints are data.
+- **Note anomalies immediately.** Unusual behavior is easier to interpret when documented fresh.
+- **Track what surprised you.** Surprises often contain the most valuable learning.
+
+### 3. Document Raw Results
+
+When the experiment ends, capture the raw data before any interpretation:
+
+| Metric | Target | Actual | Met? |
+|--------|--------|--------|------|
+| **Primary:** [your metric] | [target threshold] | [actual number] | Yes/No |
+| **Secondary 1:** [metric] | [expected range] | [actual] | In range? |
+| **Secondary 2:** [metric] | [expected range] | [actual] | In range? |
+| **Guardrail:** [metric] | [red line] | [actual] | Safe? |
+
+**Qualitative observations:** Document anything notable that numbers alone don't capture — user reactions, unexpected behaviors, feedback themes.
+
+---
+
+## Your Turn
+
+Run the experiment, collect data, and fill in the execution log and results table above. Share the raw results when the experiment is complete.
+
+---
+
+**[a]** Advanced Elicitation — Guidance on handling mid-experiment issues
+**[p]** Party Mode — Bring in other Vortex agents for execution support
+**[c]** Continue — Proceed to analyzing results
+
+## Next Step
+
+When your experiment is complete and raw results are documented, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-05-analyze.md

package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-05-analyze.md

@@ -0,0 +1,84 @@
+---
+step: 5
+workflow: lean-experiment
+title: Analyze Results & Capture Learning
+---
+
+# Step 5: Analyze Results & Capture Learning
+
+The experiment is done. Now the real work begins: honest interpretation. Not spin. Not "finding the silver lining." Honest assessment of what the data tells you about your hypothesis and assumptions.
+
+## Why This Matters
+
+Most teams analyze experiment results backwards — they start with the outcome they wanted and work backwards to justify it. "The conversion rate was low, but users who DID convert were really engaged!" That's not analysis. That's rationalization. Real analysis starts with the pre-defined success criteria and asks one question: did we meet them or not? Everything else follows from that honest answer.
+
+## Your Task
+
+### 1. Primary Metric Assessment
+
+Start with the metric that matters most:
+
+| Question | Your Answer |
+|----------|-------------|
+| **What was the primary metric result?** | [actual number] |
+| **Did it meet the success threshold?** | Yes / No / Borderline |
+| **Did it hit the failure threshold?** | Yes / No |
+| **What does this tell you about the riskiest assumption?** | [Validated / Invalidated / Inconclusive] |
+
+**If the result is borderline:** Resist the urge to call it "close enough." Borderline results mean you need a sharper experiment, a larger sample, or a different metric — not a looser standard.
+
+### 2. Secondary Metric Analysis
+
+For each secondary metric:
+
+| Metric | Result | What It Tells You |
+|--------|--------|-------------------|
+| [Secondary 1] | [result] | [interpretation] |
+| [Secondary 2] | [result] | [interpretation] |
+
+**Look for the story the secondary metrics tell:** Do they explain *why* the primary metric succeeded or failed? Do they reveal something unexpected?
+
+### 3. Capture Validated Learning
+
+This is the most valuable output of the experiment — what you now know that you didn't know before.
+
+**What we set out to learn:**
+[Your original hypothesis and riskiest assumption]
+
+**What we actually learned:**
+1. [First key learning — what the data showed]
+2. [Second key learning — what surprised you]
+3. [Third key learning — what assumption was updated]
+
+**Assumptions updated:**
+
+| Assumption | Previous Status | New Status | Evidence |
+|-----------|----------------|------------|----------|
+| [Riskiest assumption] | Unvalidated | Validated / Invalidated / Inconclusive | [What data supports this?] |
+| [Other assumption] | [status] | [new status] | [evidence] |
+
+### 4. Identify New Questions
+
+Good experiments answer one question and raise two more. What new questions did this experiment surface?
+
+- [ ] [New question 1]
+- [ ] [New question 2]
+- [ ] [New question 3]
+
+---
+
+## Your Turn
+
+Complete the analysis above. Be honest about what the data shows — not what you hoped it would show. Share your analysis and I'll help you extract the maximum learning.
+
+---
+
+**[a]** Advanced Elicitation — Deep dive into statistical interpretation
+**[p]** Party Mode — Bring in other Vortex agents for analysis critique
+**[c]** Continue — Proceed to the decision: pivot, patch, or persevere
+
+## Next Step
+
+When your analysis is complete, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-06-decide.md

package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-06-decide.md

@@ -0,0 +1,111 @@
+---
+step: 6
+workflow: lean-experiment
+title: Decide & Route
+---
+
+# Step 6: Decide & Route
+
+You've run the experiment, analyzed the results, and captured the learning. Now make the decision: based on the evidence, what do you do next? And package everything as an HC4 experiment context artifact so the next agent in the Vortex has what they need.
+
+## Why This Matters
+
+The hardest part of lean experimentation isn't running experiments — it's acting on the results. Teams that invest effort in an experiment naturally want it to "work." But the discipline is in the decision: if the data says pivot, you pivot. If the data says the assumption was wrong, you accept it. The HC4 artifact preserves your learning so it's not lost when you move forward.
+
+## Your Task
+
+### 1. Make the Decision
+
+Based on your analysis from Step 5:
+
+| Signal | Decision | What It Means |
+|--------|----------|---------------|
+| Primary metric met success threshold | **Persevere** | The hypothesis held. Move to production monitoring or test the next assumption. |
+| Primary metric in borderline zone | **Patch** | The direction is right but needs refinement. Iterate on the experiment design or scope. |
+| Primary metric hit failure threshold | **Pivot** | The assumption was wrong. Re-examine the problem definition or hypothesis. |
+
+**Your decision:** [Pivot / Patch / Persevere]
+
+**Rationale:** [Why this decision follows from the evidence — not from hope]
+
+### 2. Generate the HC4 Artifact
+
+I'll produce the HC4 Experiment Context artifact with this structure:
+
+```yaml
+---
+contract: HC4
+type: artifact
+source_agent: wade
+source_workflow: lean-experiment
+target_agents: [noah]
+input_artifacts:
+  - path: "_bmad-output/vortex-artifacts/{your-hc3-artifact}"
+    contract: HC3
+created: YYYY-MM-DD
+---
+```
+
+**HC4 Required Body Sections:**
+1. **Experiment Summary** — Name, type, duration, graduation status
+2. **Hypothesis Tested** — Original statement, riskiest assumption, expected outcomes
+3. **Method** — Experiment type, sample, what was built, execution details
+4. **Pre-Defined Success Criteria** — Metrics with targets and actual results
+5. **Results** — Key findings, validated learning, assumption updates
+6. **Expected Production Behavior** (if graduating) — What to expect at scale
+7. **Signal Thresholds** (if graduating) — When to investigate anomalies
+
+**Save to:** `{output_folder}/vortex-artifacts/hc4-experiment-results-{date}.md`
+
+### 3. Validation Questions
+
+Before finalizing:
+
+- [ ] Does the decision honestly follow from the data?
+- [ ] Is the HC4 artifact self-contained — could Noah interpret production signals without reading HC3?
+- [ ] Are success criteria results documented with actual numbers, not vague assessments?
+- [ ] Are new questions and next steps clearly identified?
+
+---
+
+## Your Turn
+
+Confirm your decision (pivot/patch/persevere) and review the HC4 artifact. I'll generate the final file once you approve.
+
+---
+
+**[a]** Advanced Elicitation — Deep dive into decision rationale
+**[p]** Party Mode — Bring in other Vortex agents for decision review
+**[c]** Continue — Generate the HC4 artifact and proceed to routing
+
+---
+
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Experiment succeeded, graduating to production | signal-interpretation | Noah 📡 | Monitor production signals against experiment predictions (HC4) |
+| Experiment complete, need to capture learning | learning-card | Max 🧭 | Capture validated learning before it fades |
+| User behavior was surprising or unexplained | empathy-map | Isla 🔍 | Understand why users behaved unexpectedly |
+| Assumption invalidated, need new direction | pivot-resynthesis | Mila 🔬 | Re-synthesize problem definition with new evidence |
+| Need to test next assumption in the risk map | lean-experiment | Wade 🧪 | Run the next experiment in the testing sequence |
+
+> **Note:** These are evidence-based recommendations. You can navigate to any Vortex agent
+> at any time based on your judgment.
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.
+
+### Insufficient Evidence for Routing
+
+If the evidence doesn't clearly point to a single next step:
+
+| To route to... | You need... |
+|----------------|-------------|
+| Noah 📡 | Graduated experiment with defined production behavior and signal thresholds |
+| Max 🧭 | Completed experiment with documented learning and assumption updates |
+| Isla 🔍 | Specific unexplained user behavior requiring qualitative investigation |
+| Mila 🔬 | Invalidated assumption requiring problem re-definition |
+
+**Recommended:** Run **Max's [VN] Vortex Navigation** for a full gap analysis across all streams.

package/_bmad/bme/_vortex/workflows/lean-experiment/validate.md

@@ -0,0 +1,30 @@
+# Validate Lean Experiment
+
+**Status:** Coming in v1.2.0
+
+**Agent:** Wade (Lean Experiments Specialist)
+
+**Stream:** Externalize
+
+## Overview
+
+This validation workflow helps you review lean experiments to ensure they're scientifically sound and focused on learning.
+
+## What Gets Validated
+
+- Is the hypothesis specific and falsifiable?
+- Is the experiment design appropriate for the hypothesis?
+- Are success criteria clear and measurable?
+- Are results documented with evidence?
+- Are learnings actionable?
+- Is the pivot/persevere decision justified?
+
+## Coming in v1.2.0
+
+This validation workflow will be available alongside the lean-experiment workflow in March 2026.
+
+## Questions?
+
+For questions or to request early access:
+- GitHub Issues: https://github.com/amalik/convoke-agents/issues
+- Tag with: `workflow:lean-experiment` and `v1.2.0`

package/_bmad/bme/_vortex/workflows/lean-experiment/workflow.md

@@ -0,0 +1,26 @@
+---
+workflow: lean-experiment
+type: step-file
+description: Execute Build-Measure-Learn cycles with hypothesis testing
+author: Wade (lean-experiments-specialist)
+version: 1.2.0
+---
+
+# Lean Experiment Workflow
+
+Execute Build-Measure-Learn cycles to validate or invalidate hypotheses.
+
+## Steps Overview
+
+1. **State Hypothesis** - What do you believe is true?
+2. **Design Experiment** - How will you test it?
+3. **Define Metrics** - What will you measure?
+4. **Run Experiment** - Execute and collect data
+5. **Analyze Results** - What did you learn?
+6. **Decide: Pivot or Persevere** - What's next?
+
+---
+
+## INITIALIZATION
+
+Load step: {project-root}/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-01-hypothesis.md

package/_bmad/bme/_vortex/workflows/lean-persona/lean-persona.template.md

@@ -0,0 +1,163 @@
+---
+title: "Lean Persona: {persona-name}"
+date: {date}
+created-by: {user-name} with Emma (contextualization-expert)
+type: lean-persona
+status: HYPOTHESIS
+version: 1.0
+---
+
+# Lean Persona: {persona-name}
+
+> **Remember:** This is a hypothesis until validated. Every insight below needs testing with real users.
+
+## Executive Summary
+
+**Job-to-be-Done:**
+{job-summary}
+
+**Riskiest Assumptions:**
+{top-3-assumptions}
+
+**Next Validation Steps:**
+{next-validation-steps}
+
+---
+
+## Job-to-be-Done
+
+### Primary Job
+{primary-job}
+
+### Context
+{job-context}
+
+### Frequency & Importance
+{job-frequency-importance}
+
+### Current Solution
+{current-solution}
+
+---
+
+## Current State Analysis
+
+### How They Solve It Today
+{current-solution-details}
+
+### Pain Points with Current Solution
+{pain-points}
+
+### Workarounds & Hacks
+{workarounds}
+
+### Cost of Current Solution
+{current-cost}
+
+---
+
+## Problem Contexts
+
+### When Does This Problem Occur?
+{problem-timing}
+
+### Where Does This Problem Occur?
+{problem-location}
+
+### Why Does This Problem Matter Now?
+{problem-urgency}
+
+### What Triggers the Need?
+{problem-triggers}
+
+---
+
+## Forces & Anxieties
+
+### Forces Pushing Toward Change
+**What makes them want to switch?**
+{push-forces}
+
+### Forces Pulling Back to Status Quo
+**What makes them hesitate?**
+{pull-forces}
+
+### Anxieties About Changing
+{anxieties}
+
+### Habits That Need Breaking
+{habits}
+
+---
+
+## Success Criteria
+
+### Desired Outcome
+{desired-outcome}
+
+### Success Metrics
+{success-metrics}
+
+### Time to Value
+{time-to-value}
+
+### Acceptable Trade-offs
+{tradeoffs}
+
+---
+
+## Assumptions to Validate
+
+### Critical Assumptions (Test First)
+{critical-assumptions}
+
+### Important Assumptions (Test Soon)
+{important-assumptions}
+
+### Nice-to-Validate (Test Later)
+{nice-to-validate}
+
+---
+
+## Validation Plan
+
+### Experiment 1: {experiment-1-name}
+- **Hypothesis:** {experiment-1-hypothesis}
+- **Method:** {experiment-1-method}
+- **Success Criteria:** {experiment-1-success}
+- **Timeline:** {experiment-1-timeline}
+
+### Experiment 2: {experiment-2-name}
+- **Hypothesis:** {experiment-2-hypothesis}
+- **Method:** {experiment-2-method}
+- **Success Criteria:** {experiment-2-success}
+- **Timeline:** {experiment-2-timeline}
+
+### Experiment 3: {experiment-3-name}
+- **Hypothesis:** {experiment-3-hypothesis}
+- **Method:** {experiment-3-method}
+- **Success Criteria:** {experiment-3-success}
+- **Timeline:** {experiment-3-timeline}
+
+---
+
+## Next Steps
+
+1. **Validate riskiest assumption first:** {riskiest-assumption}
+2. **Talk to {target-interview-count} potential users** within {timeline}
+3. **Run {experiment-type}** to test {what-youre-testing}
+4. **Decision criteria:** If {success-metric} reaches {threshold}, then {decision}
+
+---
+
+## Revision History
+
+| Date | What Changed | Why | New Assumptions |
+|------|--------------|-----|-----------------|
+| {date} | Initial creation | First hypothesis | All assumptions untested |
+
+---
+
+**Created with:** Convoke v2.0.0 - Vortex Pattern (Contextualize Stream)
+**Agent:** Emma (Contextualization Expert)
+**Workflow:** lean-persona

package/_bmad/bme/_vortex/workflows/lean-persona/steps/step-01-define-job.md

@@ -0,0 +1,72 @@
+---
+step: 1
+workflow: lean-persona
+title: Define Job-to-be-Done
+---
+
+# Step 1: Define Job-to-be-Done
+
+Before we create a lean persona, we need to understand the fundamental job your user is trying to accomplish.
+
+## Why This Matters
+
+Jobs-to-be-done is the foundation of lean personas. People don't buy products - they "hire" solutions to get a job done. Understanding the job helps us:
+- Focus on behavior, not demographics
+- Identify what truly matters to users
+- Find better competing solutions we might not have considered
+- Design value propositions that resonate
+
+## Your Task
+
+Answer these questions to define the job-to-be-done:
+
+### 1. What job is the user trying to accomplish?
+Be specific. Not "manage finances" but "ensure I don't overspend on discretionary purchases each month."
+
+### 2. Give this persona a name
+A simple identifier (e.g., "Budget-Conscious Parent", "Efficiency-Driven PM"). This is for reference, not a demographic label.
+
+### 3. How often does this job occur?
+- Daily? Weekly? Monthly? Annually?
+- Is it predictable or unpredictable?
+- How urgent is it when it arises?
+
+### 4. How important is this job to the user?
+On a scale: Mission-critical / Very important / Important / Nice-to-have
+Why does it matter to them?
+
+### 5. What evidence do you have?
+- User interviews? (how many?)
+- Surveys? Observations?
+- Analytics? Support tickets?
+- Or is this a hypothesis to validate?
+
+## Example
+
+**Persona Name:** Time-Strapped Remote Manager
+
+**Job-to-be-Done:** Keep my distributed team aligned on priorities without wasting time in status meetings.
+
+**Frequency:** Daily (checking alignment), Weekly (setting priorities)
+
+**Importance:** Mission-critical - Team misalignment directly impacts delivery and morale
+
+**Evidence:**
+- 5 user interviews with remote team managers
+- Analysis of 100+ support tickets about "meeting overload"
+- Survey of 200 remote managers (68% cited "too many meetings" as top frustration)
+- HYPOTHESIS: We believe eliminating daily standups would improve team productivity
+
+---
+
+## Your Turn
+
+Please define the job-to-be-done using the structure above.
+
+**Important:** If you're working from a hypothesis (not validated research), clearly mark assumptions. Every assumption needs a plan to validate it.
+
+## Next Step
+
+When you've defined the job and I've confirmed it's specific enough, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/lean-persona/steps/step-02-current-solution.md