@claude-flow/cli 3.37.0 → 3.38.1

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-11T17:05:49.193Z",
-  "gitSha": "6ce18b5a",
+  "generatedAt": "2026-08-12T14:05:18.962Z",
+  "gitSha": "b8c37da8",
   "catalog": {
     "agents": 164,
     "tools": 397,

package/dist/src/commands/memory.js

@@ -214,7 +214,15 @@ const storeCommand = {
                 ]
             });
             output.writeln();
-            output.printSuccess('Data stored successfully');
+            if (result.persistWarning) {
+                // #2968: the write ran, but the checkpoint signal indicates it may
+                // not have reached disk (sql.js fallback driver) — do not print an
+                // unconditional green success for a write that might vanish.
+                output.printWarning(`Data stored, but persistence is not guaranteed: ${result.persistWarning}`);
+            }
+            else {
+                output.printSuccess('Data stored successfully');
+            }
             return { success: true, data: { ...storeData, id: result.id, embedding: result.embedding, provenanceType: provenance || 'unknown' } };
         }
         catch (error) {

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/memory/memory-bridge.d.ts

@@ -67,6 +67,13 @@ export declare function bridgeStoreEntry(options: {
     cached?: boolean;
     attested?: boolean;
     error?: string;
+    /** #2968: set when the post-write checkpoint failed in a way that
+     *  indicates this connection may not durably persist writes at all
+     *  (the sql.js fallback driver, engaged when better-sqlite3's native
+     *  binding is missing). The write above still ran and `success` is
+     *  still true — this is advisory, not a failure — but callers should
+     *  surface it instead of only printing an unconditional success message. */
+    persistWarning?: string;
 } | null>;
 /**
  * Search entries via AgentDB v3.

package/dist/src/memory/memory-bridge.js

@@ -897,12 +897,27 @@ export async function bridgeStoreEntry(options) {
         // `sqlite3` vector count) then see a stale/empty main DB file and report
         // "0 vectors" / empty search. A PASSIVE checkpoint flushes committed pages
         // into the main file without blocking writers. Best-effort, never fatal.
+        let persistWarning;
         try {
             if (typeof ctx.db.pragma === 'function') {
                 ctx.db.pragma('wal_checkpoint(PASSIVE)');
             }
         }
-        catch { /* non-WAL, busy, or unsupported — non-fatal */ }
+        catch (checkpointErr) {
+            // #2968: on the sql.js fallback driver (engaged when better-sqlite3's
+            // native binding never got built — e.g. a skipped optionalDependency
+            // postinstall), this PRAGMA isn't implemented and throws "Invalid
+            // PRAGMA command". sql.js has no WAL journal to checkpoint at all, so
+            // this specific failure is the strongest signal available here that
+            // the insert above may exist only in this process's in-memory image
+            // and never reach disk — not the ordinary "non-WAL, busy, or
+            // unsupported" case the old blanket catch assumed. Surface it rather
+            // than swallow it silently; other pragma failures stay non-fatal.
+            const msg = checkpointErr instanceof Error ? checkpointErr.message : String(checkpointErr);
+            if (/Invalid PRAGMA/i.test(msg)) {
+                persistWarning = `sql.js fallback driver in use — this write may not be durably persisted to disk (${msg}). Install better-sqlite3's native binding to restore durable writes (see issue #2968: npm rebuild better-sqlite3, or reinstall with install scripts enabled).`;
+            }
+        }
         // Phase 2: Write-through to TieredCache
         const safeNs = String(namespace).replace(/:/g, '_');
         const safeKey = String(key).replace(/:/g, '_');
@@ -918,6 +933,7 @@ export async function bridgeStoreEntry(options) {
             guarded: true,
             cached: true,
             attested: true,
+            ...(persistWarning ? { persistWarning } : {}),
         };
     }
     catch (err) {
@@ -995,10 +1011,17 @@ export async function bridgeSearchEntries(options) {
         const whereExtra = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
         let rows;
         try {
+            // #2982/#2976: this pre-rank SELECT truncates the corpus to 1000 rows
+            // before BM25/embedding scoring runs. Without ORDER BY, SQLite returns
+            // rows in arbitrary storage order (effectively oldest-inserted-first at
+            // scale), so on any corpus over 1000 entries the newest — and often
+            // most relevant — rows never reach scoring at all. bridgeListEntries()
+            // already orders by updated_at DESC for the same reason; mirror it here.
             const stmt = ctx.db.prepare(`
         SELECT id, key, namespace, content, embedding, provenance_type
         FROM memory_entries
         WHERE ${ACTIVE_MEMORY_ROW_SQL} ${whereExtra}
+        ORDER BY updated_at DESC
         LIMIT 1000
       `);
             rows = filterParams.length > 0 ? stmt.all(...filterParams) : stmt.all();
@@ -1506,10 +1529,14 @@ export async function bridgeSearchHNSW(queryEmbedding, options, dbPath) {
             : '';
         let rows;
         try {
+            // #2982/#2976: same unordered pre-rank truncation as bridgeSearchEntries
+            // above — without ORDER BY, a corpus over 10000 rows silently drops
+            // its newest entries before cosine scoring ever runs.
             const stmt = ctx.db.prepare(`
         SELECT id, key, namespace, content, embedding
         FROM memory_entries
         WHERE status = 'active' AND embedding IS NOT NULL ${nsFilter}
+        ORDER BY updated_at DESC
         LIMIT 10000
       `);
             rows = nsFilter

package/dist/src/memory/memory-initializer.d.ts

@@ -448,6 +448,9 @@ export declare function storeEntry(options: {
         model: string;
     };
     error?: string;
+    /** #2968: set when the bridge's checkpoint failed in a way indicating
+     *  this write may not be durably persisted (sql.js fallback driver). */
+    persistWarning?: string;
 }>;
 /**
  * Search entries using sql.js with vector similarity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.37.0",
+  "version": "3.38.1",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",