 ██████╗ ██████╗ ███╗   ██╗██╗   ██╗ ██████╗ ██╗  ██╗███████╗
 ██╔════╝██╔═══██╗████╗  ██║██║   ██║██╔═══██╗██║ ██╔╝██╔════╝
 ██║     ██║   ██║██╔██╗ ██║██║   ██║██║   ██║█████╔╝ █████╗
 ██║     ██║   ██║██║╚██╗██║╚██╗ ██╔╝██║   ██║██╔═██╗ ██╔══╝
 ╚██████╗╚██████╔╝██║ ╚████║ ╚████╔╝ ╚██████╔╝██║  ██╗███████╗
 ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝  ╚═══╝   ╚═════╝ ╚═╝  ╚═╝╚══════╝
   Discover what has to be discovered. Ship what's ready to ship.

Convoke is built in BMAD Method's format. Where BMAD Method is installed, it extends it. Where it isn't, it runs on its own.

BMAD builds. Convoke covers the lifecycle either side of the build — deciding what deserves building before you start, and finding out whether what you shipped is actually fit to run. It installs as teams of specialist agents, plus skills that add capabilities to agents you already have.

Portability is a direction, not yet a destination. The export tooling takes a standalone BMAD skill anywhere; Convoke's own team agents are not there yet — see Extending Convoke for exactly where the line falls today.

The lifecycle

Each stage is a job. Where Convoke has a team for the job, it's named underneath. Where it doesn't yet, the column is empty — that's the roadmap, drawn honestly.

  ┌───────────┐ ┌───────────┐ ╔═══════════╗ ┌───────────┐ ┌ ─ ─ ─ ─ ┐
  │ frame the │ │  decide   │ ║           ║ │  is it    │  capture   
  │  problem  │▶│  what to  │▶║   build   ║▶│  fit to   │▶ what the  
  │           │ │   build   │ ║           ║ │   ship?   │  system    
  │           │ │           │ ║           ║ │           │  knows     
  └───────────┘ └───────────┘ ╚═══════════╝ └───────────┘ └ ─ ─ ─ ─ ┘
     Vortex        Vortex      BMAD Method       Gyre          —

The job	Team
Frame the right problem and understand the people who have it	Vortex
Turn research into hypotheses, and hypotheses into experiments	Vortex
Build it	BMAD Method — not ours
Find out whether it's actually ready for production	Gyre
Capture what an existing system already knows	—

Convoke works standalone or as an extension — no BMAD Method installation is required either way.

Your first 15 minutes

Install — npm install convoke-agents && npx -p convoke-agents convoke-install (details in INSTALLATION.md)
Personalize — open _bmad/bme/_vortex/config.yaml (or _bmad/bme/_gyre/config.yaml) and replace {user} with your name, so agents know who they're talking to
Pick a starting point
- Vortex: activate Emma → choose Lean Persona → follow the guided steps
- Gyre: activate Scout → choose Full Analysis → walk the pipeline
Find your artifact — outputs land in _bmad-output/vortex-artifacts/ or .gyre/
Follow the Compass — every workflow ends by routing you to whichever agent should pick up next. You never have to guess what comes after.

How activation works. Each agent is a markdown file containing a persona, a menu, and its workflow instructions. When Claude reads it, it adopts that expertise and shows you a numbered menu. In Claude Code, agents are slash commands (/bmad-agent-bme-contextualization-expert is Emma); in the terminal or on Claude.ai, paste the agent file into the conversation. Full list in the Agent Guide.

Something not working? Run npx -p convoke-agents convoke-doctor, or check the FAQ.

Teams

Vortex — discovery

Vortex takes you from "who are these users and what is actually wrong" to "here is what the evidence says we should do next" — a continuous loop, not a one-shot checklist. Each stream builds on the last, and when a gap appears the Compass routes you back to fill it.

Emma 🎯 · Isla 🔍 · Mila 🔬 · Liam 💡 · Wade 🧪 · Noah 📡 · Max 🧭

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.

— Emma, framing the problem for a meal-planning product

Emma's user guide · The full journey, every stream →

Gyre — production readiness

Gyre detects your stack, builds a capabilities model specific to it, and tells you what is missing. No generic checklists — it reads your filesystem and reports absences, then keeps the model current as you close them. Findings land in .gyre/ as classifications and evidence summaries — never file contents or secrets, though evidence does name the files and modules a finding rests on. Committing the directory is the intended workflow.

Scout 🔎 · Atlas 📐 · Lens 🔬 · Coach 🏋️

DL-001 · reliability · blocker — 46 Python files with local tests (pytest/unittest) exist across BMB and Core modules, but CI pipeline (ci.yml) only runs Node.js tests (npm test, npm run test:integration). Python test failures are completely invisible to CI […]

— Lens, from Gyre's run against this repository. Since fixed: ci.yml now has a python-test job.

The Gyre team guide · The findings file that quote came from →

Extending Convoke

Teams do lifecycle jobs. These three do something different — they change what your agents can do, and how far they travel.

Enhance — skills for existing agents. A skill adds a workflow without editing the agent that offers it. The first one is RICE-scored backlog management: run /bmad-enhance-initiatives-backlog directly. It also declares a menu patch for the PM agent, which lands only where that agent exists as a file — on BMAD v6.3+ layouts, where agents are skills rather than .md files, the slash command is the working path. The Enhance Guide documents the pattern for writing your own.

Portability — take skills elsewhere. npx -p convoke-agents convoke-export <skill> turns a BMAD skill into a self-contained, LLM-agnostic instruction document, then writes adapters into the export target for Claude ({target}/CLAUDE.md), GitHub Copilot ({target}/.github/copilot-instructions.md) and Cursor ({target}/.cursor/rules/). Four skills drive it end to end: bmad-export-skill, bmad-validate-exports, bmad-generate-catalog and bmad-seed-catalog.

Skills are classified by tier: standalone exports cleanly, light-deps carries dependency notes, pipeline is flagged non-portable. Where that leaves Convoke today, precisely: all 12 Convoke agents are pipeline — every Vortex and Gyre agent, and Team Factory. Exporting one emits "Framework-only skill. This skill depends on the full Convoke installation and cannot run standalone. […]" The exception is the Enhance backlog skill, classified light-deps, which does export. So what travels cleanly today is the upstream BMAD skill set plus that one — not the teams. Making the teams portable is roadmap, not a shipped feature.

Team Factory — build your own team. /bmad-agent-bme-team-factory walks you through composition pattern, agent scope with overlap detection, contract design and integration wiring, and persists the decisions as a resumable spec. Output passes the same validation as the native teams. It can also add an agent to an existing team, or a skill to an existing agent.

Install

npm install convoke-agents@latest
npx -p convoke-agents convoke-install

That installs everything — both teams and the skill modules. convoke-install-vortex and convoke-install-gyre exist and currently do the same thing; per-team installation is not yet a real distinction.

INSTALLATION.md covers prerequisites, what lands where, configuration, verification and troubleshooting.

Update

npm install convoke-agents@latest                  # fetch the new package first
npx -p convoke-agents convoke-version              # what you have
npx -p convoke-agents convoke-update --dry-run     # what would change
npx -p convoke-agents convoke-update               # apply, with automatic backup

The @latest is not decoration: where convoke-agents is already a recorded dependency, a bare npm install convoke-agents respects the range in your package.json and will not cross a major version boundary — it appears to succeed while keeping you on your current major. And skipping the install step means convoke-update refreshes your project from the package version you already have, so it reconciles your files rather than upgrading them.

Your artifacts in _bmad-output/ and .gyre/ are never touched. UPDATE-GUIDE.md covers migration paths and troubleshooting.

Documentation

Document	What's in it
Installation	Prerequisites, install options, configuration, troubleshooting
Update Guide	Migration paths between versions
Changelog	Complete release history
Agent Guide	Every agent, workflow and handoff contract in detail
BMAD Compatibility	Which BMAD Method versions Convoke runs against
Testing	Test suite, CI pipeline, agent test results
Development Guide	Architecture, building agents, contributing
FAQ	Common questions

Writing a Convoke skill? Read The Convoke Operator Covenant first — one axiom and seven Operator Rights every Convoke skill honours. Operator-facing behaviour is an architectural concern in agent systems, not a styling one: a skill that violates the Covenant erodes trust across the whole ecosystem, not just its own surface.

Contributing

Contributions are welcome in these areas:

Agents — new domain specialists, workflow improvements
Teams — new team modules, built with the Team Factory
Testing — edge cases, performance
Documentation — tutorials, translations, walkthroughs

Found a quality issue with an agent, or want a capability that is not there? Open an issue and pick the Agent/Workflow Feedback template. Architecture and development patterns are in the Development Guide.

License

MIT — see LICENSE.

Acknowledgments

Built on BMAD Method and the Innovation Vortex from Jurgen Appelo's unFIX model. The agents that built this — and there were a lot of them — are named in CREDITS.md.

Get started · The lifecycle · Teams · Install · Update · Changelog