convoke-agents 2.4.0 → 3.0.1

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

@@ -5,7 +5,7 @@ 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
@@ -182,6 +182,90 @@ async function refreshInstallation(projectRoot, options = {}) {
     }
   }
 
+  // 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));
@@ -264,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';
@@ -342,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) {
@@ -378,7 +475,32 @@ 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`);
   }
 
-  // 6a. Copy Enhance workflow skill wrappers and register in manifests
+  // 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}`;
@@ -457,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)) {

package/scripts/update/lib/validator.js

@@ -468,6 +468,161 @@ async function validateEnhanceModule(projectRoot) {
   return check;
 }
 
+/**
+ * Validate a SKILL.md file has required frontmatter fields
+ * @param {string} skillMdPath - Absolute path to SKILL.md file
+ * @returns {Promise<object>} Validation result { valid, errors }
+ */
+async function validateSkillMd(skillMdPath) {
+  const errors = [];
+
+  if (!fs.existsSync(skillMdPath)) {
+    errors.push(`SKILL.md not found: ${skillMdPath}`);
+    return { valid: false, errors };
+  }
+
+  const content = fs.readFileSync(skillMdPath, 'utf8');
+
+  // Extract YAML frontmatter between --- delimiters
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) {
+    errors.push('SKILL.md missing YAML frontmatter (--- delimiters)');
+    return { valid: false, errors };
+  }
+
+  let frontmatter;
+  try {
+    frontmatter = yaml.load(fmMatch[1]);
+  } catch (err) {
+    errors.push(`SKILL.md frontmatter parse error: ${err.message}`);
+    return { valid: false, errors };
+  }
+
+  if (!frontmatter || typeof frontmatter !== 'object') {
+    errors.push('SKILL.md frontmatter is empty or not an object');
+    return { valid: false, errors };
+  }
+
+  if (!frontmatter.name || typeof frontmatter.name !== 'string') {
+    errors.push('SKILL.md missing required field: name');
+  }
+
+  if (!frontmatter.description || typeof frontmatter.description !== 'string') {
+    errors.push('SKILL.md missing required field: description');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate step files in a skill directory follow sequential numbering
+ * @param {string} skillDir - Absolute path to skill directory
+ * @returns {Promise<object>} Validation result { valid, errors }
+ */
+async function validateStepFiles(skillDir) {
+  const errors = [];
+
+  if (!fs.existsSync(skillDir)) {
+    errors.push(`Skill directory not found: ${skillDir}`);
+    return { valid: false, errors };
+  }
+
+  // Collect step files from skill dir and steps/ subdirectory
+  const stepFiles = [];
+  const entries = fs.readdirSync(skillDir);
+
+  for (const entry of entries) {
+    if (/^step-\d+-/.test(entry) && entry.endsWith('.md')) {
+      stepFiles.push(entry);
+    }
+  }
+
+  const stepsSubdir = path.join(skillDir, 'steps');
+  if (fs.existsSync(stepsSubdir)) {
+    const subEntries = fs.readdirSync(stepsSubdir);
+    for (const entry of subEntries) {
+      if (/^step-\d+-/.test(entry) && entry.endsWith('.md')) {
+        stepFiles.push(entry);
+      }
+    }
+  }
+
+  if (stepFiles.length === 0) {
+    // No step files is valid — some skills are single-file (agent-activation type)
+    return { valid: true, errors };
+  }
+
+  // Extract step numbers and check for sequential numbering
+  const stepNumbers = stepFiles
+    .map(f => {
+      const match = f.match(/^step-(\d+)-/);
+      return match ? parseInt(match[1], 10) : null;
+    })
+    .filter(n => n !== null)
+    .sort((a, b) => a - b);
+
+  // Remove duplicates (same step number in root and steps/)
+  const uniqueSteps = [...new Set(stepNumbers)];
+
+  // Check for gaps in sequence
+  for (let i = 0; i < uniqueSteps.length - 1; i++) {
+    if (uniqueSteps[i + 1] - uniqueSteps[i] > 1) {
+      errors.push(
+        `Step numbering gap: step-${String(uniqueSteps[i]).padStart(2, '0')} to step-${String(uniqueSteps[i + 1]).padStart(2, '0')} (missing step-${String(uniqueSteps[i] + 1).padStart(2, '0')})`
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate skill cohesion — workflow.md exists if step files exist
+ * @param {string} skillDir - Absolute path to skill directory
+ * @returns {Promise<object>} Validation result { valid, errors }
+ */
+async function validateSkillCohesion(skillDir) {
+  const errors = [];
+
+  if (!fs.existsSync(skillDir)) {
+    errors.push(`Skill directory not found: ${skillDir}`);
+    return { valid: false, errors };
+  }
+
+  const entries = fs.readdirSync(skillDir);
+  const hasStepFiles = entries.some(e => /^step-\d+-/.test(e) && e.endsWith('.md'));
+  const hasStepsSubdir = fs.existsSync(path.join(skillDir, 'steps'));
+  const hasWorkflow = entries.includes('workflow.md');
+
+  // If step files or steps/ subdirectory exist, workflow.md should too
+  if ((hasStepFiles || hasStepsSubdir) && !hasWorkflow) {
+    errors.push('Skill has step files but no workflow.md');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate a complete skill package (SKILL.md + step files + cohesion)
+ * @param {string} skillDir - Absolute path to skill directory
+ * @returns {Promise<object>} Validation result { valid, errors }
+ */
+async function validateSkill(skillDir) {
+  const allErrors = [];
+
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const skillMdResult = await validateSkillMd(skillMdPath);
+  allErrors.push(...skillMdResult.errors);
+
+  const stepResult = await validateStepFiles(skillDir);
+  allErrors.push(...stepResult.errors);
+
+  const cohesionResult = await validateSkillCohesion(skillDir);
+  allErrors.push(...cohesionResult.errors);
+
+  return { valid: allErrors.length === 0, errors: allErrors };
+}
+
 module.exports = {
   validateInstallation,
   validateConfigStructure,
@@ -477,5 +632,9 @@ module.exports = {
   validateUserDataIntegrity,
   validateDeprecatedWorkflows,
   validateWorkflowStepStructure,
-  validateEnhanceModule
+  validateEnhanceModule,
+  validateSkillMd,
+  validateStepFiles,
+  validateSkillCohesion,
+  validateSkill
 };