convoke-agents 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -916,5 +916,5 @@ No changes to installation flow. Reinstallation will fix the Wade workflow bug.
 **For detailed technical documentation, see:**
 - [README.md](README.md) - Project overview
 - [INSTALLATION.md](INSTALLATION.md) - Installation guide
-- [BMAD-METHOD-COMPATIBILITY.md](BMAD-METHOD-COMPATIBILITY.md) - Integration details
+- [BMAD-METHOD-COMPATIBILITY.md](docs/BMAD-METHOD-COMPATIBILITY.md) - Integration details
 - User guides in `_bmad/bme/_vortex/guides/`

package/INSTALLATION.md

@@ -17,7 +17,7 @@ Convoke works **standalone** or as an extension to [BMAD Method](https://github.
 ## Quick Install
 
 ```bash
-npm install convoke-agents && npx convoke-install-vortex
+npm install convoke-agents && npx -p convoke-agents convoke-install-vortex
 ```
 
 All 7 Vortex agents (Emma, Isla, Mila, Liam, Wade, Noah, Max) with 22 workflows are installed and ready to use.
@@ -30,10 +30,10 @@ All 7 Vortex agents (Emma, Isla, Mila, Liam, Wade, Noah, Max) with 22 workflows
 
 ```bash
 # Install into your project
-npm install convoke
+npm install convoke-agents
 
 # Install all Vortex agents and workflows
-npx convoke-install-vortex
+npx -p convoke-agents convoke-install-vortex
 ```
 
 ### Option 2: Clone from Source (Contributors Only)
@@ -42,7 +42,7 @@ For contributors or developers who want to modify agents or contribute to the pr
 
 ```bash
 git clone https://github.com/amalik/convoke-agents.git
-cd convoke
+cd convoke-agents
 npm install
 ```
 
@@ -153,7 +153,7 @@ Hey Amalik! I'm Emma — your Contextualization Expert...
 If the agent doesn't activate or you see raw markdown instead, run diagnostics:
 
 ```bash
-npx convoke-doctor
+npx -p convoke-agents convoke-doctor
 ```
 
 This checks project root, config validity, agent files, workflows, output directory, and version consistency — with actionable fix suggestions for each issue.
@@ -165,14 +165,14 @@ This checks project root, config validity, agent files, workflows, output direct
 Start with diagnostics — it catches most issues:
 
 ```bash
-npx convoke-doctor
+npx -p convoke-agents convoke-doctor
 ```
 
 ### Permission denied errors
 
 ```bash
 chmod +x scripts/*.js
-npx convoke-install-vortex
+npx -p convoke-agents convoke-install-vortex
 ```
 
 ### Config file already exists
@@ -191,7 +191,7 @@ Check that files are in place:
 ```bash
 ls -la _bmad/bme/_vortex/agents/
 ls -la _bmad/bme/_vortex/workflows/
-npx convoke-doctor
+npx -p convoke-agents convoke-doctor
 ```
 
 ---
@@ -201,7 +201,7 @@ npx convoke-doctor
 1. **Read the user guides** in `_bmad-output/vortex-artifacts/`
 2. **Activate an agent** — start with Emma for strategic framing or Isla for user research
 3. **Follow a workflow** — each agent presents a menu of guided workflows
-4. **Check updates** — run `npx convoke-version` periodically
+4. **Check updates** — run `npx -p convoke-agents convoke-version` periodically
 
 See the [Agent Guide](docs/agents.md) for detailed workflow descriptions and the recommended Vortex flow.
 
@@ -222,7 +222,7 @@ rm -rf _bmad/bme/_vortex/
 rm -rf _bmad-output/vortex-artifacts/
 
 # 4. Uninstall npm package
-npm uninstall convoke
+npm uninstall convoke-agents
 ```
 
 ---

package/README.md

@@ -1,38 +1,47 @@
 <div align="center">
 
-<pre>
-  ██████╗ ██████╗ ███╗   ██╗██╗   ██╗ ██████╗ ██╗  ██╗███████╗
+```
+ ██████╗ ██████╗ ███╗   ██╗██╗   ██╗ ██████╗ ██╗  ██╗███████╗
  ██╔════╝██╔═══██╗████╗  ██║██║   ██║██╔═══██╗██║ ██╔╝██╔════╝
  ██║     ██║   ██║██╔██╗ ██║██║   ██║██║   ██║█████╔╝ █████╗
  ██║     ██║   ██║██║╚██╗██║╚██╗ ██╔╝██║   ██║██╔═██╗ ██╔══╝
  ╚██████╗╚██████╔╝██║ ╚████║ ╚████╔╝ ╚██████╔╝██║  ██╗███████╗
-  ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝  ╚═══╝   ╚═════╝ ╚═╝  ╚═╝╚══════╝
-       Agent teams for complex systems
-</pre>
-
-**Validate your product ideas before writing a single line of code — 7 discovery agents guide you from insight to evidence**
+ ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝  ╚═══╝   ╚═════╝ ╚═╝  ╚═╝╚══════╝
+                Agent teams for complex systems
+```
 
 [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://github.com/amalik/convoke-agents)
-[![Agents](https://img.shields.io/badge/agents-7-brightgreen)](docs/agents.md)
-[![Workflows](https://img.shields.io/badge/workflows-22-success)](docs/agents.md)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 </div>
 
-Most teams skip validation and build on assumptions. Convoke guides you through seven discovery streams — from understanding your users to testing your riskiest assumptions — so you can make evidence-based decisions before committing to code. Each stream builds on the previous one's findings, and when gaps appear, the system routes you back to fill them.
+Convoke organizes AI agents into domain-specialized teams. Each team brings deep expertise to a specific discipline — product discovery, implementation, operations, or whatever your domain requires. **Vortex**, the product discovery team, is the first. You can install teams independently or combine them.
+
+---
+
+## Vortex — Product Discovery Team
+
+**7 agents guide you from insight to evidence and back again — a continuous discovery loop, not a one-shot checklist**
+
+[![Agents](https://img.shields.io/badge/agents-7-brightgreen)](docs/agents.md)
+[![Workflows](https://img.shields.io/badge/workflows-22-success)](docs/agents.md)
+
+**Most teams skip validation and build on assumptions.**
+
+Vortex guides you through seven discovery streams — from understanding your users to interpreting production signals — so you can make evidence-based decisions before, during, and after you build. Each stream builds on the previous one's findings, and when gaps appear, the system routes you back to fill them.
 
 ```
                          7 Streams · 7 Agents
 
   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
-  │   Isla 🔍    │──▶│   Mila 🔬    │──▶│   Liam 💡    │──▶│   Wade 🧪    │
+  │     Isla    │──▶│     Mila    │──▶│     Liam    │──▶│     Wade    │
   │  Empathize  │   │ Synthesize  │   │ Hypothesize │   │ Externalize │
   └─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘
          ▲                                                       │
          │                                                       │
          │                                                       ▼
-  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │
-  │   Emma 🎯    │◀──│   Max  🧭    │◀──│   Noah 📡    │◀──────────┘
+  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐            │
+  │     Emma    │◀──│     Max     │◀──│     Noah    │◀───────────┘
   │Contextualize│   │ Systematize │   │  Sensitize  │
   └─────────────┘   └─────────────┘   └─────────────┘
          │                 │                 │
@@ -40,7 +49,35 @@ Most teams skip validation and build on assumptions. Convoke guides you through
           ▶ Start at Emma · back to any stream
 ```
 
-Each agent above runs one of these streams. You don't follow a fixed path — the system guides you to whichever stream needs attention based on what you've learned so far.
+*Suggested flow. Each workflow ends with a Compass routing to whichever stream needs attention — you can start or return to any agent.*
+
+<details>
+<summary>22 Vortex Workflows</summary>
+
+- Assumption Mapping
+- Behavior Analysis
+- Contextualize Scope
+- Empathy Map
+- Experiment Design
+- Hypothesis Engineering
+- Lean Experiment
+- Lean Persona
+- Learning Card
+- MVP
+- Pattern Mapping
+- Pivot Patch Persevere
+- Pivot Resynthesis
+- Product Vision
+- Production Monitoring
+- Proof of Concept
+- Proof of Value
+- Research Convergence
+- Signal Interpretation
+- User Discovery
+- User Interview
+- Vortex Navigation
+
+</details>
 
 | Agent | Stream | What they do |
 |-------|--------|-------------|
@@ -49,35 +86,78 @@ Each agent above runs one of these streams. You don't follow a fixed path — th
 | **Mila** 🔬 | Synthesize | Converge research into clear problem definitions |
 | **Liam** 💡 | Hypothesize | Turn problems into testable hypotheses and experiments |
 | **Wade** 🧪 | Externalize | Test assumptions with MVPs, experiments, and prototypes |
-| **Noah** 📡 | Sensitize | Interpret production signals and user behavior |
+| **Noah** 📡 | Sensitize | Interpret production signals, user behavior, and engagement patterns |
 | **Max** 🧭 | Systematize | Capture learnings and decide: pivot, patch, or persevere |
 
+### What Agents Produce
+
+Here's a sample of real output from a busy parents meal planning project — each excerpt is from the [full 7-agent journey example](_bmad-output/journey-examples/busy-parents-7-agent-journey.md).
+
+#### Emma 🎯 Contextualize
+
+Emma frames the right problem. Here's the Job-to-be-Done she produced:
+
+> **Job-to-be-Done:** Eliminate the daily 5:30 PM dinner decision so I can feed my family well without the mental load of planning, shopping, and deciding under time pressure.
+>
+> **Riskiest Assumptions:**
+> 1. Decision fatigue — not cooking skill or ingredient access — is the primary barrier to weeknight dinner success
+> 2. Parents would trust and act on an externally-provided dinner suggestion rather than needing to choose themselves
+> 3. "Good enough" nutrition is an acceptable standard — parents aren't seeking perfection, they're seeking relief from guilt
+
+#### Liam 💡 Hypothesize
+
+Liam turns problems into testable ideas. Here's one of three hypotheses he produced:
+
+> **Hypothesis 1: The Pre-Commute Decision Eliminator**
+>
+> We believe that busy parents will act on a single dinner suggestion delivered at 4:00 PM within 3 minutes because the decision burden — not cooking — is their primary barrier, and an earlier intervention catches them before the anxiety spiral begins.
+>
+> **Riskiest Assumption:** Parents will trust and act on an automated suggestion without second-guessing. Research shows they want "someone to tell me what to make" — but "someone" may need to be a trusted person, not an algorithm.
+
+#### Max 🧭 Systematize
+
+Max captures what you learned and decides what to do next:
+
+> **Recommendation: PATCH** (iterate on timing, don't pivot direction)
+>
+> The core hypothesis is validated. The product direction (decision elimination via single suggestion) is correct. The timing mechanism needs refinement — shift from fixed 4:00 PM delivery to adaptive delivery based on each user's observed engagement pattern.
+>
+> **Three Actions:**
+> 1. **Implement adaptive timing** — shift the push notification to match each user's observed engagement window. Engineering effort: 1-2 sprints.
+> 2. **Route to Isla for timing investigation** — qualitative research on why users engage at 3:15 PM. Is it anxiety relief, logistical planning, or habit?
+> 3. **Test willingness to pay immediately** — the mechanism works, but we have no commercial validation. Run a landing page test with pricing before further product investment.
+
+Want to see the complete walkthrough of all 7 agents applied to the example above?
+
+**[See the full 7-agent journey example →](_bmad-output/journey-examples/busy-parents-7-agent-journey.md)**
+
 ---
 
-## Quick Start
+### Quick Start
 
-### Prerequisites
+#### Prerequisites
 
 - Node.js 18+ or Bun
 - Git
 - Claude Code or Claude.ai
 
-### Install
+#### Install
 
 ```bash
-npm install convoke-agents && npx convoke-install-vortex
+npm install convoke-agents && npx -p convoke-agents convoke-install-vortex
 ```
 
-All 7 agents with 22 workflows are installed and ready to use.
+All 7 agents with 22 workflows are installed and ready to use. Something not working? Run `npx -p convoke-agents convoke-doctor` or check the [FAQ](docs/faq.md).
 
-### Personalize
+#### Personalize
 
 Open `_bmad/bme/_vortex/config.yaml` and replace `{user}` with your name. Agents use this to personalize their interactions.
 
-### Activate an Agent
+#### Activate an Agent
+
+**Claude Code / Terminal**
 
 ```bash
-# Read an agent file to activate it
 cat _bmad/bme/_vortex/agents/contextualization-expert.md          # Emma  🎯
 cat _bmad/bme/_vortex/agents/discovery-empathy-expert.md          # Isla  🔍
 cat _bmad/bme/_vortex/agents/research-convergence-specialist.md   # Mila  🔬
@@ -87,14 +167,13 @@ cat _bmad/bme/_vortex/agents/production-intelligence-specialist.md # Noah  📡
 cat _bmad/bme/_vortex/agents/learning-decision-expert.md          # Max   🧭
 ```
 
-**How activation works:** Each agent is a markdown file containing a full persona, menu system, and workflow instructions. When Claude reads the file, it adopts that agent's expertise and presents you with an interactive menu.
+**Claude.ai**
 
-- **Claude Code / Terminal:** Use the `cat` commands above
-- **Claude.ai:** Copy the contents of any agent file and paste into the chat
+Open any agent file from `_bmad/bme/_vortex/agents/` and paste its contents into your conversation.
 
-Pick a workflow from the menu and follow the guided steps.
+**How activation works:** Each agent is a markdown file containing a full persona, menu system, and workflow instructions. When Claude reads the file, it adopts that agent's expertise and presents you with an interactive menu. Pick a workflow from the menu and follow the guided steps.
 
-### Your First 15 Minutes
+#### Your First 15 Minutes
 
 1. **Personalize** — If you haven't already, edit `_bmad/bme/_vortex/config.yaml` and replace `{user}` with your name
 2. **Activate Emma** — `cat _bmad/bme/_vortex/agents/contextualization-expert.md`
@@ -105,7 +184,7 @@ Pick a workflow from the menu and follow the guided steps.
 
 Each workflow ends with a Compass routing suggestion. You don't need to follow a linear path — the system guides you to whichever stream needs attention.
 
-### What Gets Installed
+#### What Gets Installed
 
 ```
 your-project/
@@ -121,69 +200,25 @@ your-project/
 
 ---
 
-## Updating
+### Updating
 
 ```bash
-npx convoke-version              # Check current version
-npx convoke-update --dry-run     # Preview changes
-npx convoke-update               # Apply update (auto-backup)
-npx convoke-doctor               # Diagnose issues
+npx -p convoke-agents convoke-version          # Check current version
+npx -p convoke-agents convoke-update --dry-run  # Preview changes
+npx -p convoke-agents convoke-update            # Apply update (auto-backup)
+npx -p convoke-agents convoke-doctor            # Diagnose issues
 ```
 
 Your data in `_bmad-output/` is never touched. Automatic backups are created before every update.
 
 > **Tip:** If `npx convoke-update` reports "Already up to date" but you know a newer version exists, npx may be serving a cached copy. Force the latest with:
 > ```bash
-> npx -p convoke-agents@latest convoke-update
+> npx -p convoke-agents@latest convoke-update --yes
 > ```
 
 See [UPDATE-GUIDE.md](UPDATE-GUIDE.md) for migration paths and troubleshooting.
 
-## What Agents Produce
-
-Here's a sample of real output from a busy parents meal planning project — each excerpt is from the [full 7-agent journey example](_bmad-output/journey-examples/busy-parents-7-agent-journey.md).
-
-### Emma 🎯 Contextualize
-
-Emma frames the right problem. Here's the Job-to-be-Done she produced:
-
-> **Job-to-be-Done:** Eliminate the daily 5:30 PM dinner decision so I can feed my family well without the mental load of planning, shopping, and deciding under time pressure.
->
-> **Riskiest Assumptions:**
-> 1. Decision fatigue — not cooking skill or ingredient access — is the primary barrier to weeknight dinner success
-> 2. Parents would trust and act on an externally-provided dinner suggestion rather than needing to choose themselves
-> 3. "Good enough" nutrition is an acceptable standard — parents aren't seeking perfection, they're seeking relief from guilt
-
-### Liam 💡 Hypothesize
-
-Liam turns problems into testable ideas. Here's one of three hypotheses he produced:
-
-> **Hypothesis 1: The Pre-Commute Decision Eliminator**
->
-> We believe that busy parents will act on a single dinner suggestion delivered at 4:00 PM within 3 minutes because the decision burden — not cooking — is their primary barrier, and an earlier intervention catches them before the anxiety spiral begins.
->
-> **Riskiest Assumption:** Parents will trust and act on an automated suggestion without second-guessing. Research shows they want "someone to tell me what to make" — but "someone" may need to be a trusted person, not an algorithm.
-
-### Max 🧭 Systematize
-
-Max captures what you learned and decides what to do next:
-
-> **Recommendation: PATCH** (iterate on timing, don't pivot direction)
->
-> The core hypothesis is validated. The product direction (decision elimination via single suggestion) is correct. The timing mechanism needs refinement — shift from fixed 4:00 PM delivery to adaptive delivery based on each user's observed engagement pattern.
->
-> **Three Actions:**
-> 1. **Implement adaptive timing** — shift the push notification to match each user's observed engagement window. Engineering effort: 1-2 sprints.
-> 2. **Route to Isla for timing investigation** — qualitative research on why users engage at 3:15 PM. Is it anxiety relief, logistical planning, or habit?
-> 3. **Test willingness to pay immediately** — the mechanism works, but we have no commercial validation. Run a landing page test with pricing before further product investment.
-
-Want to see the complete walkthrough of all 7 agents applied to the example above?
-
-**📖 [See the full 7-agent journey example →](_bmad-output/journey-examples/busy-parents-7-agent-journey.md)**
-
----
-
-## Using the Agents
+### Using the Agents
 
 Each agent can be used independently or as part of the full Vortex flow:
 
@@ -195,7 +230,7 @@ Each agent can be used independently or as part of the full Vortex flow:
 6. **Noah (Sensitize)** — Start here when experiments have graduated to production
 7. **Max (Systematize)** — Start here when you have results and need to decide next steps
 
-Max's **Vortex Navigation** workflow helps identify which stream needs attention based on evidence gaps — you don't have to follow a linear path. Every workflow ends with a **Vortex Compass** that routes you to the right next agent based on what you learned. Ten handoff contracts (HC1-HC10) ensure structured information flows between agents, so each agent gets exactly the data it needs from the previous one.
+Max's **Vortex Navigation** workflow helps identify which stream needs attention based on evidence gaps — you don't have to follow a linear path. Every workflow ends with a **Vortex Compass** that routes you to the right next agent based on what you learned. Ten handoff contracts (HC1-HC10) ensure structured information flows between agents — see the [contracts directory](_bmad/bme/_vortex/contracts/) for details.
 
 For detailed workflow descriptions and usage examples, see the [Agent Guide](docs/agents.md) and the individual user guides:
 
@@ -211,17 +246,16 @@ For detailed workflow descriptions and usage examples, see the [Agent Guide](doc
 
 ## How It Fits with BMAD Core
 
-Convoke handles **pre-implementation validation**. BMAD Core handles **implementation**.
+Convoke handles **discovery and validation**. BMAD Core handles **implementation**.
 
 ```
-Convoke (Vortex)                                BMAD Core
-┌──────────────────────────────────────┐       ┌──────────────────────┐
-│ Isla → Mila → Liam → Wade → Noah    │ ───>  │ PM → Architect → Dev │
-│   ↑                          ↓       │       │ "Let's build it"     │
-│   └──── Max ◀── Noah    Max ↻        │       └──────────────────────┘
-│ Emma provides context at any point   │
-│ "Should we build this?"             │
-└──────────────────────────────────────┘
+Convoke Teams                              BMAD Core
+┌──────────────────────────────┐          ┌──────────────────────┐
+│ Vortex (Product Discovery)   │ ──────>  │ PM → Architect → Dev │
+│   "Should we build this?"    │          │ "Let's build it"     │
+│                              │ <──────  │                      │
+│ [Future teams]               │  signals │                      │
+└──────────────────────────────┘          └──────────────────────┘
 ```
 
 Convoke works standalone or as an extension — no BMAD Method installation required.
@@ -247,7 +281,7 @@ Convoke works standalone or as an extension — no BMAD Method installation requ
 - **v1.6.x** — Wave 3: Complete 7-stream Vortex (added Mila, Liam, Noah — 7 agents, 22 workflows, handoff contracts, Compass routing)
 - **v1.7.0** — Wave 4: Quality & onboarding (P0 test suite, docs audit tool, all 22 workflows production-ready, README overhaul, package size fix)
 - **v2.0.0** — Product renamed to Convoke. CLI commands renamed to `convoke-*`. Package: `npm install convoke-agents`
-- **Next** — Multi-agent collaboration, cross-agent workflows, analytics
+- **Next** — Additional domain-specialized teams, multi-agent collaboration, cross-team workflows
 
 ---
 

package/UPDATE-GUIDE.md

@@ -11,10 +11,10 @@ How to update your Convoke installation to the latest version.
 npm install convoke-agents@latest
 
 # Preview changes (dry run)
-npx convoke-update --dry-run
+npx -p convoke-agents convoke-update --dry-run
 
 # Apply the update
-npx convoke-update
+npx -p convoke-agents convoke-update
 ```
 
 Your data is backed up automatically before any changes.
@@ -23,7 +23,7 @@ Your data is backed up automatically before any changes.
 
 ## Update Commands
 
-### `npx convoke-update`
+### `convoke-update`
 
 Main update command — applies migrations and refreshes your installation.
 
@@ -34,27 +34,29 @@ Main update command — applies migrations and refreshes your installation.
 | `--verbose` or `-v` | Show detailed output |
 
 ```bash
-npx convoke-update --dry-run     # Preview
-npx convoke-update               # Apply with confirmation
-npx convoke-update --yes         # Apply without confirmation
+npx -p convoke-agents convoke-update --dry-run     # Preview
+npx -p convoke-agents convoke-update               # Apply with confirmation
+npx -p convoke-agents convoke-update --yes          # Apply without confirmation
 ```
 
-### `npx convoke-version`
+### `convoke-version`
 
 Show current version, latest available version, and migration history.
 
 ```bash
-npx convoke-version
+npx -p convoke-agents convoke-version
 ```
 
-### `npx convoke-doctor`
+### `convoke-doctor`
 
 Run diagnostics on your installation. Checks project root, config validity, agent files, workflows, output directory permissions, migration lock status, and version consistency — with actionable fix suggestions.
 
 ```bash
-npx convoke-doctor
+npx -p convoke-agents convoke-doctor
 ```
 
+> **Why `-p convoke-agents`?** The CLI commands (`convoke-update`, `convoke-doctor`, etc.) are binaries inside the `convoke-agents` package. Without `-p convoke-agents`, npx tries to find a standalone package with that name, which doesn't exist.
+
 ---
 
 ## Migration Paths
@@ -93,8 +95,8 @@ What happens:
 
 ```bash
 npm install convoke-agents@latest
-npx convoke-update --dry-run  # Preview
-npx convoke-update            # Apply
+npx -p convoke-agents convoke-update --dry-run  # Preview
+npx -p convoke-agents convoke-update            # Apply
 ```
 
 ---
@@ -141,7 +143,7 @@ Artifacts created with earlier agents (Emma, Isla, Wade, Max) were not designed
 
 ### What Is Managed by the Update System
 
-These change between versions but are handled automatically by `npx convoke-update`:
+These change between versions but are handled automatically by `convoke-update`:
 
 - **Agent definition files** — Persona, menu, and instruction content in `_bmad/bme/_vortex/agents/`
 - **Workflow step files** — Step content, templates, and validation in `_bmad/bme/_vortex/workflows/`
@@ -160,10 +162,10 @@ A previous migration may have crashed. Remove the lock file:
 
 ```bash
 rm _bmad-output/.migration-lock
-npx convoke-update
+npx -p convoke-agents convoke-update
 ```
 
-Or run `npx convoke-doctor` to diagnose — it detects stale locks.
+Or run `npx -p convoke-agents convoke-doctor` to diagnose — it detects stale locks.
 
 ### Update fails and won't rollback
 
@@ -181,7 +183,7 @@ cp -r _bmad-output/.backups/{backup-dir}/workflows _bmad/bme/_vortex/
 
 ### "Already up to date" but version is outdated
 
-npx caches package binaries. If you installed at an older version, `npx convoke-update` may keep running the cached script instead of the latest. Force-fetch the latest:
+npx caches package binaries. If you installed at an older version, `convoke-update` may keep running the cached script instead of the latest. Force-fetch the latest:
 
 ```bash
 npx -p convoke-agents@latest convoke-update
@@ -194,7 +196,7 @@ This tells npx to download `convoke-agents@latest` first, then run the `convoke-
 Reinstall from scratch (preserves user data):
 
 ```bash
-npx convoke-install-vortex
+npx -p convoke-agents convoke-install-vortex
 ```
 
 ### Check migration logs
@@ -210,10 +212,10 @@ cat _bmad-output/.logs/migration-*.log | tail -100
 
 If you encounter issues:
 
-1. Run `npx convoke-doctor` for diagnostics
+1. Run `npx -p convoke-agents convoke-doctor` for diagnostics
 2. Check migration logs in `_bmad-output/.logs/`
 3. Restore from backup in `_bmad-output/.backups/`
-4. [Report an issue](https://github.com/amalik/convoke-agents/issues) — include your version (`npx convoke-version`) and error message
+4. [Report an issue](https://github.com/amalik/convoke-agents/issues) — include your version (`npx -p convoke-agents convoke-version`) and error message
 
 ---
 

package/index.js

@@ -5,11 +5,11 @@
  * 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
+ *   npx -p convoke-agents convoke-install-vortex  – Install all Vortex agents (primary)
+ *   npx -p convoke-agents convoke-install        – Install all agents (umbrella alias)
+ *   npx -p convoke-agents convoke-update          – Check for and apply updates
+ *   npx -p convoke-agents convoke-version         – Show installed vs latest version
+ *   npx -p convoke-agents convoke-doctor          – Diagnose installation issues
  *
  * @license MIT
  */
@@ -45,11 +45,11 @@ if (require.main === module) {
   }
   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(`  ${CYAN}npx -p convoke-agents convoke-install-vortex${RESET}  Install all Vortex agents`);
+  console.log(`  ${CYAN}npx -p convoke-agents convoke-install${RESET}         Install all agents ${GRAY}(alias)${RESET}`);
+  console.log(`  ${CYAN}npx -p convoke-agents convoke-update${RESET}          Check for updates`);
+  console.log(`  ${CYAN}npx -p convoke-agents convoke-version${RESET}         Show version info`);
+  console.log(`  ${CYAN}npx -p convoke-agents convoke-doctor${RESET}          Diagnose issues`);
   console.log('');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convoke-agents",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Agent teams for complex systems, compatible with BMad Method",
   "main": "index.js",
   "files": [

package/scripts/convoke-doctor.js

@@ -48,6 +48,9 @@ async function main() {
   // 7. Version consistency
   checks.push(checkVersionConsistency(projectRoot));
 
+  // 8. Workflow step structure
+  checks.push(checkWorkflowStepStructure(projectRoot));
+
   printResults(checks);
 
   const failed = checks.filter(c => !c.passed);
@@ -66,7 +69,7 @@ function checkProjectRoot(projectRoot) {
     name: 'Project root',
     passed: false,
     error: 'Could not find _bmad/ directory',
-    fix: 'Run this command from inside a Convoke project, or run: npx convoke-install'
+    fix: 'Run this command from inside a Convoke project, or run: npx -p convoke-agents convoke-install'
   };
 }
 
@@ -78,7 +81,7 @@ function checkConfig(projectRoot) {
       name: 'Config file',
       passed: false,
       error: 'config.yaml not found',
-      fix: 'Run: npx convoke-install'
+      fix: 'Run: npx -p convoke-agents convoke-install'
     };
   }
 
@@ -91,7 +94,7 @@ function checkConfig(projectRoot) {
         name: 'Config file',
         passed: false,
         error: 'config.yaml is empty or invalid',
-        fix: 'Delete _bmad/bme/_vortex/config.yaml and run: npx convoke-install'
+        fix: 'Delete _bmad/bme/_vortex/config.yaml and run: npx -p convoke-agents convoke-install'
       };
     }
 
@@ -100,7 +103,7 @@ function checkConfig(projectRoot) {
         name: 'Config file',
         passed: false,
         error: 'config.yaml missing agents section',
-        fix: 'Run: npx convoke-update'
+        fix: 'Run: npx -p convoke-agents convoke-update'
       };
     }
 
@@ -110,7 +113,7 @@ function checkConfig(projectRoot) {
       name: 'Config file',
       passed: false,
       error: `YAML parse error: ${err.message}`,
-      fix: 'Check config.yaml for syntax errors, or delete and run: npx convoke-install'
+      fix: 'Check config.yaml for syntax errors, or delete and run: npx -p convoke-agents convoke-install'
     };
   }
 }
@@ -124,7 +127,7 @@ function checkAgents(projectRoot) {
       name: 'Agent files',
       passed: false,
       error: 'agents/ directory not found',
-      fix: 'Run: npx convoke-install-vortex'
+      fix: 'Run: npx -p convoke-agents convoke-install-vortex'
     };
   }
 
@@ -135,7 +138,7 @@ function checkAgents(projectRoot) {
       name: 'Agent files',
       passed: false,
       error: `Missing: ${missing.join(', ')}`,
-      fix: 'Run: npx convoke-install-vortex to reinstall'
+      fix: 'Run: npx -p convoke-agents convoke-install-vortex to reinstall'
     };
   }
 
@@ -150,7 +153,7 @@ function checkAgents(projectRoot) {
       name: 'Agent files',
       passed: false,
       error: `Empty agent files: ${empty.join(', ')}`,
-      fix: 'Run: npx convoke-install to restore agent files'
+      fix: 'Run: npx -p convoke-agents convoke-install to restore agent files'
     };
   }
 
@@ -166,7 +169,7 @@ function checkWorkflows(projectRoot) {
       name: 'Workflow directories',
       passed: false,
       error: 'workflows/ directory not found',
-      fix: 'Run: npx convoke-install'
+      fix: 'Run: npx -p convoke-agents convoke-install'
     };
   }
 
@@ -179,7 +182,7 @@ function checkWorkflows(projectRoot) {
       name: 'Workflow directories',
       passed: false,
       error: `Missing: ${missing.join(', ')}`,
-      fix: 'Run: npx convoke-update to restore workflows'
+      fix: 'Run: npx -p convoke-agents convoke-update to restore workflows'
     };
   }
 
@@ -281,13 +284,44 @@ function checkVersionConsistency(projectRoot) {
       name: 'Version consistency',
       passed: false,
       error: `Package: ${packageVersion}, Config: ${installedVersion}`,
-      fix: 'Run: npx convoke-update'
+      fix: 'Run: npx -p convoke-agents convoke-update'
     };
   } catch (_err) {
     return { name: 'Version consistency', passed: true, info: 'Could not read config version' };
   }
 }
 
+function checkWorkflowStepStructure(projectRoot) {
+  const workflowsDir = path.join(projectRoot, '_bmad/bme/_vortex/workflows');
+
+  if (!fs.existsSync(workflowsDir)) {
+    return { name: 'Workflow step structure', passed: true, info: 'No workflows directory' };
+  }
+
+  const issues = [];
+
+  for (const wf of WORKFLOW_NAMES) {
+    const stepsDir = path.join(workflowsDir, wf, 'steps');
+    if (!fs.existsSync(stepsDir)) continue;
+
+    const files = fs.readdirSync(stepsDir).filter(f => f.endsWith('.md'));
+    if (files.length < 4 || files.length > 6) {
+      issues.push(`${wf}: ${files.length} step files (expected 4-6)`);
+    }
+  }
+
+  if (issues.length > 0) {
+    return {
+      name: 'Workflow step structure',
+      passed: false,
+      error: issues.join('; '),
+      fix: 'Run: npx -p convoke-agents convoke-install-vortex to reinstall clean workflow files'
+    };
+  }
+
+  return { name: 'Workflow step structure', passed: true, info: 'All workflows have valid step counts' };
+}
+
 function printResults(checks) {
   const passed = checks.filter(c => c.passed);
   const failed = checks.filter(c => !c.passed);

package/scripts/docs-audit.js

@@ -22,7 +22,7 @@ const USER_FACING_DOCS = [
   'UPDATE-GUIDE.md',
   'INSTALLATION.md',
   'CHANGELOG.md',
-  'BMAD-METHOD-COMPATIBILITY.md',
+  'docs/BMAD-METHOD-COMPATIBILITY.md',
   '_bmad/bme/_vortex/guides/EMMA-USER-GUIDE.md',
   '_bmad/bme/_vortex/guides/ISLA-USER-GUIDE.md',
   '_bmad/bme/_vortex/guides/MILA-USER-GUIDE.md',

package/scripts/postinstall.js

@@ -40,7 +40,7 @@ async function main() {
       const agentNames = AGENTS.map(a => a.name).join(' + ');
       console.log('To install agents into your project, run:');
       console.log('');
-      console.log(`  ${CYAN}npx convoke-install${RESET}  - Install all agents (${agentNames})`);
+      console.log(`  ${CYAN}npx -p convoke-agents convoke-install${RESET}  - Install all agents (${agentNames})`);
       console.log('');
       return;
     }
@@ -73,10 +73,10 @@ async function main() {
       }
 
       console.log('To preview changes without applying:');
-      console.log(`  ${CYAN}npx convoke-update --dry-run${RESET}`);
+      console.log(`  ${CYAN}npx -p convoke-agents convoke-update --dry-run${RESET}`);
       console.log('');
       console.log('To apply the update:');
-      console.log(`  ${CYAN}npx convoke-update${RESET}`);
+      console.log(`  ${CYAN}npx -p convoke-agents convoke-update${RESET}`);
       console.log('');
       console.log(`${BOLD}Your data will be backed up automatically before any changes.${RESET}`);
       console.log('');
@@ -94,7 +94,7 @@ async function main() {
     const agentNames = AGENTS.map(a => a.name).join(' + ');
     console.log('To install agents into your project, run:');
     console.log('');
-    console.log(`  ${CYAN}npx convoke-install${RESET}  - Install all agents (${agentNames})`);
+    console.log(`  ${CYAN}npx -p convoke-agents convoke-install${RESET}  - Install all agents (${agentNames})`);
     console.log('');
   }
 }

package/scripts/update/convoke-migrate.js

@@ -39,7 +39,7 @@ async function main() {
     console.error('');
     console.error(chalk.red(`Migration '${migrationName}' not found.`));
     console.error('');
-    console.error('Run ' + chalk.cyan('npx convoke-migrate') + ' to see available migrations.');
+    console.error('Run ' + chalk.cyan('npx -p convoke-agents convoke-migrate') + ' to see available migrations.');
     console.error('');
     process.exit(1);
   }
@@ -152,10 +152,10 @@ function showAvailableMigrations() {
     console.log('');
   });
 
-  console.log('Usage: ' + chalk.cyan('npx convoke-migrate <migration-name>'));
+  console.log('Usage: ' + chalk.cyan('npx -p convoke-agents convoke-migrate <migration-name>'));
   console.log('');
   console.log(chalk.yellow('Warning: Manual migrations bypass safety checks.'));
-  console.log(chalk.yellow('         Use ' + chalk.cyan('npx convoke-update') + ' for normal updates.'));
+  console.log(chalk.yellow('         Use ' + chalk.cyan('npx -p convoke-agents convoke-update') + ' for normal updates.'));
   console.log('');
 }
 

package/scripts/update/convoke-update.js

@@ -86,7 +86,7 @@ async function main() {
     case 'no-project':
       console.log(chalk.red('Not in a Convoke project. Could not find _bmad/ directory.'));
       console.log('');
-      console.log('Run: ' + chalk.cyan('npx convoke-install'));
+      console.log('Run: ' + chalk.cyan('npx -p convoke-agents convoke-install'));
       console.log('');
       process.exit(1);
       break;
@@ -94,7 +94,7 @@ async function main() {
     case 'fresh':
       console.log(chalk.yellow('No previous installation detected.'));
       console.log('');
-      console.log('Run: ' + chalk.cyan('npx convoke-install'));
+      console.log('Run: ' + chalk.cyan('npx -p convoke-agents convoke-install'));
       console.log('');
       process.exit(0);
       break;
@@ -102,7 +102,7 @@ async function main() {
     case 'broken':
       console.log(chalk.red('Installation appears incomplete or corrupted.'));
       console.log('');
-      console.log('Recommend running: ' + chalk.cyan('npx convoke-install'));
+      console.log('Recommend running: ' + chalk.cyan('npx -p convoke-agents convoke-install'));
       console.log('');
       process.exit(1);
       break;
@@ -110,7 +110,7 @@ async function main() {
     case 'no-version':
       console.log(chalk.yellow('Could not detect current version.'));
       console.log('');
-      console.log('Run: ' + chalk.cyan('npx convoke-install'));
+      console.log('Run: ' + chalk.cyan('npx -p convoke-agents convoke-install'));
       console.log('');
       process.exit(0);
       break;

package/scripts/update/convoke-version.js

@@ -25,7 +25,7 @@ async function main() {
     console.log(chalk.yellow('Status:           Not in a Convoke project'));
     console.log(`Package version:  ${chalk.cyan(targetVersion)}`);
     console.log('');
-    console.log('Run: ' + chalk.cyan('npx convoke-install'));
+    console.log('Run: ' + chalk.cyan('npx -p convoke-agents convoke-install'));
     console.log('');
     return;
   }
@@ -38,7 +38,7 @@ async function main() {
     console.log(chalk.yellow('Status:           Not installed'));
     console.log(`Package version:  ${chalk.cyan(targetVersion)}`);
     console.log('');
-    console.log('Run: ' + chalk.cyan('npx convoke-install'));
+    console.log('Run: ' + chalk.cyan('npx -p convoke-agents convoke-install'));
     console.log('');
     return;
   }
@@ -50,7 +50,7 @@ async function main() {
     console.log('');
     console.log(chalk.yellow('This indicates an installation error.'));
     console.log('');
-    console.log('Try running: ' + chalk.cyan('npx convoke-install'));
+    console.log('Try running: ' + chalk.cyan('npx -p convoke-agents convoke-install'));
     console.log('');
     console.log('If the problem persists, check the installation logs.');
     console.log('');
@@ -64,7 +64,7 @@ async function main() {
     console.log('');
     console.log(chalk.yellow('Some required files are missing.'));
     console.log('');
-    console.log('Run: ' + chalk.cyan('npx convoke-install') + ' to reinstall');
+    console.log('Run: ' + chalk.cyan('npx -p convoke-agents convoke-install') + ' to reinstall');
     console.log('');
     return;
   }

package/scripts/update/lib/migration-runner.js

@@ -48,16 +48,30 @@ async function runMigrations(fromVersion, options = {}) {
     return { success: true, migrations: [], skipped: true };
   }
 
-  console.log(chalk.cyan(`Found ${migrations.length} migration(s) to apply:`));
-  migrations.forEach((m, i) => {
-    const icon = m.breaking ? chalk.red('⚠') : chalk.green('✓');
-    console.log(`  ${i + 1}. ${icon} ${m.name} - ${m.description}`);
+  // Filter out already-applied migrations using history in config.yaml
+  const configPath = path.join(projectRoot, '_bmad/bme/_vortex/config.yaml');
+  const unappliedMigrations = migrations.filter(m => {
+    if (registry.hasMigrationBeenApplied(m.name, configPath)) {
+      console.log(chalk.yellow(`Skipping already-applied: ${m.name}`));
+      return false;
+    }
+    return true;
   });
+
+  if (unappliedMigrations.length === 0) {
+    console.log(chalk.yellow('No new migrations to apply'));
+  } else {
+    console.log(chalk.cyan(`Found ${unappliedMigrations.length} migration(s) to apply:`));
+    unappliedMigrations.forEach((m, i) => {
+      const icon = m.breaking ? chalk.red('⚠') : chalk.green('✓');
+      console.log(`  ${i + 1}. ${icon} ${m.name} - ${m.description}`);
+    });
+  }
   console.log('');
 
   // If dry run, just preview
   if (dryRun) {
-    return await previewMigrations(migrations);
+    return await previewMigrations(unappliedMigrations);
   }
 
   // 2. Acquire migration lock
@@ -75,9 +89,9 @@ async function runMigrations(fromVersion, options = {}) {
 
     // 4. Execute migration deltas sequentially
     console.log(chalk.cyan('[2/5] Running migration deltas...'));
-    for (let i = 0; i < migrations.length; i++) {
-      const migration = migrations[i];
-      console.log(chalk.cyan(`\nMigration ${i + 1}/${migrations.length}: ${migration.name}`));
+    for (let i = 0; i < unappliedMigrations.length; i++) {
+      const migration = unappliedMigrations[i];
+      console.log(chalk.cyan(`\nMigration ${i + 1}/${unappliedMigrations.length}: ${migration.name}`));
 
       try {
         const changes = await executeMigration(migration, projectRoot, { verbose });
@@ -108,14 +122,8 @@ async function runMigrations(fromVersion, options = {}) {
     console.log(chalk.green('✓ Installation refreshed'));
     console.log('');
 
-    // 6. Update migration history in config.yaml
-    console.log(chalk.cyan('[4/5] Updating configuration...'));
-    await updateMigrationHistory(projectRoot, fromVersion, toVersion, results);
-    console.log(chalk.green('✓ Migration history updated'));
-    console.log('');
-
-    // 7. Validate installation
-    console.log(chalk.cyan('[5/5] Validating installation...'));
+    // 6. Validate installation (before writing history, so rollback stays clean)
+    console.log(chalk.cyan('[4/5] Validating installation...'));
     const validationResult = await validator.validateInstallation(backupMetadata, projectRoot);
 
     validationResult.checks.forEach(check => {
@@ -140,6 +148,17 @@ async function runMigrations(fromVersion, options = {}) {
     console.log(chalk.green('✓ Installation validated'));
     console.log('');
 
+    // 7. Update migration history in config.yaml (after validation succeeds)
+    console.log(chalk.cyan('[5/5] Updating configuration...'));
+    const hasDeltas = results.some(r => r.name !== 'refresh-installation');
+    if (hasDeltas) {
+      await updateMigrationHistory(projectRoot, fromVersion, toVersion, results);
+      console.log(chalk.green('✓ Migration history updated'));
+    } else {
+      console.log(chalk.green('✓ No new deltas to record'));
+    }
+    console.log('');
+
     // 8. Cleanup old backups
     const deletedCount = await backupManager.cleanupOldBackups(5, projectRoot);
     if (deletedCount > 0) {
@@ -222,7 +241,7 @@ async function previewMigrations(migrations) {
   console.log(chalk.gray('  - Update user guides (with .bak backup)'));
   console.log('');
   console.log(chalk.green('To apply these changes, run:'));
-  console.log(chalk.cyan('  npx convoke-update'));
+  console.log(chalk.cyan('  npx -p convoke-agents convoke-update'));
   console.log('');
 
   return { success: true, dryRun: true, previews };

package/scripts/update/lib/refresh-installation.js

@@ -73,8 +73,14 @@ async function refreshInstallation(projectRoot, options = {}) {
   if (!isSameRoot) {
     for (const wf of WORKFLOW_NAMES) {
       const src = path.join(workflowsSource, wf);
+      const dest = path.join(workflowsTarget, wf);
       if (fs.existsSync(src)) {
-        await fs.copy(src, path.join(workflowsTarget, wf), { overwrite: true });
+        // Remove existing workflow directory first to clear stale files
+        // (e.g., renamed step files from previous versions)
+        if (fs.existsSync(dest)) {
+          await fs.remove(dest);
+        }
+        await fs.copy(src, dest, { overwrite: true });
         changes.push(`Refreshed workflow: ${wf}`);
         if (verbose) console.log(`    Refreshed workflow: ${wf}`);
       }