@claude-flow/cli 3.36.0 → 3.38.0

package/.claude/skills/sparc-methodology/SKILL.md

@@ -472,28 +472,28 @@ mcp__claude-flow__swarm_monitor {
 
 ```bash
 # Execute specific mode
-npx claude-flow sparc run <mode> "task description"
+npx @claude-flow/cli@latest sparc run <mode> "task description"
 
 # Use alpha features
 npx claude-flow@alpha sparc run <mode> "task description"
 
 # List all available modes
-npx claude-flow sparc modes
+npx @claude-flow/cli@latest sparc modes
 
 # Get help for specific mode
-npx claude-flow sparc help <mode>
+npx @claude-flow/cli@latest sparc help <mode>
 
 # Run with options
-npx claude-flow sparc run <mode> "task" --parallel --monitor
+npx @claude-flow/cli@latest sparc run <mode> "task" --parallel --monitor
 
 # Execute TDD workflow
-npx claude-flow sparc tdd "feature description"
+npx @claude-flow/cli@latest sparc tdd "feature description"
 
 # Batch execution
-npx claude-flow sparc batch <mode1,mode2,mode3> "task"
+npx @claude-flow/cli@latest sparc batch <mode1,mode2,mode3> "task"
 
 # Pipeline execution
-npx claude-flow sparc pipeline "task description"
+npx @claude-flow/cli@latest sparc pipeline "task description"
 ```
 
 ### Method 3: Local Installation
@@ -911,58 +911,58 @@ mcp__claude-flow__sparc_mode {
 
 ```bash
 # Step 1: Research and planning
-npx claude-flow sparc run researcher "authentication patterns"
+npx @claude-flow/cli@latest sparc run researcher "authentication patterns"
 
 # Step 2: Architecture design
-npx claude-flow sparc run architect "design auth system"
+npx @claude-flow/cli@latest sparc run architect "design auth system"
 
 # Step 3: TDD implementation
-npx claude-flow sparc tdd "user authentication feature"
+npx @claude-flow/cli@latest sparc tdd "user authentication feature"
 
 # Step 4: Code review
-npx claude-flow sparc run reviewer "review auth implementation"
+npx @claude-flow/cli@latest sparc run reviewer "review auth implementation"
 
 # Step 5: Documentation
-npx claude-flow sparc run documenter "document auth API"
+npx @claude-flow/cli@latest sparc run documenter "document auth API"
 ```
 
 ### Workflow 2: Bug Investigation
 
 ```bash
 # Step 1: Analyze issue
-npx claude-flow sparc run analyzer "investigate bug #456"
+npx @claude-flow/cli@latest sparc run analyzer "investigate bug #456"
 
 # Step 2: Debug systematically
-npx claude-flow sparc run debugger "fix memory leak in service X"
+npx @claude-flow/cli@latest sparc run debugger "fix memory leak in service X"
 
 # Step 3: Create tests
-npx claude-flow sparc run tester "regression tests for bug #456"
+npx @claude-flow/cli@latest sparc run tester "regression tests for bug #456"
 
 # Step 4: Review fix
-npx claude-flow sparc run reviewer "validate bug fix"
+npx @claude-flow/cli@latest sparc run reviewer "validate bug fix"
 ```
 
 ### Workflow 3: Performance Optimization
 
 ```bash
 # Step 1: Profile performance
-npx claude-flow sparc run analyzer "profile API response times"
+npx @claude-flow/cli@latest sparc run analyzer "profile API response times"
 
 # Step 2: Identify bottlenecks
-npx claude-flow sparc run optimizer "optimize database queries"
+npx @claude-flow/cli@latest sparc run optimizer "optimize database queries"
 
 # Step 3: Implement improvements
-npx claude-flow sparc run coder "implement caching layer"
+npx @claude-flow/cli@latest sparc run coder "implement caching layer"
 
 # Step 4: Benchmark results
-npx claude-flow sparc run tester "performance benchmarks"
+npx @claude-flow/cli@latest sparc run tester "performance benchmarks"
 ```
 
 ### Workflow 4: Complete Pipeline
 
 ```bash
 # Execute full development pipeline
-npx claude-flow sparc pipeline "e-commerce checkout feature"
+npx @claude-flow/cli@latest sparc pipeline "e-commerce checkout feature"
 
 # This automatically runs:
 # 1. researcher - Gather requirements
@@ -1070,19 +1070,19 @@ mcp__claude-flow__token_usage {
 
 ```bash
 # List modes
-npx claude-flow sparc modes
+npx @claude-flow/cli@latest sparc modes
 
 # Run specific mode
-npx claude-flow sparc run <mode> "task"
+npx @claude-flow/cli@latest sparc run <mode> "task"
 
 # TDD workflow
-npx claude-flow sparc tdd "feature"
+npx @claude-flow/cli@latest sparc tdd "feature"
 
 # Full pipeline
-npx claude-flow sparc pipeline "task"
+npx @claude-flow/cli@latest sparc pipeline "task"
 
 # Batch execution
-npx claude-flow sparc batch <modes> "task"
+npx @claude-flow/cli@latest sparc batch <modes> "task"
 ```
 
 ### Most Common MCP Calls

package/.claude/skills/swarm-advanced/SKILL.md

@@ -237,7 +237,7 @@ mcp__claude-flow__workflow_execute({
 ### CLI Fallback
 ```bash
 # Quick research swarm
-npx claude-flow swarm "research AI trends in 2025" \
+npx @claude-flow/cli@latest swarm "research AI trends in 2025" \
   --strategy research \
   --mode distributed \
   --max-agents 6 \
@@ -381,7 +381,7 @@ mcp__claude-flow__pipeline_create({
 ### CLI Fallback
 ```bash
 # Quick development swarm
-npx claude-flow swarm "build REST API with authentication" \
+npx @claude-flow/cli@latest swarm "build REST API with authentication" \
   --strategy development \
   --mode hierarchical \
   --monitor \
@@ -581,7 +581,7 @@ mcp__claude-flow__trend_analysis({
 ### CLI Fallback
 ```bash
 # Quick testing swarm
-npx claude-flow swarm "test application comprehensively" \
+npx @claude-flow/cli@latest swarm "test application comprehensively" \
   --strategy testing \
   --mode star \
   --parallel \

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 4,
-  "generatedAt": "2026-08-10T17:40:16.814Z",
-  "gitSha": "f35c545f",
+  "generatedAt": "2026-08-11T22:42:24.276Z",
+  "gitSha": "6b01dc5a",
   "catalog": {
     "agents": 164,
     "tools": 397,

package/dist/src/commands/migrate-agent-detection.d.ts

@@ -0,0 +1,27 @@
+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;
+}
+/**
+ * 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 declare function detectRemovedAgentGaps(cwd: string, removedAgents: RemovedAgentMapping[], options?: DetectRemovedAgentGapsOptions): RemovedAgentGap[];
+//# sourceMappingURL=migrate-agent-detection.d.ts.map

package/dist/src/commands/migrate-agent-detection.js

@@ -0,0 +1,113 @@
+/**
+ * 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';
+/**
+ * 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) {
+    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;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+function isPluginInstalled(pluginName, cwd, registry) {
+    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, basename) {
+    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, basename, depth) {
+    if (depth > MAX_AGENT_DIR_DEPTH)
+        return false;
+    let entries;
+    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, removedAgents, options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const registry = readInstalledPluginsRegistry(homeDir);
+    const gaps = [];
+    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;
+}
+//# sourceMappingURL=migrate-agent-detection.js.map

package/dist/src/commands/migrate.js

@@ -5,6 +5,7 @@
 import { output } from '../output.js';
 import * as fs from 'fs';
 import * as path from 'path';
+import { detectRemovedAgentGaps } from './migrate-agent-detection.js';
 // Migration targets
 const MIGRATION_TARGETS = [
     { value: 'config', label: 'Configuration', hint: 'Migrate configuration files' },
@@ -15,6 +16,21 @@ const MIGRATION_TARGETS = [
     { value: 'embeddings', label: 'Embeddings', hint: 'Migrate to ONNX with hyperbolic support' },
     { 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 = [
+    { 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 = {
     name: 'status',
@@ -101,10 +117,13 @@ const statusCommand = {
         if (migrationState) {
             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();
         output.writeln(output.bold('Migration Status'));
@@ -130,7 +149,26 @@ const statusCommand = {
         else {
             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 } };
     }
 };
 // Run migration

package/dist/src/commands/proxy-lifecycle.d.ts

@@ -7,13 +7,30 @@
  */
 import type { Command } from '../types.js';
 import { type ProxyStatus } from '../proxy/lifecycle.js';
-/** Pinned and reviewed; later upgrades remain explicit commands. */
-export declare const DEFAULT_PROXY_RELEASE = "0.4.0";
+/**
+ * Pinned and reviewed; later upgrades remain explicit commands.
+ *
+ * Keep this the single source of truth — interpolate it rather than writing
+ * the version into user-facing strings, or the pin silently drifts out of
+ * sync with the text that advertises it.
+ */
+export declare const DEFAULT_PROXY_RELEASE = "0.7.3";
 /**
  * Human-oriented next steps for `ruflo proxy` and `ruflo proxy status`.
  * Keep this independent of the command framework so the state-specific
  * guidance has a small, direct regression-test surface.
  */
+/**
+ * Lines shown when the binary on disk is an older release than the current
+ * pin — empty otherwise, including when the version is unknown (`null`),
+ * where the honest move is to say nothing rather than guess.
+ *
+ * Bumping `DEFAULT_PROXY_RELEASE` only ever changed what a *new* install
+ * gets. Someone who installed the previous pin has no reason to run
+ * `install` again and no signal that anything moved, so a fix that motivated
+ * a bump reaches exactly the people who never needed it. This is the signal.
+ */
+export declare function proxyUpdateGuidance(status: ProxyStatus): string[];
 export declare function proxyConsoleGuidance(status: ProxyStatus): string[];
 export declare function printProxyConsoleGuidance(status: ProxyStatus): void;
 export declare const proxyLifecycleSubcommands: Command[];

package/dist/src/commands/proxy-lifecycle.js

@@ -11,8 +11,14 @@ import { installProxy, uninstallProxy } from '../proxy/install.js';
 import { startForeground, startBackground, stopProxy, getProxyStatus, readProxyLogTail, watchProxyLog, ProxyNotInstalledError, ProxyAlreadyRunningError, } from '../proxy/lifecycle.js';
 import { proxyTokenPath } from '../proxy/paths.js';
 import { removeInjectedToken, startTokenRefreshPump } from '../proxy/token-bridge.js';
-/** Pinned and reviewed; later upgrades remain explicit commands. */
-export const DEFAULT_PROXY_RELEASE = '0.4.0';
+/**
+ * Pinned and reviewed; later upgrades remain explicit commands.
+ *
+ * Keep this the single source of truth — interpolate it rather than writing
+ * the version into user-facing strings, or the pin silently drifts out of
+ * sync with the text that advertises it.
+ */
+export const DEFAULT_PROXY_RELEASE = '0.7.3';
 const PROXY_COMMAND = 'npx ruflo@latest proxy';
 const AUTH_COMMAND = 'npx ruflo@latest auth';
 /**
@@ -20,6 +26,25 @@ const AUTH_COMMAND = 'npx ruflo@latest auth';
  * Keep this independent of the command framework so the state-specific
  * guidance has a small, direct regression-test surface.
  */
+/**
+ * Lines shown when the binary on disk is an older release than the current
+ * pin — empty otherwise, including when the version is unknown (`null`),
+ * where the honest move is to say nothing rather than guess.
+ *
+ * Bumping `DEFAULT_PROXY_RELEASE` only ever changed what a *new* install
+ * gets. Someone who installed the previous pin has no reason to run
+ * `install` again and no signal that anything moved, so a fix that motivated
+ * a bump reaches exactly the people who never needed it. This is the signal.
+ */
+export function proxyUpdateGuidance(status) {
+    if (!status.installed || !status.version || status.version === DEFAULT_PROXY_RELEASE)
+        return [];
+    return [
+        '',
+        `An update is available — installed v${status.version}, current pin v${DEFAULT_PROXY_RELEASE}.`,
+        `  ${PROXY_COMMAND} update              Re-verify and replace with v${DEFAULT_PROXY_RELEASE}`,
+    ];
+}
 export function proxyConsoleGuidance(status) {
     if (!status.installed) {
         return [
@@ -31,6 +56,7 @@ export function proxyConsoleGuidance(status) {
             `  ${PROXY_COMMAND} start --service`,
         ];
     }
+    const update = proxyUpdateGuidance(status);
     if (!status.running) {
         return [
             '',
@@ -39,6 +65,7 @@ export function proxyConsoleGuidance(status) {
             '',
             'Foreground mode (shows live logs; Ctrl+C stops it):',
             `  ${PROXY_COMMAND} start`,
+            ...update,
             '',
             'Optional: enable Cognitum cloud routing (local-only is the default):',
             `  ${AUTH_COMMAND} login`,
@@ -50,6 +77,7 @@ export function proxyConsoleGuidance(status) {
         'Meta Proxy is ready.',
         `  Logs:    ${PROXY_COMMAND} logs`,
         `  Stop:    ${PROXY_COMMAND} stop`,
+        ...update,
         '',
         'Optional: enable Cognitum cloud routing (local-only is the default):',
         `  ${AUTH_COMMAND} login`,
@@ -122,10 +150,21 @@ const installSub = {
 };
 const updateSub = {
     name: 'update',
-    description: 'Re-verify and replace the installed binary with a specific version (never automatic)',
-    options: [{ name: 'release', description: 'Release version to install', type: 'string', required: true }],
+    description: 'Re-verify and replace the installed binary with the pinned release (never automatic)',
+    options: [
+        // Defaults to the pin, matching `install`. `--release` was previously
+        // required, which meant the only in-product way to reach a newer binary
+        // was to already know its version number — so bumping the pin moved
+        // nothing for anyone who had already installed. Still never automatic:
+        // this runs only when a user types it.
+        {
+            name: 'release',
+            description: `Release version to install (default: ${DEFAULT_PROXY_RELEASE})`,
+            type: 'string',
+        },
+    ],
     action: async (ctx) => {
-        const version = typeof ctx.flags.release === 'string' ? ctx.flags.release : undefined;
+        const version = typeof ctx.flags.release === 'string' ? ctx.flags.release : DEFAULT_PROXY_RELEASE;
         if (!version) {
             output.printError('ruflo proxy update requires --release <x.y.z>');
             return { success: false, exitCode: 1 };
@@ -212,6 +251,11 @@ const statusSub = {
         }
         output.writeln('Meta Proxy');
         output.writeln(`  Installation: ${status.installed ? 'ready' : 'not installed'}`);
+        if (status.installed) {
+            // "unknown" rather than an assumed version: the manifest is the only
+            // record of what was installed, and asking the binary would start it.
+            output.writeln(`  Version: ${status.version ?? 'unknown (no install manifest)'}`);
+        }
         output.writeln(`  Process: ${status.running ? `running (pid ${status.pid})` : 'not running'}`);
         if (status.stalePidFile)
             output.writeln('  (a stale PID file was found and will be cleared on next start)');