convoke-agents 2.0.0

package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-05-recommendation.md

@@ -0,0 +1,65 @@
+---
+step: 5
+workflow: vortex-navigation
+title: Recommendation
+---
+
+# Step 5: Generate Recommendation
+
+Based on the scoring matrix and gap analysis, let's formulate a clear recommendation for your next stream focus.
+
+## Your Task
+
+### Primary Recommendation
+
+**Recommended next stream:** {stream name}
+
+**Rationale:**
+- Score: {total from matrix} (highest/near-highest)
+- Critical gap addressed: {which gap}
+- Risk reduced: {which risk}
+- Why now: {urgency or dependency reason}
+
+### Alternative Option
+
+If the primary recommendation isn't feasible:
+
+**Alternative stream:** {stream name}
+**When to choose this instead:** {conditions}
+
+### What NOT to Do Next
+
+**Avoid:** {stream name}
+**Why:** {rationale -- e.g., "You don't have enough evidence yet" or "This depends on completing X first"}
+
+### Expected Outcomes
+
+If you successfully complete the recommended stream, you should:
+1. {outcome 1 -- specific deliverable or learning}
+2. {outcome 2}
+3. {outcome 3}
+
+### Success Criteria
+
+How will you know the stream was successful?
+- [ ] {measurable criterion 1}
+- [ ] {measurable criterion 2}
+- [ ] {measurable criterion 3}
+
+### Confidence Assessment
+
+**Confidence in this recommendation:** {high / medium / low}
+**Key assumption behind recommendation:** {what could make this wrong}
+**Re-evaluate if:** {trigger condition to reconsider}
+
+---
+
+## Your Turn
+
+Review and refine the recommendation. Challenge it: Does this recommendation feel right given everything you've learned? If something feels off, that intuition is worth exploring.
+
+## Next Step
+
+When the recommendation is finalized, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-06-navigation-plan.md

package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-06-navigation-plan.md

@@ -0,0 +1,72 @@
+---
+step: 6
+workflow: vortex-navigation
+title: Create Navigation Plan
+---
+
+# Step 6: Create Navigation Plan
+
+Let's turn the recommendation into an actionable plan with clear next steps, timeline, and success criteria.
+
+## Your Task
+
+### Navigation Plan
+
+**Target stream:** {recommended stream}
+**Agent to activate:** {agent name and file}
+**Estimated duration:** {timeframe}
+
+### Immediate Next Steps
+
+1. **First action:** {what to do right now}
+   - Agent/workflow: {which agent and workflow to use}
+   - Expected output: {deliverable}
+
+2. **Second action:** {next step}
+   - Agent/workflow: {which agent and workflow}
+   - Expected output: {deliverable}
+
+3. **Third action:** {following step}
+   - Agent/workflow: {which agent and workflow}
+   - Expected output: {deliverable}
+
+### Resources Needed
+
+- [ ] {resource 1 -- e.g., "Access to 5 target users for interviews"}
+- [ ] {resource 2 -- e.g., "Analytics dashboard access"}
+- [ ] {resource 3}
+
+### Checkpoints
+
+**Checkpoint 1** (after {timeframe}):
+- Check: {what to evaluate}
+- If on track: continue
+- If off track: {adjustment}
+
+**Checkpoint 2** (after {timeframe}):
+- Check: {what to evaluate}
+- If sufficient evidence gathered: move to next stream
+- If insufficient: extend or pivot approach
+
+### Re-navigation Triggers
+
+Come back to Vortex Navigation if:
+- [ ] A major assumption is invalidated
+- [ ] The team discovers a new critical gap
+- [ ] The recommended stream produces unexpected insights
+- [ ] External conditions change significantly
+- [ ] {custom trigger}
+
+---
+
+## Synthesize
+
+Now let's create the final navigation recommendation artifact using the template.
+
+**Output file:** `{output_folder}/vortex-navigation-{date}.md`
+
+Fill in the template with all decisions made during this workflow.
+
+---
+
+**Reminder:** Navigation is not a one-time activity. As you progress through the recommended stream and generate new evidence, revisit this workflow to recalibrate your direction. The Vortex is iterative by design.

package/_bmad/bme/_vortex/workflows/vortex-navigation/validate.md

@@ -0,0 +1,75 @@
+---
+workflow: validate-vortex-navigation
+type: single-file
+description: Validate a vortex navigation recommendation against evidence and reasoning
+author: Max (learning-decision-expert)
+---
+
+# Validate Vortex Navigation Recommendation
+
+Bring me a navigation recommendation and I'll validate the reasoning, evidence basis, and plan quality.
+
+## Validation Process
+
+### 1. Evidence Basis Check
+
+For the recommendation, ask:
+- Is the current state assessment accurate and complete?
+- Are all relevant artifacts accounted for?
+- Is evidence quality rated honestly (not inflated)?
+
+**Red Flags:**
+- Streams marked "complete" with no artifacts
+- High confidence with limited evidence
+- Key streams not assessed at all
+
+### 2. Gap Analysis Quality
+
+- Are the identified gaps real risks or just "nice to know"?
+- Is the critical gap truly the most critical?
+- Are there obvious gaps that were missed?
+
+### 3. Scoring Integrity
+
+- Do the scores align with the evidence inventory?
+- Is there comfort zone bias (familiar streams scored higher)?
+- Are feasibility scores realistic?
+
+### 4. Recommendation Logic
+
+- Does the recommended stream address the most critical gap?
+- Is the rationale clear and evidence-based?
+- Does the alternative make sense as a backup?
+- Is the "avoid" recommendation justified?
+
+### 5. Plan Actionability
+
+- Are next steps specific enough to execute?
+- Are success criteria measurable?
+- Are re-navigation triggers appropriate?
+
+---
+
+## Validation Criteria
+
+**Strong Navigation:**
+- Accurate state assessment with evidence
+- Critical gaps clearly identified
+- Scoring aligns with evidence
+- Recommendation logically follows from analysis
+- Plan is specific and actionable
+
+**Needs Work:**
+- Some gaps in state assessment
+- Scoring doesn't fully align with evidence
+- Plan needs more specificity
+
+**Weak Navigation:**
+- State assessment based on assumptions
+- Critical gaps not identified
+- Recommendation driven by preference, not evidence
+- Plan is vague or unrealistic
+
+---
+
+Ready to validate your navigation recommendation? Share it with me and I'll provide detailed feedback.

package/_bmad/bme/_vortex/workflows/vortex-navigation/vortex-navigation.template.md

@@ -0,0 +1,105 @@
+---
+title: "Vortex Navigation: {date}"
+date: {date}
+created-by: {user-name} with Max (learning-decision-expert)
+current-streams-completed: {list}
+recommended-next-stream: {stream}
+confidence: {high/medium/low}
+status: DRAFT
+---
+
+# Vortex Navigation Recommendation
+
+## Current State Summary
+
+**Streams completed:** {completed-list}
+**Streams in progress:** {in-progress-list}
+**Streams not started:** {not-started-list}
+
+**Team context:** {brief-context}
+
+---
+
+## Evidence Summary
+
+**Total artifacts reviewed:** {count}
+**Strongest evidence areas:** {areas}
+**Weakest evidence areas:** {areas}
+
+### Key Learnings to Date
+
+1. {learning-1}
+2. {learning-2}
+3. {learning-3}
+
+---
+
+## Gap Analysis
+
+### Critical Gaps
+
+| Gap | Risk Level | Stream to Address |
+|-----|-----------|-------------------|
+{gap-rows}
+
+### Untested Assumptions
+
+{untested-assumptions-list}
+
+---
+
+## Stream Evaluation Scores
+
+| Stream | Gap Severity | Risk Reduction | Dependency | Feasibility | Time Sensitivity | **Total** |
+|--------|-------------|----------------|------------|-------------|-----------------|-----------|
+{scoring-rows}
+
+---
+
+## Recommendation
+
+**Primary:** {recommended-stream}
+
+**Rationale:** {rationale}
+
+**Alternative:** {alternative-stream} (if {condition})
+
+**Avoid:** {avoid-stream} (because {reason})
+
+---
+
+## Navigation Plan
+
+**Target stream:** {stream}
+**Agent:** {agent-name} ({agent-file})
+**Duration:** {estimated-timeframe}
+
+### Next Steps
+
+1. {step-1}
+2. {step-2}
+3. {step-3}
+
+### Success Criteria
+
+- [ ] {criterion-1}
+- [ ] {criterion-2}
+- [ ] {criterion-3}
+
+### Re-navigation Triggers
+
+- {trigger-1}
+- {trigger-2}
+- {trigger-3}
+
+---
+
+**Created by:** {creator-name}
+**Created with:** Max (learning-decision-expert) - Convoke v2.0.0
+**Date:** {creation-date}
+**Version:** 1.0
+**Status:** {status}
+
+---
+
+*This navigation recommendation should be revisited as new evidence emerges from the recommended stream.*

package/_bmad/bme/_vortex/workflows/vortex-navigation/workflow.md

@@ -0,0 +1,54 @@
+---
+workflow: vortex-navigation
+type: step-file
+description: Navigate between Vortex streams based on current evidence and learning
+author: Max (learning-decision-expert)
+version: 1.5.0
+---
+
+# Vortex Navigation Workflow
+
+This workflow helps you decide which Vortex stream to focus on next based on your current progress, evidence, and learning gaps.
+
+## What is Vortex Navigation?
+
+The Innovation Vortex has 7 streams that teams can move between non-linearly. Rather than following a fixed sequence, teams should navigate based on what they've learned and what gaps remain. This workflow assesses your current state and recommends where to focus next.
+
+**The 7 Vortex Streams:**
+1. **Contextualize** (Emma) - Define problem space, vision, personas
+2. **Empathize** (Isla) - Understand users through research and empathy mapping
+3. **Synthesize** - Combine insights into actionable patterns
+4. **Hypothesize** - Generate testable hypotheses from insights
+5. **Externalize** (Wade) - Test hypotheses through experiments
+6. **Sensitize** - Measure impact and gather feedback
+7. **Systematize** (Max) - Capture learnings and make strategic decisions
+
+## 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. **Current State Assessment** - Where are you now? Which streams have you completed?
+2. **Evidence Inventory** - What artifacts, learning cards, and evidence exist?
+3. **Gap Analysis** - What's missing? What assumptions remain untested?
+4. **Stream Evaluation** - Which streams would provide the most value right now?
+5. **Recommendation** - Prioritized recommendation with rationale
+6. **Navigation Plan** - Concrete plan for the next stream with success criteria
+
+## Output
+
+**Artifact:** Navigation recommendation in `{output_folder}/vortex-navigation-{date}.md`
+
+**Template:** Uses [vortex-navigation.template.md](vortex-navigation.template.md)
+
+---
+
+## INITIALIZATION
+
+Load config from {project-root}/_bmad/bme/_vortex/config.yaml
+
+Load step: {project-root}/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-01-current-state.md

package/index.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+/**
+ * Convoke – Vortex Pattern
+ * Product discovery through Contextualize, Empathize, Externalize, and Systematize streams.
+ *
+ * This is a CLI-first package. Use the bin commands:
+ *   npx convoke-install-vortex  – Install all Vortex agents (primary)
+ *   npx convoke-install         – Install all agents (umbrella alias)
+ *   npx convoke-update          – Check for and apply updates
+ *   npx convoke-version         – Show installed vs latest version
+ *   npx convoke-doctor          – Diagnose installation issues
+ *
+ * @license MIT
+ */
+
+const path = require('path');
+const { AGENTS } = require('./scripts/update/lib/agent-registry');
+
+function getPackageInfo() {
+  const pkg = require(path.join(__dirname, 'package.json'));
+  return {
+    name: pkg.name,
+    version: pkg.version,
+    description: pkg.description
+  };
+}
+
+if (require.main === module) {
+  const info = getPackageInfo();
+  const BOLD = '\x1b[1m';
+  const RESET = '\x1b[0m';
+  const CYAN = '\x1b[36m';
+  const GREEN = '\x1b[32m';
+  const GRAY = '\x1b[90m';
+
+  console.log('');
+  console.log(`${BOLD}${info.name}${RESET} v${info.version}`);
+  console.log(info.description);
+  console.log('');
+  console.log(`${GREEN}Agents:${RESET}`);
+  for (const agent of AGENTS) {
+    const padded = agent.name.padEnd(5);
+    console.log(`  ${padded}${CYAN}${agent.icon}${RESET} – ${agent.title}`);
+  }
+  console.log('');
+  console.log(`${GREEN}Commands:${RESET}`);
+  console.log(`  ${CYAN}npx convoke-install-vortex${RESET}  Install all Vortex agents`);
+  console.log(`  ${CYAN}npx convoke-install${RESET}         Install all agents ${GRAY}(alias)${RESET}`);
+  console.log(`  ${CYAN}npx convoke-update${RESET}          Check for updates`);
+  console.log(`  ${CYAN}npx convoke-version${RESET}         Show version info`);
+  console.log(`  ${CYAN}npx convoke-doctor${RESET}          Diagnose issues`);
+  console.log('');
+}
+
+module.exports = { getPackageInfo };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "convoke-agents",
+  "version": "2.0.0",
+  "description": "Agent teams for complex systems, compatible with BMad Method",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "scripts/",
+    "_bmad/bme/_vortex/",
+    "INSTALLATION.md",
+    "UPDATE-GUIDE.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "bin": {
+    "convoke-install-vortex": "scripts/install-vortex-agents.js",
+    "convoke-install": "scripts/install-all-agents.js",
+    "convoke-update": "scripts/update/convoke-update.js",
+    "convoke-version": "scripts/update/convoke-version.js",
+    "convoke-migrate": "scripts/update/convoke-migrate.js",
+    "convoke-doctor": "scripts/convoke-doctor.js"
+  },
+  "scripts": {
+    "install:agents": "node scripts/install-all-agents.js",
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test tests/unit/*.test.js",
+    "test:p0": "node --test tests/p0/*.test.js",
+    "test:p0:gate": "node --test tests/p0/*.test.js",
+    "test:integration": "node --test tests/integration/*.test.js",
+    "test:all": "node --test tests/**/*.test.js",
+    "test:coverage": "c8 node --test tests/unit/*.test.js tests/integration/*.test.js tests/p0/*.test.js",
+    "lint": "eslint scripts/ index.js tests/",
+    "docs:audit": "node scripts/docs-audit.js"
+  },
+  "keywords": [
+    "convoke-agents",
+    "bmad-enhanced",
+    "bmad",
+    "agents",
+    "lean-startup",
+    "validated-learning",
+    "vortex",
+    "contextualize",
+    "externalize",
+    "empathize",
+    "systematize",
+    "user-research",
+    "decision-making",
+    "mvp",
+    "product-strategy",
+    "ai-agents"
+  ],
+  "author": "Convoke Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amalik/convoke-agents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/amalik/convoke-agents/issues"
+  },
+  "homepage": "https://github.com/amalik/convoke-agents#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "fs-extra": "^11.3.3",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "c8": "^10.1.3",
+    "eslint": "^10.0.0"
+  }
+}