π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(migrate): implement ADR-128's promised removed-agent detection (ADR-382 Part B) (#2973)
rUv2c8f86358364
diff --git a/v3/@claude-flow/cli/__tests__/migrate-agent-detection.test.ts b/v3/@claude-flow/cli/__tests__/migrate-agent-detection.test.tsnew file mode 100644index 0000000000..c9e2b7e876--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/migrate-agent-detection.test.ts@@ -0,0 +1,128 @@+/**+ * ADR-382 Part B β removed-agent detection for `ruflo migrate status`.+ *+ * Tests target detectRemovedAgentGaps() directly (not the full statusCommand+ * action) because the production call path defaults to the REAL+ * os.homedir() plugin registry β asserting against that would make the+ * suite depend on whatever happens to be installed on the machine running+ * it. The homeDir override exists precisely so tests can supply an isolated+ * registry.+ */+import { describe, it, expect } from 'vitest';+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';+import { join } from 'node:path';+import { tmpdir } from 'node:os';+import { detectRemovedAgentGaps, type RemovedAgentMapping } from '../src/commands/migrate-agent-detection.js';++const REMOVED_AGENTS: RemovedAgentMapping[] = [+ { basename: 'coder.md', plugin: 'ruflo-core' },+ { basename: 'researcher.md', plugin: 'ruflo-core' },+ { basename: 'reviewer.md', plugin: 'ruflo-core' },+ { basename: 'tester.md', plugin: 'ruflo-testgen' },+ { basename: 'memory-specialist.md', plugin: 'ruflo-rag-memory' },+ { basename: 'security-auditor.md', plugin: 'ruflo-security-audit' },+ { basename: 'sparc-orchestrator.md', plugin: 'ruflo-sparc' },+ { basename: 'goal-planner.md', plugin: 'ruflo-goals' },+ { basename: 'adr-architect.md', plugin: 'ruflo-adr' },+];++function project(): string {+ return mkdtempSync(join(tmpdir(), 'migrate-agent-gaps-'));+}++function emptyHome(): string {+ const home = mkdtempSync(join(tmpdir(), 'migrate-agent-gaps-home-'));+ return home;+}++function homeWithInstalledPlugins(plugins: Record<string, Array<{ scope?: string; projectPath?: string }>>): string {+ const home = emptyHome();+ mkdirSync(join(home, '.claude', 'plugins'), { recursive: true });+ writeFileSync(+ join(home, '.claude', 'plugins', 'installed_plugins.json'),+ JSON.stringify({ version: 2, plugins: plugins })+ );+ return home;+}++describe('detectRemovedAgentGaps', () => {+ it('surfaces all 9 suggestions when every agent is missing and no plugins are installed', () => {+ const cwd = project();+ const homeDir = emptyHome();++ const gaps = detectRemovedAgentGaps(cwd, REMOVED_AGENTS, { homeDir });++ expect(gaps).toHaveLength(9);+ expect(gaps.map(g => g.agent).sort()).toEqual(+ [...REMOVED_AGENTS.map(a => a.basename)].sort()+ );+ for (const gap of gaps) {+ expect(gap.installCommand).toBe(`ruflo plugins install ${gap.plugin}`);+ }+ });++ it('does not flag agents whose owning plugin is installed (user scope)', () => {+ const cwd = project();+ const homeDir = homeWithInstalledPlugins({+ 'ruflo-core@ruflo': [{ scope: 'user' }],+ });++ const gaps = detectRemovedAgentGaps(cwd, REMOVED_AGENTS, { homeDir });++ const flaggedAgents = gaps.map(g => g.agent);+ expect(flaggedAgents).not.toContain('coder.md');+ expect(flaggedAgents).not.toContain('researcher.md');+ expect(flaggedAgents).not.toContain('reviewer.md');+ // The other 6 (different owning plugins) are still flagged.+ expect(gaps).toHaveLength(6);+ });++ it('honors project-scoped installs only for the matching project', () => {+ const cwd = project();+ const otherProject = project();+ const homeDir = homeWithInstalledPlugins({+ 'ruflo-testgen@ruflo': [{ scope: 'project', projectPath: otherProject }],+ });++ const gaps = detectRemovedAgentGaps(cwd, REMOVED_AGENTS, { homeDir });++ // Installed for a different project β tester.md should still be flagged here.+ expect(gaps.map(g => g.agent)).toContain('tester.md');+ });++ it('reports no gaps when every agent basename is present on disk', () => {+ const cwd = project();+ const homeDir = emptyHome();+ const agentsDir = join(cwd, '.claude', 'agents');+ mkdirSync(join(agentsDir, 'core'), { recursive: true });+ mkdirSync(join(agentsDir, 'testing'), { recursive: true });+ mkdirSync(join(agentsDir, 'memory'), { recursive: true });++ for (const { basename } of REMOVED_AGENTS) {+ // Distribution across subdirectories doesn't matter β detection walks+ // the whole .claude/agents/ tree, matching the "**/basename.md" intent.+ writeFileSync(join(agentsDir, 'core', basename), '# stub agent\n');+ }++ const gaps = detectRemovedAgentGaps(cwd, REMOVED_AGENTS, { homeDir });++ expect(gaps).toEqual([]);+ });++ it('reports no gaps for a project with no .claude/agents directory at all once plugins cover everything', () => {+ const cwd = project();+ const homeDir = homeWithInstalledPlugins({+ 'ruflo-core@ruflo': [{ scope: 'user' }],+ 'ruflo-testgen@ruflo': [{ scope: 'user' }],+ 'ruflo-rag-memory@ruflo': [{ scope: 'user' }],+ 'ruflo-security-audit@ruflo': [{ scope: 'user' }],+ 'ruflo-sparc@ruflo': [{ scope: 'user' }],+ 'ruflo-goals@ruflo': [{ scope: 'user' }],+ 'ruflo-adr@ruflo': [{ scope: 'user' }],+ });++ const gaps = detectRemovedAgentGaps(cwd, REMOVED_AGENTS, { homeDir });++ expect(gaps).toEqual([]);+ });+});diff --git a/v3/@claude-flow/cli/src/commands/migrate-agent-detection.ts b/v3/@claude-flow/cli/src/commands/migrate-agent-detection.tsnew file mode 100644index 0000000000..2cbffb07d3--- /dev/null+++ b/v3/@claude-flow/cli/src/commands/migrate-agent-detection.ts@@ -0,0 +1,141 @@+/**+ * ADR-382 Part B β the `ruflo migrate` mitigation ADR-128 promised and never+ * shipped: detect the 9 forked agents ADR-128 Phase 2 deleted from the init+ * template (each plugin is now canonical) and, when a project is missing one+ * AND the owning plugin isn't installed, surface an install suggestion.+ * See v3/docs/adr/ADR-382-init-scaffold-content-drift-remediation.md and+ * https://github.com/ruvnet/ruflo/issues/2971.+ *+ * Kept in a sibling module (not migrate.ts) because migrate.ts is already+ * near/over the 500-line budget β see CLAUDE.md file-size rule.+ */+import * as fs from 'fs';+import * as path from 'path';+import * as os from 'os';++export interface RemovedAgentMapping {+ /** Basename as it shipped in the init template, e.g. "coder.md". */+ basename: string;+ /** Marketplace plugin id (name in .claude-plugin/marketplace.json) that now owns it. */+ plugin: string;+}++export interface RemovedAgentGap {+ agent: string;+ plugin: string;+ installCommand: string;+}++export interface DetectRemovedAgentGapsOptions {+ /**+ * Override for the Claude Code plugin-registry home directory. Defaults to+ * os.homedir(). Tests inject an isolated temp dir so results don't depend+ * on whatever is actually installed on the machine running the suite.+ */+ homeDir?: string;+}++interface InstalledPluginEntry {+ scope?: string;+ projectPath?: string;+}++type InstalledPluginsRegistry = Record<string, InstalledPluginEntry[]>;++/**+ * Claude Code records every plugin install (marketplace-scoped, "user" or+ * "project") in a single global file β ~/.claude/plugins/installed_plugins.json,+ * keyed "<plugin>@<marketplace>". This is the only real on-disk signal for+ * "is the owning plugin installed"; there is no per-project marker and no+ * ruflo-side tracking for marketplace plugins (ruflo's own PluginManager+ * manifest at .claude-flow/plugins/installed.json tracks a different,+ * npm-package-based plugin system).+ */+function readInstalledPluginsRegistry(homeDir: string): InstalledPluginsRegistry {+ const registryPath = path.join(homeDir, '.claude', 'plugins', 'installed_plugins.json');+ try {+ if (!fs.existsSync(registryPath)) return {};+ const raw = fs.readFileSync(registryPath, 'utf-8');+ const parsed = JSON.parse(raw);+ if (parsed && typeof parsed === 'object' && parsed.plugins && typeof parsed.plugins === 'object') {+ return parsed.plugins as InstalledPluginsRegistry;+ }+ return {};+ } catch {+ return {};+ }+}++function isPluginInstalled(pluginName: string, cwd: string, registry: InstalledPluginsRegistry): boolean {+ const resolvedCwd = path.resolve(cwd);+ const prefix = `${pluginName}@`;+ for (const [key, entries] of Object.entries(registry)) {+ if (!key.startsWith(prefix)) continue;+ if (!Array.isArray(entries)) continue;+ for (const entry of entries) {+ if (entry?.scope === 'project') {+ if (entry.projectPath && path.resolve(entry.projectPath) === resolvedCwd) return true;+ } else {+ // "user" scope (or unspecified) applies to every project.+ return true;+ }+ }+ }+ return false;+}++function agentFileExists(cwd: string, basename: string): boolean {+ const agentsDir = path.join(cwd, '.claude', 'agents');+ return findBasename(agentsDir, basename, 0);+}++// .claude/agents/ is a shallow tree (category/[subcategory]/name.md); a small+// depth guard is enough to avoid pathological recursion without needing a+// real glob dependency for a two-or-three-level lookup.+const MAX_AGENT_DIR_DEPTH = 6;++function findBasename(dir: string, basename: string, depth: number): boolean {+ if (depth > MAX_AGENT_DIR_DEPTH) return false;+ let entries: fs.Dirent[];+ try {+ entries = fs.readdirSync(dir, { withFileTypes: true });+ } catch {+ return false;+ }+ for (const entry of entries) {+ if (entry.isDirectory()) {+ if (findBasename(path.join(dir, entry.name), basename, depth + 1)) return true;+ } else if (entry.isFile() && entry.name === basename) {+ return true;+ }+ }+ return false;+}++/**+ * Returns one gap row per removed agent that is both missing from the+ * project's .claude/agents/ tree and not covered by an installed owning+ * plugin. Pure filesystem checks, no CLI version comparison (ADR-382 Part B+ * scope note: a filesystem check is sufficient and accurate here).+ */+export function detectRemovedAgentGaps(+ cwd: string,+ removedAgents: RemovedAgentMapping[],+ options: DetectRemovedAgentGapsOptions = {}+): RemovedAgentGap[] {+ const homeDir = options.homeDir ?? os.homedir();+ const registry = readInstalledPluginsRegistry(homeDir);+ const gaps: RemovedAgentGap[] = [];++ for (const { basename, plugin } of removedAgents) {+ if (agentFileExists(cwd, basename)) continue;+ if (isPluginInstalled(plugin, cwd, registry)) continue;+ gaps.push({+ agent: basename,+ plugin,+ installCommand: `ruflo plugins install ${plugin}`,+ });+ }++ return gaps;+}diff --git a/v3/@claude-flow/cli/src/commands/migrate.ts b/v3/@claude-flow/cli/src/commands/migrate.tsindex 2dfd320285..ea8edbf27a 100644--- a/v3/@claude-flow/cli/src/commands/migrate.ts+++ b/v3/@claude-flow/cli/src/commands/migrate.ts@@ -7,6 +7,7 @@ import type { Command, CommandContext, CommandResult } from '../types.js';import { output } from '../output.js';import * as fs from 'fs';import * as path from 'path';+import { detectRemovedAgentGaps, type RemovedAgentMapping } from './migrate-agent-detection.js';// Migration targetsconst MIGRATION_TARGETS = [@@ -19,6 +20,22 @@ const MIGRATION_TARGETS = [{ value: 'all', label: 'All', hint: 'Full migration' }];+// ADR-128 Phase 2 deleted these 9 forked agents from the init template,+// making each plugin canonical β but ADR-128's own Consequences section+// promised "`ruflo migrate` should detect removed agents and print install+// suggestions," which never shipped until ADR-382 Part B (issue #2971).+const REMOVED_AGENTS: RemovedAgentMapping[] = [+ { basename: 'coder.md', plugin: 'ruflo-core' },+ { basename: 'researcher.md', plugin: 'ruflo-core' },+ { basename: 'reviewer.md', plugin: 'ruflo-core' },+ { basename: 'tester.md', plugin: 'ruflo-testgen' },+ { basename: 'memory-specialist.md', plugin: 'ruflo-rag-memory' },+ { basename: 'security-auditor.md', plugin: 'ruflo-security-audit' },+ { basename: 'sparc-orchestrator.md', plugin: 'ruflo-sparc' },+ { basename: 'goal-planner.md', plugin: 'ruflo-goals' },+ { basename: 'adr-architect.md', plugin: 'ruflo-adr' },+];+// Status commandconst statusCommand: Command = {name: 'status',@@ -115,10 +132,14 @@ const statusCommand: Command = {components.push({ component: 'Migration State', status: migrationState, migrationNeeded: 'no' });}+ // ADR-382 Part B: agents ADR-128 removed from the init template that are+ // both missing from this project and not covered by an installed plugin.+ const removedAgentGaps = detectRemovedAgentGaps(cwd, REMOVED_AGENTS);+// Display resultsif (ctx.flags.format === 'json') {- output.printJson({ components, migrationState });- return { success: true, data: { components, migrationState } };+ output.printJson({ components, migrationState, removedAgentGaps });+ return { success: true, data: { components, migrationState, removedAgentGaps } };}output.writeln();@@ -147,7 +168,29 @@ const statusCommand: Command = {output.printSuccess('No migration needed.');}- return { success: true, data: { components, needsMigration } };+ if (removedAgentGaps.length > 0) {+ output.writeln();+ output.writeln(output.bold('Removed Agents (ADR-128)'));+ output.printTable({+ columns: [+ { key: 'agent', header: 'Agent', width: 24 },+ { key: 'plugin', header: 'Owning Plugin', width: 20 },+ { key: 'installCommand', header: 'Install', width: 34 }+ ],+ data: removedAgentGaps.map(g => ({+ agent: output.warning(g.agent),+ plugin: g.plugin,+ installCommand: output.dim(g.installCommand)+ })),+ border: false+ });+ output.writeln();+ output.printInfo(+ `${removedAgentGaps.length} agent(s) removed by ADR-128 are missing from .claude/agents/ and not covered by an installed plugin.`+ );+ }++ return { success: true, data: { components, needsMigration, removedAgentGaps } };}};