convoke-agents 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.2.0] - 2026-03-14
+
+### Changed
+
+- **Agent activation migrated from commands to skills** — `.claude/commands/bmad-agent-bme-*.md` replaced by `.claude/skills/bmad-agent-bme-{id}/SKILL.md` (BMAD v6.1.0 format)
+- **Agent manifest uses v6.1.0 12-column schema** — BME agents now populate all fields including `canonicalId`, `module`, `communicationStyle`, `capabilities`
+- **Removed redundant `createAgentManifest()`** from installer — `refreshInstallation()` is now the single code path for manifest generation
+
+### Added
+
+- **`src/module.yaml`** — External module spec definition for future BMAD registration
+- **Agent customize files** — `_bmad/_config/agents/bme-{name}.customize.yaml` generated on install (never overwritten)
+- **Legacy command cleanup** — Automatically removes `.claude/commands/bmad-agent-bme-*` files from prior installs
+
+### Removed
+
+- **`_bmad/bme/_config/module.yaml`** — Stale legacy file with deprecated agent references deleted
+
+---
+
 ## [2.0.0] - 2026-03-07
 
 ### Changed

package/README.md

@@ -155,7 +155,7 @@ Open `_bmad/bme/_vortex/config.yaml` and replace `{user}` with your name. Agents
 
 #### Activate an Agent
 
-**Claude Code (slash commands)**
+**Claude Code (skills)**
 
 ```
 /bmad-agent-bme-contextualization-expert          # Emma  🎯

package/_bmad/bme/_vortex/config.yaml

@@ -33,7 +33,7 @@ workflows:
   - learning-card
   - pivot-patch-persevere
   - vortex-navigation
-version: 1.6.2
+version: 2.2.0
 user_name: '{user}'
 communication_language: en
 party_mode_enabled: true

package/_bmad/bme/_vortex/guides/EMMA-USER-GUIDE.md

@@ -56,9 +56,9 @@ cat _bmad/bme/_vortex/agents/contextualization-expert.md
 
 ---
 
-### Method 2: Slash Command (BMAD Environments Only)
+### Method 2: Skill Activation (BMAD Environments Only)
 
-If your environment supports BMAD slash commands:
+If your environment supports BMAD skills:
 
 ```
 /bmad-agent-bme-contextualization-expert

package/_bmad/bme/_vortex/guides/ISLA-USER-GUIDE.md

@@ -45,9 +45,9 @@ cat _bmad/bme/_vortex/agents/discovery-empathy-expert.md
 
 ---
 
-### Method 2: Slash Command (BMAD Environments Only)
+### Method 2: Skill Activation (BMAD Environments Only)
 
-If your environment supports BMAD slash commands:
+If your environment supports BMAD skills:
 
 ```
 /bmad-agent-bme-discovery-empathy-expert

package/_bmad/bme/_vortex/guides/LIAM-USER-GUIDE.md

@@ -57,9 +57,9 @@ cat _bmad/bme/_vortex/agents/hypothesis-engineer.md
 
 ---
 
-### Method 2: Slash Command (BMAD Environments Only)
+### Method 2: Skill Activation (BMAD Environments Only)
 
-If your environment supports BMAD slash commands:
+If your environment supports BMAD skills:
 
 ```
 /bmad-agent-bme-hypothesis-engineer

package/_bmad/bme/_vortex/guides/MAX-USER-GUIDE.md

@@ -44,9 +44,9 @@ cat _bmad/bme/_vortex/agents/learning-decision-expert.md
 
 ---
 
-### Method 2: Slash Command (BMAD Environments Only)
+### Method 2: Skill Activation (BMAD Environments Only)
 
-If your environment supports BMAD slash commands:
+If your environment supports BMAD skills:
 
 ```
 /bmad-agent-bme-learning-decision-expert

package/_bmad/bme/_vortex/guides/MILA-USER-GUIDE.md

@@ -56,9 +56,9 @@ cat _bmad/bme/_vortex/agents/research-convergence-specialist.md
 
 ---
 
-### Method 2: Slash Command (BMAD Environments Only)
+### Method 2: Skill Activation (BMAD Environments Only)
 
-If your environment supports BMAD slash commands:
+If your environment supports BMAD skills:
 
 ```
 /bmad-agent-bme-research-convergence-specialist

package/_bmad/bme/_vortex/guides/NOAH-USER-GUIDE.md

@@ -58,9 +58,9 @@ cat _bmad/bme/_vortex/agents/production-intelligence-specialist.md
 
 ---
 
-### Method 2: Slash Command (BMAD Environments Only)
+### Method 2: Skill Activation (BMAD Environments Only)
 
-If your environment supports BMAD slash commands:
+If your environment supports BMAD skills:
 
 ```
 /bmad-agent-bme-production-intelligence-specialist

package/_bmad/bme/_vortex/guides/WADE-USER-GUIDE.md

@@ -57,9 +57,9 @@ cat _bmad/bme/_vortex/agents/lean-experiments-specialist.md
 
 ---
 
-### Method 2: Slash Command (BMAD Environments Only)
+### Method 2: Skill Activation (BMAD Environments Only)
 
-If your environment supports BMAD slash commands:
+If your environment supports BMAD skills:
 
 ```
 /bmad-agent-bme-lean-experiments-specialist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convoke-agents",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Agent teams for complex systems, compatible with BMad Method",
   "main": "index.js",
   "files": [
@@ -11,7 +11,8 @@
     "UPDATE-GUIDE.md",
     "CHANGELOG.md",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "src/"
   ],
   "bin": {
     "convoke-install-vortex": "scripts/install-vortex-agents.js",

package/scripts/docs-audit.js

@@ -522,13 +522,13 @@ async function runAudit(opts = {}) {
     const content = fs.readFileSync(absPath, 'utf8');
     allDocsContent.push(content);
 
-    // Skip stale-reference checks for CHANGELOG — historical entries
-    // (e.g., "Added 4 agents" in v1.0) are accurate for their time period
+    // Skip stale-reference and broken-path checks for CHANGELOG — historical entries
+    // reference files that may have been deleted or renamed in past versions
     if (relPath !== 'CHANGELOG.md') {
       allFindings.push(...checkStaleReferences(content, relPath));
+      allFindings.push(...checkBrokenPaths(content, relPath, projectRoot));
     }
     allFindings.push(...checkBrokenLinks(content, relPath, projectRoot));
-    allFindings.push(...checkBrokenPaths(content, relPath, projectRoot));
     allFindings.push(...checkIncompleteAgentTables(content, relPath));
     allFindings.push(...checkInternalNamingLeaks(content, relPath));
     allFindings.push(...checkStaleBrandReferences(content, relPath));

package/scripts/install-vortex-agents.js

@@ -29,7 +29,7 @@ function printBanner() {
 }
 
 function checkPrerequisites(projectRoot) {
-  console.log(`${CYAN}[1/6]${RESET} Checking prerequisites...`);
+  console.log(`${CYAN}[1/5]${RESET} Checking prerequisites...`);
 
   const bmadDir = path.join(projectRoot, '_bmad');
 
@@ -53,7 +53,7 @@ function checkPrerequisites(projectRoot) {
 }
 
 function archiveDeprecatedWorkflows(projectRoot) {
-  console.log(`${CYAN}[2/6]${RESET} Archiving deprecated workflows...`);
+  console.log(`${CYAN}[2/5]${RESET} Archiving deprecated workflows...`);
 
   const sourceDir = path.join(__dirname, '..', '_bmad', 'bme', '_vortex');
   const targetDir = path.join(projectRoot, '_bmad', 'bme', '_vortex');
@@ -94,32 +94,8 @@ function cleanupLegacyFiles(projectRoot) {
   console.log(`${GREEN}  ✓${RESET} Legacy cleanup complete`);
 }
 
-function csvEscape(value) {
-  return `"${String(value).replace(/"/g, '""')}"`;
-}
-
-function createAgentManifest(projectRoot) {
-  console.log(`${CYAN}[3/6]${RESET} Creating agent manifest...`);
-
-  const manifestPath = path.join(projectRoot, '_bmad', '_config', 'agent-manifest.csv');
-  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-
-  const header = '"agent_id","name","title","icon","role","identity","communication_style","expertise","submodule","path"\n';
-  const rows = AGENTS.map(a => {
-    const p = a.persona;
-    return [
-      a.id, a.name, a.title, a.icon,
-      p.role, p.identity, p.communication_style, p.expertise,
-      'bme', `_bmad/bme/_vortex/agents/${a.id}.md`,
-    ].map(csvEscape).join(',');
-  }).join('\n') + '\n';
-
-  fs.writeFileSync(manifestPath, header + rows);
-  console.log(`${GREEN}  ✓${RESET} Created agent-manifest.csv`);
-}
-
 function createOutputDirectory(projectRoot) {
-  console.log(`${CYAN}[4/6]${RESET} Setting up output directory...`);
+  console.log(`${CYAN}[3/5]${RESET} Setting up output directory...`);
 
   const outputDir = path.join(projectRoot, '_bmad-output', 'vortex-artifacts');
   fs.mkdirSync(outputDir, { recursive: true });
@@ -128,11 +104,11 @@ function createOutputDirectory(projectRoot) {
 }
 
 function verifyInstallation(projectRoot) {
-  console.log(`${CYAN}[6/6]${RESET} Verifying installation...`);
+  console.log(`${CYAN}[5/5]${RESET} Verifying installation...`);
 
   const checks = [
     ...AGENTS.map(a => ({ path: `_bmad/bme/_vortex/agents/${a.id}.md`, name: `${a.name} agent file` })),
-    ...AGENTS.map(a => ({ path: `.claude/commands/bmad-agent-bme-${a.id}.md`, name: `${a.name} slash command` })),
+    ...AGENTS.map(a => ({ path: `.claude/skills/bmad-agent-bme-${a.id}/SKILL.md`, name: `${a.name} skill` })),
     { path: '_bmad/bme/_vortex/config.yaml', name: 'Configuration file' },
   ];
 
@@ -175,7 +151,7 @@ function printSuccess() {
   console.log(`  ${YELLOW}1.${RESET} Personalize your config:`);
   console.log(`     Edit ${CYAN}_bmad/bme/_vortex/config.yaml${RESET} and replace ${YELLOW}{user}${RESET} with your name`);
   console.log('');
-  console.log(`  ${YELLOW}2.${RESET} Activate an agent with a slash command (Claude Code):`);
+  console.log(`  ${YELLOW}2.${RESET} Activate an agent (skill) in Claude Code:`);
   for (const agent of AGENTS) {
     console.log(`     ${CYAN}/bmad-agent-bme-${agent.id}${RESET}  (${agent.name})`);
   }
@@ -193,11 +169,10 @@ async function main() {
     printBanner();
     checkPrerequisites(projectRoot);
     archiveDeprecatedWorkflows(projectRoot);
-    createAgentManifest(projectRoot);
     createOutputDirectory(projectRoot);
 
-    // Use refreshInstallation for agents, workflows, config, and user guides
-    console.log(`${CYAN}[5/6]${RESET} Installing agents, workflows, config, and guides...`);
+    // Use refreshInstallation for agents, workflows, config, guides, manifest, and skills
+    console.log(`${CYAN}[4/5]${RESET} Installing agents, workflows, config, and guides...`);
     await refreshInstallation(projectRoot, { backupGuides: false });
     console.log(`${GREEN}  ✓${RESET} Installation refreshed`);
 

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

@@ -112,31 +112,96 @@ async function refreshInstallation(projectRoot, options = {}) {
     return `"${String(value).replace(/"/g, '""')}"`;
   }
 
-  const header = '"agent_id","name","title","icon","role","identity","communication_style","expertise","submodule","path"';
+  function parseCSVRow(row) {
+    const fields = [];
+    let current = '';
+    let inQuotes = false;
+    for (let i = 0; i < row.length; i++) {
+      const ch = row[i];
+      if (inQuotes) {
+        if (ch === '"' && row[i + 1] === '"') {
+          current += '"';
+          i++;
+        } else if (ch === '"') {
+          inQuotes = false;
+        } else {
+          current += ch;
+        }
+      } else if (ch === '"') {
+        inQuotes = true;
+      } else if (ch === ',') {
+        fields.push(current);
+        current = '';
+      } else {
+        current += ch;
+      }
+    }
+    fields.push(current);
+    return fields;
+  }
 
-  // Read existing non-bme rows to preserve them
+  const V610_HEADER = 'name,displayName,title,icon,capabilities,role,identity,communicationStyle,principles,module,path,canonicalId';
+  // Detect schema from existing manifest or default to v6.1.0
+  let header;
+  let isV610 = true;
   let preservedRows = [];
+
   if (fs.existsSync(manifestPath)) {
     const existing = (await fs.readFile(manifestPath, 'utf8')).trim().split('\n');
-    // Skip header, keep rows where submodule is NOT bme
+    header = existing[0];
+    isV610 = header.startsWith('name,') || header.includes('canonicalId');
+
+    // Filter out bme rows, preserve everything else
     preservedRows = existing.slice(1).filter(row => {
-      // submodule is the 9th field (index 8) in the CSV
-      const fields = row.match(/"([^"]*(?:""[^"]*)*)"/g);
-      if (!fields || fields.length < 9) return true; // keep unrecognised rows
-      const submodule = fields[8].replace(/^"|"$/g, '');
-      return submodule !== 'bme';
+      if (!row.trim()) return false;
+      if (isV610) {
+        // v6.1.0: module is column 10 (index 9) — handle quoted CSV fields
+        const parsed = parseCSVRow(row);
+        if (!parsed || parsed.length < 10) return true;
+        return parsed[9] !== 'bme';
+      } else {
+        // Legacy: submodule is column 9 (index 8) — quoted CSV
+        const fields = row.match(/"([^"]*(?:""[^"]*)*)"/g);
+        if (!fields || fields.length < 9) return true;
+        const submodule = fields[8].replace(/^"|"$/g, '');
+        return submodule !== 'bme';
+      }
     });
+  } else {
+    header = V610_HEADER;
+    isV610 = true;
   }
 
-  // Build fresh bme rows from registry
-  const bmeRows = AGENTS.map(a => {
-    const p = a.persona;
-    return [
-      a.id, a.name, a.title, a.icon,
-      p.role, p.identity, p.communication_style, p.expertise,
-      'bme', `_bmad/bme/_vortex/agents/${a.id}.md`,
-    ].map(csvEscape).join(',');
-  });
+  // Build fresh bme rows matching the detected schema
+  let bmeRows;
+  if (isV610) {
+    bmeRows = AGENTS.map(a => {
+      const p = a.persona;
+      return [
+        csvEscape(a.name),           // name
+        csvEscape(''),               // displayName
+        csvEscape(a.title),          // title
+        csvEscape(a.icon),           // icon
+        csvEscape(''),               // capabilities
+        csvEscape(p.role),           // role
+        csvEscape(p.identity),       // identity
+        csvEscape(p.communication_style), // communicationStyle
+        csvEscape(p.expertise),      // principles
+        csvEscape('bme'),            // module
+        csvEscape(`_bmad/bme/_vortex/agents/${a.id}.md`), // path
+        csvEscape(`bmad-agent-bme-${a.id}`), // canonicalId
+      ].join(',');
+    });
+  } else {
+    bmeRows = AGENTS.map(a => {
+      const p = a.persona;
+      return [
+        a.id, a.name, a.title, a.icon,
+        p.role, p.identity, p.communication_style, p.expertise,
+        'bme', `_bmad/bme/_vortex/agents/${a.id}.md`,
+      ].map(csvEscape).join(',');
+    });
+  }
 
   const allRows = [...preservedRows, ...bmeRows].join('\n') + '\n';
   await fs.writeFile(manifestPath, header + '\n' + allRows, 'utf8');
@@ -171,26 +236,38 @@ async function refreshInstallation(projectRoot, options = {}) {
     if (verbose) console.log('    Skipped guide copy (dev environment)');
   }
 
-  // 6. Generate .claude/commands/ slash command files for each agent
-  const commandsTarget = path.join(projectRoot, '.claude', 'commands');
-  await fs.ensureDir(commandsTarget);
-
-  // Remove deprecated command files (agents no longer in registry)
-  const currentCommandFiles = new Set(AGENTS.map(a => `bmad-agent-bme-${a.id}.md`));
-  const existingCommands = (await fs.readdir(commandsTarget)).filter(f => f.startsWith('bmad-agent-bme-'));
-  for (const file of existingCommands) {
-    if (!currentCommandFiles.has(file)) {
-      await fs.remove(path.join(commandsTarget, file));
-      changes.push(`Removed deprecated command: ${file}`);
-      if (verbose) console.log(`    Removed deprecated command: ${file}`);
+  // 6. Clean up legacy .claude/commands/ and generate .claude/skills/ for each agent
+  const commandsDir = path.join(projectRoot, '.claude', 'commands');
+  if (fs.existsSync(commandsDir)) {
+    const legacyCommands = (await fs.readdir(commandsDir)).filter(f => f.startsWith('bmad-agent-bme-'));
+    for (const file of legacyCommands) {
+      await fs.remove(path.join(commandsDir, file));
+      changes.push(`Removed legacy command: ${file}`);
+      if (verbose) console.log(`    Removed legacy command: ${file}`);
+    }
+  }
+
+  const skillsDir = path.join(projectRoot, '.claude', 'skills');
+
+  // Remove stale skill directories (agents no longer in registry)
+  const currentSkillDirs = new Set(AGENTS.map(a => `bmad-agent-bme-${a.id}`));
+  if (fs.existsSync(skillsDir)) {
+    const existingSkills = (await fs.readdir(skillsDir)).filter(d => d.startsWith('bmad-agent-bme-'));
+    for (const dir of existingSkills) {
+      if (!currentSkillDirs.has(dir)) {
+        await fs.remove(path.join(skillsDir, dir));
+        changes.push(`Removed stale skill: ${dir}`);
+        if (verbose) console.log(`    Removed stale skill: ${dir}`);
+      }
     }
   }
 
   for (const agent of AGENTS) {
-    const filename = `bmad-agent-bme-${agent.id}.md`;
+    const skillDir = path.join(skillsDir, `bmad-agent-bme-${agent.id}`);
+    await fs.ensureDir(skillDir);
     const content = `---
-name: '${agent.id}'
-description: '${agent.id} agent'
+name: bmad-agent-bme-${agent.id}
+description: ${agent.id} agent
 ---
 
 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
@@ -204,9 +281,51 @@ You must fully embody this agent's persona and follow all activation instruction
 6. WAIT for user input before proceeding
 </agent-activation>
 `;
-    await fs.writeFile(path.join(commandsTarget, filename), content, 'utf8');
-    changes.push(`Refreshed command: ${filename}`);
-    if (verbose) console.log(`    Refreshed command: ${filename}`);
+    await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf8');
+    changes.push(`Refreshed skill: bmad-agent-bme-${agent.id}/SKILL.md`);
+    if (verbose) console.log(`    Refreshed skill: bmad-agent-bme-${agent.id}/SKILL.md`);
+  }
+
+  // 7. Generate agent customize files (only if they don't already exist)
+  const customizeDir = path.join(projectRoot, '_bmad', '_config', 'agents');
+  await fs.ensureDir(customizeDir);
+
+  const CUSTOMIZE_TEMPLATE = `# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+
+# Add custom menu items (appended to base menu)
+menu: []
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+`;
+
+  for (const agent of AGENTS) {
+    const filename = `bme-${agent.name.toLowerCase()}.customize.yaml`;
+    const filePath = path.join(customizeDir, filename);
+    if (!fs.existsSync(filePath)) {
+      await fs.writeFile(filePath, CUSTOMIZE_TEMPLATE, 'utf8');
+      changes.push(`Created customize file: ${filename}`);
+      if (verbose) console.log(`    Created customize file: ${filename}`);
+    }
   }
 
   return changes;

package/src/module.yaml

@@ -0,0 +1,6 @@
+code: bme
+name: "Convoke: Vortex Discovery Framework"
+header: "Convoke — Vortex Discovery Framework"
+subheader: "7 AI agents for product discovery based on the Shiftup Innovation Vortex"
+description: "Domain-specialized agent teams for structured product discovery: Contextualize, Empathize, Synthesize, Hypothesize, Externalize, Sensitize, Systematize"
+default_selected: false