convoke-agents 2.3.1 → 3.0.0

package/scripts/update/lib/agent-registry.js

@@ -133,6 +133,71 @@ const WAVE3_STREAMS = new Set(['Synthesize', 'Hypothesize', 'Sensitize']);
 const _wave3AgentIds = new Set(AGENTS.filter(a => WAVE3_STREAMS.has(a.stream)).map(a => a.id));
 const WAVE3_WORKFLOW_NAMES = new Set(WORKFLOWS.filter(w => _wave3AgentIds.has(w.agent)).map(w => w.name));
 
+// ── Gyre Module ──────────────────────────────────────────────────────
+const GYRE_AGENTS = [
+  {
+    id: 'stack-detective', name: 'Scout', icon: '\u{1F50E}',
+    title: 'Stack Detective', stream: 'Detect',
+    persona: {
+      role: 'Technology Stack Detective + Architecture Classification Specialist',
+      identity: 'Methodical investigator who detects project technology stacks by analyzing filesystem artifacts. Reads manifests, configs, and IaC files. Never guesses — reports what evidence supports. Asks targeted guard questions derived from detection results to confirm architecture intent. Produces the Stack Profile (GC1) that downstream agents use to generate contextual models.',
+      communication_style: 'Methodical and evidence-driven. Reports findings with source references. Says things like \'I found evidence of...\' and \'Based on the manifests, this appears to be...\' Never speculates — distinguishes confirmed detections from inferences.',
+      expertise: '- Evidence over inference — every detection claim cites a specific file or pattern - Guard questions clarify ambiguity, not confirm the obvious - Privacy boundary: Stack Profile carries categories, never file contents or secrets - Report secondary stacks as warnings, not errors - Detection is the foundation — get it right and everything downstream improves',
+    },
+  },
+  {
+    id: 'model-curator', name: 'Atlas', icon: '\u{1F4D0}',
+    title: 'Model Curator', stream: 'Model',
+    persona: {
+      role: 'Contextual Model Generation + Capabilities Curation Specialist',
+      identity: 'Knowledgeable curator who generates capabilities manifests unique to each detected stack. Balances industry standards (DORA, OpenTelemetry, Google PRR) with practical relevance. Explains why each capability matters. Transparent about confidence levels — distinguishes well-known patterns from emerging practices.',
+      communication_style: 'Knowledgeable and transparent — explains reasoning behind each capability. Says things like \'This capability matters for your stack because...\' and \'I\'m less confident about this one — it\'s an emerging practice.\' Respects team ownership of the model.',
+      expertise: '- Industry standards inform but don\'t dictate — every capability must be relevant to THIS stack - Web search for current best practices keeps the model fresh - Model is team-owned — amendments from Coach (GC4) are respected on regeneration - Transparency about sources and confidence builds trust - Generate ≥20 capabilities for supported archetypes',
+    },
+  },
+  {
+    id: 'readiness-analyst', name: 'Lens', icon: '\u{1F52C}',
+    title: 'Readiness Analyst', stream: 'Analyze',
+    persona: {
+      role: 'Absence Detection + Cross-Domain Correlation Specialist',
+      identity: 'Thorough analyst who compares the capabilities manifest against what actually exists in the project. Identifies absences — what\'s missing, not just what\'s misconfigured. Runs observability and deployment domain analyses with cross-domain correlation for compound findings.',
+      communication_style: 'Thorough and honest — presents findings with evidence and confidence levels. Says things like \'I found no evidence of...\' and \'These two gaps amplify each other.\' Never inflates severity — a nice-to-have stays a nice-to-have.',
+      expertise: '- Absence detection finds what\'s missing, not just what\'s broken - Source-tag every finding (static analysis vs contextual model) - Cross-domain correlation reveals compound gaps that single-domain analysis misses - Confidence levels must reflect actual evidence strength - Never inflate severity — accuracy builds credibility',
+    },
+  },
+  {
+    id: 'review-coach', name: 'Coach', icon: '\u{1F3CB}',
+    title: 'Review Coach', stream: 'Review',
+    persona: {
+      role: 'Findings Review + Model Amendment + Feedback Capture Specialist',
+      identity: 'Patient guide who respects the user\'s expertise. Presents findings clearly — severity-first summary, then walkthrough. For model review, presents each capability one at a time with keep/remove/edit options. Captures feedback on missed gaps to improve the model over time.',
+      communication_style: 'Patient and respectful — lets the user decide what\'s relevant. Says things like \'Here\'s what we found — let me walk you through it\' and \'Did Gyre miss anything you know about?\' Explains why feedback matters for model improvement.',
+      expertise: '- Severity-first presentation respects the user\'s time - Model review is a conversation, not a checklist - Feedback capture improves the model for the whole team - Amendments persist — the model becomes team-owned through review - Never push — the user knows their system best',
+    },
+  },
+];
+
+const GYRE_WORKFLOWS = [
+  // Scout — Detect
+  { name: 'stack-detection', agent: 'stack-detective' },
+  // Atlas — Model
+  { name: 'model-generation', agent: 'model-curator' },
+  // Lens — Analyze
+  { name: 'gap-analysis', agent: 'readiness-analyst' },
+  { name: 'delta-report', agent: 'readiness-analyst' },
+  // Coach — Review
+  { name: 'model-review', agent: 'review-coach' },
+  // Orchestration
+  { name: 'full-analysis', agent: 'stack-detective' },
+  // Validation
+  { name: 'accuracy-validation', agent: 'model-curator' },
+];
+
+// Derived lists for Gyre
+const GYRE_AGENT_FILES = GYRE_AGENTS.map(a => `${a.id}.md`);
+const GYRE_AGENT_IDS = GYRE_AGENTS.map(a => a.id);
+const GYRE_WORKFLOW_NAMES = GYRE_WORKFLOWS.map(w => w.name);
+
 module.exports = {
   AGENTS,
   WORKFLOWS,
@@ -141,4 +206,9 @@ module.exports = {
   WORKFLOW_NAMES,
   USER_GUIDES,
   WAVE3_WORKFLOW_NAMES,
+  GYRE_AGENTS,
+  GYRE_WORKFLOWS,
+  GYRE_AGENT_FILES,
+  GYRE_AGENT_IDS,
+  GYRE_WORKFLOW_NAMES,
 };

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

@@ -2,9 +2,10 @@
 
 const fs = require('fs-extra');
 const path = require('path');
+const yaml = require('js-yaml');
 const { getPackageVersion } = require('./utils');
 const configMerger = require('./config-merger');
-const { AGENTS, AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, USER_GUIDES } = require('./agent-registry');
+const { AGENTS, AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, USER_GUIDES, GYRE_AGENTS, GYRE_AGENT_FILES, GYRE_AGENT_IDS, GYRE_WORKFLOW_NAMES } = require('./agent-registry');
 
 /**
  * Refresh Installation for Convoke
@@ -90,6 +91,181 @@ async function refreshInstallation(projectRoot, options = {}) {
     if (verbose) console.log('    Skipped workflow copy (dev environment)');
   }
 
+  // 2a. Enhance module — read config, copy directory tree, patch target agent menu
+  const packageEnhance = path.join(packageRoot, '_bmad', 'bme', '_enhance');
+  const enhanceConfigPath = path.join(packageEnhance, 'config.yaml');
+
+  let enhanceConfig = null;
+  if (fs.existsSync(enhanceConfigPath)) {
+    try {
+      enhanceConfig = yaml.load(fs.readFileSync(enhanceConfigPath, 'utf8'));
+    } catch (err) {
+      const msg = `Enhance config.yaml parse error: ${err.message} — skipping Enhance installation`;
+      changes.push(msg);
+      if (verbose) console.log(`    ⚠ ${msg}`);
+    }
+  } else {
+    changes.push('Enhance config.yaml not found — skipping Enhance installation');
+    if (verbose) console.log('    ⚠ Enhance config.yaml not found — skipping Enhance installation');
+  }
+
+  if (enhanceConfig) {
+    // 2b. Copy _enhance/ directory tree
+    const targetEnhance = path.join(projectRoot, '_bmad', 'bme', '_enhance');
+
+    if (!isSameRoot) {
+      await fs.copy(packageEnhance, targetEnhance, { overwrite: true });
+      changes.push('Refreshed Enhance module: _bmad/bme/_enhance/');
+      if (verbose) console.log('    Refreshed Enhance module: _bmad/bme/_enhance/');
+    } else {
+      changes.push('Skipped Enhance copy (dev environment — files already in place)');
+      if (verbose) console.log('    Skipped Enhance copy (dev environment)');
+    }
+
+    // 2c. Patch target agent menu for each registered workflow
+    if (isSameRoot) {
+      changes.push('Skipped Enhance menu patch (dev environment — source files unchanged)');
+      if (verbose) console.log('    Skipped Enhance menu patch (dev environment)');
+    }
+
+    for (const workflow of (isSameRoot ? [] : enhanceConfig.workflows || [])) {
+      const targetAgentRel = workflow.target_agent;
+      const targetAgentPath = path.join(projectRoot, '_bmad', targetAgentRel);
+
+      if (!fs.existsSync(targetAgentPath)) {
+        const msg = `${targetAgentRel} not found — BMM module must be installed first. Skipping Enhance menu patch.`;
+        changes.push(msg);
+        if (verbose) console.log(`    ⚠ ${msg}`);
+        continue;
+      }
+
+      let agentContent = fs.readFileSync(targetAgentPath, 'utf8');
+      const patchName = workflow.menu_patch_name || workflow.name;
+
+      // Idempotency: skip if patch already present
+      if (agentContent.includes(patchName)) {
+        changes.push(`Enhance menu patch already present in ${targetAgentRel} — skipping`);
+        if (verbose) console.log(`    Enhance menu patch already present in ${targetAgentRel} — skipping`);
+        continue;
+      }
+
+      // Build the <item> tag
+      const entryPath = `{project-root}/_bmad/bme/_enhance/${workflow.entry}`;
+      const itemTag = `    <item cmd="IB or fuzzy match on ${patchName}" exec="${entryPath}">[IB] 📦 Initiatives Backlog (Convoke Enhance)</item>`;
+
+      // Find insertion anchor: prefer </menu>, fallback to last <item>
+      const menuCloseIdx = agentContent.lastIndexOf('</menu>');
+      if (menuCloseIdx !== -1) {
+        // Insert before the </menu> line (not at the </menu> character position,
+        // which would prepend existing line indentation to the inserted tag)
+        const lineStart = agentContent.lastIndexOf('\n', menuCloseIdx - 1) + 1;
+        agentContent = agentContent.slice(0, lineStart) + itemTag + '\n' + agentContent.slice(lineStart);
+      } else {
+        // Fallback: insert after last <item>...</item> line
+        const lastItemMatch = agentContent.match(/.*<item[^]*?<\/item>/g);
+        if (lastItemMatch) {
+          const lastItem = lastItemMatch[lastItemMatch.length - 1];
+          const lastItemIdx = agentContent.lastIndexOf(lastItem);
+          const insertIdx = lastItemIdx + lastItem.length;
+          agentContent = agentContent.slice(0, insertIdx) + '\n' + itemTag + agentContent.slice(insertIdx);
+        } else {
+          const msg = `${targetAgentRel} menu structure not recognized — manual patch required. Skipping Enhance menu patch.`;
+          changes.push(msg);
+          if (verbose) console.log(`    ⚠ ${msg}`);
+          continue;
+        }
+      }
+
+      fs.writeFileSync(targetAgentPath, agentContent, 'utf8');
+      changes.push(`Patched ${targetAgentRel} with Enhance menu item: ${patchName}`);
+      if (verbose) console.log(`    Patched ${targetAgentRel} with Enhance menu item: ${patchName}`);
+    }
+  }
+
+  // 2d. Gyre module — copy agents, workflows, contracts, config
+  const packageGyre = path.join(packageRoot, '_bmad', 'bme', '_gyre');
+  const targetGyre = path.join(projectRoot, '_bmad', 'bme', '_gyre');
+
+  if (fs.existsSync(packageGyre)) {
+    // Copy Gyre agents
+    const gyreAgentsSource = path.join(packageGyre, 'agents');
+    const gyreAgentsTarget = path.join(targetGyre, 'agents');
+    await fs.ensureDir(gyreAgentsTarget);
+
+    if (!isSameRoot) {
+      for (const file of GYRE_AGENT_FILES) {
+        const src = path.join(gyreAgentsSource, file);
+        if (fs.existsSync(src)) {
+          await fs.copy(src, path.join(gyreAgentsTarget, file), { overwrite: true });
+          changes.push(`Refreshed Gyre agent: ${file}`);
+          if (verbose) console.log(`    Refreshed Gyre agent: ${file}`);
+        }
+      }
+    } else {
+      changes.push('Skipped Gyre agent copy (dev environment)');
+      if (verbose) console.log('    Skipped Gyre agent copy (dev environment)');
+    }
+
+    // Copy Gyre workflows
+    const gyreWorkflowsSource = path.join(packageGyre, 'workflows');
+    const gyreWorkflowsTarget = path.join(targetGyre, 'workflows');
+    await fs.ensureDir(gyreWorkflowsTarget);
+
+    if (!isSameRoot) {
+      for (const wf of GYRE_WORKFLOW_NAMES) {
+        const src = path.join(gyreWorkflowsSource, wf);
+        const dest = path.join(gyreWorkflowsTarget, wf);
+        if (fs.existsSync(src)) {
+          if (fs.existsSync(dest)) {
+            await fs.remove(dest);
+          }
+          await fs.copy(src, dest, { overwrite: true });
+          changes.push(`Refreshed Gyre workflow: ${wf}`);
+          if (verbose) console.log(`    Refreshed Gyre workflow: ${wf}`);
+        }
+      }
+    } else {
+      changes.push('Skipped Gyre workflow copy (dev environment)');
+      if (verbose) console.log('    Skipped Gyre workflow copy (dev environment)');
+    }
+
+    // Copy Gyre contracts
+    const gyreContractsSource = path.join(packageGyre, 'contracts');
+    const gyreContractsTarget = path.join(targetGyre, 'contracts');
+    if (fs.existsSync(gyreContractsSource)) {
+      await fs.ensureDir(gyreContractsTarget);
+      if (!isSameRoot) {
+        await fs.copy(gyreContractsSource, gyreContractsTarget, { overwrite: true });
+        changes.push('Refreshed Gyre contracts');
+        if (verbose) console.log('    Refreshed Gyre contracts');
+      }
+    }
+
+    // Copy Gyre config.yaml
+    const gyreConfigSource = path.join(packageGyre, 'config.yaml');
+    const gyreConfigTarget = path.join(targetGyre, 'config.yaml');
+    if (!isSameRoot && fs.existsSync(gyreConfigSource)) {
+      // Merge Gyre config preserving user prefs, same as Vortex
+      const gyreUpdates = {
+        agents: GYRE_AGENT_IDS,
+        workflows: GYRE_WORKFLOW_NAMES
+      };
+      const gyreConfigMerged = await configMerger.mergeConfig(gyreConfigTarget, version, gyreUpdates);
+      await configMerger.writeConfig(gyreConfigTarget, gyreConfigMerged);
+      changes.push(`Updated Gyre config.yaml to v${version}`);
+      if (verbose) console.log(`    Updated Gyre config.yaml to v${version}`);
+    }
+
+    // Copy Gyre README
+    const gyreReadmeSource = path.join(packageGyre, 'README.md');
+    const gyreReadmeTarget = path.join(targetGyre, 'README.md');
+    if (!isSameRoot && fs.existsSync(gyreReadmeSource)) {
+      await fs.copy(gyreReadmeSource, gyreReadmeTarget, { overwrite: true });
+      changes.push('Refreshed Gyre README.md');
+      if (verbose) console.log('    Refreshed Gyre README.md');
+    }
+  }
+
   // 3. Update config.yaml (merge, preserving user prefs)
   const configPath = path.join(targetVortex, 'config.yaml');
   await fs.ensureDir(path.dirname(configPath));
@@ -172,35 +348,45 @@ async function refreshInstallation(projectRoot, options = {}) {
     isV610 = true;
   }
 
-  // Build fresh bme rows matching the detected schema
+  // Build fresh bme rows matching the detected schema (Vortex + Gyre agents)
+  function buildAgentRow610(a, submodule) {
+    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/${submodule}/agents/${a.id}.md`), // path
+      csvEscape(`bmad-agent-bme-${a.id}`), // canonicalId
+    ].join(',');
+  }
+
+  function buildAgentRowLegacy(a, submodule) {
+    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/${submodule}/agents/${a.id}.md`,
+    ].map(csvEscape).join(',');
+  }
+
   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(',');
-    });
+    bmeRows = [
+      ...AGENTS.map(a => buildAgentRow610(a, '_vortex')),
+      ...GYRE_AGENTS.map(a => buildAgentRow610(a, '_gyre')),
+    ];
   } 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(',');
-    });
+    bmeRows = [
+      ...AGENTS.map(a => buildAgentRowLegacy(a, '_vortex')),
+      ...GYRE_AGENTS.map(a => buildAgentRowLegacy(a, '_gyre')),
+    ];
   }
 
   const allRows = [...preservedRows, ...bmeRows].join('\n') + '\n';
@@ -250,7 +436,10 @@ async function refreshInstallation(projectRoot, options = {}) {
   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}`));
+  const currentSkillDirs = new Set([
+    ...AGENTS.map(a => `bmad-agent-bme-${a.id}`),
+    ...GYRE_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) {
@@ -286,6 +475,78 @@ You must fully embody this agent's persona and follow all activation instruction
     if (verbose) console.log(`    Refreshed skill: bmad-agent-bme-${agent.id}/SKILL.md`);
   }
 
+  // 6b. Generate .claude/skills/ for Gyre agents
+  for (const agent of GYRE_AGENTS) {
+    const skillDir = path.join(skillsDir, `bmad-agent-bme-${agent.id}`);
+    await fs.ensureDir(skillDir);
+    const content = `---
+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.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from {project-root}/_bmad/bme/_gyre/agents/${agent.id}.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+    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`);
+  }
+
+  // 6c. Copy Enhance workflow skill wrappers and register in manifests
+  if (enhanceConfig && !isSameRoot) {
+    for (const workflow of enhanceConfig.workflows || []) {
+      const canonicalId = `bmad-enhance-${workflow.name}`;
+      const skillDir = path.join(skillsDir, canonicalId);
+      await fs.ensureDir(skillDir);
+
+      // Copy source SKILL.md from package (shipped via npm, not generated)
+      const sourceSkillPath = path.join(packageRoot, '_bmad', 'bme', '_enhance', 'workflows', workflow.name, 'SKILL.md');
+      const targetSkillPath = path.join(skillDir, 'SKILL.md');
+      await fs.copy(sourceSkillPath, targetSkillPath, { overwrite: true });
+      changes.push(`Refreshed Enhance skill: ${canonicalId}/SKILL.md`);
+      if (verbose) console.log(`    Refreshed Enhance skill: ${canonicalId}/SKILL.md`);
+
+      // Append to workflow-manifest.csv if not already present
+      const wfManifestPath = path.join(projectRoot, '_bmad', '_config', 'workflow-manifest.csv');
+      if (fs.existsSync(wfManifestPath)) {
+        const wfCsv = fs.readFileSync(wfManifestPath, 'utf8');
+        if (!wfCsv.includes(`"${canonicalId}"`)) {
+          const wfRow = `\n"${workflow.name}","Manage RICE initiatives backlog — triage review findings, rescore existing items, or bootstrap new backlogs.","bme","_bmad/bme/_enhance/${workflow.entry}","${canonicalId}"`;
+          fs.appendFileSync(wfManifestPath, wfRow, 'utf8');
+          changes.push(`Added ${canonicalId} to workflow-manifest.csv`);
+          if (verbose) console.log(`    Added ${canonicalId} to workflow-manifest.csv`);
+        }
+      } else {
+        if (verbose) console.log('    ⚠ workflow-manifest.csv not found — skipping manifest registration');
+      }
+
+      // Append to skill-manifest.csv if not already present
+      const skManifestPath = path.join(projectRoot, '_bmad', '_config', 'skill-manifest.csv');
+      if (fs.existsSync(skManifestPath)) {
+        const skCsv = fs.readFileSync(skManifestPath, 'utf8');
+        if (!skCsv.includes(`"${canonicalId}"`)) {
+          const skRow = `\n"${canonicalId}","${canonicalId}","Manage RICE initiatives backlog — triage review findings, rescore existing items, or bootstrap new backlogs.","bme","_bmad/bme/_enhance/workflows/${workflow.name}/SKILL.md","true"`;
+          fs.appendFileSync(skManifestPath, skRow, 'utf8');
+          changes.push(`Added ${canonicalId} to skill-manifest.csv`);
+          if (verbose) console.log(`    Added ${canonicalId} to skill-manifest.csv`);
+        }
+      } else {
+        if (verbose) console.log('    ⚠ skill-manifest.csv not found — skipping manifest registration');
+      }
+    }
+  } else if (enhanceConfig && isSameRoot) {
+    changes.push('Skipped Enhance skill registration (dev environment — source files unchanged)');
+    if (verbose) console.log('    Skipped Enhance skill registration (dev environment)');
+  }
+
   // 7. Generate agent customize files (only if they don't already exist)
   const customizeDir = path.join(projectRoot, '_bmad', '_config', 'agents');
   await fs.ensureDir(customizeDir);
@@ -318,7 +579,7 @@ menu: []
 prompts: []
 `;
 
-  for (const agent of AGENTS) {
+  for (const agent of [...AGENTS, ...GYRE_AGENTS]) {
     const filename = `bme-${agent.name.toLowerCase()}.customize.yaml`;
     const filePath = path.join(customizeDir, filename);
     if (!fs.existsSync(filePath)) {