convoke-agents 2.0.0

package/_bmad/bme/_vortex/workflows/empathy-map/validate.md

@@ -0,0 +1,117 @@
+---
+workflow: validate-empathy-map
+type: single-file
+description: Validate an existing empathy map against user research evidence
+author: Isla (discovery-empathy-expert)
+---
+
+# Validate Existing Empathy Map
+
+Bring me an empathy map and I'll help you validate it against user research evidence.
+
+## Why Validation Matters
+
+Empathy maps lose value if they're based on assumptions instead of research. Validation ensures:
+- Every insight traces back to evidence
+- No speculation or "we think users want..."
+- Team stays grounded in user reality
+
+## Validation Process
+
+### 1. Evidence Check
+
+For each insight in the empathy map, ask:
+
+**Can you point to research that supports this?**
+- Direct quote from interview?
+- Observed behavior?
+- Survey data?
+- Analytics?
+
+**Red Flags:**
+- "We think users want..."
+- "Users probably feel..."
+- "Based on our internal discussions..."
+- No citation to research source
+
+### 2. Specificity Check
+
+**Is the target user specific enough?**
+- ❌ "Mobile users"
+- ❌ "Marketing professionals"
+- ✅ "Marketing managers at mid-sized B2B companies managing lead generation"
+
+**Are pain points concrete?**
+- ❌ "Bad UX"
+- ✅ "Campaign creation button hidden in nested menu (3 clicks deep)"
+
+**Are gains measurable?**
+- ❌ "Want to be more efficient"
+- ✅ "Complete campaign setup in under 10 minutes vs. current 45 minutes"
+
+### 3. Completeness Check
+
+**Did you explore all dimensions?**
+- [ ] Says (direct quotes)
+- [ ] Thinks (inferred thoughts)
+- [ ] Does (observable actions)
+- [ ] Feels (emotional states)
+- [ ] Pains (obstacles/frustrations)
+- [ ] Gains (desired outcomes)
+
+**Did you capture both positive and negative?**
+- Not just problems (pain points)
+- Also aspirations (gains)
+- Moments of delight AND frustration
+
+### 4. Actionability Check
+
+**Can designers use this?**
+- Are pain points specific enough to inform design decisions?
+- Are gains clear enough to prioritize features?
+
+**Can product managers use this?**
+- Can they defend feature decisions with user insights?
+- Can they communicate user needs to stakeholders?
+
+---
+
+## Your Turn
+
+**Please share:**
+1. The empathy map you want to validate (paste content or provide file path)
+2. The research sources that informed it
+
+I'll review it and provide:
+- **Evidence gaps** - Insights lacking research support
+- **Specificity issues** - Vague statements that need clarification
+- **Missing dimensions** - Areas you didn't explore
+- **Validation score** - Overall assessment (Strong / Needs Work / Speculative)
+
+---
+
+## Validation Criteria
+
+**Strong Empathy Map:**
+- ✅ Every insight backed by cited research
+- ✅ Specific target user definition
+- ✅ Concrete, measurable pain points and gains
+- ✅ All 6 dimensions explored (Says, Thinks, Does, Feels, Pains, Gains)
+- ✅ Both positive and negative aspects captured
+- ✅ Actionable for designers and product managers
+
+**Needs Work:**
+- ⚠️ Some insights lack research support
+- ⚠️ Target user could be more specific
+- ⚠️ Pain points or gains are vague
+- ⚠️ Missing some dimensions
+
+**Speculative:**
+- ❌ Many insights are assumptions
+- ❌ No clear research sources
+- ❌ "We think" instead of "Users said"
+- ❌ Not actionable
+
+---
+
+Ready to validate your empathy map? Share it with me and I'll provide detailed feedback! 🎨

package/_bmad/bme/_vortex/workflows/empathy-map/workflow.md

@@ -0,0 +1,45 @@
+---
+workflow: empathy-map
+type: step-file
+description: Create user empathy maps through structured 6-step process
+author: Isla (discovery-empathy-expert)
+version: 1.5.0
+---
+
+# Create Empathy Map Workflow
+
+This workflow guides you through creating a comprehensive empathy map for a target user.
+
+## What is an Empathy Map?
+
+An empathy map is a collaborative visualization used to articulate what we know about a particular type of user. It externalizes knowledge about users to create a shared understanding and aid decision-making.
+
+## Workflow Structure
+
+**Step-file architecture:**
+- Just-in-time loading (each step loads only when needed)
+- Sequential enforcement (must complete step N before step N+1)
+- State tracking in frontmatter (progress preserved)
+
+## Steps Overview
+
+1. **Define Target User** - Who are we creating this empathy map for?
+2. **Says & Thinks** - What do they say aloud? What do they think?
+3. **Does & Feels** - What actions do they take? What emotions do they feel?
+4. **Pain Points** - What frustrates, blocks, or challenges them?
+5. **Gains** - What do they want to achieve? What are their needs?
+6. **Synthesize** - Create the final empathy map artifact
+
+## Output
+
+**Artifact:** Empathy map markdown file in `{output_folder}/empathy-map-{user-name}-{date}.md`
+
+**Template:** Uses [empathy-map.template.md](empathy-map.template.md)
+
+---
+
+## INITIALIZATION
+
+Load config from {project-root}/_bmad/bme/_vortex/config.yaml
+
+Load step: {project-root}/_bmad/bme/_vortex/workflows/empathy-map/steps/step-01-define-user.md

package/_bmad/bme/_vortex/workflows/experiment-design/steps/step-01-setup.md

@@ -0,0 +1,66 @@
+---
+step: 1
+workflow: experiment-design
+title: Setup & Input Validation
+---
+
+# Step 1: Setup & Input Validation
+
+Before we design any experiment, we need to know exactly what hypothesis we're testing and verify the foundation is strong enough to build an experiment on.
+
+## Why This Matters
+
+A poorly designed experiment wastes more than time — it produces false confidence. If the hypothesis contract is vague, the experiment will test nothing meaningful. If the riskiest assumption isn't clearly identified, you'll test the wrong thing. This step ensures we start with a well-formed hypothesis contract so every experiment decision that follows is grounded in a real, testable bet.
+
+## Your Task
+
+### 1. What Hypothesis Contract Do You Have?
+
+Liam expects a hypothesis contract — ideally produced by the hypothesis-engineering workflow as an HC3-compliant artifact:
+- **HC3 Hypothesis Contract** (from Liam's `hypothesis-engineering` workflow)
+- **Enriched HC3** (from Liam's `assumption-mapping` workflow, with deepened risk analysis)
+
+You can also bring **any well-formed hypothesis** — Liam accepts input from outside the Vortex pattern. It doesn't have to be HC3-compliant, but having a structured hypothesis with a clear riskiest assumption makes experiment design dramatically sharper.
+
+### 2. Provide Your Input
+
+Please provide the file path or describe the hypothesis contract you want to design an experiment for. For example:
+- `_bmad-output/vortex-artifacts/hc3-hypothesis-contract-2026-02-25.md`
+- `_bmad-output/vortex-artifacts/hc3-experiment-design-2026-02-25.md` (if re-designing)
+- Or: "I have a hypothesis about user onboarding that I want to test"
+
+### 3. Input Validation
+
+I'll check your artifact against the HC3 schema to assess readiness:
+
+**HC3 Frontmatter Check:**
+- `contract: HC3`
+- `type: artifact`
+- `source_agent` (who produced it)
+- `source_workflow` (which workflow)
+- `target_agents: [wade]`
+- `input_artifacts` (upstream references)
+- `created` (date)
+
+**HC3 Body Section Check:**
+- Problem Context (Problem Statement, JTBD Reference, Key Pains Targeted)
+- Hypothesis Contracts (1-3 in 4-field format: Expected Outcome, Target Behavior Change, Rationale, Riskiest Assumption)
+- Assumption Risk Map (Lethality × Uncertainty classifications)
+- Recommended Testing Order (prioritized assumptions)
+- Flagged Concerns (optional — routing signals)
+
+**If your input is non-conforming:** That's okay — we don't reject hypotheses. I'll guide you to identify which elements are present and which gaps we need to work around during experiment design. But the sharper your hypothesis contract, the better your experiment will be. If you can't prove it wrong, it's not a hypothesis — and if you can't describe what you're testing, you're not ready to design an experiment.
+
+> For the full HC3 schema reference, see `{project-root}/_bmad/bme/_vortex/contracts/hc3-hypothesis-contract.md`
+
+---
+
+## Your Turn
+
+Please provide your hypothesis contract — file path, description, or both. I'll validate it and we'll proceed to identifying your experiment targets.
+
+## Next Step
+
+When your hypothesis contract is provided and validated, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/experiment-design/steps/step-02-context.md

package/_bmad/bme/_vortex/workflows/experiment-design/steps/step-02-context.md

@@ -0,0 +1,77 @@
+---
+step: 2
+workflow: experiment-design
+title: Hypothesis Context & Experiment Targets
+---
+
+# Step 2: Hypothesis Context & Experiment Targets
+
+Now let's load your hypothesis contract, review the risk map, and figure out exactly what this experiment needs to test. The riskiest assumption gets tested first — not the easiest one.
+
+## Why This Matters
+
+Most teams design experiments that test the wrong thing. They pick the assumption they can validate cheaply, not the one that could kill the hypothesis. Or they design an experiment so broad that it tests everything and proves nothing. This step forces clarity: what specific assumption are we targeting, and what question will the experiment answer?
+
+## Your Task
+
+### 1. Load and Review the Hypothesis Contract
+
+Review the complete hypothesis contract from Step 1. For each hypothesis, examine:
+
+| Field | What to extract |
+|-------|----------------|
+| **Expected Outcome** | What measurable result do we expect? |
+| **Target Behavior Change** | What specific user behavior should change? |
+| **Rationale** | What evidence supports this hypothesis? |
+| **Riskiest Assumption** | What single assumption could invalidate everything? |
+| **Hypothesis Statement** | "We believe that [target users] will [expected behavior] because [rationale]" |
+
+### 2. Review the Assumption Risk Map
+
+From the hypothesis contract (or from the assumption-mapping workflow if you ran it):
+
+| Priority | Assumption | Lethality | Uncertainty | Status |
+|----------|-----------|-----------|-------------|--------|
+| 1 (Test First) | *The assumption this experiment should target* | High | High/Med | Unvalidated |
+| 2 (Test Soon) | *Next priority* | Med/High | High/Med | Unvalidated |
+
+**Focus on "Test First" assumptions.** These are the ones with high lethality and high uncertainty — if they're wrong, the hypothesis collapses, and we don't have evidence either way.
+
+### 3. Select the Experiment Target
+
+Choose the specific assumption this experiment will test:
+
+| Element | Your answer |
+|---------|------------|
+| **Target Assumption** | *Which assumption from the risk map?* |
+| **Why This One?** | *Why is this the right assumption to test first?* |
+| **What Hypothesis Does It Belong To?** | *H1, H2, or H3?* |
+| **Testable Question** | *"If we do [intervention], will we observe [expected behavior]?"* |
+| **What Would Prove It Wrong?** | *What result would invalidate this assumption?* |
+
+**Challenge:** If you can't articulate what would prove the assumption wrong, it's not testable. Go back and sharpen the hypothesis.
+
+### 4. Scope the Experiment
+
+Before designing methodology, establish boundaries:
+
+| Constraint | Consideration |
+|-----------|--------------|
+| **Available Resources** | What can you realistically deploy? (users, budget, time, tools) |
+| **Access to Users** | Can you reach the target users? How many? |
+| **Measurement Capability** | Can you actually measure the expected behavior change? |
+| **Timeline Pressure** | How quickly do you need signal? |
+
+These constraints will guide methodology selection in the next step. Don't design a 6-week A/B test if you need signal in 2 weeks. Don't plan for 1,000 users if you can reach 20.
+
+---
+
+## Your Turn
+
+Load your hypothesis contract, review the risk map, select the experiment target, and articulate the testable question. Share your analysis and I'll help you challenge anything that feels too comfortable.
+
+## Next Step
+
+When your experiment target is clear and the testable question is articulated, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/experiment-design/steps/step-03-design.md

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

@@ -0,0 +1,114 @@
+---
+step: 3
+workflow: experiment-design
+title: Experiment Methodology & Success Criteria
+---
+
+# Step 3: Experiment Methodology & Success Criteria
+
+You know what assumption to test and what question the experiment needs to answer. Now let's design the experiment — methodology, metrics, success criteria, and duration. The key rule: define success before you see results.
+
+## Why This Matters
+
+The most dangerous moment in an experiment is after you see the data. That's when teams move the goalposts — "well, we didn't hit our target, but the qualitative feedback was positive!" Pre-defined success criteria prevent this. You commit to what success looks like before the experiment runs, and you hold yourself to it. No rationalizing. No reinterpreting. The data either supports the hypothesis or it doesn't.
+
+## Your Task
+
+### 1. Select Experiment Methodology
+
+Choose the methodology that best fits your target assumption and constraints from Step 2:
+
+| Methodology | Best For | Signal Strength | Cost/Effort |
+|------------|---------|-----------------|-------------|
+| **User Interview** | Validating user motivations, pain points, willingness | Qualitative (moderate) | Low |
+| **Concierge Test** | Testing value proposition with manual delivery | Moderate | Medium |
+| **Landing Page / Smoke Test** | Testing demand and willingness to act | Moderate | Low-Medium |
+| **Prototype Test** | Testing usability and comprehension | Moderate-High | Medium |
+| **A/B Test** | Testing behavior change at scale | High (quantitative) | High |
+| **Wizard of Oz** | Testing experience without building | Moderate-High | Medium |
+
+**Challenge:** Are you picking the right methodology, or the comfortable one? If the assumption is about user behavior at scale, a 5-person interview won't cut it. If the assumption is about willingness to pay, a landing page with no price won't test it. Match the methodology to the assumption, not to your budget.
+
+### 2. Define Pre-Defined Success Criteria
+
+**This is the most important part of experiment design.** Define success criteria BEFORE seeing any results:
+
+| Criterion | Metric | Target Threshold | What It Means |
+|-----------|--------|-----------------|---------------|
+| **Primary** | *The key metric that determines pass/fail* | *Specific number or percentage* | *If we hit this, the assumption is supported* |
+| **Secondary** | *Supporting metric* | *Specific threshold* | *Additional signal that strengthens or weakens the finding* |
+| **Kill Criteria** | *What would definitively invalidate the assumption* | *Specific threshold* | *If we see this, the hypothesis is dead — no rationalizing* |
+
+**Guidance:**
+- Thresholds must be **specific and measurable** — not "significant improvement" but "15% increase in conversion"
+- Define what **invalidation** looks like — what result would prove the assumption wrong?
+- Commit to these BEFORE the experiment runs. Write them down. Don't change them.
+
+### 3. Select Metrics
+
+**Primary Metric** — The single metric that determines experiment outcome:
+
+| Element | Your answer |
+|---------|------------|
+| **Metric Name** | *What are you measuring?* |
+| **How Measured** | *Tool, method, or observation technique* |
+| **Baseline** | *Current value or expected control value* |
+| **Target** | *What value would support the assumption?* |
+| **Minimum Detectable Effect** | *Smallest meaningful difference* |
+
+**Secondary Metrics** — Additional signals to monitor (don't optimize for these):
+
+| Metric | Purpose | How Measured |
+|--------|---------|-------------|
+| *Secondary metric 1* | *What additional signal does this provide?* | *Tool or method* |
+| *Secondary metric 2* | *What additional signal does this provide?* | *Tool or method* |
+
+### 4. Estimate Duration and Sample Size
+
+| Element | Your estimate | Rationale |
+|---------|--------------|-----------|
+| **Duration** | *How long will the experiment run?* | *Why this timeframe?* |
+| **Sample Size** | *How many participants/data points?* | *Minimum needed for signal* |
+| **Recruitment** | *How will you find participants?* | *Channel, criteria, incentives* |
+| **Controls** | *What's the baseline comparison?* | *Control group, historical data, or before/after* |
+
+**Challenge:** Is your sample size big enough to detect the effect you're looking for? Is the duration long enough for the behavior change to manifest? Don't design a 1-week test for a behavior that takes 3 weeks to change.
+
+### 5. Produce the Experiment Brief
+
+Consolidate your design into a structured experiment brief:
+
+| Field | Value |
+|-------|-------|
+| **Experiment Name** | *Descriptive name* |
+| **Target Assumption** | *From Step 2* |
+| **Methodology** | *Selected approach* |
+| **Hypothesis Statement** | *"We believe that [target users] will [expected behavior] because [rationale]"* |
+| **Primary Metric** | *Key indicator + target threshold* |
+| **Secondary Metrics** | *Supporting indicators* |
+| **Success Criteria** | *Pre-defined pass/fail thresholds* |
+| **Kill Criteria** | *What would invalidate the assumption* |
+| **Sample Size** | *Minimum participants/data points* |
+| **Duration** | *Estimated timeframe* |
+| **Recruitment** | *How participants are selected* |
+| **Controls** | *Baseline comparison method* |
+
+---
+
+## Your Turn
+
+Design the experiment: select methodology, define success criteria with specific thresholds, choose metrics, and estimate duration. Share your experiment brief and I'll help you stress-test it.
+
+---
+
+**[a]** Advanced Elicitation — Deep dive into experiment design with guided questioning
+**[p]** Party Mode — Bring in other Vortex agents to challenge your experiment design
+**[c]** Continue — Proceed to synthesis and routing
+
+---
+
+## Next Step
+
+When your experiment brief is complete, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/experiment-design/steps/step-04-synthesize.md

package/_bmad/bme/_vortex/workflows/experiment-design/steps/step-04-synthesize.md

@@ -0,0 +1,128 @@
+---
+step: 4
+workflow: experiment-design
+title: Synthesize & Route
+---
+
+# Step 4: Synthesize & Route
+
+You've identified the experiment target, designed the methodology, defined success criteria, and produced an experiment brief. Now let's produce the enriched HC3 artifact and figure out what happens next.
+
+## Why This Matters
+
+An experiment brief sitting in a document is useless. It needs to become an artifact that Wade can pick up and execute — with every detail he needs to run the experiment without coming back to ask questions. This step produces that artifact and routes you to the right next step.
+
+## Your Task
+
+### 1. Generate the Enriched HC3 Artifact
+
+Produce the enriched HC3 by combining the original hypothesis contract with the experiment design from Step 3.
+
+**HC3 Frontmatter:**
+
+```yaml
+---
+contract: HC3
+type: artifact
+source_agent: liam
+source_workflow: experiment-design
+target_agents: [wade]
+input_artifacts:
+  - path: "{original_hc3_path}"
+    contract: HC3
+created: {date}
+---
+```
+
+**HC3 Body — Original Sections (preserve from input):**
+1. Problem Context
+2. Hypothesis Contracts (1-3 in 4-field format)
+3. Assumption Risk Map
+4. Recommended Testing Order
+5. Flagged Concerns (if any)
+
+**HC3 Body — New Section 6: Experiment Design**
+
+| Field | Value |
+|-------|-------|
+| Experiment Name | *From Step 3 experiment brief* |
+| Target Assumption | *Which assumption this experiment tests* |
+| Methodology | *Selected experiment approach* |
+| Hypothesis Statement | *"We believe that [target users] will [expected behavior] because [rationale]"* |
+| Primary Metric | *Key indicator + target threshold* |
+| Secondary Metrics | *Supporting indicators (if any)* |
+| Success Criteria | *Pre-defined pass/fail thresholds* |
+| Kill Criteria | *What would invalidate the assumption* |
+| Sample Size | *Minimum participants/data points* |
+| Duration | *Estimated experiment timeframe* |
+| Recruitment/Selection | *How participants are selected (if applicable)* |
+| Controls | *Baseline comparison method* |
+
+**Save to:** `{output_folder}/vortex-artifacts/hc3-experiment-design-{date}.md`
+
+### 2. Validation Questions
+
+Before routing, verify the experiment design is sound:
+
+**Design Quality Check:**
+- [ ] The experiment targets the riskiest assumption, not the easiest one to test
+- [ ] Success criteria are pre-defined with specific, measurable thresholds
+- [ ] Kill criteria are defined — you know what would prove the assumption wrong
+- [ ] Methodology matches the type of assumption being tested
+- [ ] Sample size and duration are realistic for the methodology chosen
+
+**Completeness Check:**
+- [ ] All experiment brief fields are filled with specific values, not placeholders
+- [ ] Primary metric has a baseline and target threshold
+- [ ] The experiment would survive scrutiny from a skeptic
+
+**Handoff Check:**
+- [ ] Wade could execute this experiment without asking clarifying questions
+- [ ] The enriched HC3 contains everything needed: hypothesis, risk map, AND experiment design
+- [ ] Success criteria are objective — two different people would agree on pass/fail
+
+---
+
+## Your Turn
+
+Generate the enriched HC3 artifact and verify it passes the validation checks. Confirm when you're satisfied that the experiment design is complete and honest.
+
+---
+
+**[a]** Advanced Elicitation — Deep dive into experiment design validation with guided questioning
+**[p]** Party Mode — Bring in other Vortex agents to challenge your experiment design
+**[c]** Continue — 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 design is complete and ready for execution | lean-experiment | Wade 🧪 | Experiment design ready for execution (HC3) |
+| Hypothesis needs revision — design constraints revealed structural weaknesses | hypothesis-engineering | Liam 💡 | Revise hypothesis based on design constraints |
+| Pre-experiment validation needed — can't design experiment without more user data | user-interview | Isla 🔍 | Pre-experiment validation needed |
+
+> **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 gathered so far doesn't clearly point to a single next step:
+
+| To route to... | You need... |
+|----------------|-------------|
+| Wade 🧪 | Complete experiment brief with methodology, success criteria, metrics, and duration |
+| Liam 💡 | Clear signal that hypothesis needs structural revision before experiment design |
+| Isla 🔍 | Specific user knowledge gap that prevents experiment design |
+
+**Workflow-specific signals:**
+- Cannot define success criteria → hypothesis may be too vague; revisit **Liam's hypothesis-engineering**
+- Cannot select methodology → assumption type unclear; revisit **Liam's assumption-mapping** to sharpen the risk map
+- Need user behavior data before designing experiment → route to **Isla** for targeted interviews
+
+**Recommended:** Revisit earlier steps to strengthen your experiment design, or run **Max's [VN] Vortex Navigation** for a full gap analysis.

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

@@ -0,0 +1,51 @@
+---
+workflow: experiment-design
+type: step-file
+description: Design experiments targeting riskiest assumptions first — methodology, success criteria, metrics, and duration before handing off to Wade
+author: Liam (hypothesis-engineer)
+version: 1.6.0
+---
+
+# Experiment Design Workflow
+
+This workflow guides you through designing the experiment that will test your riskiest assumptions — selecting methodology, defining success criteria before you see results, choosing metrics, and producing an experiment brief that Wade can execute.
+
+## What is Experiment Design?
+
+Experiment design is the bridge between having a hypothesis and actually testing it. A hypothesis without an experiment is just an opinion. An experiment without design is just messing around.
+
+What's the bold version of your experiment? Most teams default to the cheapest, safest test — a survey, a landing page, a "would you use this?" question. But cheap tests produce cheap answers. This workflow forces you to design an experiment that actually tests the riskiest assumption, with pre-defined success criteria you commit to before seeing any results. No moving the goalposts.
+
+If you can't define what would prove your hypothesis wrong, you're not ready to test it.
+
+## Workflow Structure
+
+**Step-file architecture:**
+- Just-in-time loading (each step loads only when needed)
+- Sequential enforcement (must complete step N before step N+1)
+- State tracking in frontmatter (progress preserved)
+
+## Steps Overview
+
+1. **Setup & Input Validation** - Validate your hypothesis contract (HC3 artifact or equivalent input)
+2. **Hypothesis Context & Experiment Targets** - Load the hypothesis, review the risk map, identify what to test
+3. **Experiment Methodology & Success Criteria** - Design the experiment: methodology, metrics, success thresholds, duration
+4. **Synthesize & Route** - Produce enriched HC3 with experiment parameters and route via Compass
+
+## Output
+
+**Artifact:** Enriched HC3 Hypothesis Contract with experiment parameters appended, saved to `{output_folder}/vortex-artifacts/hc3-experiment-design-{date}.md`
+
+**Template:** None (enriched HC3 artifact is generated inline during Step 4)
+
+**Schema:** Conforms to HC3 contract (`_bmad/bme/_vortex/contracts/hc3-hypothesis-contract.md`) with additional Experiment Design section
+
+**Consumer:** Wade (lean-experiment) uses this enriched HC3 as the experiment brief — methodology, success criteria, and metrics are ready for execution.
+
+---
+
+## INITIALIZATION
+
+Load config from {project-root}/_bmad/bme/_vortex/config.yaml
+
+Load step: {project-root}/_bmad/bme/_vortex/workflows/experiment-design/steps/step-01-setup.md

package/_bmad/bme/_vortex/workflows/hypothesis-engineering/steps/step-01-setup.md

@@ -0,0 +1,66 @@
+---
+step: 1
+workflow: hypothesis-engineering
+title: Setup & Input Validation
+---
+
+# Step 1: Setup & Input Validation
+
+Before we engineer any hypotheses, we need to know exactly what problem we're working from and verify the foundation is solid enough to build on.
+
+## Why This Matters
+
+Good hypotheses are falsifiable — if you can't prove it wrong, it's not a hypothesis. But falsifiability starts with a clear problem definition. If the problem is vague, the hypotheses will be vague. If the evidence is weak, the assumptions will be invisible. This step ensures we start with a validated problem definition so every hypothesis we engineer is grounded in real evidence, not guesswork.
+
+## Your Task
+
+### 1. What Problem Definition Do You Have?
+
+Liam expects a problem definition — ideally produced by Mila's research-convergence workflow as an HC2-compliant artifact:
+- **HC2 Problem Definition** (from Mila's `research-convergence` workflow)
+- **HC2 Revised Problem Definition** (from Mila's `pivot-resynthesis` workflow)
+
+You can also bring **any well-formed problem definition** — Liam accepts input from outside the Vortex pattern. It doesn't have to be HC2-compliant, but having a structured problem definition with explicit JTBD and Pains & Gains makes hypothesis engineering dramatically stronger.
+
+### 2. Provide Your Input
+
+Please provide the file path or describe the problem definition you want to engineer hypotheses from. For example:
+- `_bmad-output/vortex-artifacts/hc2-problem-definition-2026-02-25.md`
+- Or: "I have a problem statement and some user research findings I'd like to use"
+
+### 3. Input Validation
+
+I'll check your artifact against the HC2 schema to assess readiness:
+
+**HC2 Frontmatter Check:**
+- `contract: HC2`
+- `type: artifact`
+- `source_agent` (who produced it)
+- `source_workflow` (which workflow)
+- `target_agents: [liam]`
+- `input_artifacts` (upstream references)
+- `created` (date)
+
+**HC2 Body Section Check:**
+- Converged Problem Statement (Problem Statement, Confidence, Scope)
+- Jobs-to-be-Done (Primary JTBD + Functional/Emotional/Social Jobs)
+- Pains (prioritized list with evidence sources)
+- Gains (prioritized list with evidence sources)
+- Evidence Summary (artifacts analyzed, convergence assessment, gaps)
+- Assumptions (with basis and risk if wrong)
+
+**If your input is non-conforming:** That's okay — we don't reject problem definitions. I'll guide you to identify which elements are present and which gaps we need to work around during hypothesis engineering. But let's stress-test what we have: the stronger the problem definition, the sharper the hypotheses.
+
+> For the full HC2 schema reference, see `{project-root}/_bmad/bme/_vortex/contracts/hc2-problem-definition.md`
+
+---
+
+## Your Turn
+
+Please provide your problem definition — file path, description, or both. I'll validate it and we'll proceed to unpacking the opportunity space.
+
+## Next Step
+
+When your problem definition is provided and validated, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/hypothesis-engineering/steps/step-02-context.md