convoke-agents 2.3.1 → 3.0.0

package/README.md

@@ -10,12 +10,24 @@
                 Agent teams for complex systems
 ```
 
-[![Version](https://img.shields.io/badge/version-2.3.1-blue)](https://github.com/amalik/convoke-agents)
+[![Version](https://img.shields.io/badge/version-3.0.0-blue)](https://github.com/amalik/convoke-agents)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 </div>
 
-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.
+Convoke extends AI agents with two types of installable modules: **Teams** bring new agents for a domain, **Skills** add new capabilities to existing agents. Install them independently or combine them.
+
+| Team | Agents | Domain |
+|------|--------|--------|
+| **Vortex** | 7 agents, 22 workflows | Product discovery — from user insight to evidence-based decisions |
+| **Gyre** | 4 agents, 7 workflows | Production readiness — from stack detection to gap analysis |
+
+### What's New
+
+- **Gyre team** — 4 agents analyze your project's production readiness: detect your stack, model what "ready" looks like, find what's missing, and help you act on it
+- **Team Factory** — guided workflow for creating new BMAD-compliant teams from scratch (`/bmad-team-factory`)
+- **Skill Validator** — new `validateSkill()` quality gate in the update system for factory-generated skills ([development docs](docs/development.md))
+- See the [CHANGELOG](CHANGELOG.md) for the full release details
 
 ---
 
@@ -26,8 +38,6 @@ Convoke organizes AI agents into domain-specialized teams. Each team brings deep
 [![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.
 
 ```
@@ -49,7 +59,17 @@ Vortex guides you through seven discovery streams — from understanding your us
           ▶ Start at Emma · back to any stream
 ```
 
-*Suggested flow. Each workflow ends with a Compass routing to whichever stream needs attention — you can start or return to any agent.*
+*Each workflow ends with a Compass routing to whichever stream needs attention — you can start or return to any agent.*
+
+| Agent | Stream | What they do |
+|-------|--------|-------------|
+| **Emma** 🎯 | Contextualize | Frame the right problem — personas, product vision, scope |
+| **Isla** 🔍 | Empathize | Understand users — empathy maps, interviews, discovery research |
+| **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, user behavior, and engagement patterns |
+| **Max** 🧭 | Systematize | Capture learnings and decide: pivot, patch, or persevere |
 
 <details>
 <summary>22 Vortex Workflows</summary>
@@ -79,16 +99,6 @@ Vortex guides you through seven discovery streams — from understanding your us
 
 </details>
 
-| Agent | Stream | What they do |
-|-------|--------|-------------|
-| **Emma** 🎯 | Contextualize | Frame the right problem — personas, product vision, scope |
-| **Isla** 🔍 | Empathize | Understand users — empathy maps, interviews, discovery research |
-| **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, 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).
@@ -123,41 +133,160 @@ Max captures what you learned and decides what to do next:
 > 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.
+> 1. **Implement adaptive timing** — shift the push notification to match each user's observed engagement window.
 > 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)**
 
+For detailed workflow descriptions, see the [Agent Guide](docs/agents.md) and individual user guides: [Emma](_bmad/bme/_vortex/guides/EMMA-USER-GUIDE.md) | [Isla](_bmad/bme/_vortex/guides/ISLA-USER-GUIDE.md) | [Mila](_bmad/bme/_vortex/guides/MILA-USER-GUIDE.md) | [Liam](_bmad/bme/_vortex/guides/LIAM-USER-GUIDE.md) | [Wade](_bmad/bme/_vortex/guides/WADE-USER-GUIDE.md) | [Noah](_bmad/bme/_vortex/guides/NOAH-USER-GUIDE.md) | [Max](_bmad/bme/_vortex/guides/MAX-USER-GUIDE.md)
+
+---
+
+## Gyre — Production Readiness Team
+
+**4 agents assess whether your project is ready to ship — detect your stack, model what "ready" means, find what's missing, and refine together**
+
+[![Agents](https://img.shields.io/badge/agents-4-brightgreen)](docs/agents.md)
+[![Workflows](https://img.shields.io/badge/workflows-7-success)](docs/agents.md)
+
+Most teams ship to production without knowing if they're actually ready — missing SLOs, incomplete observability, unreviewed deployment strategies. Gyre analyzes your project's filesystem, builds a capabilities model tailored to your specific tech stack, and surfaces what's absent. No generic checklists — every finding is contextual to your project.
+
+```
+                    4 Agents · 4 Contracts
+
+  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+  │    Scout    │──▶│    Atlas    │──▶│    Lens     │──▶│    Coach    │
+  │   Detect    │   │   Model     │   │   Analyze   │   │   Review    │
+  │   Stack     │   │   Capabil.  │   │   Gaps      │   │   Refine    │
+  └─────────────┘   └──────▲──────┘   └─────────────┘   └──────┬──────┘
+                           │                                   │
+                           └────────────── GC4 ────────────────┘
+                                       feedback
+```
+
+*Linear pipeline with a feedback loop. Coach amendments feed back to Atlas — the model improves with every review.*
+
+| Agent | Role | What they do |
+|-------|------|-------------|
+| **Scout** 🔎 | Detect | Scan filesystem artifacts to classify your tech stack — language, containers, CI/CD, observability, cloud provider |
+| **Atlas** 📐 | Model | Generate a capabilities manifest using industry standards (DORA, OpenTelemetry, Google PRR) and web search |
+| **Lens** 🔬 | Analyze | Compare capabilities against what actually exists — surface absences, compound risks, severity-prioritized findings |
+| **Coach** 🏋️ | Review | Walk through findings conversationally — amend the model, capture feedback, track progress over time |
+
+<details>
+<summary>7 Gyre Workflows</summary>
+
+- Full Analysis (end-to-end pipeline)
+- Stack Detection
+- Model Generation
+- Gap Analysis
+- Model Review
+- Delta Report
+- Accuracy Validation
+
+</details>
+
+### What Gyre Produces
+
+Gyre writes structured artifacts to `.gyre/` in your project root — safe to commit, containing technology categories only (no file contents, paths, or secrets):
+
+- **Stack Profile** (`.gyre/stack-profile.yaml`) — classified tech stack with detection confidence
+- **Capabilities Manifest** (`.gyre/capabilities.yaml`) — 20+ capabilities across observability, deployment, reliability, and security
+- **Findings Report** (`.gyre/findings.yaml`) — absence-based findings tagged by severity, confidence, and source
+- **Feedback Log** (`.gyre/feedback.yaml`) — team amendments that persist and improve the model over time
+
+**Three modes:** *Crisis* (first run, full pipeline), *Anticipation* (re-analysis with cached model), *Regeneration* (fresh model rebuild).
+
+**Delta tracking:** Run Gyre after making improvements to see what you've resolved — findings are tagged [NEW], [CARRIED], or resolved.
+
+User guides: [Scout](_bmad/bme/_gyre/guides/SCOUT-USER-GUIDE.md) | [Atlas](_bmad/bme/_gyre/guides/ATLAS-USER-GUIDE.md) | [Lens](_bmad/bme/_gyre/guides/LENS-USER-GUIDE.md) | [Coach](_bmad/bme/_gyre/guides/COACH-USER-GUIDE.md)
+
+---
+
+## Extending Convoke
+
+### Team Factory
+
+Create fully-wired, BMAD-compliant teams through a guided workflow — zero post-creation fixes.
+
+```
+/bmad-team-factory
+```
+
+The factory guides you through composition pattern selection (Independent or Sequential), agent scope definition with overlap detection, contract design, and integration wiring. Decision state is persisted as a spec file for resume and express mode. Output passes the same validation as native teams.
+
+Three capabilities:
+- **Create Team** — build a new team from scratch with full integration
+- **Add Agent** — extend an existing team with a new agent
+- **Add Skill** — give an existing agent a new workflow
+
+### Enhance — Agent Skills
+
+Skills give existing agents new workflows — installed via menu patching, not agent modification. The first skill adds RICE-scored backlog management to the PM agent:
+
+```
+                    Initiatives Backlog
+
+  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+  │  [T] Triage │   │  [R] Review │   │  [C] Create │
+  │  Ingest new │   │   Rescore   │   │  Bootstrap  │
+  │  findings   │   │  existing   │   │ from scratch│
+  └──────┬──────┘   └──────┬──────┘   └──────┬──────┘
+         │                 │                 │
+         ▼                 ▼                 ▼
+  ┌──────────────────────────────────────────────────┐
+  │          initiatives-backlog.md                  │
+  │   RICE-scored · Categorized · Change-tracked     │
+  └──────────────────────────────────────────────────┘
+```
+
+Activate from the PM agent menu or directly: `/bmad-enhance-initiatives-backlog`
+
+The [Enhance Guide](_bmad/bme/_enhance/guides/ENHANCE-GUIDE.md) documents the complete pattern for building your own skills.
+
 ---
 
-### Quick Start
+## Quick Start
 
-#### Prerequisites
+### Prerequisites
 
 - Node.js 18+ or Bun
 - Git
 - Claude Code or Claude.ai
 
-#### Install
+### Install
+
+**Everything (Vortex + Gyre):**
+
+```bash
+npm install convoke-agents && npx -p convoke-agents convoke-install
+```
+
+**Vortex only:**
 
 ```bash
 npm install convoke-agents && npx -p convoke-agents convoke-install-vortex
 ```
 
-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).
+**Gyre only:**
+
+```bash
+npm install convoke-agents && npx -p convoke-agents convoke-install-gyre
+```
+
+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.
+Open `_bmad/bme/_vortex/config.yaml` (or `_bmad/bme/_gyre/config.yaml`) and replace `{user}` with your name. Agents use this to personalize their interactions.
 
-#### Activate an Agent
+### Activate an Agent
 
 **Claude Code (skills)**
 
 ```
+# Vortex
 /bmad-agent-bme-contextualization-expert          # Emma  🎯
 /bmad-agent-bme-discovery-empathy-expert          # Isla  🔍
 /bmad-agent-bme-research-convergence-specialist   # Mila  🔬
@@ -165,54 +294,92 @@ Open `_bmad/bme/_vortex/config.yaml` and replace `{user}` with your name. Agents
 /bmad-agent-bme-lean-experiments-specialist        # Wade  🧪
 /bmad-agent-bme-production-intelligence-specialist # Noah  📡
 /bmad-agent-bme-learning-decision-expert           # Max   🧭
+
+# Gyre
+/bmad-agent-bme-stack-detective                    # Scout 🔎
+/bmad-agent-bme-model-curator                      # Atlas 📐
+/bmad-agent-bme-readiness-analyst                  # Lens  🔬
+/bmad-agent-bme-review-coach                       # Coach 🏋️
 ```
 
 **Claude Code (terminal) / Other AI assistants**
 
 ```bash
-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  🔬
-cat _bmad/bme/_vortex/agents/hypothesis-engineer.md               # Liam  💡
-cat _bmad/bme/_vortex/agents/lean-experiments-specialist.md       # Wade  🧪
-cat _bmad/bme/_vortex/agents/production-intelligence-specialist.md # Noah  📡
-cat _bmad/bme/_vortex/agents/learning-decision-expert.md          # Max   🧭
+# Vortex
+cat _bmad/bme/_vortex/agents/contextualization-expert.md    # Emma  🎯
+# ... (see user guides for full list)
+
+# Gyre
+cat _bmad/bme/_gyre/agents/stack-detective.md               # Scout 🔎
+cat _bmad/bme/_gyre/agents/model-curator.md                 # Atlas 📐
+cat _bmad/bme/_gyre/agents/readiness-analyst.md             # Lens  🔬
+cat _bmad/bme/_gyre/agents/review-coach.md                  # Coach 🏋️
 ```
 
-**Claude.ai**
-
-Open any agent file from `_bmad/bme/_vortex/agents/` and paste its contents into your conversation.
+**Claude.ai** — Open any agent file and paste its contents into your conversation.
 
 **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`
-3. **See the menu** — Emma presents numbered options. Select **Lean Persona** from the menu
-4. **Follow the steps** — Emma walks you through 6 guided steps, asking questions at each one
-5. **Find your artifact** — When done, your lean persona is saved in `_bmad-output/vortex-artifacts/`
-6. **Follow the Compass** — At the end, Emma's Vortex Compass suggests which agent to use next based on what you learned
+1. **Personalize** — edit the config.yaml for your chosen team and replace `{user}` with your name
+2. **Pick a starting point:**
+   - **Vortex:** Activate Emma → select **Lean Persona** from the menu → follow the guided steps
+   - **Gyre:** Activate Scout → select **Full Analysis** from the menu → walk through the pipeline
+3. **Find your artifact** — outputs are saved in `_bmad-output/vortex-artifacts/` or `.gyre/`
+4. **Follow the Compass** — each workflow ends with a routing suggestion for which agent to use next
 
-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/
-├── _bmad/bme/_vortex/
-│   ├── agents/           # 7 agent definition files
-│   ├── workflows/        # 22 workflows
-│   ├── contracts/        # Artifact contract schemas
-│   ├── guides/           # User guides (all 7 agents)
-│   └── config.yaml       # Configuration
+├── _bmad/bme/
+│   ├── _vortex/              # Team: Product Discovery
+│   │   ├── agents/           # 7 agent definition files
+│   │   ├── workflows/        # 22 workflows
+│   │   ├── contracts/        # Handoff contracts (HC1-HC5 artifact, HC6-HC10 routing)
+│   │   ├── guides/           # User guides (all 7 agents)
+│   │   └── config.yaml       # Configuration
+│   ├── _gyre/                # Team: Production Readiness
+│   │   ├── agents/           # 4 agent definition files
+│   │   ├── workflows/        # 7 workflows
+│   │   ├── contracts/        # Artifact contract schemas (GC1-GC4)
+│   │   ├── guides/           # User guides (all 4 agents)
+│   │   └── config.yaml       # Configuration
+│   └── _enhance/             # Skill: Agent Capability Upgrades
+│       ├── workflows/        # Skill workflows (initiatives-backlog)
+│       ├── extensions/       # Agent menu patch descriptors
+│       ├── guides/           # Module author guide
+│       └── config.yaml       # Configuration
 └── _bmad-output/
-    └── vortex-artifacts/  # Generated artifacts
+    ├── vortex-artifacts/     # Vortex generated artifacts
+    └── gyre-artifacts/       # Gyre generated artifacts
 ```
 
 ---
 
-### Updating
+## How It Fits with BMAD Core
+
+Convoke handles **discovery, validation, and readiness**. BMAD Core handles **implementation**.
+
+```
+Convoke Modules                            BMAD Core
+┌──────────────────────────────┐          ┌──────────────────────┐
+│ Teams                        │          │                      │
+│   Vortex (Product Discovery) │ ──────>  │ PM → Architect → Dev │
+│   Gyre (Prod. Readiness)     │ <──────  │ "Let's build it"     │
+│                              │          │                      │
+│ Skills                       │  signals │                      │
+│   Enhance (Agent Upgrades)   │ ──────>  │                      │
+│                              │          │                      │
+└──────────────────────────────┘          └──────────────────────┘
+```
+
+Teams and Skills are peer module types — both installable, both independent. Convoke works standalone or as an extension — no BMAD Method installation required.
+
+---
+
+## Updating
 
 ```bash
 npx -p convoke-agents convoke-version          # Check current version
@@ -221,7 +388,7 @@ 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.
+Your data in `_bmad-output/` and `.gyre/` 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
@@ -230,48 +397,6 @@ Your data in `_bmad-output/` is never touched. Automatic backups are created bef
 
 See [UPDATE-GUIDE.md](UPDATE-GUIDE.md) for migration paths and troubleshooting.
 
-### Using the Agents
-
-Each agent can be used independently or as part of the full Vortex flow:
-
-1. **Emma (Contextualize)** — Start here when defining a new product or problem space
-2. **Isla (Empathize)** — Start here when you need to understand users better
-3. **Mila (Synthesize)** — Start here when you have research to converge into a problem definition
-4. **Liam (Hypothesize)** — Start here when you have a problem definition and need testable hypotheses
-5. **Wade (Externalize)** — Start here when you have hypotheses ready to test
-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 — 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:
-
-- [Emma User Guide](_bmad/bme/_vortex/guides/EMMA-USER-GUIDE.md)
-- [Isla User Guide](_bmad/bme/_vortex/guides/ISLA-USER-GUIDE.md)
-- [Mila User Guide](_bmad/bme/_vortex/guides/MILA-USER-GUIDE.md)
-- [Liam User Guide](_bmad/bme/_vortex/guides/LIAM-USER-GUIDE.md)
-- [Wade User Guide](_bmad/bme/_vortex/guides/WADE-USER-GUIDE.md)
-- [Noah User Guide](_bmad/bme/_vortex/guides/NOAH-USER-GUIDE.md)
-- [Max User Guide](_bmad/bme/_vortex/guides/MAX-USER-GUIDE.md)
-
----
-
-## How It Fits with BMAD Core
-
-Convoke handles **discovery and validation**. BMAD Core handles **implementation**.
-
-```
-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.
-
 ---
 
 ## Documentation
@@ -279,6 +404,7 @@ Convoke works standalone or as an extension — no BMAD Method installation requ
 | Document | Description |
 |----------|-------------|
 | [Agent Guide](docs/agents.md) | Detailed agent descriptions, workflows, and positioning |
+| [BMAD Compatibility](docs/BMAD-METHOD-COMPATIBILITY.md) | Compatibility matrix with BMAD Method versions |
 | [Testing](docs/testing.md) | Automated test suite, CI pipeline, and agent test results |
 | [Development Guide](docs/development.md) | Architecture, building agents, and contributing |
 | [FAQ](docs/faq.md) | Common questions about the framework |
@@ -289,11 +415,11 @@ Convoke works standalone or as an extension — no BMAD Method installation requ
 
 ## Roadmap
 
-- **v1.1.0–v1.5.x** — Waves 1-2: Foundation (Emma, Isla, Wade, Max — agent definitions, workflows, update system, CI/CD)
-- **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** — Additional domain-specialized teams, multi-agent collaboration, cross-team workflows
+- **v1.x** — Vortex foundation: 7 agents, 22 workflows, update system, CI/CD
+- **v2.0** — Product renamed to Convoke. CLI commands: `convoke-*`. Package: `convoke-agents`
+- **v2.x** — Enhance module (Skills architecture, RICE initiatives-backlog), Gyre team (production readiness, 4 agents), Team Factory
+- **Next** — Forge (domain knowledge extraction for enterprise brownfield engagements)
+- **Future** — Additional teams, Forge-Gyre integration, cross-team workflows
 
 ---
 
@@ -302,11 +428,11 @@ Convoke works standalone or as an extension — no BMAD Method installation requ
 We welcome contributions in these areas:
 
 - **Agents** — New domain-specialized agents, workflow improvements
+- **Teams** — New team modules via the Team Factory
 - **Testing** — Edge cases, performance testing
 - **Documentation** — Tutorials, translations, video walkthroughs
-- **Integration** — IDE plugins, third-party tools
 
-**Have feedback?** Found a quality issue, want a missing capability, or have a general comment about an agent? Open an issue and select the **Agent/Workflow Feedback** template — takes under 30 seconds.
+**Have feedback?** Found a quality issue, want a missing capability, or have a general comment about an agent? Open an issue and select the **Agent/Workflow Feedback** template.
 
 See the [Development Guide](docs/development.md) for architecture details and agent development patterns.
 
@@ -349,6 +475,12 @@ Every agent below contributed to the design, implementation, testing, or documen
 - Noah 📡 Sensitize — Production intelligence and signal interpretation
 - Max 🧭 Systematize — Learning capture and pivot/persevere decisions
 
+**BME — Gyre Pattern Agents**
+- Scout 🔎 Stack Detective — Technology stack detection and classification
+- Atlas 📐 Model Curator — Contextual capabilities manifest generation
+- Lens 🔬 Readiness Analyst — Absence detection and cross-domain correlation
+- Coach 🏋️ Review Coach — Guided review, amendment, and feedback capture
+
 **CIS — Creative & Innovation Strategies**
 - Carson 🧠 Brainstorming Coach — Creative ideation facilitation
 - Dr. Quinn 🔬 Problem Solver — Systematic problem-solving
@@ -369,7 +501,7 @@ Every agent below contributed to the design, implementation, testing, or documen
 
 <div align="center">
 
-**Innovation Vortex Pattern** — *Discover what has to be discovered, deliver what has to be delivered*
+**Discover what has to be discovered. Ship what's ready to ship.**
 
 [Get Started](#quick-start) | [Agents](docs/agents.md) | [Docs](#documentation) | [Roadmap](#roadmap)
 

package/UPDATE-GUIDE.md

@@ -2,6 +2,10 @@
 
 How to update your Convoke installation to the latest version.
 
+- **Package:** `convoke-agents`
+- **Version:** 3.0.0
+- **Last Updated:** 2026-03-25
+
 ---
 
 ## Quick Update
@@ -61,37 +65,62 @@ npx -p convoke-agents convoke-doctor
 
 ## Migration Paths
 
-### From v1.4.x to v1.5.x
+### From v2.4.x to v3.0.0
+
+**Breaking changes:** Team Factory extension workflows (add-agent, add-skill) are new capabilities that change the module API surface.
+
+What happens:
+- **Team Factory extensions** — Add Agent and Add Skill workflows with appender modules (registry, config, CSV)
+- **Multi-team docs-audit** — Audit tool now validates against all registered teams (Vortex + Gyre), not just Vortex
+- **Extension validator** — New validation for factory-generated agent and skill extensions
+
+### From v2.3.x to v2.4.0
 
 **Breaking changes:** None
 
 What happens:
-- Isla (Discovery & Empathy Expert) and Max (Learning & Decision Expert) agents added
-- 6 new workflows installed (empathy-map resurrected for Isla)
-- Installer updated to `convoke-install-vortex`
-- Legacy installers (`install-emma`, `install-wade`) show deprecation warnings
+- **Gyre team installed** — 4 new agents (Scout, Atlas, Lens, Coach), 7 workflows, 4 contract schemas (GC1-GC4), 4 user guides
+- **Team Factory** — guided workflow for creating new BMAD-compliant teams (`/bmad-team-factory`)
+- **Skill Validator** — new `validateSkill()` quality gate for factory-generated skills
+- Gyre skill wrappers added to `.claude/skills/`
+- Agent manifest updated with 4 new entries
+
+If you previously had only Vortex installed, Gyre files are added alongside — nothing in `_bmad/bme/_vortex/` changes.
 
-### From v1.3.x to v1.5.x
+### From v2.0.x to v3.0.0
 
 **Breaking changes:** None
 
 What happens:
-- Architecture refactor (internal — no user-facing changes)
-- Agent files and workflows refreshed
-- Isla + Max agents added with 6 new workflows
+- Enhance module added (Skills architecture, initiatives-backlog)
+- Gyre team added (4 agents, 7 workflows)
+- Agent activation migrated from `.claude/commands/` to `.claude/skills/` (v2.2.0)
+- Legacy command files automatically cleaned up
 
-### From v1.0.x to v1.6.x
+### From v1.7.x to v3.0.0
+
+**Breaking changes:**
+- Product renamed: `bmad-enhanced` → `convoke-agents` (npm package name)
+- CLI commands renamed: `bmad-*` → `convoke-*`
+
+What happens:
+- All CLI commands use `convoke-` prefix
+- `_bmad/` directory preserved (BMAD Method compatibility)
+- All 11 agents installed (7 Vortex + 4 Gyre)
+
+### From v1.0.x to v3.0.0
 
 **Breaking changes:**
 - Workflow renamed: `empathy-map` → `lean-persona` (for Emma)
 - Agent roles updated: `empathy-mapper` → `contextualization-expert`, `wireframe-designer` → `lean-experiments-specialist`
 - Module renamed: `_designos` → `_vortex`
+- Product renamed: `bmad-enhanced` → `convoke-agents`
+- CLI commands renamed: `bmad-*` → `convoke-*`
 
 What happens:
 - Old workflows preserved in `_bmad/bme/_vortex/workflows/_deprecated/`
-- All 22 Vortex workflows installed
-- Config structure updated (preferences preserved)
-- 7 agents installed (Emma, Isla, Mila, Liam, Wade, Noah, Max)
+- Full migration chain applied: file renames, config updates, new agents, new modules
+- All 11 agents + Enhance module installed
 
 ```bash
 npm install convoke-agents@latest
@@ -115,15 +144,19 @@ Every update creates a backup before making changes:
 ### What's Never Touched
 
 - All user-generated files in `_bmad-output/`
+- Gyre analysis artifacts in `.gyre/` (stack-profile, capabilities, findings, feedback)
 - User preferences (name, language settings)
 - Custom configuration values
+- Coach amendments and feedback in `.gyre/feedback.yaml`
 
 ### What Gets Updated
 
-- Agent definition files
+- Agent definition files (Vortex and Gyre)
 - Workflow files (steps, templates, validation)
-- Vortex config.yaml (with preference preservation — user-added agents and workflows are kept after core entries)
+- Config files (with preference preservation — user-added entries are kept)
 - User guides
+- Claude Code skill wrappers in `.claude/skills/`
+- Agent manifest in `_bmad/_config/`
 
 ---
 
@@ -131,24 +164,29 @@ Every update creates a backup before making changes:
 
 ### Your Artifacts Survive Updates
 
-All user-generated content in `_bmad-output/` (planning artifacts, implementation artifacts, vortex artifacts) works with updated agents **without regeneration**. When you update from v1.5.x to v1.6.x, your existing artifacts remain valid inputs to both original and new agents.
+All user-generated content works with updated agents **without regeneration**:
+
+- **Vortex artifacts** in `_bmad-output/vortex-artifacts/` — personas, hypotheses, learning cards, etc.
+- **Gyre artifacts** in `.gyre/` — stack profiles, capabilities manifests, findings reports, feedback logs
 
-Artifacts created with earlier agents (Emma, Isla, Wade, Max) were not designed specifically for the newer agents (Mila, Liam, Noah), but the handoff contracts are backward-compatible by design. A product vision created with v1.5.x works as input to Mila after updating to v1.6.x — the required fields are present.
+Handoff contracts (HC1-HC5 for Vortex, GC1-GC4 for Gyre) are backward-compatible by design. Artifacts created with older agent versions remain valid inputs after updating.
 
 ### What Is Backward-Compatible
 
-- **Artifact content** — Everything in `_bmad-output/` (planning artifacts, implementation artifacts, vortex artifacts)
-- **Handoff contract fields** — The fields agents produce and consume (HC1-HC5 schemas) are stable across versions
+- **Artifact content** — Everything in `_bmad-output/` and `.gyre/`
+- **Handoff contract fields** — The fields agents produce and consume are stable across versions
 - **Workflow outputs** — Templates and generated documents maintain their structure
+- **Coach amendments** — Model customizations in `.gyre/capabilities.yaml` and `.gyre/feedback.yaml` persist through updates and regeneration
 
 ### What Is Managed by the Update System
 
 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/`
+- **Agent definition files** — Persona, menu, and instruction content in `_bmad/bme/_vortex/agents/` and `_bmad/bme/_gyre/agents/`
+- **Workflow step files** — Step content, templates, and validation
+- **Skill wrappers** — Claude Code skill files in `.claude/skills/`
 - **Internal file structure** — The layout of `_bmad/bme/` may change between versions
-- **User guides** — Updated guides are installed in `_bmad/bme/_vortex/guides/`
+- **User guides** — Updated guides are installed in each team's `guides/` directory
 
 You do not need to manually update these — the update system replaces them while preserving your preferences and artifacts.
 
@@ -196,7 +234,9 @@ This tells npx to download `convoke-agents@latest` first, then run the `convoke-
 Reinstall from scratch (preserves user data):
 
 ```bash
-npx -p convoke-agents convoke-install-vortex
+npx -p convoke-agents convoke-install          # Everything
+npx -p convoke-agents convoke-install-vortex   # Vortex only
+npx -p convoke-agents convoke-install-gyre     # Gyre only
 ```
 
 ### Check migration logs

package/_bmad/bme/_enhance/config.yaml

@@ -0,0 +1,8 @@
+name: enhance
+version: 1.0.0
+description: "Enhance module — capability upgrades for existing BMAD agents"
+workflows:
+  - name: initiatives-backlog
+    entry: workflows/initiatives-backlog/workflow.md
+    target_agent: bmm/agents/pm.md
+    menu_patch_name: "initiatives-backlog"