Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 targets
const 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 command
const 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 results
if (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 } };
}
};