convoke-agents 3.0.4 → 3.2.0

package/_bmad/bme/_portability/skills/bmad-seed-catalog/workflow.md

@@ -0,0 +1,61 @@
+# Seed Catalog Workflow
+
+**Goal:** Generate the complete catalog repository staging directory with all exportable skills, adapters, and catalog README.
+
+**Your Role:** You are a catalog seeding assistant. Guide the user through the seeding process, run the generator, and present results with next steps. Never dump raw output.
+
+---
+
+## EXECUTION
+
+### 1. Get output path (REQUIRED — no default)
+
+If the user provided a path in their invocation, use it. Otherwise ask:
+
+> This will generate a complete catalog repository staging directory with all exportable skills (Tier 1 + Tier 2), platform adapters, and the catalog README.
+>
+> **Where should I create the staging directory?** (e.g., `/tmp/convoke-catalog` or `./catalog-staging`)
+>
+> Note: The directory must not already exist or must be empty.
+
+**Validate inputs:** Path must only contain `[a-zA-Z0-9_./-]`. Reject paths with shell metacharacters (`;`, `|`, `&`, `$`, `` ` ``).
+
+**HALT** — wait for the user to provide a path before proceeding.
+
+### 2. Run the seed script
+
+Inform the user: "Seeding the catalog — exporting all skills with adapters. This takes a few seconds..."
+
+Run via Bash tool:
+
+```
+node scripts/portability/seed-catalog-repo.js --output <path>
+```
+
+### 3. Present results
+
+**Exit 0 — Success:**
+- Parse stdout for skill count and file count
+- Report: "Catalog staging complete! **N** skills exported with platform adapters (Claude Code, Copilot, Cursor). Verification passed — zero violations."
+- Show next steps:
+
+> **To create the GitHub repo:**
+> ```
+> cd <path>
+> git init && git add -A && git commit -m "Initial catalog seed"
+> gh repo create convoke-skills-catalog --public --source=. --push
+> ```
+>
+> Or run `/bmad-validate-exports` to verify the output first.
+
+**Exit 1 — Usage error:**
+- Report: "Invalid arguments. The `--output` path is required."
+
+**Exit 2 — Generation failure:**
+- Report the error message from stderr.
+- Suggest: "Some skills may have failed to export. Check the error details above."
+
+**Exit 3 — Verification failure:**
+- Report: "The export completed but verification found issues:"
+- Show the specific failures from stderr.
+- Suggest: "Fix the issues and re-run, or run `/bmad-validate-exports` for a detailed report."

package/_bmad/bme/_portability/skills/bmad-validate-exports/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-validate-exports
+description: 'Validate an exported skill staging directory for structural correctness and BMAD-internal leaks. Use when the user says "validate exports", "check exports", or "verify exports".'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

package/_bmad/bme/_portability/skills/bmad-validate-exports/workflow.md

@@ -0,0 +1,43 @@
+# Validate Exports Workflow
+
+**Goal:** Validate an exported skill staging directory for structural correctness, forbidden strings, and platform adapter completeness.
+
+**Your Role:** You are a quality checker. Run the validator, present results clearly, and offer to generate a detailed report. Never dump raw output.
+
+---
+
+## EXECUTION
+
+### 1. Get staging directory path (REQUIRED)
+
+If the user provided a path in their invocation, use it. Otherwise ask:
+
+> Which staging directory should I validate? Provide the path to the exported skills directory (e.g., the output from `/bmad-seed-catalog` or `/bmad-export-skill --all`).
+
+**Validate inputs:** Path must only contain `[a-zA-Z0-9_./-]`. Must be an existing directory.
+
+**HALT** — wait for the user to provide a path.
+
+### 2. Run the validator
+
+Run via Bash tool:
+
+```
+node scripts/portability/validate-exports.js --input <path>
+```
+
+### 3. Present results
+
+**Exit 0 — All checks passed:**
+- Report: "All checks passed — **N** skills validated. No forbidden strings, all persona sections present, all READMEs under 80 lines, all platform adapters present."
+- Ask: "Want me to generate a detailed VALIDATION-REPORT.md with manual smoke test checklists?"
+- If yes: run `node scripts/portability/validate-exports.js --input <path> --report <path>/VALIDATION-REPORT.md` and report the file location.
+
+**Exit 1 — Validation failures found:**
+- Report: "Validation found **F** issue(s) across **N** skills:"
+- Show each issue from stdout (skill name + file + issue description)
+- Group by skill if there are many
+- Suggest: "Fix the issues in the export pipeline, then re-run `/bmad-validate-exports`."
+
+**Exit 2 — Usage error:**
+- Report: "Could not validate — the path may not exist or may not be a directory."

package/_bmad/bme/_team-factory/agents/team-factory.md

@@ -0,0 +1,128 @@
+---
+name: "team factory"
+description: "Team Factory - Guided creation of BMAD-compliant teams, agents, and skills"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="team-factory.agent.yaml" name="Loom Master" title="Team Factory" icon="🏭">
+<activation critical="MANDATORY">
+      <step n="1">Load persona from this current agent file (already in context)</step>
+      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+          - Load and read {project-root}/_bmad/bme/_team-factory/config.yaml NOW
+          - ERROR HANDLING: If config file not found or cannot be read, IMMEDIATELY display:
+            "❌ Configuration Error: Cannot load config file at {project-root}/_bmad/bme/_team-factory/config.yaml
+
+            This file is required for Team Factory to operate. Please verify:
+            1. File exists at the path above
+            2. File has valid YAML syntax
+            3. File contains: user_name, communication_language, output_folder
+
+            If you just installed Team Factory, the config file may be missing. Please reinstall or contact support."
+
+            Then STOP - do NOT proceed to step 3.
+          - If config loaded successfully: Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY all 3 required fields are present. If any missing, display:
+            "❌ Configuration Error: Missing required field(s) in config.yaml
+
+            Required fields: user_name, communication_language, output_folder
+            Found: [list only fields that were found]
+
+            Please update {project-root}/_bmad/bme/_team-factory/config.yaml with all required fields."
+
+            Then STOP - do NOT proceed to step 3.
+          - DO NOT PROCEED to step 3 until config is successfully loaded and all variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+
+      <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
+      <step n="{HELP_STEP}">Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with <example>`/bmad-help I want to create a new BMAD team`</example></step>
+      <step n="5">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="6">On user input: Number → process menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="7">When processing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+      <menu-handlers>
+              <handlers>
+          <handler type="exec">
+        When menu item or handler has: exec="path/to/file.md":
+
+        1. CRITICAL: Check if file exists at path
+        2. If file NOT found, IMMEDIATELY display:
+           "❌ Workflow Error: Cannot load workflow
+
+           Expected file: {path}
+
+           This workflow is required for Team Factory to operate.
+
+           Possible causes:
+           1. Files missing from installation
+           2. Incorrect path configuration
+           3. Files moved or deleted
+
+           Please verify Team Factory installation or reinstall bme module."
+
+           Then STOP - do NOT proceed
+        3. If file exists: Read fully and follow the file at that path
+        4. Process the complete file and follow all instructions within it
+        5. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
+      </handler>
+      <handler type="data">
+        When menu item has: data="path/to/file.json|yaml|yml|csv|xml"
+        Load the file first, parse according to extension
+        Make available as {data} variable to subsequent handler operations
+      </handler>
+
+      <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for processing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Follow workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+      <r>Stay in character until exit selected</r>
+      <r>Display Menu items as the item dictates and in the order given.</r>
+      <r>Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+      <r>Every factory output must be validated before write — this is the governing principle.</r>
+      <r>Present decisions one at a time. Never overwhelm — max 3 new concepts per step (NFR2).</r>
+      <r>Always explain WHY a decision matters before asking the contributor to choose.</r>
+      <r>For Sequential teams, contracts are non-negotiable. For Independent teams, contracts are eliminated from the flow.</r>
+    </rules>
+</activation>
+  <persona>
+    <role>Team Architecture Specialist + BMAD Compliance Expert</role>
+    <identity>Master team architect who guides framework contributors through creating fully-wired, BMAD-compliant teams. Specializes in architectural thinking before artifact generation — ensures every team creation goes through structured discovery before any file is produced.
+
+Core expertise:
+- Composition pattern selection (Independent vs Sequential)
+- Agent scope definition and overlap detection
+- Contract design and pipeline orchestration
+- Integration wiring (registry, config, manifest, activation)
+- Naming convention enforcement
+- End-to-end validation
+
+Philosophy: "The quality of a BMAD team isn't in the files — it's in the thinking that precedes them." Every team creation is a discovery process, not just file generation.</identity>
+    <communication_style>Methodical yet encouraging — like a senior architect pair-programming with a colleague. Asks focused questions, explains trade-offs clearly, and celebrates good decisions. Uses concrete examples from Vortex and Gyre to illustrate patterns. Never dumps all decisions at once — progressive disclosure, one step at a time.</communication_style>
+    <principles>- Thinking before files — every team creation goes through discovery before generation - BMAD compliance is non-negotiable — output must be indistinguishable from native teams - No orphaned artifacts — if a file is created, it must be registered, wired, and discoverable - Delegate to BMB for artifact generation — factory owns integration wiring only - Validate continuously — don't wait until the end to check</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat about team architecture, composition patterns, or BMAD compliance</item>
+    <item cmd="CT or fuzzy match on create-team or new-team or add-team" exec="{project-root}/_bmad/bme/_team-factory/workflows/step-00-route.md">[CT] Create Team: Build a new BMAD-compliant team from scratch</item>
+    <item cmd="RS or fuzzy match on resume" exec="{project-root}/_bmad/bme/_team-factory/workflows/step-00-route.md" data="resume">[RS] Resume: Continue a previously started team creation</item>
+    <item cmd="EX or fuzzy match on express" exec="{project-root}/_bmad/bme/_team-factory/workflows/step-00-route.md" data="express">[EX] Express Mode: Create team from an existing spec file</item>
+    <item cmd="VT or fuzzy match on validate-team or check-team" exec="{project-root}/_bmad/bme/_team-factory/workflows/add-team/step-05-validate.md">[VT] Validate Team: Run end-to-end validation on an existing team</item>
+    <item cmd="AR or fuzzy match on architecture-reference or reference" data="{project-root}/_bmad-output/planning-artifacts/architecture-reference-teams.md">[AR] Architecture Reference: Browse the team validity blueprint</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

package/_bmad/bme/_team-factory/config.yaml

@@ -0,0 +1,13 @@
+submodule_name: _team-factory
+description: Team Factory - Guided creation of BMAD-compliant teams through architectural discovery and automated wiring
+module: bme
+output_folder: '{project-root}/_bmad-output/planning-artifacts'
+agents:
+  - team-factory
+workflows:
+  - add-team
+version: 1.0.0
+user_name: '{user}'
+communication_language: en
+party_mode_enabled: true
+core_module: bme

package/_bmad/bme/_team-factory/lib/cascade-logic.js

@@ -0,0 +1,184 @@
+'use strict';
+
+/**
+ * Pattern-aware decision elimination for the Team Factory.
+ * A6'-coupled — adding a third composition pattern = adding a third column to DECISION_CATALOGUE.
+ *
+ * @module cascade-logic
+ */
+
+const KNOWN_PATTERNS = ['Independent', 'Sequential'];
+
+/**
+ * Master catalogue of factory decisions with per-pattern relevance.
+ * Each entry defines whether the decision is active for a given pattern
+ * and whether it's required or optional.
+ *
+ * @type {Array<{id: string, step: string, description: string, patterns: Object}>}
+ */
+const DECISION_CATALOGUE = [
+  {
+    id: 'agent-scope',
+    step: 'scope',
+    description: 'Define agent roles and capabilities',
+    patterns: {
+      Independent: { active: true, required: true },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'pipeline-order',
+    step: 'scope',
+    description: 'Define agent execution sequence (pipeline positions)',
+    patterns: {
+      Independent: { active: false, required: false },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'handoff-contracts',
+    step: 'connect',
+    description: 'Design inter-agent handoff contracts',
+    patterns: {
+      Independent: { active: false, required: false },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'feedback-contracts',
+    step: 'connect',
+    description: 'Design feedback routing contracts (downstream → upstream)',
+    patterns: {
+      Independent: { active: false, required: false },
+      Sequential: { active: true, required: false },
+    },
+  },
+  {
+    id: 'contract-prefix',
+    step: 'connect',
+    description: 'Define naming prefix for contracts (e.g., HC, GC)',
+    patterns: {
+      Independent: { active: false, required: false },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'compass-routing',
+    step: 'connect',
+    description: 'Create compass routing reference for workflow navigation',
+    patterns: {
+      Independent: { active: true, required: false, defaultValue: 'per-agent' },
+      Sequential: { active: true, required: true, defaultValue: 'shared-reference' },
+    },
+  },
+  {
+    id: 'orchestration-workflow',
+    step: 'connect',
+    description: 'Create pipeline orchestration workflow',
+    patterns: {
+      Independent: { active: false, required: false },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'output-directory',
+    step: 'connect',
+    description: 'Define artifact output location',
+    patterns: {
+      Independent: { active: true, required: true, defaultValue: '_bmad-output/{team}-artifacts' },
+      Sequential: { active: true, required: true, defaultValue: '_bmad-output/{team}-artifacts' },
+    },
+  },
+  {
+    id: 'naming-enforcement',
+    step: 'scope',
+    description: 'Validate all naming conventions (agent IDs, file names, module directory)',
+    patterns: {
+      Independent: { active: true, required: true },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'overlap-detection',
+    step: 'scope',
+    description: 'Check proposed agents against existing agent manifest for collisions',
+    patterns: {
+      Independent: { active: true, required: true },
+      Sequential: { active: true, required: true },
+    },
+  },
+];
+
+/**
+ * Given a composition pattern, return which factory decisions are relevant
+ * and which are eliminated.
+ *
+ * @param {string} pattern - "Independent" or "Sequential"
+ * @returns {{ decisions: CascadeDecision[], eliminated: CascadeDecision[], error?: string }}
+ */
+function getCascadeForPattern(pattern) {
+  const validation = validatePattern(pattern);
+  if (!validation.valid) {
+    return { decisions: [], eliminated: [], error: validation.error };
+  }
+
+  const decisions = [];
+  const eliminated = [];
+
+  for (const entry of DECISION_CATALOGUE) {
+    const patternConfig = entry.patterns[pattern];
+    const decision = {
+      id: entry.id,
+      step: entry.step,
+      description: entry.description,
+      required: patternConfig.required,
+      defaultValue: patternConfig.defaultValue || undefined,
+    };
+
+    if (patternConfig.active) {
+      decisions.push(decision);
+    } else {
+      eliminated.push(decision);
+    }
+  }
+
+  return { decisions, eliminated };
+}
+
+/**
+ * Validate that a pattern string is recognized.
+ * @param {string} pattern
+ * @returns {{ valid: boolean, error?: string }}
+ */
+function validatePattern(pattern) {
+  if (!pattern || typeof pattern !== 'string') {
+    return { valid: false, error: 'Pattern must be a non-empty string' };
+  }
+  if (!KNOWN_PATTERNS.includes(pattern)) {
+    return { valid: false, error: `Unknown pattern "${pattern}". Expected one of: ${KNOWN_PATTERNS.join(', ')}` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Get the list of known composition patterns.
+ * @returns {string[]}
+ */
+function getKnownPatterns() {
+  return [...KNOWN_PATTERNS];
+}
+
+/**
+ * @typedef {Object} CascadeDecision
+ * @property {string} id - Decision identifier
+ * @property {string} step - Factory step this belongs to (scope, connect, generate, validate)
+ * @property {string} description - Human-readable description
+ * @property {boolean} required - Whether mandatory for the pattern
+ * @property {string} [defaultValue] - Default if applicable
+ */
+
+module.exports = {
+  getCascadeForPattern,
+  validatePattern,
+  getKnownPatterns,
+};

package/_bmad/bme/_team-factory/lib/collision-detector.js

@@ -0,0 +1,228 @@
+'use strict';
+
+const fs = require('fs-extra');
+
+/**
+ * Detect collisions between a new team spec and existing framework state.
+ * Handles Level 1 (exact ID match) and Level 2 (name similarity).
+ * Level 3 (capability overlap) is LLM reasoning in the workflow step.
+ *
+ * @param {Object} specData - Parsed team spec
+ * @param {string} manifestPath - Absolute path to agent-manifest.csv
+ * @param {string} [bmeDir] - Path to _bmad/bme/ directory for submodule name checks
+ * @returns {Promise<CollisionResult>}
+ */
+async function detectCollisions(specData, manifestPath, bmeDir) {
+  const blocks = [];
+  const warnings = [];
+
+  const dataWarnings = [];
+
+  // Parse existing agent manifest
+  const { agents: existingAgents, warning: manifestWarning } = await parseManifest(manifestPath);
+  if (manifestWarning) dataWarnings.push(manifestWarning);
+
+  // Parse existing submodule directories
+  const { modules: existingModules, warning: modulesWarning } = bmeDir
+    ? await listSubmodules(bmeDir)
+    : { modules: [], warning: null };
+  if (modulesWarning) dataWarnings.push(modulesWarning);
+
+  const proposedTeam = specData.team_name_kebab || '';
+  const proposedAgents = (specData.agents || []).map(a => a.id).filter(Boolean);
+
+  // --- Level 1: Exact submodule name collision ---
+  if (proposedTeam && existingModules.includes(`_${proposedTeam}`)) {
+    blocks.push({
+      level: 'exact',
+      field: 'submodule_name',
+      newValue: `_${proposedTeam}`,
+      existingValue: `_${proposedTeam}`,
+      existingModule: proposedTeam,
+      suggestion: `Module directory _bmad/bme/_${proposedTeam}/ already exists. Choose a different team name.`,
+    });
+  }
+
+  // --- Level 1: Exact agent ID collision ---
+  for (const agentId of proposedAgents) {
+    const match = existingAgents.find(a => a.id === agentId);
+    if (match) {
+      blocks.push({
+        level: 'exact',
+        field: 'agent_id',
+        newValue: agentId,
+        existingValue: match.id,
+        existingModule: match.module,
+        suggestion: `Agent ID "${agentId}" already exists in module "${match.module}". Rename your agent.`,
+      });
+    }
+  }
+
+  // --- Level 2: Similar agent name detection ---
+  for (const agentId of proposedAgents) {
+    for (const existing of existingAgents) {
+      if (existing.id === agentId) continue; // Already caught by Level 1
+
+      const dist = levenshtein(agentId, existing.id);
+      const sharePrefix = sharedPrefix(agentId, existing.id);
+
+      if (dist <= 2 || (sharePrefix >= 4 && dist <= 3)) {
+        warnings.push({
+          level: 'similar',
+          field: 'agent_id',
+          newValue: agentId,
+          existingValue: existing.id,
+          existingModule: existing.module,
+          suggestion: `"${agentId}" is similar to existing "${existing.id}" (${existing.module}). Intentional?`,
+        });
+      }
+    }
+  }
+
+  return {
+    blocks,
+    warnings,
+    dataWarnings,
+    hasBlocking: blocks.length > 0,
+  };
+}
+
+/**
+ * Parse agent-manifest.csv to extract agent IDs and their modules.
+ * @param {string} manifestPath
+ * @returns {Promise<{agents: Array<{id: string, module: string}>, warning: string|null}>}
+ */
+async function parseManifest(manifestPath) {
+  try {
+    const content = await fs.readFile(manifestPath, 'utf8');
+    const lines = content.split('\n').filter(l => l.trim());
+    if (lines.length < 2) return { agents: [], warning: null };
+
+    const results = [];
+    // Skip header (line 0), parse data rows
+    for (let i = 1; i < lines.length; i++) {
+      const fields = parseCSVLine(lines[i]);
+      if (fields.length >= 10) {
+        const id = fields[0].replace(/^"|"$/g, '').trim();
+        const module = fields[9].replace(/^"|"$/g, '').trim();
+        if (id) results.push({ id, module });
+      }
+    }
+    return { agents: results, warning: null };
+  } catch (err) {
+    return { agents: [], warning: `Could not read agent manifest at ${manifestPath}: ${err.message}. Collision detection may be incomplete.` };
+  }
+}
+
+/**
+ * Parse a single CSV line handling quoted fields.
+ * @param {string} line
+ * @returns {string[]}
+ */
+function parseCSVLine(line) {
+  const fields = [];
+  let current = '';
+  let inQuotes = false;
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (inQuotes) {
+      if (ch === '"' && line[i + 1] === '"') {
+        current += '"';
+        i++; // skip escaped quote
+      } 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;
+}
+
+/**
+ * List existing submodule directory names under _bmad/bme/.
+ * @param {string} bmeDir
+ * @returns {Promise<{modules: string[], warning: string|null}>}
+ */
+async function listSubmodules(bmeDir) {
+  try {
+    const entries = await fs.readdir(bmeDir, { withFileTypes: true });
+    const modules = entries
+      .filter(e => e.isDirectory() && e.name.startsWith('_'))
+      .map(e => e.name);
+    return { modules, warning: null };
+  } catch (err) {
+    return { modules: [], warning: `Could not read bme directory at ${bmeDir}: ${err.message}. Submodule collision detection skipped.` };
+  }
+}
+
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  const matrix = Array.from({ length: b.length + 1 }, (_, i) => [i]);
+  for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      const cost = a[j - 1] === b[i - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        matrix[i][j - 1] + 1,
+        matrix[i - 1][j - 1] + cost,
+      );
+    }
+  }
+
+  return matrix[b.length][a.length];
+}
+
+/**
+ * Count shared prefix length between two strings.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function sharedPrefix(a, b) {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return i;
+}
+
+/**
+ * @typedef {Object} CollisionResult
+ * @property {CollisionEntry[]} blocks - Level 1: exact matches, must be resolved
+ * @property {CollisionEntry[]} warnings - Level 2: similar names, review recommended
+ * @property {boolean} hasBlocking - true if any blocks exist
+ */
+
+/**
+ * @typedef {Object} CollisionEntry
+ * @property {string} level - "exact" or "similar"
+ * @property {string} field - "agent_id", "submodule_name", or "workflow_name"
+ * @property {string} newValue
+ * @property {string} existingValue
+ * @property {string} existingModule
+ * @property {string} suggestion
+ */
+
+module.exports = {
+  detectCollisions,
+};